venice-text-routing

Venice テキストモデルのルーティング

このスキルは、「どの Venice テキストモデルを呼び出すか」という判断ロジックを定めます。venice-chat（呼び出しインターフェース）の上位に位置するルーティング層であり、venice-models（モデル検索 API）を利用します。

主な用途：ローカルエージェントがプロンプトを受け取り、ローカルモデルで対応できるかを判断し、対応できない場合は、プライバシー／モダリティ／機能要件を満たす Venice モデルのうち、最も安価なものを選びます。

スナップショットの鮮度

以下のマトリクスを適用する前に、snapshots/text-routing.json を読み込んでください。ファイルが存在しない場合、または snapshot_date が30日より古い場合は、python scripts/refresh_routing.py を実行して GET /models?type=text と GET /models/traits?type=text から再生成してください。それ以外の場合はキャッシュされたファイルを信頼し、ルーティングの判断ごとに /models を呼び出さないでください。

refresh_routing.py は snapshots/text-routing.json と routing-matrix.md の両方を書き換えます。どちらのエンドポイントも公開されているため、キーは不要です。VENICE_API_KEY／--api-key は任意で指定でき、そのキーに合わせて結果を調整します（modelPrivacy に制限のあるキーでは、フィルタリングされたカタログが表示されます）。初回インストール時に一度実行し、その後は約1か月ごとに実行してください（CI で毎晩実行するのでもかまいません）。

スナップショットでは、各モデルの privacy ラベルは、supportsE2EE が true の場合は e2ee、supportsTeeAttestation のみが true の場合は tee、それ以外の場合はモデル自身の private／anonymized の値になります（/models ではすべての TEE／E2EE モデルが private であるため、tee と e2ee もプライベートとして扱ってください）。tier は入力価格のみで分類されます。beta_access は model_spec.beta を反映します（ベータアクセス可能なキーにのみ表示されるため、同梱されたキーなしのスナップショットでは常に false です）。beta_status は model_spec.betaModel を反映します（呼び出し可能ですが、変更または削除される可能性があります）。

各モデルについて、スナップショットに含まれるのは、マトリクスに示された13個の機能フラグ、max_images、available_context_tokens、max_completion_tokens、100万トークンあたりの入力／出力価格、beta_access、beta_status、offline、region_restrictions、deprecation_date のみです。それ以外の情報が必要なフィルター（uncensored、supportsLogProbs、reasoningEffortOptions、maxVideos、cache_input／extended の価格、replacementModelId）では、GET /models?type=text を読み込む必要があります。

このスキルを読み込むタイミング

• 実行時に、プロンプトに応じて Venice のテキストモデルを選ぶ場合。
• 難しいプロンプトへの対応時に Venice へエスカレーションする、ローカルファーストのエージェントを構築する場合。
• プライバシー層（anonymized、private、TEE、E2EE）を判断する場合。
• trait によるショートカット（default_reasoning、most_intelligent など）と、手動でフィルタリングした候補から選ぶ場合。

チャット呼び出しインターフェースについては、venice-chat を参照してください。すべてのモデルフィールドを取得するには、venice-models を参照してください。

プライバシー階層

リクエストを満たす範囲で、最も制限の少ない階層を選んでください。制限の強い階層ほど候補が絞られ、コストも高くなることがよくあります。

model_spec.privacy の値は private と anonymized の2つだけです。TEE と E2EE は private に追加される機能フラグです。

階層	セレクター（GET /models）	保証内容	使用するケース
匿名化	privacy: "anonymized"	Venice は上流プロバイダーに対してお客様の身元を隠しますが、プロバイダーにはプロンプトが見える可能性があります	機密性の低いワークロード。いくつかのクローズドな最先端モデル（Claude、GPT、Gemini）を利用できる唯一の方法です。
プライベート	privacy: "private"	契約によって保証されたゼロデータ保持です。コンテンツは推論のためだけに処理され、保持されません	ユーザーデータ、ビジネスロジック、および公開チャットボットには入力しない情報のデフォルトとして使用します。
TEE	capabilities.supportsTeeAttestation: true	ハードウェアの Trusted Execution Environment 内で実行され、リモートアテステーションが利用できます（GET /api/v1/tee/attestation）	規制対象データ、検証可能な推論や署名付き推論に使用します。
E2EE	capabilities.supportsE2EE: true	TEE に加え、クライアント側で暗号化します（ECDH secp256k1 → HKDF-SHA256 → AES-256-GCM）。Venice が中継するのは暗号文のみです	最も強力な保護です。医療、法律、秘密情報に使用します。E2EE フローは venice-chat が必要です。

現在、掲載されている TEE モデルはすべて E2EE にも対応しており、e2ee-* ID（例：e2ee-glm-5-3-p、e2ee-kimi-k3-p、e2ee-qwen3-8-27b）を使用します。TEE と E2EE は同じモデル ID を使用します。E2EE には E2EE ヘッダーを送信し、TEE のみの場合はヘッダーを省略するか、venice_parameters.enable_e2ee: false を設定してください。従来の tee-* ID は e2ee-* モデルの非掲載エイリアスです。プレフィックスで振り分けず、機能フラグを使用してください。

E2EE のトレードオフ：E2EE リクエストでは、Venice はウェブ検索、スクレイピング、キャラクター、Venice のシステムプロンプトを挿入せず、file パーツは 400 を返します。また、E2EE ガイドでは stream: true が必須とされ、関数呼び出しは非対応と記載されています（supportsFunctionCalling が示すのはモデルの機能であり、E2EE モードの機能ではありません）。一部の E2EE モデルには小さな上限もあります（例：e2ee-qwen-2-5-7b はコンテキストが32K、出力トークンが4,096）。E2EE は /responses ではサポートされません。TEE のみの場合はサポートされます（enable_e2ee: false を指定）。

API キーには modelPrivacy 制限を設定できます。PRIVATE_TEXT（テキスト、埋め込み、判定モデルはプライベート、TEE、または E2EE である必要があります）または PRIVATE_ONLY（すべてのモデルが対象）です。このようなキーの /models リストはすでにフィルタリングされており、許可されていないモデルは 403 を返します。そのようなキーでは privacy: "private" で絞り込んでください。

出典：docs.venice.ai/overview/privacy、docs.venice.ai/guides/features/tee-e2ee-models。

TEE クレームの検証

推論が本当にエンクレーブ内で実行されたことを確認するためのエンドポイントが 2 つあります。どちらも GET で、意図的に認証不要です（アテステーションの証拠は、認証情報を持たない第三者でも検証できる必要があるためです）。また、IP ごとに 1 分あたり 10 リクエストにレート制限されており、それを超えると 429 が返されます。どちらも公開済みの OpenAPI 仕様には含まれないパスですが、実際に利用可能であり、GET /models の supportsTeeAttestation 機能説明に記載されています。

エンドポイント	クエリ	返される内容
GET /api/v1/tee/attestation	model（必須）、nonce（任意、64 桁の 16 進数／32 バイト。アテステーションをチャレンジに紐付けます）	アテステーションレポート、TEE プロバイダー、検証結果、署名鍵／アドレス。
GET /api/v1/tee/signature	model と request_id（必須）、signing_algo（任意の ecdsa | ecdsa-p256 | rsa）	特定のリクエストに対するプロバイダーの署名と、リクエスト／レスポンスのハッシュ。

モデルが存在するものの TEE アテステーションを受けていない場合、どちらのエンドポイントも 400 を返します。モデル ID が不明な場合は 404 を返します。検証に失敗すると、アテステーションエンドポイントは verified: false とともに 502 を返します。TEE プロバイダーが利用できない場合は、どちらのエンドポイントも 502 を返します。TEE モデルからのチャットレスポンスには、X-Venice-TEE: true と X-Venice-TEE-Provider が含まれます。

信頼の連鎖は、次の順序で検証してください。アテステーションを取得して署名公開鍵とハードウェアの種類を確認し、復元された署名者がアテステーションの署名アドレスと一致することを確認してから、署名エンドポイントが返した署名対象のテキストそのものに対する署名を検証します。リクエストとレスポンスのハッシュは、文書化された正規形式から自分で再計算できない限り、プロバイダーが報告した値として扱ってください。

機能フィルター

プロンプトの要件 → model_spec フィールド（全一覧は venice-models の model_spec.capabilities セクションを参照）。対応するフラグを持たないモデルに画像／音声／動画パーツ、tools／tool_choice、text 以外の response_format、または logprobs を送信すると、推論の前に 400 が返されます。一方、一部の機能（例：enable_x_search）は無視されるだけです。

要件	フィルター	注記
ビジョン（単一画像）	capabilities.supportsVision	単一画像モデルでは、画像を含むメッセージのうち最後のものの画像だけが保持されます。
ビジョン（複数画像）	supportsVision && supportsMultipleImages	capabilities.maxImages を遵守してください。上限はメッセージあたり10画像です。
音声入力	capabilities.supportsAudioInput	Base64 のみ対応しています。URL は受け付けられません。
動画入力	capabilities.supportsVideoInput	data:video/... URL、リダイレクトのない一般公開 URL、一部モデルでは YouTube リンクに対応しています。リクエストあたり最大3本の動画です。
ドキュメント（PDF、DOCX など）	—	ドキュメントの file パーツはサーバー側でテキストに抽出されるため、任意のテキストモデルで使用できます（E2EE では不可）。file パーツとして送信された画像ファイルは画像として扱われ、ビジョン機能が必要です。
推論	capabilities.supportsReasoning	推論の強度を調整するには、supportsReasoningEffort も必要です。また、reasoningEffortOptions の値を選択してください（デフォルト：defaultReasoningEffort）。
ツール／関数呼び出し	capabilities.supportsFunctionCalling	エージェントループには必須です。
コード中心のタスク	capabilities.optimizedForCode	GET /models?type=code は、このサブセットのみを返します。
Web 検索（Venice）	—	すべてのテキストモデルで supportsWebSearch は true です。venice_parameters.enable_web_search で切り替えます。
X／Twitter 検索	capabilities.supportsXSearch	xAI ネイティブ（Grok モデル）。検索1回あたり約$0.01です。
構造化 JSON 出力	capabilities.supportsResponseSchema	response_format: {type: "json_schema", json_schema: {name, schema, strict}}。
大きなコンテキスト	availableContextTokens >= N	prompt_cache_key と組み合わせ、pricing.cache_input を持つモデルを優先してください。入力トークン数が context_token_threshold を超えると価格が上がる pricing.extended に注意してください。
長い出力	maxCompletionTokens >= N	上限が適用されているモデルでは、これを超えるリクエストは拒否されます。
コンテンツフィルタリングを最小限にする	model_spec.uncensored: true	Venice が無検閲と分類したモデルにのみ存在します。上流プロバイダーでフィルタリングされる場合があります。
Logprobs	capabilities.supportsLogProbs	主に評価／サンプリングのデバッグ向けです。

コスト階層

これらの区分はこのスキル独自の規約（refresh_routing.py が使用する境界と同じ）であり、model_spec.pricing.input.usd の100万トークンあたりの価格を基準にしています。上限は含まれません（ちょうど$1.00のモデルはMに分類されます）。スナップショットの tier_boundaries_usd_per_1m_input には、各区分の含まれない上限が示されています。フィルターを満たすモデルがある中で、最も低い区分を選んでください。

階層	入力100万トークンあたりの価格	用途
XS	< $0.20	分類、意図抽出、簡単な要約。
S	$0.20 – < $1	一般的なチャット、基本的なエージェント、軽量なビジョン。
M	$1 – < $4	中程度の推論、高度なコード処理、複数画像のビジョン。
L	$4 – < $10	高度な推論、複雑なツール利用。
Frontier	≥ $10	最も高価なクローズドモデル（例：2026-10-02時点の claude-fable-5、openai-gpt-6-astra、openai-gpt-54-pro）。

出力価格は同じ区分内でも大きく異なる（入力価格の約1.5倍から約10倍）ため、同額の場合は出力価格で比較してください。モデルごとの正式な価格は model_spec.pricing に記載されています（入力と出力の料金はスナップショット内の pricing_per_1m にも複製されています）。この文章にある金額をハードコードしないでください。

ルーティングの決定木

上から順に確認し、最初に該当するルールで停止します。

1. Local-first check
   - Prompt is ≤ ~500 tokens, no special-capability requirement,
     no privacy escalation, no tool calls expected
     → handle on the local model. Do not call Venice.

2. Privacy gate
   - User flagged "private" OR prompt contains regulated data (PHI, secrets, legal),
     OR the API key has modelPrivacy PRIVATE_TEXT / PRIVATE_ONLY:
       require model_spec.privacy === "private"   (includes every TEE/E2EE model;
       in the snapshot accept privacy "private", "tee" or "e2ee").
   - User flagged "E2EE" / "must be encrypted end to end":
       require capabilities.supportsE2EE. Use /chat/completions only.
   - User flagged "TEE" / "verifiable inference":
       require capabilities.supportsTeeAttestation.
   - Otherwise: any tier acceptable (still prefer "private" when otherwise tied).

3. Modality gate
   - Image input present  → require supportsVision (+ supportsMultipleImages if > 1).
   - Audio input present  → require supportsAudioInput.
   - Video input present  → require supportsVideoInput.

4. Capability gate
   - Tool calls expected               → require supportsFunctionCalling.
   - Code-heavy task                   → prefer optimizedForCode (or call /models?type=code).
   - Chain-of-thought / planning / hard math
                                       → require supportsReasoning;
                                         prefer supportsReasoningEffort to dial reasoning effort.
   - Structured JSON output required   → require supportsResponseSchema.
   - X/Twitter content needed          → require supportsXSearch.
   - Refusal-free / minimal filtering  → prefer model_spec.uncensored (or trait most_uncensored).

5. Context size gate
   - Estimated prompt tokens > availableContextTokens, or expected output > maxCompletionTokens
     → bump up to a model with sufficient limits. Prefer ones with cache_input pricing.

6. Frontier override
   - User asked for "best", "frontier", "most intelligent", "smartest"
     → resolve trait `most_intelligent` from the snapshot. Skip cost-min step.

7. Cost minimization
   - From surviving candidates, pick the smallest cost tier (XS → S → M → L → Frontier).
     Tie-break by lower output $/1M, then lower input $/1M.

8. Sanity filters (apply throughout)
   - Drop model_spec.beta === true (snapshot: beta_access) unless your key has
     beta access (such models are only listed to beta-access keys anyway).
     betaModel === true (snapshot: beta_status) marks callable beta-status
     models that may change or disappear; don't drop them, prefer non-beta when tied.
   - Drop model_spec.offline === true.
   - Drop candidates whose model_spec.regionRestrictions lists the caller's country (403 otherwise).
   - Prefer models without model_spec.deprecation.

Trait のショートカット

プロンプトが名前付き Trait に明確に対応する場合は、マトリックスをスキップし、スナップショットの traits ブロック（GET /models/traits?type=text から取得）で Trait を解決します。Trait 名は、リクエストの model 値として直接指定することもできます。

Trait	用途	解決先（2026-10-02）
default	一般的なチャット／汎用。	zai-org-glm-5-2
function_calling_default	エージェントのループ、ツールの使用。	zai-org-glm-5-2
default_reasoning	モデルを指定せずに「段階的に考えて」と指示する場合。	kimi-k3
default_code	コード生成／リファクタリング／レビュー。	deepseek-v4-pro-0813
default_vision	特別な要件のない画像入力。	qwen-3-8-27b
most_intelligent	「利用可能な中で最高」、最先端モデルへの切り替え。	grok-4-7
most_uncensored	最小限のフィルタリング／レッドチーム／創作。	venice-uncensored-1-2

マッピングは時間とともに変わるため、必ずスナップショットまたはエンドポイントから読み取ってください。エンドポイントが返すキーのみが存在します（現在、fastest Trait はありません）。セッション開始時に解決済みの Trait → ID マップをキャッシュし（HTTP 呼び出しは 1 回）、再利用してください。

ローカル優先パターン

ローカルエージェントが Venice を「エスカレーション用バックエンド」として利用する場合：

1. プロンプトを低コストでスコアリングする（ローカルで）：

   • プロンプトと予想出力のトークン数。
   • モダリティのシグナル（画像／音声／動画のパーツがあるか）。
   • キーワードのシグナル：「code」、「reason」、「step by step」、「private」、「secret」、「encrypt」、「best」、「frontier」。
   • ユーザー指定のオーバーライド（例：--model frontier、--privacy e2ee）。

2. ローカルか Venice かを決定する：

   • 推定トークン数がローカルモデルの快適に処理できるコンテキスト長以下で、機能またはプライバシーのエスカレーションも不要な場合 → ローカルで処理を続けます。
   • それ以外の場合 → ステップ 3 に進みます。

3. 上記の判断ツリーを実行して Venice のモデルを選びます。

4. venice-chat 経由で呼び出します：

   curl https://api.venice.ai/api/v1/chat/completions \
     -H "Authorization: Bearer $VENICE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "<chosen id>",
       "messages": [...],
       "venice_parameters": {"include_venice_system_prompt": false}
     }'
   

5. 影響範囲を制限する：送信前に、選択したモデルと推定コストを記録します。ユーザーの --max-cost 上限を超えるエスカレーションは拒否してください。レスポンスに cost フィールドがある場合、実際に課金された金額が示されます。

例

例 1 — ローカル優先が有効

プロンプト：「このメールを 1 文で要約してください：…」（約 200 トークン）

• ステップ 1 → ローカルで処理できます。Venice を呼び出さないでください。

例 2 — プライバシーと推論

プロンプト：「顧客の解約データセット（PII）です。解約を促す要因について推論してください。」

• ステップ 2 → プライバシーゲートにより privacy: "private" が必要です。
• ステップ 4 → 推論が必要 → supportsReasoning: true。
• ステップ 7 → 推論に対応するプライベートな候補の中から、最も安価なモデルを選びます。
• → プライベートな推論モデル、またはユーザーがアテステーションも求めている場合は、TEE 専用モードの e2ee-* モデル。

例 3 — 複数画像のビジョン

プロンプト：商品写真 3 枚 ＋「これらの製造品質を比較してください。」

• ステップ 3 → supportsVision && supportsMultipleImages && maxImages >= 3。
• ステップ 7 → 残った候補の中で最も安価なモデル、または traits.default_vision。

例 4 — 長文書に対する最先端の知能

プロンプト：「この 400 ページの契約書一式について、あなたの最高の見解を聞かせてください。」（約 200K トークン）

• ステップ 5 → availableContextTokens が約 200K を下回るモデルを、コンテキストゲートで除外します。
• ステップ 6 → 最先端モデルへの切り替え（most_intelligent）が適用されます。解決されたモデルが引き続きステップ 5 の条件を満たすことを確認してください。
• → traits.most_intelligent（スナップショットの内容によります。2026-10-02 時点では、コンテキスト長が 500K の grok-4-7）。
• pricing.extended でコストを見積もります。2026-10-02 時点では、入力が 200,000 トークンを超えると grok-4-7 の料金はおよそ 2 倍になるため、約 200K のプロンプトでも閾値を超える可能性があります。

例 5 — ツールを使うコードエージェント

プロンプト：「このリポジトリをリファクタリングしてください。シェルと編集ツールを利用できます。」

• ステップ 4 → supportsFunctionCalling && optimizedForCode。
• ステップ 7 → 残った候補の中で最も安価なモデル → ツールにも対応していれば traits.default_code、そうでなければ optimizedForCode で絞り込んだ traits.function_calling_default。

今後の拡張

構造化出力を優先するランタイム向けに、将来的に scripts/route.py CLI を追加する可能性があります（route.py --prompt '...' --max-cost 0.001 --need-vision → {"model_id": "...", "estimated_cost": ..., "tier": "..."}）。上記の文章による決定木が引き続き正式な情報源です。

必要に応じて、関連するルーティングスキル（venice-image-routing、venice-audio-routing、venice-video-routing）でもこの構成を踏襲できます。

注意点

• モデル ID をハードコードしないでください。 Venice ではモデルが頻繁に追加・廃止されるため、スナップショットに対して特性またはフィルターを使って解決してください。
• 古いスナップショットは、黙って誤った情報を返します。 最大経過日数は30日です。モデル ID で 404 が発生した場合は、それより早く更新してください。
• ID のプレフィックスでルーティングしないでください。 privacy、supportsTeeAttestation、supportsE2EE を使用してください。tee-* ID は非掲載のレガシーエイリアスです。
• プライバシーと無検閲は別のものです。 most_uncensored／model_spec.uncensored と privacy: "private" は、それぞれ独立した要素です。
• most_intelligent が最も高価なモデルとは限りません。 これは厳選された候補であり、中程度のコスト層に位置する場合があります。
• E2EE 対応モデルでは、E2EE ヘッダーが存在する場合、enable_e2ee はデフォルトで true です。 venice-chat を参照してください。ルーティングの判断ではモデルを選択し、チャットスキルがハンドシェイクを処理します。
• リージョン制限。 model_spec.regionRestrictions[]（制限対象モデルにのみ存在）には、リクエストが 403 になる対象国が記載されています。
• 特性キーは type によって異なります。 常に ?type=text を指定してください。画像の特性を使い回さないでください。

関連項目

• venice-models — /models、/models/traits、/models/compatibility_mapping（このスキルが利用する検出 API）。
• venice-chat — /chat/completions（このスキルがモデルを選択する呼び出し先）。
• venice-responses — /responses（E2EE 非対応）。
• venice-auth — Bearer 認証と x402 ウォレット認証。
• venice-api-keys — modelPrivacy キー制限。
• venice-billing — 実際の支出がルーティング時の見積もりと一致したことの確認（ADMIN キー）。
• venice-errors — ルーティングされたリクエストでの 402／403／422／429 の処理。
• モデルごとのスナップショット：snapshots/text-routing.json。
• モデルごとの人間が読みやすいマトリックス：routing-matrix.md。