model-management

モデル管理

モデルを変更するたびに、このワークフローに従ってください。実装は最小限に抑え、ユーザーが変更を明示的に承認しない限り、公開契約を維持してください。実際のリクエストでプロバイダーの動作を確認してください。

まずコンテキストを読み込む

1. リポジトリの AGENTS.md を読みます。
2. 現行のレジストリエントリー、ランタイム設定、ハンドラー、スキーマ、テストを読みます。Pollinations が現在提供している内容については、リポジトリを信頼できる情報源とします。
3. 該当するローカルの有効な計画があれば読みます。
   • temp/manage_inference.md
   • temp/manage_inferenceport.md
   • temp/manage_gpus.md
   • temp/manage_azure_limits.md
4. GitHub で、すでに作業を実装している、または作業と競合する可能性のあるオープンまたはマージ済みの PR を確認します。
5. プロバイダーの最新の公式ドキュメント、カタログ、料金、提供状況、クォータ、非推奨に関する告知を確認します。その後、対象のルートに対して正確にプローブします。ドキュメントよりも実際の応答を優先します。

temp の計画は、リポジトリの真実ではなく、無視対象の運用状態です。リンクされたワークツリーで作業していて計画が見つからない場合は、git worktree list でプライマリーチェックアウトを特定し、そこで計画を読みます。残高、価格、PR の状況、クォータ、候補の順位をこのスキルにコピーしてはいけません。

ルートまたはモデルを推奨する前に operating-policy.md を読みます。タスクに必要な他のリファレンスのみを読みます。

タスク	必須のリファレンス
コードの検索またはローカル実行	repository-and-local-testing.md
追加、更新、ルート変更、名前変更、削除	change-and-test-matrix.md
新しいモデル、プロバイダー、モデル ID、または価格	billing-verification.md

必須の確認ゲート

このゲートは、追跡対象のモデル変更を提案する場合にのみ適用します。読み取り専用の状況確認、すでに文書化された計画上の決定に対する承認、運用上の事実の訂正を、別の変更にすり替えてはいけません。一般的な「確認」は、提示した正確な契約に対する承認としてのみ扱います。

ユーザーがモデルのビジネス契約と推論契約の全容を確認するまで、モデルを編集してはいけません。ユーザーに値を調べさせるのではなく、まずコードとプロバイダーを確認してください。

モデルごとに完全な行を 1 行提示します。

フィールド	必須値
正式名称	変更後の公開モデル ID
エイリアス	互換性のあるすべてのエイリアス、または none
priceMultiplier	プロバイダーコストを反映した正確な倍率
paidOnly	購入済みパックの残高が必要かどうか
Pollinations GPU	Pollinations が本番ハードウェアを運用している場合のみ yes
レジストリプロバイダー	設定されているプライマリープロバイダー
プライマリールート	プロバイダー、デプロイメント／ホスト、正確な上流モデル ID
最善のフォールバック候補	プロバイダー、デプロイメント／ホスト、正確な上流モデル ID、および最も有力な実行可能な代替案である理由。または、検索したルートを添えて none found
Pollinations のフォールバック	use <candidate> または none。採用しない理由、または実行可能な候補がない理由も記載

次のように尋ねます。

確認してください。正式名称 X、エイリアス A/none、価格倍率 M、有料のみ yes/no、Pollinations GPU yes/no、レジストリプロバイダー P、プライマリールート R、最善のフォールバック候補 C/none found、Pollinations のフォールバック判断 use C/none。これらはすべて正しいですか？

値が不明、推測に基づく、矛盾している、またはルートによって異なる場合は UNKNOWN と記し、根拠を説明して、その値についての明確な判断を待ちます。一括承認が有効なのは、すべての行が完全な場合に限られます。

公開 API の変更には個別の確認が必要です

モデルの承認は、公開エンドポイント、メソッド、トランスポート、リクエストまたはレスポンスのスキーマ、ストリーミング動作、イベントプロトコルの追加、名称変更、削除、変更を許可するものではありません。具体的なユーザーまたは開発者の問題を解決するものでない限り、API サーフェスの変更を提案しないでください。

編集する前に、次の内容を提示してください。

• ユーザーまたは開発者の問題と、現在の公開契約。
• 提案するルート、メソッド、トランスポート、スキーマ、ストリーミング動作、イベントの詳細。
• 手順 4 の順序に従って特定した互換性の参照先。
• 変更が追加、動作変更、非推奨化、破壊的変更のいずれに当たるか、および影響を受けるクライアント。
• 移行、共存、削除の計画、または none。

次のように明記してください。This adds/changes the public API: ... そのうえで、その API 変更の内容を明示して承認を求めてください。問題、標準、または互換性への影響が不明確な場合は、編集しないでください。

シークレットには別途承認が必要です

モデルの承認は、認証情報の追加、ローテーション、同期、デプロイ、失効、その他の変更を許可するものではありません。AGENTS.md に記載されている正確な承認文言、実行順序、検証、ロールバックの規則に従ってください。ここでそのプロセスを重複して記載したり、緩和したりしないでください。

ワークフロー

1. 現在の状態を照合する

• エイリアスを正規のレジストリエントリに解決します。
• API キーにはモデル ID ではなくモデルカテゴリが保存されるため、名称変更でキーに触れることはありません。モデルのカテゴリが変わると、制限付きキーがアクセスできるモデルが変わります。その点を PR に明記してください。
• 各モダリティのレジストリと、現在の本番リビジョン以降に main にマージされたすべてのモデル変更を監査します。本番環境は main より遅れている場合があります。
• モデルまたはプロバイダーがレジストリに見つからない場合は、再追加する前に git log --all -- <path> と gh pr list --state merged --search <model> を確認します。意図的に削除された、追加後に取り消された、または置き換えられた可能性があります。
• 実行時に到達可能なすべてのルートと、設定されているフォールバックを追跡します。
• 設定されているプロバイダーと、観測されたリクエストを処理したプロバイダーを区別します。
• 予定している変更を、オープン中の PR と有効な計画項目と照合します。
• 本番環境での検証が済んだら、リリース済みの作業を有効な計画から削除します。完了済みのアーカイブは残さないでください。

2. 正確なルートを調査する

• リリース、モデルの識別情報、料金、リージョン、プレビュー状況、クォータ、レート制限、コンテキスト、入力、出力、ツール、キャッシュ、非推奨化については、プロバイダーまたはモデルの公式情報を使用してください。
• プロバイダー間で同一の正規モデルが重複しないようにしてください。
• ルート間の重要な違いを列挙してください。モデル名が同じでも、機能が同じとは限りません。
• Pollinations が使用する正確なデプロイとリクエスト形式を検証してください。
• 追加または変更のたびに、プロバイダーのカタログと公式ドキュメントを横断してウェブ検索を新たに実行し、実行可能なフォールバックルートを見つけてください。リポジトリ内のインテグレーションや、記憶している情報だけに頼らないでください。有力な候補はそれぞれ、最新の公式モデルページと料金情報で確認したうえで、正確なルートを検証してください。チェックポイントの識別情報、機能、パラメーター、形式、安全性／プライバシー、可用性、レイテンシー、価格、権限、課金を比較してください。最適な候補を推奨するか、none found と記載してください。プライマリルートが正常に動作している場合でも、フォールバックに関する判断を省略しないでください。
• プロバイダー管理のルーティング／フォールバックのデフォルトと制御方法を確認してください。識別情報、機能、価格、データレジデンシー、可観測性に関するトレードオフを報告してください。

Novita を直接調査する場合は、既存の認可済みキーを使用して、対応する モデルカタログ とアカウントクォータを使用してください。クォータの問い合わせでは modal=llm が必要です。productType=Public Endpoint と正確なモデルを quotaObject に指定し、RPM と TPM を別々に問い合わせたうえで、返された識別情報を確認してください。OpenAI 互換のベース URL は https://api.novita.ai/openai/v1 です。Chat Completionsを使用して、正確な上流モデルを検証してください。ストリーミングでは stream_options.include_usage を指定し、トラフィックをルーティングする前に、ローカルの Gen を通じて、最終使用量、キャッシュ／推論の課金、機能、バースト容量を確認してください。ゲートウェイが利用可能でも、直接アクセスや独立した容量があるとは限りません。Novita をバックエンドとする OpenRouter／Vercel のルートは、同じ上流プールを共有している場合があります。プロバイダーへの直接支払いと、ゲートウェイ経由のトラフィックへの課金は区別してください。対応する課金ソースについては、Economics の Novita コネクターガイドを使用してください。既存の公開契約とフォールバックの仕組みを維持してください。

3. 契約を確認する

必須の行を提示し、編集前に明示的な確認を得てください。機能やアクセスの変更が意図的なものであれば、その旨を明確に記載してください。

4. 必要最小限かつ完全な変更を実装する

• 公式の公開 ID には <publisher-slug>/<official-model-slug> を使用します。両方の要素を小文字にし、パブリッシャーのモデルファミリーとバージョンを維持して、パブリッシャーの公開スラッグがある場合はそれに従います。バージョンを決して創作、削除したり、明示せずに進めたりしないでください。
• publisher は人が読めるパブリッシャー名（OpenAI、Anthropic、xAI）であり、推論プロバイダーではありません。プロバイダーのデプロイ ID、大小文字、句読点、リビジョンサフィックスは、パブリッシャーの公開モデル ID ではなくルーティングの詳細である場合、内部に保持してください。
• 公開用の公式 ID に推論プロバイダーを決して含めないでください。プロバイダーをまたいで同じパブリッシャーモデルを一つの公開 ID にまとめ、レジストリの順序付きフォールバック関係を通じた自動ルーティングを宣言してください。
• 非公開のフォールバック用レジストリエントリーには <public-canonical-id>:<provider> という名前を付けます。公開レジストリキー、カタログ、リクエストのモデル、権限には公開 ID を使用します。フォールバック ID と優先順位は分けてください。これらの ID に :fallback、番号付きフォールバックサフィックス、優先順位ラベルを決して使用しないでください。
• OpenRouter の固定エンドポイントには、最初から意味のある修飾子を付けます。形式は <public-canonical-id>:<provider>:<route-qualifier> です。例：google/gemini-2.5-flash-lite:openrouter:vertex-global、google/gemini-2.5-flash-lite:openrouter:ai-studio。同じプロバイダーを通じた複数のデプロイは明確に区別してください。ラベルは小文字にし、優先順位や一時的なフォールバックの役割を決して含めないでください。順序を変更するときもフォールバックのレジストリ ID は維持します。固定バックエンドのないプロバイダー管理ルーティングでは、エンドポイント修飾子を創作しないでください。
• provider フィールドとルート設定を正とし、名前で上流エンドポイントを選択しないでください。フォールバック専用エントリーはエイリアスなしで非公開に保ち、カタログと直接のモデル選択から除外します。ルート固有のコストはサービング定義に設定し、呼び出し元にはリクエストされた公開モデルの価格を適用します。既存の共有フォールバック機構を使用してください。
• 公式 ID の名称変更中も、既存の resolved_model_requested、model_used、x-model-used、プロバイダー、試行ごとの、コミュニティ、キャッシュの各アトリビューションの意味を維持してください。記録される ID は、新しい表記（非公開のフォールバックレジストリ ID を含む）に変更できますが、プライマリ ID を実行 ID として強制しないでください。明示的なプライマリ実行 ID とそのアナリティクス／ヘッダーの仕様は #14543 まで保留です。影響を受けるコンシューマーと公開 API の変更は別途確認してください。x-model-used を暗黙に別用途へ転用したり、過去のイベントを書き換えたりしないでください。
• 内部ルートの命名では、既存のサフィックスを含め、公開用公式 ID 全体を維持してください。たとえば、google/gemini-2.5-flash-lite:search のルートは google/gemini-2.5-flash-lite:search:openrouter:ai-studio のようにできます。これらは命名例であり、設定済みルートを宣言するものではありません。ルートは明示的なレジストリキーで関連付けてください。プロバイダーやフォールバック関係を推測するために、コロンサフィックスを分割または削除しないでください。この例では、フォールバックでも検索を含め、公開モデルの動作を維持する必要があります。
• ユーザーが、同じパブリッシャーモデルのうち、価格が別設定または有料限定のものを意図的に選択する必要がある場合は、推論プロバイダーをスラッグに含めず、<public-canonical-id>:paid として公開してください。独自の価格、paidOnly の値、権限、エイリアスを持つ別個の公開契約として扱います。自動フォールバックルーティングに :paid を使用しないでください。
• 複数のエントリーが同じパブリッシャーモデルの操作やパラメータプリセットにすぎない場合は、そのモデルの ID に統合し、明示的なエンドポイントまたはリクエストフィールドで操作を選択してください。別の公式モデルを作成したり、エイリアスで動作を選択したりしないでください。
• 既存のハンドラー、トランスフォーム、プロバイダー設定、スキーマ、汎用フォールバック基盤を再利用してください。
• 各レスポンスでプロバイダーが報告する使用量（使用量ブロックや fal の x-fal-billable-units のような課金ヘッダー）に基づいて課金してください。リクエストからプロバイダーの計算式（丸め、最小値、参照ごとの単位、パラメータ乗数）を再構築しないでください。ルートから使用量が報告されない場合は、リクエストから使用量を算出し、プロバイダーの課金記録と照合してください。
• 明示的に承認されたフォールバック判断のみ実装してください。承認済みのペアには共有の汎用フォールバックシステムを使用し、モデル固有の再試行レイヤーや未承認のフォールバックを追加しないでください。
• 確認済みの新しい公開機能（上記の API 変更確認に従う）は、一つの実装を基盤として二つのサーフェスから公開してください。Pollinations ネイティブルートは /v1 の外部に、標準互換ルートは /v1 配下に配置します。
• 互換性の仕様は次の順で決定してください。（1）現行の公式 OpenAI API、（2）OpenAI に同等の仕様がない場合は、現在公開されている OpenRouter の仕様（ここではプロトコル設計の参考であり、推論プロバイダーのフォールバックではありません）、（3）どちらにも機能の仕様がない場合は、明示的に API 契約を決定するまで作業を停止します。確認した正確な参照先を文書化してください。
• /v1 は互換性のための名前空間として扱ってください。選択した標準のルート、トランスポート、リクエスト、レスポンス、ストリーミング、イベントの仕様に厳密に合わせ、プロバイダー固有のプロトコルはルートアダプターの背後に置きます。Pollinations 固有または上流プロバイダーのスキーマを /v1 配下に置かないでください。
• Pollinations ネイティブルートでも、選択した標準のスキーマを優先してください。意図的にネイティブ仕様と異なる場合は、独自の明示的な API 変更確認が必要です。
• 入力、出力、トランスポートに実質的な違いがある機能を、単に model を切り替えるだけで一つのエンドポイントにまとめないでください。共有する内部ハンドラー、認可、課金、オブザーバビリティの経路は再利用しつつ、異なる操作は分けてください。
• エイリアスは ID のみを担うものとして扱います。公式モデルに解決したら、動作におけるリクエストされたエイリアスは破棄してください。-high、-search、-reasoning、-1080p などのエイリアス表記からパラメータを推測しないでください。明示的なリクエストパラメータと公式モデルのデフォルトのみを適用します。旧動作を維持する必要がある場合は、別の公式モデルを残してください。
• 汎用ハンドラーにおける公式モデル ID には、解決済みのレジストリエントリーを使用してください。レスポンス、トラッキング、課金、ルーティングの動作に対するモデル ID のリストを、ハンドラーレベルで管理しないでください。
• 同じレジストリ全体の監査で見つかった、古い保存済みエイリアスはすべて、一つの D1 移行 PR で公式 ID に統一してください。古い ID を置き換え、無関係なフィールドと配列順序を保持し、旧 ID と新 ID のペアを重複排除し、冪等性を証明して、デプロイ後に監査対象の旧 ID 件数がすべて 0 であることを検証してください。
• すべての移行文を D1 のクエリごとの CPU 上限内に収めてください。エイリアスごとに一つの文を使い、CASE 内で instr() による事前絞り込みを行い、一致しない行に JSON 関数が実行されないようにします。本番規模（約 150k 件の apikey 行）では、テーブル全体への単一の JSON スキャンはエラー 7429 で失敗します。
• 現在の変更可能なエイリアスを使って、過去のアナリティクスを書き換えないでください。
• 変更した公開 ID を使用するすべてのコンシューマーを、同時に更新してください。
• 新しいバージョンやチェックポイントを含め、新しいモデルにエイリアスを設定しないでください。
• 削除するまでは、既存のエイリアスの参照先を維持してください。
• すべての旧エイリアスを、明示的な移行を通じて廃止してください。
• モデル名とエイリアスは shared/registry/ で管理してください。公開一覧には、重複する Markdown リストを維持するのではなく、稼働中のモデルカタログを使用してください。
• OpenRouter のレジストリコストには、クレジット購入手数料 5.5% を含めます。ゼロ以外の基本レートとコストバリアントのレートは、それぞれ baseRate * 1.055 として記述してください（例：perMillion(0.75) * 1.055）。検索、キャッシュストレージ、その他の課金対象の調整額（プロバイダーが報告する料金を含む）も反映してください。priceMultiplier は変更せず、手数料込みのコストから価格を算出します。これはプロバイダー全体に適用する変換ではなく、レジストリエントリーで宣言してください。手数料は一度だけ適用します。同じプロバイダーへのフォールバックでは手数料込みのレートを引き継げますが、手数料の加算または欠落が生じる異なるプロバイダーへのフォールバックでは、明示的なコストが必要です。
• モデルごと、または緊密に関連するモデルファミリーの変更ごとに PR を一つにしてください。
• 生成済みの APIDOCS.md は決して編集しないでください。ソーススキーマまたはルートを更新してください。

5. エンドツーエンドで検証する

• change-and-test-matrix.md の該当する行を実行します。
• 新しいモデルとプロバイダー/モデル ID の変更については、宣言されたモダリティのマトリックス全体と billing-verification.md を実行します。
• エイリアス、権限、エラー、キャッシュ、容量、/models メタデータをテストします。
• フォールバックが構成されている場合は、それを直接プローブし、強制フォールバックを通じて同じ適用可能な E2E マトリックスを実行します。これには機能、パラメーター、権限、キャッシュ動作、課金、プロバイダー帰属、エラー、および想定されるバーストが含まれます。フォールバックが承認されていない場合は、調査した候補と却下理由を記録します。
• すべてのメディアが、サポートされているリクエスト存続時間の予算内で完全に返されることを検証します。該当する場合は、永続メディアのチェックも含めます。
• 正確なエビデンスと不確実性を PR に記録します。

6. PR を開く

公開する前に:

• 変更したファイルをリポジトリのフォーマッターで整形します。
• 触れたすべてのサービスに対して、焦点を絞ったテストと型チェックを実行します。
• 完全な差分をレビューし、無関係な変更やデッドコードがないか確認します。
• 承認された契約、正確なプライマリ候補とフォールバック候補、フォールバック、価格ソース、ライブプローブ、E2E 結果、エビデンス、容量結果、制限事項、および非推奨/クォータのゲートを含めます。
• ライブ、レイテンシ、安全性、または製品に関する決定が未解決のままである場合は、PR をドラフトのままにします。

PR の説明には、影響を受ける各モデルについて、その公開モデル ID を使用したユーザーに表示される変更表を含める必要があります:

モデル	アクション	変更	変更前	変更後	有効
<public ID>	NEW / UPDATE / RETIRE	価格 / バランス / 機能 / 可用性	正確な以前の値	正確な値	本番環境へのデプロイまたは予定日と時刻

• 新しく利用可能になった公開モデル ID には NEW を、既存モデルの変更には UPDATE を、可用性からの削除には RETIRE を、モデルを削除する PR で使用します。レジストリは廃止日を保持しません。プロバイダーの期限は、影響を受けるルートにコードコメントとして記します。
• 廃止は、それが決定された時点でのみ告知します (他のプロバイダーがそのモデルを維持することはありません): Effective に将来の日付とタイムゾーン (例: 2026-11-02 00:00 UTC) を含む RETIRE 行を持つ表を含む PR をマージします。ニュースは、削除 PR がマージされるまでそれを予定として表示します。延期するには、新しい日付の新しい RETIRE 行をマージします。撤回するには、Effective として Cancelled を使用します。日付を早めることは避けてください。
• 変更のみを含めます。ベースおよび提案されたコード/カタログから値を読み取ります。PR タイトルから推測したり、欠落している値をでっち上げたりしないでください。
• 価格については、通貨、課金単位、および変更された各レート (たとえば、100万トークンあたりの入力/出力) を含めます。バランスアクセスについては、Quest + Paid または Paid only と記載します。機能については、追加または削除されたものを明記します。
• 新しいモデルの場合は、変更前に Unavailable を使用し、変更後に初期価格、バランスアクセス、および機能を含めます。廃止の場合は、Available → Retired を表示します。明示的に構成または承認された場合にのみ、代替を含めます。
• マージはデプロイではありません。予定日または検証済みのデプロイがわかっていない限り、On production deployment (not live yet) を使用します。該当する場合は、既存の通知とその notice_id をリンクします。
• ユーザーに表示される違いがないプロバイダーのみの変更の場合は、ステータス行を追加する代わりに、価格、バランスアクセス、機能、および可用性が変更されていないことを明記します。プロバイダーと検証のエビデンスは、サマリーの下に別途保持します。

完了ゲート

モデルの変更は、該当するすべての項目が満たされるまで完了ではありません。

• 設定されたモデル、エイリアス、プロバイダー、ルート、価格、アクセス、モダリティ、機能が、承認済みの契約と一致している。
• 宣言されたすべてのサーフェスについて、プロバイダーへの直接リクエストとローカル E2E リクエストが成功している。
• 最適なフォールバック候補と、使用するかどうかの判断が文書化されており、設定されたすべてのフォールバックについて、プロバイダーへの直接検証と強制フォールバック E2E 検証が成功している。
• 明示的に承認されていない限り、既存の機能が失われていない。
• すべてのゼロ以外の使用量フィールドの内訳が説明され、確定した料金で請求されている。ルートが使用量を報告する場合は、プロバイダーが報告した使用量に基づいている。
• 不正なリクエストや拒否されたリクエストに対して、不透明な 5xx レスポンスではなく、有用な 4xx レスポンスが返される。
• キャパシティとメディアのレイテンシーが、想定される本番環境の負荷に適合している。
• カタログの説明文が開発者向けで、タイトルを繰り返しておらず、提供元のロゴが正しく表示される。
• 別途明示的な確認を得ずに、公開 API のサーフェスを追加または変更していない。
• 未承認のシークレット変更やデプロイ変更を行っていない。
• PR に含まれるのは、このモデル、または密接に関連するモデルファミリーのみである。