#模型配置
本页面是 Pi 官方文档 的中文翻译。仅供学习参考。
本参考列出 models.json 的字段。示例见配置兼容端点，文件位置见配置。
在 models.json 中加入 "$schema": "https://pi.dev/schemas/models.schema.json"，以便编辑器校验和补全。
#Provider
providers 下的每个键是 Provider ID。内置 Provider ID 会修改该 Provider。其他 ID 会新增 Provider，并需要在 Provider 或模型级别提供 baseUrl 和 api。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | 显示名称。 | |
baseUrl | string | API 基础 URL。也作用于该 Provider 的内置模型。 | |
apiKey | string | 字面 Key、"$NAME" 环境变量插值，或 "!command" 的输出。 | |
api | string | 该 Provider 模型使用的 API，例如 "openai-completions"、"openai-responses"、"anthropic-messages" 或 "google-generative-ai"。 | |
oauth | "radius" | OAuth 登录流程。需要 baseUrl。 | |
headers | object | 请求头。值的解析方式与 apiKey 相同。 | |
compat | object | Provider 和模型的兼容性覆盖。 | |
authHeader | boolean | false | 是否把解析后的 API Key 作为 Authorization: Bearer 发送。 |
models | object[] | ||
modelOverrides | object |
#模型
每个 models 条目向该 Provider 添加一个模型。id 与已有模型相同的条目会替换它。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | string | 必填。发给 API 的模型 ID。 | |
name | string | 显示名称，也会被 --model 模式匹配。 | |
api | string | 覆盖 Provider 的 api。 | |
baseUrl | string | 覆盖 Provider 的 baseUrl。 | |
reasoning | boolean | false | 模型是否支持 thinking。 |
thinkingLevelMap | object | 每个 thinking 级别发给 Provider 的值。null 表示该级别不受支持。模型未映射的级别使用 Provider 的默认值，直到 high；xhigh 和 max 不受支持。 | |
input | ("text" | "image")[] | ["text"] | |
inputLimits | object | ||
cost | object | ||
cost.input | number | 必填。输入费用，美元 / 百万 Token。 | |
cost.output | number | 必填。输出费用，美元 / 百万 Token。 | |
cost.cacheRead | number | 必填。缓存读取费用，美元 / 百万 Token。 | |
cost.cacheWrite | number | 必填。缓存写入费用，美元 / 百万 Token。 | |
cost.tiers | object[] | 作用于整次请求的定价档。匹配的最高输入阈值应用于整次请求。 | |
cost.tiers[].inputTokensAbove | number | 必填。请求总输入超过该 Token 数时使用这一档。 | |
cost.tiers[].input | number | 必填。输入费用，美元 / 百万 Token。 | |
cost.tiers[].output | number | 必填。输出费用，美元 / 百万 Token。 | |
cost.tiers[].cacheRead | number | 必填。缓存读取费用，美元 / 百万 Token。 | |
cost.tiers[].cacheWrite | number | 必填。缓存写入费用，美元 / 百万 Token。 | |
promptCache | object | short 和 long 保留层级尽力而为的 Prompt 缓存时长（秒）。Pi 只预热已知时长的层级。 | |
contextWindow | number | 128000 | 上下文窗口，单位 Token。 |
maxTokens | number | 16384 | 最大输出 Token。 |
samplingParams | object | 合并进每次请求体的字段。只适用于 OpenAI 兼容 API。 | |
samplingParamsByThinkingLevel | object | 按 thinking 级别的 samplingParams，合并在 samplingParams 之上。 | |
headers | object | 请求头。值的解析方式与 apiKey 相同。 | |
compat | object | Provider 和模型的兼容性覆盖。 |
#模型覆盖
每个 modelOverrides 键是内置或扩展模型的 ID。未知 ID 会被忽略。cost 等对象字段与模型的对应值按字段合并；其他字段则替换它。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | 显示名称，也会被 --model 模式匹配。 | |
reasoning | boolean | 模型是否支持 thinking。 | |
thinkingLevelMap | object | 每个 thinking 级别发给 Provider 的值。null 表示该级别不受支持。模型未映射的级别使用 Provider 的默认值，直到 high；xhigh 和 max 不受支持。 | |
input | ("text" | "image")[] | ||
inputLimits | object | ||
cost | object | ||
cost.input | number | 输入费用，美元 / 百万 Token。 | |
cost.output | number | 输出费用，美元 / 百万 Token。 | |
cost.cacheRead | number | 缓存读取费用，美元 / 百万 Token。 | |
cost.cacheWrite | number | 缓存写入费用，美元 / 百万 Token。 | |
cost.tiers | object[] | 作用于整次请求的定价档。匹配的最高输入阈值应用于整次请求。 | |
cost.tiers[].inputTokensAbove | number | 必填。请求总输入超过该 Token 数时使用这一档。 | |
cost.tiers[].input | number | 必填。输入费用，美元 / 百万 Token。 | |
cost.tiers[].output | number | 必填。输出费用，美元 / 百万 Token。 | |
cost.tiers[].cacheRead | number | 必填。缓存读取费用，美元 / 百万 Token。 | |
cost.tiers[].cacheWrite | number | 必填。缓存写入费用，美元 / 百万 Token。 | |
promptCache | object | short 和 long 保留层级尽力而为的 Prompt 缓存时长（秒）。Pi 只预热已知时长的层级。 | |
contextWindow | number | 上下文窗口，单位 Token。 | |
maxTokens | number | 最大输出 Token。 | |
samplingParams | object | 合并进每次请求体的字段。只适用于 OpenAI 兼容 API。 | |
samplingParamsByThinkingLevel | object | 按 thinking 级别的 samplingParams，合并在 samplingParams 之上。 | |
headers | object | 请求头。值的解析方式与 apiKey 相同。 | |
compat | object | Provider 和模型的兼容性覆盖。 |
#输入限制
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxRequestBytes | integer | 序列化后的 Provider 请求的最大字节数。 | |
images | object | ||
images.resize | object | 新图片进入对话历史之前应用的、对缓存安全的缩放配置。 | |
images.resize.maxWidth | integer | ||
images.resize.maxHeight | integer | ||
images.resize.maxBytes | integer | base64 编码后载荷的最大字节数。 | |
images.resize.jpegQuality | integer | ||
images.maxPerMessage | integer | 一条 Provider 消息中接受的最大图片数。 | |
images.maxPerRequest | integer | 一次 Provider 请求中接受的最大图片数。 |
#兼容性
compat 描述与某个 API 标准请求和响应行为之间已验证的差异。模型值按字段覆盖 Provider 值。哪些字段生效取决于模型的 api。
#openai-completions
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supportsStore | boolean | Provider 是否支持 store 字段。默认：根据 URL 自动检测。 | |
supportsDeveloperRole | boolean | Provider 是否支持用 developer 角色代替 system。默认：根据 URL 自动检测。 | |
supportsReasoningEffort | boolean | Provider 是否支持 reasoning_effort。默认：根据 URL 自动检测。 | |
supportsUsageInStreaming | boolean | true | Provider 是否支持 stream_options.include_usage，以便在流式响应中获得 Token 用量。 |
supportsFinishReason | boolean | true | 流式响应是否包含 finish_reason。为 false 时，流结束时 Pi 推断为 stop 或 toolUse。 |
maxTokensField | "max_completion_tokens" | "max_tokens" | 用哪个字段表示最大 Token。默认：根据 URL 自动检测。 | |
requiresToolResultName | boolean | 工具结果是否需要 name 字段。默认：根据 URL 自动检测。 | |
requiresAssistantAfterToolResult | boolean | 工具结果之后的用户消息是否必须先有一条 assistant 消息。默认：根据 URL 自动检测。 | |
requiresNonNullAssistantContent | boolean | 重放的、没有文本的 assistant 消息（例如只有 tool call 的消息）是否必须发送 "" 而不是 null content。默认：false。 | |
requiresToolsWithToolHistory | boolean | 没有工具的请求在对话包含 tool call 或工具结果时，是否必须发送 "tools": []。某些放在 Anthropic 前面的代理需要它，例如旧版 LiteLLM。默认：false，该字段会被省略。 | |
requiresThinkingAsText | boolean | thinking 块是否必须转换成带 <thinking> 分隔符的文本块。默认：根据 URL 自动检测。 | |
requiresReasoningContentOnAssistantMessages | boolean | 启用推理时，所有重放的 assistant 消息是否必须包含空的 reasoning_content 字段。默认：根据 URL 自动检测。 | |
thinkingFormat | "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling" | 推理或 thinking 参数的格式。省略时，Pi 根据 Provider URL 自动检测。"openai" 使用 reasoning_effort；"openrouter" 使用 reasoning.effort；"deepseek" 使用 thinking.type，并在受支持时加上 reasoning_effort；"together" 使用 reasoning.enabled，并在受支持时加上 reasoning_effort；"baseten" 使用可配置的 chat_template_args，并在受支持时加上 reasoning_effort；"zai" 使用 thinking.type；"qwen" 使用顶层 enable_thinking；"qwen-chat-template" 使用 chat_template_kwargs.enable_thinking 和 preserve_thinking；"chat-template" 使用可配置的 chat_template_kwargs；"string-thinking" 使用顶层 thinking；"ant-ling" 只在映射后的 effort 非 null 时使用 reasoning.effort。 | |
chatTemplateKwargs | object | thinkingFormat 为 "chat-template" 时，作为 chat_template_kwargs 发送的参数。用 $var 配合 "thinking.enabled"、"thinking.effort" 或 "thinking.budget" 表示由 Pi 控制的值。 | |
chatTemplateArgs | object | thinkingFormat 为 "baseten" 时，作为 chat_template_args 发送的参数。用 $var 配合 "thinking.enabled"、"thinking.effort" 或 "thinking.budget" 表示由 Pi 控制的值。 | |
openRouterRouting | object | OpenRouter 的 Provider 路由偏好。控制 OpenRouter 把请求路由到哪些上游 Provider。作为 OpenRouter API 请求体中的 provider 字段发送。见 https://openrouter.ai/docs/guides/routing/provider-selection。 | |
vercelGatewayRouting | object | Vercel AI Gateway 的路由偏好。控制网关把请求路由到哪些上游 Provider。见 https://vercel.com/docs/ai-gateway/models-and-providers/provider-options。 | |
zaiToolStream | boolean | false | z.ai 是否支持顶层 tool_stream，用于流式传输 tool call 增量。 |
thinkingTokenBudgetField | "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens" | 用来根据 thinkingBudgets 限制推理 Token 的顶层请求字段。在这些端点上，推理和答案共享 max_tokens。"thinking_token_budget" 是 vLLM，"thinking_budget" 是 Qwen、DashScope 或 SGLang，"thinking_budget_tokens" 是 llama.cpp。默认关闭，生成的目录不会设置它。 | |
supportsThinkingTokenBudget | boolean | false | thinkingTokenBudgetField: "thinking_token_budget"（vLLM）的别名。优先使用 thinkingTokenBudgetField。 |
supportsOpenAIGrammarTools | boolean | false | Provider 是否支持带 Lark 或正则语法格式的 OpenAI 自定义工具。为 false 时，受语法约束的工具回退为普通函数工具。生成的目录会为有能力的模型开启它。 |
supportsMidConvoSystemMessages | boolean | false | 该具体模型是否接受对话开始后的 system 或 developer 消息。为 false 时，后续系统消息会折进开头的系统消息。生成的目录会为已验证的模型开启它。 |
supportsMidConvoToolAdditions | boolean | false | 系统消息是否可以在对话中途引入额外工具。需要 supportsMidConvoSystemMessages。生成的目录会为有能力的模型开启它。 |
supportsStrictMode | boolean | false | Provider 是否支持工具定义中的 strict 字段。生成的有能力模型会显式开启它。 |
cacheControlFormat | "anthropic" | Prompt 缓存的 cache control 约定。Anthropic 把 cache_control 标记应用到系统 Prompt、最后一个工具定义，以及最后一条 user、assistant 或 tool-result 文本内容。 | |
sendSessionAffinityHeaders | boolean | 是否发送来自 options.sessionId 的会话亲和数据。默认：OpenRouter 端点为 true，其他为 false。 | |
sessionAffinityFormat | "openai" | "openai-nosession" | "openrouter" | 会话亲和请求头格式。openai 发送 session_id、x-client-request-id 和 x-session-affinity；openai-nosession 发送 x-client-request-id 和 x-session-affinity；openrouter 发送 x-session-id。不影响 prompt_cache_key。默认：自动检测。 | |
promptCacheKeyMode | "auto" | "enabled" | "disabled" | 控制 prompt_cache_key 请求字段。auto 在发往 api.openai.com 时发送，或在 supportsLongCacheRetention 为 true 时随长缓存保留一起发送；enabled 在缓存激活时始终发送，供兼容代理使用；disabled 从不发送。默认：auto。 | |
supportsLongCacheRetention | boolean | Provider 是否支持长 Prompt 缓存保留（prompt_cache_retention: "24h"，或按格式使用 Anthropic 风格的 cache_control.ttl: "1h"）。默认：根据 Provider 和 URL 自动检测。 | |
vllmPriority | number | 作为顶层 priority 请求字段发送的 vLLM 调度优先级。值越低越早处理，服务器默认为 0。只在 --scheduling-policy priority 时有意义。默认关闭，生成的目录不会设置它。 |
#openai-responses
也适用于 azure-openai-responses 和 openai-codex-responses。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supportsDeveloperRole | boolean | true | Provider 是否支持用 developer 角色代替 system。 |
supportsMidConvoSystemMessages | boolean | false | 该具体模型是否接受对话开始后的 developer 或 system 消息。为 false 时，后续系统消息会折进开头的系统消息。生成的目录会为已验证的模型开启它。 |
sessionAffinityFormat | "openai" | "openai-nosession" | "openrouter" | 会话亲和请求头格式。openai 发送 session-id 和 x-client-request-id；openai-nosession 发送 x-client-request-id；openrouter 发送 x-session-id。不影响 prompt_cache_key。默认：自动检测。 | |
promptCacheKeyMode | "auto" | "enabled" | "disabled" | 控制 prompt_cache_key 请求字段。auto 和 enabled 在缓存激活时发送；disabled 从不发送，供会拒绝该字段的兼容代理使用。默认：auto。 | |
supportsLongCacheRetention | boolean | true | Provider 是否支持长 Prompt 缓存保留。GPT-5.6+ 使用 prompt_cache_options.ttl: "30m"，更早的模型使用 prompt_cache_retention: "24h"。 |
supportsStrictMode | boolean | Provider 是否支持严格 JSON schema 函数工具。默认值因 API 而异；生成的 OpenAI 模型会显式开启它。 | |
supportsOpenAIGrammarTools | boolean | false | 是否发出带 Lark 或正则语法格式的 OpenAI 自定义工具。为 false 时，受语法约束的工具回退为普通函数工具。生成的目录会为有能力的模型开启它。 |
supportsAdditionalTools | boolean | false | 模型是否支持锚定在消息上的 additional_tools 输入项。 |
supportsToolSearch | boolean | false | 模型是否支持由客户端执行的工具搜索，用于锚定在转录上的添加工具。 |
supportsExplicitPromptCacheMode | boolean | false | 模型是否接受 prompt_cache_options。较旧的 OpenAI 模型会拒绝该参数。 |
supportsMidConvoEffort | boolean | false | thinking 级别变化是否作为 configuration_update 输入项发送，而不是改变 reasoning.effort，从而使变化保留 Prompt 缓存。只用于 openai-responses API，在 openai Provider 上使用 Sign in with ChatGPT 时会被忽略。 |
supportsMaxOutputTokens | boolean | true | Provider 是否接受 max_output_tokens。有些 Codex 协议网关会拒绝它。 |
#anthropic-messages
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supportsEagerToolInputStreaming | boolean | true | Provider 是否接受按工具设置的 eager_input_streaming。为 false 时，Anthropic Provider 省略 tools[].eager_input_streaming，并为启用工具的请求发送旧的 fine-grained-tool-streaming-2025-05-14 beta 头。 |
supportsLongCacheRetention | boolean | true | Provider 是否通过 cache_control.ttl 支持 Anthropic 长缓存保留。 |
sendSessionAffinityHeaders | boolean | 启用缓存时，是否根据 options.sessionId 发送 x-session-affinity。Fireworks 等用会话亲和做 Prompt 缓存路由的 Provider 需要它；打到同一副本的请求能最大化缓存命中。默认：OpenRouter 端点为 true，其他为 false。 | |
sessionAffinityFormat | "openrouter" | 会话亲和格式。openrouter 发送 x-session-id；未设置时发送 x-session-affinity。 | |
supportsCacheControlOnTools | boolean | true | Provider 是否支持在工具定义上使用 Anthropic 风格的 cache_control 标记。为 false 时，工具参数中会省略 cache_control。有些 Anthropic 兼容 Provider（例如 Fireworks）不支持工具上的该字段，可能拒绝或忽略它。 |
supportsTemperature | boolean | true | 模型是否接受 Anthropic 的 temperature 请求字段。Claude Opus 4.7+ 会拒绝非默认值。 |
forceAdaptiveThinking | boolean | false | 是否强制自适应 thinking（thinking.type: adaptive 加上 output_config.effort），与模型 ID 无关。需要自适应 thinking 的内置模型会在生成的元数据中设置它。自定义 Anthropic 兼容 Provider 可以对任何上游要求自适应格式的模型把它设为 true。对被覆盖的内置模型设为 false 可以退出。 |
allowEmptySignature | boolean | false | 是否重放空的 thinking 签名，而不是把 thinking 转换成文本。 |
supportsStrictTools | boolean | false | Provider 是否支持 Anthropic 严格工具 schema。生成的 Anthropic 模型会显式开启它。 |
supportsMidConvoEffort | boolean | false | 该具体模型的传输是否支持只含 effort 的系统消息和 thinking 绑定控制。 |
supportsMidConvoSystemMessages | boolean | false | 该具体模型是否接受对话内部的 system 角色消息。为 false 时，后续系统消息会折进顶层系统 Prompt。 |
supportsMidConvoToolChanges | boolean | false | 该具体模型是否接受对话中途的 tool_addition 和 tool_removal 块。需要 supportsMidConvoSystemMessages。 |
supportsMessageThreads | boolean | 端点是否支持 Anthropic message threads：带 session id 的请求只发送新消息，并从上次回复继续。默认：baseUrl 在 api.anthropic.com 上时为 true，否则为 false。对会转发 thread 请求字段的网关设为 true。 | |
allowedFallbackModels | object[] | Anthropic 接受用于服务端拒绝回退的模型，以及返回的回退响应所用的本地定价元数据。缺省或为空时，调用方必须省略回退；对没有允许回退目标的模型，Anthropic 会拒绝该字段。 |
#bedrock-converse-stream
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supportsStrictMode | boolean | false | 模型是否支持 Bedrock 严格工具 schema。 |
#mistral-conversations
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supportsMidConvoSystemMessages | boolean | false | 该具体模型是否接受对话开始后的系统消息。为 false 时，后续系统消息会折进开头的系统消息。 |
#typesafe-system-one
也适用于 cloudflare-workers-ai-system-one。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
imageInput | "assets" | "images" | "state-image-urls" | 服务如何接收分类器图片。"assets" 发送 TypeSafe 的 assets 映射（PNG 和 JPEG），并从 state 引用这些图片，这是 TypeSafe 以及 Workers AI 上的 Jev 所期望的。"images" 发送 Clef 的 images 列表，内容是 data URL（PNG、JPEG 和 WebP，最多四张），这是 Workers AI 上的 Clef 所期望的。"state-image-urls" 把 image_url 部分放在 state 之前，这是 OpenRouter 所期望的；OpenRouter 会丢掉 assets 且不报错。根据 Provider、baseUrl 和模型 ID 自动检测。分类器模型从 Provider 级 compat 读取它；models 和 modelOverrides 条目只作用于聊天模型。 | |
sendImageOptInHeader | boolean | 带图片的请求是否发送 TypeSafe-Danger-Zone-Images: true 头。TypeSafe 自己的 API 对其实验性图片输入要求这个头。对 typesafe-system-one API 默认为 true，除非模型被检测为 OpenRouter。 |
法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。