アプリやコーディングエージェントが渡す model 文字列を、AI Gateway 上の保存済み設定に束ねる仕組み。タスクごとにスラッグを切り、実モデルとルーティングを中央で更新する利用者向け。コードの再デプロイや各開発者のエージェント設定の手直しなしにモデル切替が可能。

#呼び出し ID

  • 識別子は vmc/<slug>。例: vmc/coding-agent、vmc/abc-123。
  • AI SDK では model: 'vmc/coding-agent'、Chat Completions / Responses / Messages では model フィールドに同じ文字列。ベース URL は https://ai-gateway.vercel.sh/v1（Messages は https://ai-gateway.vercel.sh）。
  • 埋め込み・画像・動画・TTS・STT・rerank・decision などカタログ上の各モダリティでも同じ slug を渡す。slug の背後モデルと API 種別が一致しないと 400。
  • Claude Code は /model に claude-code/vmc/<slug>、Codex は vmc/<slug> または ~/.codex/config.toml の model。vercel ai-gateway setup でエージェントを Gateway 経由にしたうえで slug を選ぶ。

#CLI での作成・更新

bash
vercel ai-gateway virtual-models create coding-agent \
  --model anthropic/claude-opus-5.5 \
  --config '{"speed":"fast","zeroDataRetention":true}'

vercel ai-gateway virtual-models edit coding-agent --model openai/gpt-6.1-sol
  • create / edit は --model、--provider-order、--provider-only、--display-name、--description と --config JSON を併用。同一キーはフラグが --config より優先。
  • --config で渡す主なキー: modelSlug、providerOrder、providerOnly、inferenceRegion（例 { "scope": "zone", "geoRegion": "eu" }）、models（モデルフォールバック配列）、speed（"fast"）、allowFallbackFromFast、sort、serviceTier、caching、providerTimeouts、has（必須能力）、zeroDataRetention、disallowPromptTraining、providerOptions、observabilityTags。
  • 一覧・詳細・削除・復元: virtual-models list、inspect、remove、restore。vercel ai-gateway models ls --virtual でカタログと併記。

#ルーティングとリクエスト上書き

Virtual Models 側で値を持つ項目はリクエストより優先。プロバイダ順（order）、プロバイダ限定（only）、モデルフォールバック（models）、fast モード、ソート、サービスティア、プロンプトキャッシュ、プロバイダタイムアウト、推論リージョン（システム資格情報の試行のみ）、必須能力（has）、観測タグは Virtual Models が設定していれば呼び出し側の同名オプションは無視。

  • providerOptions はキー単位でマージ。Virtual Models が anthropic.effort を置いていればその値が残り、未設定キーだけリクエストから入る。
  • コンプライアンス（ZDR・プロンプト学習拒否）はどちらかが on なら on。どちらも off に戻せない。
  • Virtual Models が未設定の sort / serviceTier / caching / providerTimeouts はリクエストまたはシステム既定。Virtual Models が "@default" を指定すると呼び出し側の値を捨ててシステム既定に固定。
  • チームのモデル許可リスト・プロバイダ許可リスト・ルーティングルール・チーム全体 ZDR・予算は Virtual Models 経由でもそのまま適用。許可リスト外の背後モデルは slug 経由でも拒否。

#運用

  • 作成後の slug 変更不可。設定変更・アーカイブ・復元は新規リクエストに数分以内で反映。アーカイブ中の slug は 404。
  • 本番切替前は vmc/coding-agent-candidate など別 slug で候補モデルを向け、評価後に本番 slug の --model を更新する流れを推奨。
  • チーム全員が Virtual Models を呼び出し可能。作成・編集・アーカイブは作成者か Owner（Member は作成可、編集は作成者か Owner）。

#参考文献