DeepSeek Responses API 接入说明

Commit: 4391ba3 — update Responses API support
日期: 2026-08-04
范围: src/gateway/unified_gateway.rs、src/llm/sse.rs、src/config/settings.rs、apps/gliding_code/src/config.rs、config.yaml 及测试适配

1. 背景

DeepSeek 官方推出 Responses API（POST /v1/responses）作为新一代接口，相比 Chat Completions 具备语义化的流式事件（response.*）、显式的工具调用往返结构、原生推理内容（reasoning）输出等能力。截至 2026-08-04，该接口仅支持 deepseek-v4-flash 模型（deepseek-v4-pro 预计 2026 年 8 月初启用）。

本次修改为 Gliding Horse 接入 Responses API，同时保持对 Chat Completions 的完全兼容：

• deepseek-v4-flash 请求默认路由到 /v1/responses；
• 其余模型（含 deepseek-v4-pro）自动回退到 /v1/chat/completions；
• 下游调用方（Agent Runner、工具执行器、TUI 等）无感知——两种协议在网关层统一收敛为内部 ChatCompletionResponse / StreamEvent 词汇表。

2. 整体架构

设计要点：Responses API 是网关内部的一条协议适配分支，所有 Responses 特有的结构（input items、semantic events）都在网关 / SSE 解析层完成转换，业务层看到的数据形状与 Chat Completions 完全一致。

3. 配置与开关

3.1 配置项

# config.yaml 示例
gateway:
  base_url: "https://api.deepseek.com"
  api_key: "sk-..."
  timeout_seconds: 300
  max_retries: 3
  retry_base_ms: 500
  # deepseek-v4-flash 走 Responses API (/v1/responses)，deepseek-v4-pro 继续走 chat completions
  use_responses_api: true
  model_mapping:
    planning: "deepseek-v4-pro"
    execution: "deepseek-v4-flash"

# 环境变量方式
export USE_RESPONSES_API=1        # 显式开启
export USE_RESPONSES_API=0        # 强制走 chat completions

3.2 模型能力判定

/// 仅 deepseek-v4-flash 支持 Responses API；
/// deepseek-v4-pro 在 DeepSeek 启用前继续使用 chat completions。
fn is_responses_capable_model(model: &str) -> bool {
    let m = model.to_lowercase();
    m == "deepseek-v4-flash" || m.starts_with("deepseek-v4-flash-")
}

fn should_use_responses_api(&self, model: &str) -> bool {
    *self.use_responses_api.read().unwrap() && Self::is_responses_capable_model(model)
}

即使 use_responses_api 为 true，非 deepseek-v4-flash 模型也绝不会被路由到 /v1/responses——这是硬性安全边界，防止对尚不支持该接口的模型产生 400 错误。

4. 非流式请求（chat / chat_with_model / chat_with_params）

4.1 消息转换：responses_input_items

4.2 工具定义转换：convert_responses_tools

Chat Completions 将函数定义嵌套在 function 键下，Responses API 要求扁平结构：

// chat completions（入参）
{ "type": "function", "function": { "name": "get_weather", "description": "...", "parameters": {...} } }

// responses（转换后）
{ "type": "function", "name": "get_weather", "description": "...", "parameters": {...} }

非函数工具（web_search、自定义工具）原样透传。

4.3 响应解析：parse_responses_response

关键点：Responses API 的 usage 字段是 input_tokens / output_tokens，而 Chat Completions 是 prompt_tokens / completion_tokens——解析层完成归一化，下游统计与计费展示无需改动。

4.4 重试与错误处理：send_with_retry

两种协议共享同一重试骨架（重构自原有逻辑）：

• 指数退避：retry_base_ms * 2^(attempt-1)；
• 4xx 客户端错误立即终止（不重试），并将请求体前 8K 字符嵌入错误信息便于 TUI 直接排查；
• 5xx / 网络错误按 max_retries 重试；
• 解析失败（JSON 无效 / 结构不符）也会重试并记录响应长度日志。

5. 流式请求（stream_chat_with_params）

5.1 事件映射：parse_responses_api_event

Responses API 流由语义事件组成（type: "response.*"），且没有 data: [DONE] 终止帧——终止由 response.completed / response.incomplete / response.failed 承担。parse_frame 通过 type 前缀分流到 Responses 解析器：

5.2 流式终止语义

5.3 与 Chat Completions 流式路径的关系

• SseParser / MessageStream / StreamAccumulator 完全复用；
• 差异仅在 parse_frame 内部：response.* 前缀走新解析器，其余走原有 parse_openai_stream_event；
• [DONE] 帧仍被兼容处理（parse_frame 中 payload == "[DONE]" 返回 None），因此两种协议可在同一代码路径内共存。

6. 调用链全景

7. 配置与使用示例

7.1 完整启用配置

# 1) API Key
export DEEPSEEK_API_KEY="sk-..."

# 2) 显式启用 Responses API（v4-flash 默认已开启，可省略）
export USE_RESPONSES_API=1

# 3) 运行 Gliding Code，默认模型 deepseek-v4-flash 即走 /v1/responses
./glidingcode "设计一个知识图谱的 schema"

# 4) 切换到 v4-pro（自动回退 chat completions）
./glidingcode --model deepseek-v4-pro "分析这段代码的时间复杂度"

7.2 运行时动态切换（编程接口）

// 任意时刻可切换，无需重建网关
gateway.set_use_responses_api(false); // 强制全部模型走 chat completions
gateway.set_use_responses_api(true);  // 恢复 v4-flash 走 responses

7.3 观察点

8. 测试覆盖

新增 / 适配的测试（cargo test --lib，全量 1193 项通过）：

9. 边界与限制

1. 模型支持面：Responses API 目前仅 deepseek-v4-flash；deepseek-v4-pro 在官方启用前自动走 chat completions（is_responses_capable_model 硬性判定）。
2. 温度等参数：思考模式下 temperature 等参数不生效（DeepSeek 文档说明，兼容性静默忽略，不报错）；网关仍透传参数，由 API 侧处理。
3. 无降级重试：若 /v1/responses 返回 4xx（如参数不合法），不会自动降级到 chat completions——这是有意设计，避免掩盖请求构造错误；可通过 set_use_responses_api(false) 手动回退。
4. 流式终止：Responses 流没有 [DONE]；若服务端异常断流且无终止事件，MessageStream 依赖底层 HTTP 流结束（None）自然终止。
5. usage 归一化：input_tokens/output_tokens → prompt_tokens/completion_tokens 的映射在解析层完成，计费展示沿用原有逻辑。

10. 文件变更清单