跳转到主要内容
查询请求字段在 Chat Completions(/v1/chat/completions)、Responses(/v1/responses)和 Anthropic Messages(/v1/messages)上的类型、可接受的值和默认值。支持情况仍因模型和提供商而异:每个模型页面上的快速入门表格会显示其活跃提供商在每个端点上支持哪些参数。调优建议请参阅推理参数。

不支持的参数

如果处理请求的提供商不支持请求中的某个可选采样参数,Phaseo 会丢弃该参数:它不会被发送到上游,请求也不会被拒绝,因此总是发送 OpenAI 默认值的客户端可以继续正常工作。 Phaseo 按提供商逐一判断,先依据提供商配置,再依据该路由的目录参数。如果某条路由没有声明任何参数,只会跳过目录检查;提供商配置标记为不支持的参数仍会被丢弃,例如 Cohere 上的 top_k 或 Reflection 上的 stop。 在无法使用 OpenAI 12 小时缓存的路由上,12h 的提示缓存 ttl 也会被移除,并报告为 prompt_cache_options.ttl 或 prompt_cache_breakpoint.ttl;请参阅提示缓存。 成功的响应会列出请求正文中发送但被丢弃的参数:
  • 在 X-Phaseo-Dropped-Params 标头中,例如 X-Phaseo-Dropped-Params: top_k, min_p;
  • 当请求设置 meta: true 时,在 meta.routing.dropped_params 中,例如 [{"param": "top_k", "reason": "unsupported_by_provider"}]。
来自预设或默认值而非请求正文的参数,即使被丢弃也可能不会出现在这两个位置中。它仍会记录在与请求一起存储的路由诊断中。

选择模型

model

要运行的 Phaseo 模型 ID,例如 openai/gpt-6-astra。必填。请使用模型页面快速入门中显示的 ID;对于自动化和长期集成,这是最稳妥的选择。也可以在此处使用预设名称,例如 @support-triage。

models

回退模型,在 model 之后按顺序尝试。model 仍然是必填项,并且总是最先运行。只有当一次尝试以 429、500、502、503 或 504 失败时,才会尝试下一个条目。 类型 string[] · 条目 1 到 25 个;重复项以及与 model 相同的条目会被忽略 · 示例 ["anthropic/claude-sonnet-5.5", "google/gemini-4-argon"]
  • 每次尝试都作为独立的请求进行校验、记录和计费。响应的 model 字段和路由追踪会显示实际作答的模型。
  • 流式请求只在第一个字节之前回退;视频和音乐任务只在提交时回退。
  • 已附加的动态路由上的回退优先。预设可以作为条目。phaseo/auto 不能与 models 一起使用。
  • 批处理、实时和 council 请求会以 400 拒绝 models。
  • multipart 端点接受重复的 models 字段、models[] 字段或一个 JSON 数组。
请参阅请求级模型回退。

stream

在生成过程中通过服务器发送事件返回输出,而不是返回单个响应正文。 类型 boolean · 默认值 false 适用于聊天界面和较长的响应。如果你想要一个更易于重试和解析的 JSON 响应,请不要开启它。工具调用和结构化输出的流式传输方式可能因提供商而异。请参阅流式传输。

采样

temperature

token 选择的随机程度。较低的值会产生更保守、更可重复的输出;较高的值会带来更多变化,但一致性和对架构的遵循程度会降低。 类型 number · 范围 Chat Completions 和 Responses 上为 0–2,Messages 上为 0–1 · 默认值 提供商的默认值(未设置时 Phaseo 不发送任何值) 从 0.2–0.7 开始;对于提取、分类和 JSON,请使用较低的值。调整 temperature 或 top_p,不要同时调整两者。在高度量化的模型上使用较高的 temperature 可能导致输出不稳定。

top_p

核采样:模型从累积概率达到 top_p 的最小 token 集合中进行选择。较低的值会产生更窄、更集中的输出。 类型 number · 范围 0–1 · 默认值 提供商的默认值 0.9–1.0 搭配适中的 temperature 是一个合理的基线。

top_k

将每一步的采样限制在最可能的 k 个 token 中。较低的值会让输出更可预测。并非所有提供商都支持它。 类型 integer · 范围 Chat Completions 上为 -1 或更大,Messages 上为 0 或更大 · 默认值 提供商的默认值

min_p

通过丢弃低于最低概率阈值的 token 来缩小采样范围。 类型 number · 范围 0–1 · 默认值 提供商的默认值

frequency_penalty

按 token 已出现的频率成比例地进行惩罚。当模型陷入循环或重复短语时,请调高它。 类型 number · 范围 -2–2 · 默认值 提供商的默认值,通常为 0

presence_penalty

惩罚任何已经出现过的 token,从而促使模型转向新的话题和措辞。 类型 number · 范围 -2–2 · 默认值 提供商的默认值,通常为 0

repetition_penalty

提供商特定的防重复控制,与上面两种惩罚相互独立。它的具体效果因提供商而有较大差异。 类型 number · 范围 大于 0;提供商通常最多接受 2 · 默认值 提供商的默认值

logit_bias

让特定 token 更可能或更不可能出现。键是模型分词器的 token ID;值是要添加的偏置。 类型 object(token ID 到数字) · 默认值 未设置

seed

请求带种子的采样,用于调试和回归测试。在不同提供商之间或提供商基础设施变更后,不保证输出完全相同。 类型 integer · 默认值 未设置

输出长度和停止

max_tokens

限制 Chat Completions 上的输出 token 数,在 Messages 上为必填项。用它来控制费用和延迟;值太小会截断输出。 类型 integer · 范围 1 或更大(Messages 上为 0 或更大) · 默认值 Chat Completions 上为提供商的默认值

max_output_tokens

限制 Responses 上的输出 token 数。用途与 max_tokens 相同;请发送你的端点使用的名称。 类型 integer · 范围 1 或更大 · 默认值 提供商的默认值

max_completion_tokens

限制 Chat Completions 上的输出 token 数,是 OpenAI 对 max_tokens 的较新命名。不要在一个请求中混用两者。 类型 integer · 范围 1 或更大 · 默认值 提供商的默认值

stop

一个或多个结束生成的序列,例如模板结尾或协议标记。在 Messages 上,该字段为 stop_sequences,接受数组。 类型 string 或 string[] · 默认值 未设置

token 概率

logprobs

返回每个输出 token 的对数概率,用于评估、排序和置信度评分。 类型 boolean · 默认值 false

top_logprobs

返回每个位置上最可能的候选 token 及其对数概率。需要 logprobs: true。 类型 integer · 范围 0–20

工具

tools

模型可以调用的工具。除非端点参考另有说明,否则请使用 OpenAI 工具架构;Messages 使用 Anthropic 的工具架构。声明一个工具并不会强制模型调用它。 类型 array · 默认值 未设置

tool_choice

模型是否可以调用工具:none 表示只输出文本,auto 让模型自行决定,required 强制调用,或者使用一个指定某个工具的对象。 类型 string 或 object

parallel_tool_calls

允许在一个轮次中进行多次工具调用。当你的工具必须逐个运行时(例如它们的副作用有先后顺序),请将其设为 false。 类型 boolean · 默认值 提供商的默认值(未设置时 Phaseo 不发送任何值)

max_tool_calls

限制模型为该请求进行的工具调用次数。 类型 integer · 范围 1 或更大 · 默认值 未设置

结构化输出

response_format

要求输出纯文本、JSON 或符合某个 JSON 架构的内容。可接受的格式取决于端点和提供商。 类型 string 或 object · 默认值 端点和提供商的默认值

json_schema

输出必须符合的 JSON 架构,在 response_format 中设置({"type": "json_schema", "json_schema": {...}})。让架构保持精简并针对具体任务,可以获得更好的遵循效果。 类型 object

structured_outputs

不是请求字段。在模型页面上,它标记活跃提供商支持受架构约束输出的端点。请通过 response_format 请求这种输出。

推理

reasoning

在支持推理的模型上配置推理。 未设置的字段保持模型的默认值。更高的强度有助于解决难题,但会增加延迟和 token 消耗。

reasoning_effort

Chat Completions 上 reasoning.effort 的简写。 类型 string · 取值 none、instant、minimal、low、medium、high、xhigh、max · 默认值 模型的默认值

reasoning_tokens

不是请求字段。在模型页面上,它标记报告推理 token 或接受推理预算的路由。请使用 reasoning.max_tokens 设置预算。

include_reasoning

为兼容性在 Chat Completions 上接受,但不起作用:只要模型生成了推理内容和摘要,就会返回它们。推理输出可能很大,而且并非每个模型都会返回。要减少推理输出,请降低 reasoning.effort 或将 reasoning.enabled 设为 false。 类型 boolean

服务层级和提示缓存

service_tier

当模型和提供商支持时,在 Chat Completions、Responses 和 Messages 上选择速度和价格层级。Phaseo 会将每个值映射到提供商自己的控制项。 类型 string · 默认值 standard batch 不是层级,会被拒绝;请使用 Batch API。当官方 Anthropic SDK 指向 Phaseo 时,在 /v1/messages 上请优先使用 Anthropic 的 auto 和 standard_only;如需 ultrafast、priority、flex 或 fast,请使用原始 HTTP,或使用 Chat Completions 和 Responses。请参阅服务层级。

prompt_cache_key

让共享同一提示前缀的请求(例如代理循环的各个步骤)留在持有其缓存的提供商上。 类型 string · 默认值 未设置 · 端点 Chat Completions、Responses、Messages Phaseo 会将该键固定到处理第一个成功请求的提供商和路由(部署或区域),并让之后使用同一键的请求留在那里,直到该提供商失败、Phaseo 在其上的托管配额用完,或你的路由策略不再允许它。固定按工作区区分,持续时间与提供商的缓存保留时间相同。请参阅提供商亲和性。 Phaseo 向上游发送的是你的工作区 ID 和键的哈希值,绝不会发送原始键,因此两个选择相同键的工作区不会共享提供商缓存。响应会原样返回你发送的键。API 会拒绝该字段的提供商不会收到它,并且发送它永远不会将某个提供商排除在路由之外。没有键时,Phaseo 会根据请求推导亲和性,但对于长对话和代理会话,显式键的效果更好。

prompt_cache_options

OpenAI 和 Azure OpenAI GPT-5.6 及更高版本(包括 GPT-6 Astra)、DeepInfra 和 Moonshot AI 的提示缓存模式和有效期。 类型 object · 字段 mode(implicit 或 explicit)、ttl 使用 {"mode": "explicit", "ttl": "30m"} 可让 OpenAI 只缓存你设置的断点。路由无法接受的有效期(例如 Azure OpenAI 上的 12h,或没有 1 小时价格的 Moonshot AI 模型上的 1h)会被移除,并列在 X-Phaseo-Dropped-Params 中。其他所有提供商以及 GPT-5.6 之前的 OpenAI 模型都不会收到 prompt_cache_options;这些 OpenAI 模型使用 prompt_cache_retention。也接受 provider_options.openai.prompt_cache_options;以顶层值为准。

cache_control

在顶层时,设置 Claude 提示缓存策略。在内容块、工具定义或工具结果上时,标记一个缓存断点。 类型 object · 字段 type、ttl、scope 顶层。 在 Chat Completions、Responses 和 Messages 上接受。它适用于 Anthropic 上的 Claude、AWS 上的 Claude、Amazon Bedrock 和 Google Vertex AI:Phaseo 会根据 scope(all_text、last_user_message、agent 或 none)放置最多四个断点。其他提供商会忽略它。provider_options.anthropic.cache_control 是同一设置,两者同时发送时以它为准。 在块上。 Phaseo 会将断点发送给 Claude 路由、Alibaba Model Studio 和 Venice,为 OpenAI 和 Azure OpenAI GPT-5.6 及更高版本将其转换为 prompt_cache_breakpoint,并为其他提供商移除它。OpenAI 自己的 prompt_cache_breakpoint: {"mode": "explicit"} 也可以用在相同的块上,一个块同时有两者时以它为准。 使用 type: "ephemeral",并将 ttl 设为 5m(默认)或 1h。Anthropic 每个请求最多接受四个断点;当你标记了更多断点时,Phaseo 会保留第一个和最后三个。请参阅提示缓存。

prompt_cache_retention

GPT-5.6 之前的 OpenAI 和 Azure OpenAI 模型上的提示缓存保留时间。 类型 string · 取值 in_memory、24h Phaseo 只会将它发送给这些模型,并且只有 OpenAI 列出的模型接受 24h。GPT-5.6 及更高版本使用 prompt_cache_options.ttl,其他提供商不会收到该字段。也接受 provider_options.openai.prompt_cache_retention;以顶层值为准。

路由和提供商设置

provider

限制哪些提供商可以处理请求以及它们的排序方式。routing 可作为别名使用。请参阅路由与回退。 quantizations 匹配时忽略大小写、空格、连字符和下划线,并将无歧义的名称视为别名,例如 float8 与 FP8,或 bfloat16 与 BF16。只要设置了此筛选条件,没有量化数据的 offer 就会被排除。如果没有匹配的 offer,请求会失败,并返回一个列出所请求和可用量化方式的错误,而不会路由到其他变体。

provider_options

Phaseo 透传的提供商原生设置,按提供商分键,而请求的其余部分仍使用通用架构。 类型 object google.cached_content 指定一个显式 Gemini 缓存,只能与你自己的凭据一起使用:Google AI Studio 上的 Google API 密钥,或 Vertex AI 上的 Vertex AI 凭据。在 Vertex AI 上,Phaseo 会将请求发送到缓存全名(projects/{project}/locations/{location}/cachedContents/{id})中的项目和位置;短名称则使用你服务账号 JSON 中的 project_id 和 region。使用 Phaseo 的凭据时,请求会返回 400。google.cache_control 和 google.cache_ttl 会被接受,但不会发送给 Google。 对于 Claude,优先使用顶层 cache_control;对于 OpenAI GPT-5.6 及更高版本,优先使用 prompt_cache_options;对于更早的 OpenAI 模型,优先使用 prompt_cache_retention。请参阅提示缓存。

响应附加信息和调试

meta

在响应中添加一个包含路由详情的 meta 对象,例如 meta.routing.dropped_params。 类型 boolean · 默认值 false

usage

在响应正文中请求用量统计,而不是依赖标头或控制台。 类型 boolean · 默认值 未设置

debug

返回路由追踪和上游载荷。调试输出可能包含你的请求内容,因此只应在开发环境或严格受控的环境中使用。请参阅调试请求。

请求示例

最后修改于 2026年11月5日