DeepSeek Harness (DSH) 中配置 Google Gemini 与避坑实践

实战指南：在 DeepSeek Harness (DSH) 中配置 Google Gemini 与避坑实践

随着 DeepSeek Harness（DSH）在本地 Agent 工作流中的广泛使用，不少开发者希望将 Google Gemini（如 gemini-2.5-flash / gemini-3.7-flash）接入作为日常辅助模型。Gemini 具备 1M（100 万）超大上下文窗口、极高的推理吞吐速度以及原生的多模态（Vision）识图能力，非常适合处理海量代码分析与截图定位任务。

但在实际接入 Google 官方提供的 OpenAI 兼容端点时，如果仅按标准 OpenAI 格式填写，常会遇到 HTTP 400 Bad Request 报错，导致会话直接中断。

本文将记录在 DSH 中完整配置 Google Gemini 的关键参数、底层根因分析以及多模态运行实测。

一、核心痛点：为什么直接配置会报 400？

Google 官方提供了 OpenAI 兼容接口：

text 复制代码

https://generativelanguage.googleapis.com/v1beta/openai

虽然协议兼容 OpenAI 的 Chat Completions，但 Google 端点对请求体中的部分字段有更严格的校验规则：

不支持 store 字段 ：部分 OpenAI SDK 或 Agent 框架默认会发送 store: false，Google 端点接收到非标准未知字段会直接返回 HTTP 400 Bad Request。
不支持 developer 角色 ：部分新版协议使用 developer 代替 system 角色，Google 端点无法解析该角色。
工具调用（Tool Call）强制要求 name ：在多轮工具交互中，回传 role: "tool" 时，Google 端点要求必须显式附带调用的工具名称（name 字段），缺少则会拒绝请求。
DSH 错误分类误判 ：DSH 底层如果接收到上游返回的简略 400 (no body) 响应，容易将其误归类为 CONTEXT_WINDOW_EXCEEDED（上下文超限），进而自动触发后台 Compaction（上下文压缩）。若压缩请求再次遭遇网络波动，会导致整轮对话崩溃。

因此，接入的关键是在 DSH 中通过 compat（兼容性配置）显式关闭不支持的特性并规范请求体。

二、完整配置方案

DSH 的模型配置文件通常位于项目根目录的 settings.yaml，API Key 等敏感信息推荐放置在 .credentials.yaml 中。

1. `settings.yaml` 配置

在 llm-pi-ai.providers 下新增 gemini-free（或自定义命名的 Provider），重点配置 compat 段与多模态 input：

yaml 复制代码

llm-pi-ai:
  providers:
    gemini-free:
      displayName: Google Gemini
      apiKeyEnv: GEMINI_FREE_API_KEY
      api: openai-completions
      baseURL: https://generativelanguage.googleapis.com/v1beta/openai
      compat:
        supportsStore: false             # 禁用 store 字段传递
        supportsDeveloperRole: false     # 禁用 developer 角色，自动回退为 system
        maxTokensField: max_tokens       # 明确指定 token 字段拼写
        requiresToolResultName: true     # 工具回传结果强制附带 tool name
      models:
        - id: gemini-2.5-flash
          name: Gemini 2.5 Flash
          contextWindow: 1000000
          input: [ text, image ]         # 启用文本与图片输入
        - id: gemini-3.7-flash
          name: Gemini 3.7 Flash
          contextWindow: 1000000
          input: [ text, image ]

2. 核心参数详解

supportsStore: false ：解决 Google 网关收到 store: false 报错 400 的核心开关。
supportsDeveloperRole: false ：确保系统提示词以 standard system 角色下发，避免角色不识别。
requiresToolResultName: true ：当 Agent 触发本地工具（如 grep、view_file）并将执行结果传回 Gemini 时，在 Tool Message 中保留工具名，避免被 Google 拒绝。
input: [ text, image ]：显式声明该模型支持图片输入。DSH 会在前端对话框中开启图片上传入口，并在请求体中封装标准的 Base64 / URL Image 结构。

3. `.credentials.yaml` 凭据配置

在根目录下的 .credentials.yaml 中绑定环境变量，保持配置与密钥隔离：

yaml 复制代码

GEMINI_FREE_API_KEY: "AIzaSy..."

三、实机效果与运行链路验证

配置完成后，启动 DSH 并选择配置好的 Gemini 模型，可支持以下典型工作流：

1. 多模态识图 + 工具调用完整链路

在会话中上传前端报错截图或代码架构图：

css 复制代码

[用户上传截图] ──► [Gemini 识别图片文本与问题] ──► [触发本地 Tool Call (如 grep)] 
                                                            │
[Gemini 总结输出修复建议] ◄── [DSH 回传带 name 的 Tool Result] ◄────┘

第 1 轮：Gemini 成功解析多模态图片中的报错信息，自动构建工具调用参数（如检索指定错误关键字）。
第 2 轮 ：本地执行工具完成，DSH 将工具检索到的代码上下文连同 name 规范回传，Gemini 顺利接收并输出最终修复方案。

2. 表现总结

上下文利用率高：1M Token 的窗口在面对大型单体仓库或需要一次性阅读多个日志文件时，极少触发频繁的上下文截断。
响应吞吐快：Flash 系列模型在执行工具链循环时延迟低，适合作为日常代码分析和高频调试的主力。

四、常见异常排查与维护建议

1. 如何排查 `400 status code (no body)`

Google 接口返回 400 时通常带有 Gzip 压缩，部分客户端由于未自动解压会显示为 (no body)。如果依然报错，可通过以下方式定位具体字段：

检查 settings.yaml 中的拼写，compat 下的所有键必须完全匹配。
如有必要，可在本地启动抓包代理或通过脚本发起单次请求，查看解压后的真实 JSON 错误信息（例如确认是否传递了未支持的温度参数或非标 schema）。

2. 避免历史坏块污染

如果之前由于配置缺失导致某个会话报过 400 错误，该错误轮次可能已经停留在该 Session 的本地历史记录中。即使修复了配置，直接继续对话也可能因历史消息格式异常再次触发报错。

建议：配置修改生效后，新建一个测试会话，或者使用 DSH 的会话回滚功能截断出错的轮次。

五、小结

在 DSH 中接入第三方异构模型端点时，核心在于对齐协议细节 。通过在 settings.yaml 中显式指定 compat 裁剪规则，可以规避 Google 兼容层对非标字段的严格限制，在 DSH 中稳定使用 Gemini 的 1M 长上下文与多模态能力。

DeepSeek Harness (DSH) 中配置 Google Gemini 与避坑实践

实战指南：在 DeepSeek Harness (DSH) 中配置 Google Gemini 与避坑实践

一、 核心痛点：为什么直接配置会报 400？

二、 完整配置方案

1. settings.yaml 配置