venice-text-routing

Venice 文本模型路由

此技能封装了“该调用哪个 Venice 文本模型？”的决策逻辑——路由层位于 venice-chat（调用接口）之上，并使用 venice-models（发现 API）。

主要用例：本地 Agent 接收提示词，判断本地模型能否处理；如果不能，则选择满足隐私／模态／能力要求的最便宜 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 限制的密钥会看到经过筛选的目录）。首次安装时运行一次，之后约每月运行一次（也可以在 CI 中每晚运行）。

快照中，每个模型的 privacy 标签在 supportsE2EE 为 true 时为 e2ee，仅 supportsTeeAttestation 为 true 时为 tee，否则采用模型自身的 private / anonymized 值（在 /models 中，所有 TEE/E2EE 模型都是 private，因此也应将 tee 和 e2ee 视为 private）；tier 仅按输入价格分档；beta_access 对应 model_spec.beta（仅列出对 beta-access 密钥开放的模型，因此在随附的无密钥快照中始终为 false），beta_status 对应 model_spec.betaModel（可以调用，但可能会变化或消失）。

每个模型的快照仅包含：矩阵中显示的 13 项能力标志、max_images、available_context_tokens、max_completion_tokens、每 1M token 的输入／输出价格、beta_access、beta_status、offline、region_restrictions 和 deprecation_date。需要使用其他字段的筛选（uncensored、supportsLogProbs、reasoningEffortOptions、maxVideos、cache_input / extended 价格、replacementModelId），必须读取 GET /models?type=text。

何时加载此技能

• 在运行时根据提示词选择 Venice 文本模型。
• 构建本地优先的 Agent，为难处理的提示词升级到 Venice。
• 判断隐私级别（anonymized、private、TEE 或 E2EE）。
• 在特征快捷方式（default_reasoning、most_intelligent 等）与手动筛选候选项之间进行选择。

有关聊天调用接口本身，请参阅 venice-chat。有关所有模型字段的原始发现信息，请参阅 venice-models。

隐私等级阶梯

选择满足请求的限制最少的等级——限制越严格，可选模型范围越小，成本通常也越高。

model_spec.privacy 只有两个值：private 和 anonymized。TEE 和 E2EE 是在 private 基础上的功能标志。

等级	选择器（GET /models）	保障	适用场景
匿名化	privacy: "anonymized"	Venice 会向上游提供商隐藏你的身份，但提供商仍可能看到提示词	非敏感工作负载；也是使用若干闭源前沿模型（Claude、GPT、Gemini）的唯一途径。
私密	privacy: "private"	通过合同保证零数据保留：内容仅用于推理处理，不会保留	用户数据、业务逻辑，以及任何你不会粘贴到公开聊天机器人的内容的默认选择。
TEE	capabilities.supportsTeeAttestation: true	在硬件可信执行环境中运行，并支持远程证明（GET /api/v1/tee/attestation）	受监管数据、可验证／签名推理。
E2EE	capabilities.supportsE2EE: true	TEE + 客户端加密（ECDH secp256k1 → HKDF-SHA256 → AES-256-GCM）；Venice 仅转发密文	最高级别。适用于医疗、法律和机密信息。需要使用 venice-chat 中的 E2EE 流程。

目前，所有列出的 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-p：32K 上下文、4,096 个输出令牌）。/responses 不支持 E2EE，但支持仅使用 TEE（设置 enable_e2ee: false）。

API 密钥可以带有 modelPrivacy 限制：PRIVATE_TEXT（文本、嵌入和决策模型必须为 Private、TEE 或 E2EE）或 PRIVATE_ONLY（所有模型均须符合要求）。此类密钥的 /models 列表已经过筛选；不允许使用的模型会返回 403——对于此类密钥，请筛选 privacy: "private"。

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

验证 TEE 声明

有两个端点可供你检查推理是否确实在 enclave 内运行。两者都是 GET，特意不需要身份验证（任何一方都必须能够在没有凭据的情况下验证证明证据），并且有速率限制：每个 IP 每分钟 10 个请求（超出后返回 429）。两者都不是已发布 OpenAPI 规范中的路径；它们目前可用，且 GET /models 中的 supportsTeeAttestation 能力说明指向这两个端点。

端点	查询参数	返回内容
GET /api/v1/tee/attestation	model（必填）、nonce（可选，必须恰好为 64 个十六进制字符 / 32 字节，用于将证明绑定到你的质询）	证明报告、TEE 提供方、验证结果以及签名密钥/地址。
GET /api/v1/tee/signature	model 和 request_id（必填）、signing_algo（可选，ecdsa | ecdsa-p256 | rsa）	提供方针对特定请求生成的签名，以及请求/响应哈希。

如果模型存在但未通过 TEE 证明，两者都会返回 400；如果模型 ID 未知，则返回 404。如果验证失败，证明端点会返回 502（并带有 verified: false）；如果 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	Agent 循环必需。
代码密集型任务	capabilities.optimizedForCode	GET /models?type=code 仅返回此子集。
网页搜索（Venice）	—	每个文本模型的 supportsWebSearch 均为 true。使用 venice_parameters.enable_web_search 开关控制。
X／Twitter 搜索	capabilities.supportsXSearch	xAI 原生支持（Grok 模型）。每次搜索约 $0.01。
结构化 JSON 输出	capabilities.supportsResponseSchema	response_format: {type: "json_schema", json_schema: {name, schema, strict}}。
大上下文	availableContextTokens >= N	与 prompt_cache_key 搭配使用；优先选择具有 pricing.cache_input 的模型。留意 pricing.extended：输入令牌超过 context_token_threshold 后，价格会提高。
长输出	maxCompletionTokens >= N	对设有强制上限的模型，超过上限的请求会被拒绝。
最少内容过滤	model_spec.uncensored: true	仅 Venice 归类为不受审查的模型具有此字段；上游提供商仍可能进行过滤。
Logprobs	capabilities.supportsLogProbs	用途较窄——用于评估／采样调试。

成本档位

这些档位是此技能采用的约定（与 refresh_routing.py 使用相同的边界），依据 model_spec.pricing.input.usd 的每 1M 个令牌价格划分。上限不包含在档位内（价格恰好为 $1.00 的模型归入 M 档），快照中的 tier_boundaries_usd_per_1m_input 给出了各档位不包含在内的上限。选择能满足筛选条件的最小档位。

档位	每 1M 个输入令牌的价格	适用场景
XS	< $0.20	分类、意图提取、简单摘要。
S	$0.20 – < $1	通用聊天、基础 Agent、轻量级视觉任务。
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 区块中解析该 trait（数据来源为 GET /models/traits?type=text）。也可以直接将 trait 名称用作请求中的 model 值。

Trait	用途	解析为（2026-10-02）
default	通用聊天／兜底。	zai-org-glm-5-2
function_calling_default	Agent 循环、工具使用。	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 调用），并重复使用。

本地优先模式

对于由本地 Agent 驱动 Venice 作为“升级后端”的场景：

1. 以低成本评估提示词（在本地）：

   • 提示词与预期输出的 token 数。
   • 模态信号（是否包含图像／音频／视频部分）。
   • 关键词信号：“code”“reason”“step by step”“private”“secret”“encrypt”“best”“frontier”。
   • 用户提供的覆盖选项（例如 --model frontier、--privacy e2ee）。

2. 决定使用本地模型还是 Venice：

   • 如果估算 token 数 ≤ 本地模型的舒适上下文窗口，且无需升级能力或隐私级别 → 留在本地。
   • 否则 → 继续执行第 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 — 本地优先胜出

提示词：“用一句话总结这封邮件：……”（约 200 个 token）

• 第 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 个 token）

• 第 5 步 → 上下文门槛会剔除 availableContextTokens 低于约 200K 的模型。
• 第 6 步 → 触发前沿模型优先（most_intelligent）；确认解析出的模型仍通过第 5 步的筛选。
• → traits.most_intelligent（以快照记录为准；截至 2026-10-02，grok-4-7 的上下文长度为 500K）。
• 使用 pricing.extended 估算成本：截至 2026-10-02，grok-4-7 的输入超过 200,000 个 token 后，费率大致翻倍；约 200K 个 token 的提示词可能会超过此阈值。

示例 5 — 使用工具的代码 Agent

提示词：“重构这个代码库。你可以使用 shell 和 edit 工具。”

• 第 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。