雨 雨天小六

读懂 Codex（5.4）：Responses、Responses Lite 与能力协商

· 更新于 2026-08-02 · 专栏：读懂 Codex

#Codex#Agent Runtime#Responses API#流式协议#软件架构

Responses Lite 不是把标准请求发往另一个 URL，而是把顶层指令和工具重新编码进 Input 前缀，并关闭若干能力。Codex 在请求编译处完成这种方言适配，上游 Prompt 不需要理解线协议差异。

具体问题与启用条件

本节比较两种请求方言及其能力协商；字段逐项序列化见 5.6，传输选择见 5.7—5.8。

条件来源决定字段或状态对本机制的影响
模型能力use_responses_lite选择 Lite 编码
ProviderResponses wire API两种方言仍使用 Responses 事件模型
模型能力reasoning summary、verbosity、parallel tools决定字段发送或降级

协议、类型与状态所有权

状态或协议所有者生命周期关键不变量
内部 PromptCore Turn一次采样方言无关
ResponsesApiRequestModelClient一次请求尝试反映已协商能力
AdditionalTools + developer prefixLite 编译分支请求 Input 前缀替代顶层 tools/instructions

机制调用链如下：

Prompt + ModelInfo
→ 判断 use_responses_lite
→ 标准：instructions/tools 顶层编码
→ Lite：AdditionalTools + Developer Message 前置
→ 过滤不支持的 image detail/parallel tools
→ 两种方言进入同一流事件映射
同一 Prompt 编译为标准 Responses 或 Responses Lite
图 5.4-1：方言差异限制在请求编译层，响应事件仍汇合。

机制怎样工作

标准 Responses 保留 instructions、tools 和 parallel_tool_calls 的顶层含义。Lite 则把工具序列化为 AdditionalTools Developer 输入项，把 Base Instructions 变成 Developer Message，二者插到原始 Input 前面；顶层 instructions 变为空串、tools 为空，并强制关闭并行工具调用。Lite 还移除图片 detail，并把 reasoning context 设为所有 Turn。

能力协商不是一次集中握手，而是编译期门控：模型不支持推理摘要就不发送 summary；不支持 verbosity 就省略；是否使用 sequential cutoff summaries 又取决于 Feature 与 OpenAI Provider。这样的“省略”比发送一个看似合理但服务端不认识的值更安全。

Python 风格伪代码

这段伪代码保留生产实现中会改变结果的状态、分支和异步边界；认证 SDK、遥测字段和 Rust 所有权样板被折叠为明确的领域对象。

def compile_dialect(prompt: Prompt, model: ModelInfo) -> ResponsesRequest:
    input_items = clone_items(prompt.input)
    if model.use_responses_lite:
        strip_image_detail(input_items)
        prefix = [
            AdditionalTools.from_specs(prompt.tools),
            developer_message(prompt.base_instructions.text),
        ]
        return request(
            instructions="", input=prefix + input_items, tools=None,
            parallel_tool_calls=False,
            reasoning_context="all_turns",
        )
    return request(
        instructions=prompt.base_instructions.text,
        input=input_items,
        tools=serialize_tools(prompt.tools),
        parallel_tool_calls=prompt.parallel_tool_calls,
    )

失败、取消与恢复

请求字段按模型能力逐项协商
图 5.4-2：协商结果可能是发送、降级或省略，而不是一次全有或全无的握手。
故障或边界已发生的状态对上层的结果能否直接重试恢复动作
把 Lite 当成标准请求字段已放在错误层服务端忽略或拒绝能力否重新编译方言
Lite 仍发送并行工具请求语义冲突可能 4xx否强制关闭
发送不支持的 verbosity/summary请求已编码Provider 4xx否按 ModelInfo 省略
Lite 图片保留 detailInput 已构造不兼容字段否请求投影时清除

设计取舍与验证

在 ModelClient 内适配方言，让 Prompt、History 和 ToolRouter 继续使用统一类型；代价是请求构造器承担了更多兼容逻辑。另一方案是让上游直接构造 Lite Prompt，但会把同一会话的语义历史分裂成两套表示，更难做重试和测试。

可验证契约证据方式预期结果
Lite 指令和工具进入 Input 前缀请求 body 捕获顶层字段清空且顺序稳定
Lite 关闭 parallel tool calls集成请求断言字段恒为 false
标准模式保持顶层字段同一 Prompt 的对照测试instructions/tools 不被前置消息替代

Mini Codex 对照

Mini Codex 可定义 WireDialect 策略，让两种编译器共享 Prompt 类型。若不实现 Lite，应在能力解析时明确拒绝该模型，不能静默用标准方言发送。

本节边界

这里完成请求方言选择。下一节进入与模型语义无关、但影响路由和审计的请求身份。

评论

← 返回文章列表