Skip to content

fix: 保留 Gemini 结构化输出约束并拒绝静默降级 - #886

Merged
ranxi2001 merged 3 commits into
productionfrom
fix/gemini-structured-output-8662-20261116
Nov 16, 2026
Merged

ranxi2001 merged 3 commits into
productionfrom
fix/gemini-structured-output-8662-20261116

Conversation

@ranxi2001

@ranxi2001 ranxi2001 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

解决的问题与行为变化

  • Gemini 平台的 /v1/chat/completions 将请求经过 Responses 和 Anthropic 中间态转换,原先丢失 response_format,即使请求要求 JSON Schema,上游也可能收到无格式约束的请求。
  • 保留原始格式,在 Gemini 请求构造完成后写入 JSON MIME 类型和完整 responseJsonSchema。Schema 属性顺序、大整数和约束字段保持原样,流式与非流式使用相同映射。
  • 在上游修复基础上,缺少或无效 Schema、未知格式、JSON 输出与工具或图片输出模型的组合返回发送前 400 invalid_request_error,避免静默降级。缺省、null 和 text 保持原行为。
  • 本次只覆盖 Gemini 平台的 Chat Completions 入口;其他协议和平台不在本次范围。

关联记录与来源

管理员新功能提示

  • 提示 ID 与登记项:不适用,修复已有协议行为,没有管理员新功能。
  • NewFeatureBadge 展示位置:不适用,没有 UI 改动。
  • 关闭行为:不适用,没有新提示。
  • ID 沿用 / 重新公告:不适用,没有提示 ID 变动。
  • 必要回归证据:不适用,没有提示行为改动。
  • A 已关闭后升级到 B:不适用,没有新提示。
  • 点击 B 任一入口同步隐藏:不适用,没有新提示。
  • 刷新或重新登录持久性:不适用,没有新提示。
  • C 的新 ID 与旧提示:不适用,没有新提示。

复现与验收

  • 基线:production 41778efe6,VERSION 2.21.5。测试只使用虚构请求和 mock 上游,不发送真实模型请求。
  • 前置条件与操作:
    1. 通过 Gemini API Key 或 Code Assist 账号的 Chat Completions 兼容入口传入 json_object 或 json_schema。
    2. 检查实际发送给 mock 上游的 generationConfig;对不支持的组合检查返回错误和上游发送次数。
  • 修复前:源码转换链丢失格式字段。此次未重新运行历史基线,不将源码审查写成生产复现。
  • 验收标准:Schema 原样到达上游;流式与非流式都保留约束;未知格式、缺少 Schema、工具或图片组合返回 400,且没有上游请求。
  • 回归位置:backend/internal/service/gemini_compat_response_format_test.go,覆盖普通格式、Schema、思考参数、大整数、Code Assist 包装,以及两种 stream 模式下发送前拒绝,以及排队心跳已提交响应头后的 SSE 错误与结束事件。实际执行结果见下表。
协议、调度或传输改动补充
  • 入口 /v1/chat/completions,平台 Gemini;覆盖 API Key 和 OAuth + project_id,图片判断使用账号映射后的模型名。
  • 最小虚构格式:{"type":"json_schema","json_schema":{"name":"result","strict":true,"schema":{"type":"object","properties":{"score":{"type":"integer","minimum":1,"maximum":10}},"required":["score"],"additionalProperties":false}}}。
  • 新增拒绝发生在发送上游之前;排队心跳尚未提交响应头时返回 400,已经提交 SSE 响应头时发送 invalid_response_format 错误帧与 [DONE]。上游拒绝、超时、EOF、取消沿用既有处理。本次不承诺上游对任意 JSON Schema 特性的支持。
  • 不改变重试、故障转移或幂等语义,不新增正文采集。无效组合不会因该格式处理发出或重试付费请求。
  • 并发、粘性、冷却状态由原有调用方生命周期管理,本次未修改。

实际验证

检查与执行目录 / 命令 结果 覆盖范围、证据或未运行原因
独立应用工作区:git diff --check origin/production...HEAD 通过 补丁空白检查
本地 Go 测试、lint、构建 未运行 按工作区约定交给 CI
GitHub Actions f2e5a752f6431b94d1d44601aa9fab28e054c7d1:backend 目录 make test-unit、make test-integration 通过 PR CI、push CI;包含本次 Schema 传递、发送前拒绝和排队心跳后的 SSE 错误回归
同 head CI:backend 目录 golangci-lint --timeout=30m、仓库根目录 make test-frontend、后端 govulncheck ./... 和前端审计 通过 当前 head 的 CI 与 Security Scan 检查已成功
同 head 已触发的其他回归工作流 通过 合并前核对 34 项成功、47 项按条件跳过,无 pending 或失败。Issue 578 首次因 proxy.golang.org HTTP/2 下载错误失败;未进入测试,重跑通过
真实 Gemini/供应商、生产验收 未运行 本次为源码整合,没有发付费请求或部署

兼容性与运行影响

  • 配置 / API:无新配置。原先被静默忽略的无效格式或不支持组合现在返回 400;客户端可据此修正请求。普通文本默认行为不变。
  • 数据库与回滚:无迁移,二进制回滚会恢复旧的丢弃格式行为。
  • 权限与凭据:无新增权限、凭据读取或日志;测试数据均为虚构。
  • 计费与资源:没有网关自动内容重试或计费规则修改。上游可能将传入的 Schema 计入输入 Token;本次未测真实费用或性能。
  • 残余风险:供应商支持的 JSON Schema 子集仍可能不同;网关不执行完整输出 Schema 校验,客户端需对完整输出做结构及业务校验。合并不代表发布或上线。

文档与用户可见变化

新增 docs/gemini-structured-output.md,说明字段映射、400 边界、协议范围和客户端验收责任。没有前端变化,截图不适用。

Agent 使用声明

  • Agent 名称与参与范围:Codex,源码分析、上游提交整合、补充实现与测试、文档及 PR 撰写;未使用子 Agent。
  • 模型名称:GPT-6;当前会话未提供更精确的模型 ID,该部分未知。
  • 推理强度:未知,当前会话未暴露具体配置值。

提交前自查

  • base 分支和改动范围正确,没有夹带无关修改。
  • 正文、提交、测试数据和附件不含凭据、ticket/state 或真实用户敏感信息。
  • 实际验证结果已列出,未运行和未覆盖部分已说明。
  • 已检查配置默认值、权限、兼容性及相关文档。
  • Bug 修复有针对性回归用例,执行交给 CI。
  • 管理员提示登记和接入:不适用原因已逐项说明。
  • 管理员提示回归:不适用原因已逐项说明。
  • 已填写全部参与 Agent 的声明。

feeeei and others added 3 commits November 16, 2026 22:34
/v1/chat/completions 走 Gemini 账号时,response_format 在 chat→Responses→Anthropic
转换中丢失,上游只能靠 prompt 约束 JSON 格式。现在按客户端原始 response_format 写
generationConfig:json_object 写 responseMimeType=application/json;json_schema 另把
json_schema.schema 原样写入 responseJsonSchema。请求带 tools 或上游模型为图片输出
模型时不写。

Code Assist(OAuth + project_id)包装改为原字节嵌入 request,避免 Unmarshal→Marshal
重排 schema 属性顺序、截断大整数。

(cherry picked from commit 5846bfb)
@ranxi2001
ranxi2001 merged commit e3f238e into production Nov 16, 2026
82 of 83 checks passed
@ranxi2001

Copy link
Copy Markdown
Owner Author

独立复核补充(固定合并头 f2e5a752f6431b94d1d44601aa9fab28e054c7d1):合并前审查发现仍有一个 P2 follow-up,不能把当前实现的工具检查视为覆盖全部结构化输出拒绝。

  • 原始 Chat 请求的 tools / legacy functions 若包含 code_execution、x_search、unknown/custom 等类型,在 chatcompletions_to_responses.go → responses_to_anthropic_request.go 的有损转换中可能被丢掉;随后 Gemini 入口只看转换后的 tools,response_format=json_object/json_schema + 原始工具 可绕过发送前 400 并发出上游请求。
  • 请由原作者在同一维护线程/后续 PR 继续修复,不另起竞争 writer:在 Gemini 专用入口依据原始非空 tools / functions 做 fail-closed 判断,保留合法 function 路径的明确边界,不把无关共享转换器重构混入。
  • 必须保留同一个真实请求 oracle:stream=false 与 stream=true、排队 ping 前后,最终分别为 HTTP 400 或已提交 SSE 的安全错误帧+单个 [DONE],上游发送次数为 0;同时覆盖 code_execution、x_search、legacy functions、unknown/custom。不能只测转换后 tools。
  • 还需用两段以上 mock SSE 验证 stream 累积 JSON、完整 schema 解析及业务约束(required / additionalProperties / score 范围),并确认失败不落成功 usage/history;完成后补生产编译与完整 CI。

此评论不回写已合并 PR、不请求部署或真实付费调用;应由原作者按既有线程认领并在后续变更中给出 RED→minimal production GREEN 证据。

@ranxi2001

Copy link
Copy Markdown
Owner Author

请原发布者明确 ACK:886 已于 2026-11-16T15:28:10Z 被外部合并为 e3f238e;原始 tools/functions 丢失导致的 JSON 组合拒绝绕过仍须作为后续修复提交,不可仅编辑已合并分支冒充交付。请继续同一 writer 线程,在最新 production 上开 successor Draft,保留原始请求同 oracle 的零上游发送 RED→最小生产修复 GREEN,补累计流 JSON/schema/业务校验、production compile 和新头完整 CI。请回复唯一 writer 和后续 PR 链接;本次没有另启竞争 writer。

887 的补充说明:维护者明确授权的产品自定义默认价卡并不需要伪装成或强行改成“官方价”;只须保留实际截图/原授权出处、明确默认运营价与上游成本证据不同,未提供的策略作为明确产品默认值而非供应商事实。请 ACK 当前唯一 writer 并继续本 PR,落实新模型解析 negative guard、同 oracle RED/GREEN、PG/reload 账务矩阵与 native UI 附件。未知 gpt-5.4 fallback 属既存行为,修复限新增 6.2 解析边界,不扩大为全账务重写,不回写历史快照。

刚读取 887 旧 head 95f1050 的 Inherited-model RED/GREEN 完整 raw job 日志:两者实际均是 prepare-ws-inherited-model-red.py 的 ValueError: guard fixture changed; identical baseline/candidate guard tests required,属于证据准备/基线 guard 验证失败,不是 6.2 业务 RED 或已证明生产缺陷。当前外部 head 已推进至 e76af8e,新增差异含 production/Gemini 整合与上述脚本;旧 head 失败不直接转移至新头,需新头精确执行结果。

Hermes Agent / gpt-6.1-sol;推理强度未知(会话未公开)。仅审查/协调,不代表原实现或完整验收通过。

@ranxi2001

Copy link
Copy Markdown
Owner Author

再次窄化交接:本 PR 已合并,原 writer 的 ACK/修复后继仍未在评论中出现。已检查当前全部开放 PR(#899/#900/#901),未发现本项独立 successor;#901 的有损压缩/工具续接不是 Gemini response_format 原始 tools/functions 拒绝边界的同一修复。请原 #886 writer 明确回复认领,沿原维护线程从最新 production 建独立 Draft,不重开或追加已合并 PR,不夹入 #900。仅修 Gemini 专用原始请求的 tools/functions 丢失拒绝绕过;保留 code_execution/x_search/unknown/custom/legacy functions 的同一真实请求 oracle,HTTP400 或已提交 SSE 安全 error+单个DONE、upstream send=0 的 RED→最小生产GREEN;stream 累计 JSON/schema/业务约束、无成功usage/history与生产编译仍需原始执行证据。当前只是发现与请求认领,无 ACK、无修复通过结论。

Agent:Hermes Agent / gpt-6.1-sol;推理强度未知(会话未提供)。本次仅验收协调,父仍唯一merge owner;无ready/merge/release/deploy或生产/付费操作。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants