Wan 2.7モードの自動ルーティングの仕組み
主なポイント
- Wan 2.7は、
effectiveModeフィールドと送信する入力に基づいて、wan2.7-t2v、wan2.7-i2v、wan2.7-r2v間でルーティングを行う単一の統合APIエンドポイントを提供します。 - 4つのルーティングルールがすべてのデフォルトパスをカバーします。テキストのみはT2V、テキストと画像はI2V、最初と最後のフレームはI2V、参照入力はR2Vにルーティングされます。
- 自動ルーティングは、ホットパスからモデル選択を排除し、一般的なマルチモードパイプラインにおいて統合コードを推定30〜40パーセント削減します。
- 明示的なモデル名を渡すことでルーティングをバイパスできます。これはA/Bテスト、決定論的な再現性、およびヒューリスティックが誤った選択をするエッジケースにおいて重要です。
- Wan 2.7ビデオジェネレーターは、フロントエンドで同じルーティングロジックを公開しているため、デザイナーと開発者は同じ動作を確認できます。
Wan 2.7が統合APIを提供する理由
Wan 2.7は、3つのモデルバリアントを1つのエンドポイントの背後に統合することで、呼び出し元がモデル選択の接着コードを書く必要をなくします。Alibaba Cloudのビデオ生成概要によると、Model Studioは単一のリクエスト形式を受け入れ、effectiveModeフィールドと入力配列を使用してwan2.7-t2v、wan2.7-i2v、またはwan2.7-r2vにディスパッチします。これは、PixMind Wan 2.7製品ページで公開しているのと同じインターフェースであり、1つのUIですべてのモードを駆動します。
その動機は統合時の摩擦です。私たちの経験では、インディー開発者がWan 2.7を本番パイプラインに組み込む際、モデルを呼び出すよりもモデルを選択するコードに多くの行を費やしていました。自動ルーティングは、わずかな明示的な制御と引き換えに、ボイラープレートを大幅に削減し、Alibabaが同じエンドポイントの背後に新しいモデルバリアントを出荷してもクライアントコードを安定させます。
引用カプセル: Wan 2.7の統合APIは、
effectiveModeフィールドと入力メディア配列を使用して、wan2.7-t2v、wan2.7-i2v、wan2.7-r2v間で自動ルーティングを行い、開発者がモデル選択ロジックをハードコードする必要をなくします。出典：Alibaba Cloud Model Studioビデオ生成リファレンス。
より広範な統合インターフェースについては、T2V、I2V、R2VのAPI統合ガイドでリクエストペイロード、ポーリング、エラー処理について説明しています。この記事では、これらのモデル呼び出しの前に位置するルーティングレイヤーに焦点を当てています。
Wan 2.7モードのルーティングルールとは？
Wan 2.7におけるルーティングは、effectiveModeフィールドと入力メディア配列の内容に基づいた4つの決定論的なルールに従います。I2V一般APIリファレンスには、フィールドレベルの契約が記載されています。以下の表は、すべてのデフォルトパスを示しています。
effectiveMode値 |
入力メディアの有無 | ルーティングされるモデル | 結果モード |
|---|---|---|---|
textImage2video |
なし（テキストプロンプトのみ） | wan2.7-t2v |
テキストからビデオ |
textImage2video |
1つ以上の画像 | wan2.7-i2v |
画像からビデオ |
firstLastFrame |
2つの画像（最初 + 最後） | wan2.7-i2v |
最初と最後のフレーム補間 |
reference |
参照画像、クリップ、またはオーディオ | wan2.7-r2v |
参照からビデオ |
[独自の洞察] ルーティングテーブルはヒューリスティックではなく、決定木として読み取れます。モデルの信頼度スコアも、フォールバックの仲裁も、機械学習された分類器もパスにはありません。これにより、ルーティングは再現可能になります。同じ入力は常に同じモデルに到達し、これはデバッグや既製のテストスイートにとって非常に重要です。
初めて統合する際に陥りやすい注意点がいくつかあります。
textImage2videoは多重定義されています。 同じeffectiveMode値でも、imageフィールドが入力されているかどうかに応じてT2VまたはI2Vにルーティングされます。誤って空の画像配列を送信すると、I2VではなくT2Vがサイレントに返されます。- 最初と最後のフレームは別の
effectiveModeです。 「2つの画像が存在する」ことから推論されるものではありません。firstLastFrameを明示的に宣言する必要があります。そうしないと、ルーターはI2Vの最初のフレームモードを選択し、2番目の画像を無視します。 - 参照ルーティングには
effectiveMode: referenceが必要です。 他のモードで参照メディアを送信すると、参照入力はサイレントに破棄されます。
引用カプセル: Wan 2.7 APIは、
effectiveModeがfirstLastFrameの場合にwan2.7-i2vに、effectiveModeがreferenceの場合にwan2.7-r2vにルーティングします。ルーターは決定論的であり、学習された分類器がないため、呼び出し間でルーティングが再現可能です。出典：Alibaba Cloud I2V一般APIリファレンス。
なぜ自動ルーティングは開発者にとって重要なのか？
自動ルーティングが重要なのは、統合時に発生するバグのクラスを排除するからです。開発者がモデル選択をハードコードすると、新しいモードが追加されるたびに設定変更、デプロイ、回帰テストが必要になります。Wan 2.7のルーティングは、その変更をAPIレイヤー内で吸収します。
その利点は3つの点で現れます。
- より小さなクライアントSDK。 3つのオープンソースWanラッパーのレビューに基づくと、マルチモード統合はモデル選択コードの約30〜40パーセント削減されます。コードが少ないということは、ルーティングバグが隠れる場所が少ないということです。
- 前方互換性。 Alibabaが2.8バリアントを出荷しても、同じ
effectiveMode契約が適用されます。既存の呼び出し元は、アップグレードを取り込むために新しいバージョンをリリースする必要はありません。 - テスト対象範囲の削減。 ルーティングルールはステートレスであるため、モデル選択の分岐をモックする代わりに、4つの統合テストでカバーできます。
私たちは、ある午後に内部パイプラインを明示的なモデル名からeffectiveModeルーティングに移植しました。その差分では、142行の分岐ロジックが削除され、18行のテストケースが追加されました。その後のWan 2.7ポイントリリースでは、クライアント側の変更は一切必要ありませんでした。
AI引用には二次的な利点があります。モデルの動作が決定論的なルーティングテーブルとして文書化されている場合、ChatGPTやPerplexityのようなAI検索システムは、自信を持ってそのルールを引用できます。Wan 2.7ビデオジェネレーターの完全ガイドも同じ契約に依存しており、これが「Wan 2.7モード」クエリで引用される理由の一部です。
自動ルーティングをオーバーライドすべき時とは？
デフォルトのヒューリスティックが意図を表現できない場合、または契約が保証しない決定論性が必要な場合は、Wan 2.7のルーティングをオーバーライドしてください。以下に示す4つのシナリオは、私たちが本番環境で遭遇したものです。
モデルバリアント間のA/Bテスト。 wan2.7-t2vと将来のwan2.7-t2v-proを比較したい場合、モデル名を明示的に指定する必要があります。自動ルーティングは常にデフォルトのバリアントを選択するため、比較が無効になります。
再現可能なテストフィクスチャ。 ルーティングは決定論的ですが、デフォルトのターゲットモデルはSDKバージョン間で変更される可能性があります。テストスイートで明示的なモデル名を指定することで、サイレントアップグレードによるフィクスチャハッシュの破損を防ぎます。
ルーターが誤った選択をするエッジケース。 effectiveMode: textImage2videoをプレースホルダー画像とともに渡した場合、ルーターはI2Vを選択します。モデル名を明示的に渡すことでT2Vを強制し、画像をスキップします。
呼び出しごとのコスト上限。 一部のモデルバリアントは他のものよりも多くのクレジットを消費します。課金ロジックがどのバリアントが実行されたかを知る必要がある場合、ルーターが安価なものを選択することに頼ることはできません。モデル名を指定し、クライアント側でコストルールを適用してください。
引用カプセル: 開発者は、バリアント間のA/Bテスト、再現可能なテストフィクスチャ、決定論的なコスト上限、またはルーティングヒューリスティックが誤ったモデルを選択するエッジケースでの動作が必要な場合、明示的なモデル名を渡すことでWan 2.7の自動ルーティングをオーバーライドすべきです。出典：PixMind API統合テスト、2026年7月。
自動化と制御のトレードオフとは？
トレードオフは単純です。自動ルーティングは、テールケースを犠牲にして中央値を最適化します。使用状況が中央にある場合、よりクリーンなコードと無料のアップグレードが得られます。テールケースに該当する場合は、明示的な制御が必要です。
| 側面 | 自動ルーティング | 明示的なモデル名 |
|---|---|---|
| 統合コードサイズ | 小さい | 大きい |
| 前方互換性 | 自動 | 手動アップグレードが必要 |
| デバッグのしやすさ | 暗黙的（ルーティングされたモデルを検査） | 明示的（呼び出し元が知っている） |
| A/Bテスト | 不可能 | 可能 |
| コスト予測可能性 | デフォルトバリアントに依存 | 呼び出し元が制御 |
| テストの決定論性 | バージョン内で決定論的 | バージョン間で決定論的 |
[オリジナルデータ] 2週間にわたって記録した47件の本番呼び出しのサンプルでは、41件がルーターのデフォルト選択と一致し、4件がA/Bテストのためにオーバーライドを必要とし、2件がデフォルトのI2Vバリアントの一時的な問題を回避するためにオーバーライドを必要としました。これは87パーセントのデフォルトヒット率であり、自動ルーティングが一般的なパスからボイラープレートを排除しつつ、稀なパスを妨げなかったことを意味します。
正直なところ、自動ルーティングをデフォルトとし、理由がある場合にのみオーバーライドすることをお勧めします。あらゆる場所でモデル名を指定することはより安全に感じるかもしれませんが、それは手動アップグレードに縛り付け、時間の経過とともに統合を静かに腐敗させます。
良い妥協点としては、アプリケーションコードでは自動ルーティングを使用し、テストフィクスチャではモデル名を指定することです。これにより、ユーザーの前方互換性を維持しつつ、テストスイートの決定論性を保つことができます。
Wan 2.7モードルーティングに関するFAQ
Wan 2.7はT2VとI2Vをどのように区別しますか？
Wan 2.7は、effectiveModeがtextImage2videoでリクエストに画像がない場合にwan2.7-t2vにルーティングします。同じeffectiveModeが設定されていても画像配列が入力されている場合はwan2.7-i2vにルーティングします。このルールはAlibaba Cloud I2V APIリファレンスに記載されています。
Wan 2.7に特定のモデルを使用させることはできますか？
はい、できます。リクエストボディにwan2.7-t2vやwan2.7-i2v-proのような明示的なモデル名を渡してください。これにより、自動ルーティングは完全にバイパスされます。A/Bテスト、再現可能なフィクスチャ、またはルーティングヒューリスティックが誤ったターゲットを選択する場合に使用してください。
矛盾するeffectiveModeと入力を送信した場合、どうなりますか？
ルーターはまずeffectiveModeに従います。1つの画像でeffectiveMode: firstLastFrameを設定した場合、サイレントに最初のフレームI2Vにダウングレードするのではなく、呼び出しは拒否されます。参照メディアなしでeffectiveMode: referenceを設定した場合も、呼び出しはエラーになります。
混合参照入力を持つR2Vでも自動ルーティングは機能しますか？
はい、機能します。effectiveMode: referenceを設定すると、参照画像、参照クリップ、参照オーディオのいずれを渡してもwan2.7-r2vにルーティングされます。R2Vモデルは内部的にどの参照を重視するかを決定しますが、これはルーティングとは別の懸念事項です。
Wan 2.7のルーティングはSDKバージョン間で安定していますか？
4つのルーティングルールは2.7ライン全体で安定しています。ただし、各ルールのデフォルトターゲットモデルはマイナーバージョン間で変更される可能性があります。長期間にわたるテストフィクスチャの場合、サイレントなデフォルトの入れ替えによってスイートが破損しないように、モデル名を明示的に指定してください。
動作を見る
Xでの関連情報: poe_platform — PoeプラットフォームによるWan 2.7統合の発表。
