Skip to content

fix(gemini): 修复 Gemini 流式响应提前结束与静默截断问题 - #8980

Open
universonic wants to merge 4 commits into
Wei-Shaw:mainfrom
universonic:bugfix/gemini-incomplete-stream
Open

universonic wants to merge 4 commits into
Wei-Shaw:mainfrom
universonic:bugfix/gemini-incomplete-stream

Conversation

@universonic

@universonic universonic commented Nov 20, 2026 •

Copy link
Copy Markdown

问题

通过基于 Vercel AI SDK 的客户端(如 Kilo / OpenCode 等,使用 @ai-sdk/google、@ai-sdk/anthropic、@ai-sdk/openai)调用 Gemini 模型时,频繁触发 "Response ended unexpectedly and may be incomplete."(底层因流结束时缺少合法终止事件或收到未映射的 finishReason 被归为 'other' / 'unknown')。排查定位到以下服务端根因:

  1. /v1/messages 混合调度协议错位:gateway_handler.go 在 Gemini 分组混合调度命中开启 mixed_scheduling 的 Antigravity 账号时,误调用了原生 ForwardGemini 而非 Claude 协议入口 Forward,把 Claude JSON 请求当作 Gemini 请求发送,并将原生 Gemini SSE 直接写回给期待 Anthropic SSE 的客户端。
  2. GeminiMessagesCompatService 全流式路径缺失心跳与空闲超时:/v1beta 原生流、/v1/messages 与 /v1/chat/completions 兼容流均在主协程同步阻塞读行,未接入 StreamKeepaliveInterval 与 StreamDataIntervalTimeout;长 CoT 思考期间易被前置代理/隧道(如 Cloudflare/Nginx)或客户端静默掐断。
  3. 过早提交 HTTP 200 头与首帧:流式转发在读取上游首个有效事件前即提交了 200 OK 或写出 message_start / 首个 Chat role chunk,导致上游返回空 200 流、带内错误信封、首包前断流/超时、或无正文的异常终止(OTHER / MALFORMED_FUNCTION_CALL / MALFORMED_RESPONSE / UNEXPECTED_TOOL_CALL)时无法触发重试或 Failover。
  4. 流中途断连被当作正常 chunked 结束:/v1beta 流中途读取报错返回后,Gin 正常写出 HTTP/1.1 chunked 结束块 0\r\n\r\n;且 @ai-sdk/google 的 chunkSchema 所有字段均为 .nullish(),会将流内 {"error":...} 剥离为空对象 {} 忽略,导致客户端将截断流误判为正常 EOF(finishReason: 'other')而不触发传输层重试。
  5. 长流 HTTP/2 健康探测未启用与拒绝原因映射遗漏:已实现的 HTTPUpstreamProfileLongStream(HTTP/2 ReadIdleTimeout PING 探测)未注入 Gemini / Antigravity 请求;兼容转换层未将 Gemini 内容安全拦截枚举映射为 Claude "refusal" / OpenAI "content_filter"。

改动

  • 修正 /v1/messages 混合调度入口:Gemini 分组选中非 APIKey 的 Antigravity 账号时改为调用 antigravityGatewayService.Forward。
  • 补齐共用异步 SSE 读取、心跳与精确空闲超时:新增 geminiSSEAsyncReader,为 GeminiMessagesCompatService 三条流式路径接入 StreamKeepaliveInterval(/v1beta 下对 go-genai 等客户端自动跳过注释心跳)与基于末次读取时间精确重置的 StreamDataIntervalTimeout(同步更新 Antigravity 流式超时计时器)。
  • 延迟提交响应头与首包前自动 Failover:在收到首个有效候选内容前延迟提交 200 OK 与 message_start / role 首帧;首包前遇到空流、带内错误信封、连接错误、空闲超时或无正文的异常 finishReason 时返回 UpstreamFailoverError(仅写出过心跳且未写出上游数据时标记 SafeToFailoverAfterWrite: true);若 Keepalive 提交 SSE 头后下一账号返回非重试错误,按已提交的 SSE 协议写出标准错误事件而非裸 JSON。
  • 截断流在中间件收尾后中止底层传输:新增 middleware.IsCommittedEventStream 与 MarkAbortTruncatedStream,仅对已建立为 200 text/event-stream 且中途异常中断的流标记中止,在 Recovery() 最外层待 OpsErrorLoggerMiddleware 与访问日志完成后触发 http.ErrAbortHandler(HTTP/1.1 不写 0\r\n\r\n、HTTP/2 发送 RST_STREAM),不影响非流式/前置 JSON 错误响应。
  • 启用长流连接探测与补齐安全过滤映射:为 GeminiMessagesCompatService 与 AntigravityGatewayService 上游请求注入 HTTPUpstreamProfileLongStream;统一将全部 Gemini 内容安全拦截枚举映射为 Claude "refusal" 及 OpenAI Responses / Chat Completions "content_filter"。

验证

  • go build ./... 全量编译通过。
  • go vet -tags=unit 与 golangci-lint run 检查修改涉及的 handler、service、antigravity、apicompat、middleware 包:0 issues。
  • 单元测试与竞态检测通过:
    • go test -race -tags unit ./internal/server/middleware/... ./internal/pkg/apicompat/... ./internal/pkg/antigravity/...
    • go test -race -parallel 1 -tags unit ./internal/service -run 'TestGemini.*|TestAntigravity.*|TestHandle.*Streaming.*|TestStream.*' -count=1
    • go test -race -parallel 1 -tags unit ./internal/handler -run 'TestWriteGoogleStreamingErrorAndAbort|TestGemini.*|TestStream.*' -count=1
    • go test -tags unit ./internal/handler -count=1
  • 新增回归测试覆盖:三条兼容/原生路径 SSE 心跳与 go-genai 跳过策略、Keepalive 后首包前超时/空流/无正文异常终止的 Failover 与脏数据保护、已提交 SSE 流的错误帧格式化、HTTPUpstreamProfileLongStream 传递、内容安全过滤映射,以及真实 httptest.NewServer 下截断 chunked 流中止(验证内层中间件正常收尾且普通 4xx JSON 错误不被误中止)。

关联 Issue

@universonic
universonic force-pushed the bugfix/gemini-incomplete-stream branch from 30a8861 to 554cc17 Compare November 20, 2026 04:43
…tions

- Route /v1/messages mixed-scheduled Antigravity accounts through Claude Forward instead of ForwardGemini
- Add async SSE keepalive heartbeats and idle timeout tracking across Gemini native, Messages, and Chat Completions streams
- Defer SSE header/initial event commits to enable pre-output failover on empty streams, timeouts, and empty abnormal finish reasons
- Abort truncated HTTP/1.1 chunked and HTTP/2 SSE streams after inner middleware completion so clients detect mid-stream drops
- Enable HTTPUpstreamProfileLongStream on Gemini/Antigravity upstream requests and map content-filter finish reasons to refusal/content_filter
@universonic
universonic force-pushed the bugfix/gemini-incomplete-stream branch from 554cc17 to 38ea8aa Compare November 20, 2026 11:31
@r266-tech

Copy link
Copy Markdown
Contributor

我在 38ea8aa4 上用本地流夹具验证了三个 Gemini 流式入口。上游先发出一个完整的文本 SSE 帧,随后正常结束 HTTP body,最后一帧没有 finishReason。Google 的 Candidate 说明 将空的 finishReason 定义为模型尚未停止生成。

入口 当前结果
/v1beta 返回成功,只透传文本,未触发截断响应处理
/v1/messages 发出 end_turn 和 message_stop
/v1/chat/completions 发出 finish_reason: stop 和 [DONE]

对照中,追加 finishReason: STOP 后三个入口都正常完成;同一个文本帧后的 io.ErrUnexpectedEOF 在三个入口都返回错误。PR 的现有 HTTP/1.1 中止测试也通过。这里剩下的是 HTTP 正常收尾、模型流尚未收尾的情况。建议在收尾前检查上游协议的终态,并把这三种情况一起覆盖。

本地验证与反馈由 Codex 完成。

- Require a terminal Gemini finishReason (or promptFeedback.blockReason / in-band error) before completing /v1beta, /v1/messages, and /v1/chat/completions streams at EOF
- Emit protocol-appropriate SSE error frames instead of fabricating end_turn/message_stop or finish_reason=stop/[DONE] on unfinished streams, and mark /v1/messages committed SSE streams for transport abort on failure
- Add terminal-state matrix tests covering STOP completion, clean EOF without finishReason, and io.ErrUnexpectedEOF across Gemini and Antigravity entrypoints
@universonic

Copy link
Copy Markdown
Author

感谢 @r266-tech 的细致验证与反馈!已在 c2fb138 中补齐“HTTP body 正常 io.EOF 但上游未给出协议终态”的收尾校验(同时覆盖 GeminiMessagesCompatService 与 AntigravityGatewayService 两条链路):

修补改动

  1. 统一协议终态判定:
    • 将非空且非 FINISH_REASON_UNSPECIFIED 的 finishReason、非空且非 BLOCKED_REASON_UNSPECIFIED 的 promptFeedback.blockReason 以及带内 Google error 信封作为有效协议终态。
    • 若上游尚未向客户端写出任何内容即无终态 EOF,统一返回 UpstreamFailoverError 走重试/切号。
  2. 三大流式入口截断收尾处理(已写出部分内容但缺失终态即干净 EOF):
    • /v1beta(handleNativeStreamingResponse & handleGeminiStreamingResponse):写出标准 Google SSE 错误帧并返回 missing finishReason 错误,由 GeminiV1BetaModels 标记 MarkAbortTruncatedStream 中止底层流(同时保留原生路径纯空流与带内信号透传契约)。
    • /v1/messages(handleStreamingResponse、handleClaudeStreamingResponse & gateway_handler.go):不再补发 stop_reason: "end_turn" 与 message_stop,改为发出 Anthropic event: error(stream_incomplete),并在 Handler 层对已建立的 SSE 流标记 MarkAbortTruncatedStream 中止底层流。
    • /v1/chat/completions(handleChatCompletionsStreamingResponseFromGemini & antigravity_gateway_compat_stream.go):不再补发 finish_reason: "stop" 与 data: [DONE],改为写出 SSE 错误事件并返回错误(Handler 层同步触发底层流中止)。

验证情况

  • 新增 TestGeminiStreamTerminalStateMatrix,对 Gemini 与 Antigravity 在 /v1beta、/v1/messages、/v1/chat/completions 共 6 条路径完整覆盖三组对照:
    1. 文本帧 + finishReason: "STOP" + 干净 EOF → 正常完结;
    2. 文本帧(无 finishReason)+ 干净 EOF → 返回错误、写出对应协议错误帧且禁止发出 end_turn / message_stop / stop / [DONE];
    3. 文本帧(无 finishReason)+ io.ErrUnexpectedEOF → 返回错误且禁止发出正常终态标记。
  • 全量单元测试 go test -tags=unit ./... 与 golangci-lint run ./...(v2.14.0)均通过(0 issues)。

@r266-tech

Copy link
Copy Markdown
Contributor

已在 c2fb1383e 复验。Gemini 和 Antigravity 六条路径的终态矩阵,加上上次 Gemini 的独立夹具,共 27 个场景通过 -race。原先的干净 EOF 截断和异常断流均不会再被补成正常结束,HTTP/1.1 中止测试也通过。

另用只含一个 promptFeedback SSE 帧并正常结束的流复验。Google v1beta 定义的默认枚举是 BLOCK_REASON_UNSPECIFIED,当前代码过滤的是 BLOCKED_REASON_UNSPECIFIED。Google v1beta Discovery 文档

上游反馈 c2fb1383e 实测
BLOCK_REASON_UNSPECIFIED Gemini 的 Messages 与 Chat、Antigravity 的 Messages 都返回成功的内容拒绝,分别产生 refusal 或 content_filter。
promptFeedback: {} Antigravity 的 Messages 已提交 message_start,随后才以 stream_incomplete 收尾,服务端无法在首包前重试。
blockReason: "SAFETY" Gemini 的两个兼容入口和 Antigravity 的 Messages 正常报告内容拒绝,Antigravity 的 Chat 却返回 UpstreamFailoverError。

旧 38ea8aa4 在两个中性输入的 8 个兼容场景都返回了可故障转移的错误,未写出 SSE。

可否统一这几处的终态判定,让空的反馈和默认枚举保留首包前的 failover,同时让明确的拒绝本身可以完成 Chat 流?本地复验和反馈由 Codex 完成。

…andling

- Treat both BLOCK_REASON_UNSPECIFIED and BLOCKED_REASON_UNSPECIFIED as non-blocking defaults across Gemini signal detection, Messages/Chat compat, and Antigravity transformers
- Keep empty or unspecified promptFeedback frames from committing message_start so pre-output failover remains intact
- Recognize refusal stop_reason deltas as meaningful output in Antigravity OpenAI compat streams so explicit prompt safety blocks complete with content_filter
… and candidate selection

- Mark empty abnormal finishReason failovers RequestScopedTransient to avoid unscheduling healthy accounts, and return deterministic 4xx error envelopes directly
- Preserve promptFeedback safety refusals in Antigravity non-streaming Claude collector
- Emit response.failed terminal events and wire truncated stream abort on /v1/responses
- Buffer and replay pre-candidate metadata frames on Antigravity /v1beta streams and align primary candidate selection on index==0
@r266-tech

Copy link
Copy Markdown
Contributor

在 3984a9b3 上用本地合成 SSE 复验了上条反馈。

  • 空 promptFeedback、BLOCK_REASON_UNSPECIFIED 和兼容的 BLOCKED_REASON_UNSPECIFIED 在兼容入口均于提交首帧前返回可故障转移的错误。
  • 明确的 SAFETY 在 Messages 以 refusal 收尾,在 Chat Completions(包括 Antigravity)以 content_filter 收尾。Antigravity 的 Responses 和原生 Gemini 入口也通过了拒绝对照。
  • 文本帧后的干净 EOF 和 io.ErrUnexpectedEOF 均报告截断。带 finishReason: STOP 的对照正常完成。

定向 go test -race -tags=unit、HTTP/1.1 传输中止和两个转换包的测试均通过。复验由 Codex 完成。

@universonic

Copy link
Copy Markdown
Author

补充说明最近两笔提交(28835b391、3984a9b3e)的新增改动,目前所有已知的流式终态、安全拦截与故障转移边界问题均已修复完成:

新增改动

  1. promptFeedback 默认枚举与空反馈首包前 Failover 统一(28835b391):
    • 在原生信号检测、Gemini 兼容层与 Antigravity 流式/非流式转换器中,同时将 ""、Google v1beta 标准默认枚举 "BLOCK_REASON_UNSPECIFIED" 及 "BLOCKED_REASON_UNSPECIFIED" 视为非拦截占位值。
    • 收紧 StreamingProcessor 发出 message_start 的前置条件:仅存在有效候选内容/终态或明确 promptFeedback 拦截时才提交首帧,确保空 promptFeedback: {} 与默认未指定枚举在全部兼容入口及 Antigravity /v1beta 保留零写入的首包前 Failover。
    • 在 Antigravity OpenAI 兼容流中将 stop_reason: "refusal" 识别为有效输出事件,使明确的 promptFeedback 安全拒绝在 /v1/chat/completions(content_filter + [DONE])与 /v1/responses(response.incomplete)正常完结。
  2. 请求级异常冷却豁免与多路径细节加固(3984a9b3e):
    • 对首包无正文的异常 finishReason(MALFORMED_FUNCTION_CALL / UNEXPECTED_TOOL_CALL / TOO_MANY_TOOL_CALLS / MALFORMED_RESPONSE / OTHER)生成的 UpstreamFailoverError 标记 RequestScopedTransient: true,保留重试与切号的同时避免误触发健康账号临时冷却;对 400 INVALID_ARGUMENT 等确定性 4xx 带内错误信封直接返回客户端错误,不走重试/切号。
    • 在 Antigravity 非流式聚合器 collectClaudeStreamResponse 中放行明确的 promptFeedback 安全拦截,确保非流式 /v1/messages 正常返回 stop_reason: "refusal"。
    • 在 /v1/responses 流异常中断时补充发出标准 event: response.failed 终态事件,并在 GatewayHandler.Responses 接入 SafeToFailoverAfterWrite 与截断流传输中止。
    • 在 Antigravity /v1beta 首包前缓存无候选的合法元数据帧(如前置 safetyRatings / usageMetadata),待首个有效帧到达时按序回放;统一 extractGeminiFinishReason 按缺省或 index == 0 选择主候选,并清理不可达分支。

验证状态

  • 新增 TestGeminiPromptFeedbackTerminalMatrix 与 TestGeminiReviewedBranchEdgeCases(均通过 -race 竞态检测)。
  • 后端全量单元测试 go test -tags=unit ./...、golangci-lint(v2.14.0)与安全扫描均已全部通过(0 issues)。

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