如何玩转 Cursor2API-go 流式 API?SSE 逐字输出、delta.tool_calls 与 [DONE] 机制深度解析

原创2026-10-14 13:42:261,672 阅读
文章标签:AI 应用LLM 网关后端API网关

如何玩转 Cursor2API-go 流式 API?SSE 逐字输出、delta.tool_calls 与 [DONE] 机制深度解析

Cursor2API-go 是一个用 Go 编写的 AI 模型 API 网关服务,可将 Cursor Web 转换为 OpenAI 兼容的 chat/completions 接口。这篇文章带你深度解析它的流式 API实现:从 stream: true 请求发起,到 SSE(Server-Sent Events)逐字推送、delta.tool_calls 工具调用协议,再到 [DONE] 结束标记的完整链路,帮你轻松上手流式调用与调试。

🎯 为什么需要流式(SSE)输出?

非流式请求要等模型把整段答案生成完才返回,长回答的等待感非常明显。而流式 API 采用 SSE 增量推送:模型每生成一小段内容就立即推送给客户端,实现"逐字输出"的打字机效果。

Cursor2API-go 在同一个接口 handlers/handler.go 中同时支持两种模式:

  • stream: false —— 一次性返回完整 JSON;
  • stream: true —— 返回 text/event-stream 事件流,支持 delta.content 与 delta.tool_calls。

Cursor2API-go 流式 API 服务总览面板,展示 SSE 流式响应支持状态

上图是服务启动后的总览面板(static/docs.html),可以清楚看到"支持 SSE 流式响应""Tool Calls""Thinking"等能力卡片。

🚀 快速上手:3 步发起流式调用

第 1 步:启动服务

# Linux/macOS
./start.sh
# 或 Docker
docker run -d --name cursor2api-go -p 8002:8002 cursor2api-go

服务默认监听 http://localhost:8002,默认 API Key 为 0000(建议通过 API_KEY 环境变量修改,见 config/config.go)。

第 2 步:带上 stream: true 发请求

curl -N -X POST http://localhost:8002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 0000" \
  -d '{
    "model": "gemini-3-flash",
    "stream": true,
    "messages": [{"role": "user", "content": "用一句话介绍 SSE"}]
  }'

💡 curl 记得加 -N(--no-buffer),否则终端会等响应结束才一次性显示,看不到逐字效果。

第 3 步:观察事件流输出

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1728800000,"model":"gemini-3-flash","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1728800000,"model":"gemini-3-flash","choices":[{"index":0,"delta":{"content":"SSE 是"},"finish_reason":null}]}

data: [DONE]

🔍 SSE 逐字输出机制深度解析

流式响应的核心实现在 utils/utils.go 的 StreamChatCompletion 函数中,链路非常清晰:

步骤 动作 说明
1 设置响应头 Content-Type: text/event-stream、Cache-Control: no-cache、Connection: keep-alive
2 首包发送角色 第一个 chunk 只含 delta.role: "assistant"
3 逐段推送内容 每收到一段增量就写一个 data: {json}\n\n 事件
4 每段立即 Flush 调用 http.Flusher.Flush() 保证"逐字"可见

关键细节有两个:

  1. 每个事件后立即 Flush:写入函数 writeJSONEvent 在写完一行 data: 后马上刷新缓冲区,这是"逐字输出"体验的直接来源;
  2. 性能优化:JSON 编码使用 jsonBufferPool(sync.Pool 复用字节缓冲区),减少高频流式推送下的 GC 压力。

同时你可以用 curl 的 -N 参数,或任意 SSE 客户端(如 EventSource、OpenAI SDK 的 stream 参数)消费这条事件流。

Cursor2API-go 流式 API 调用效果演示,模型逐字输出数学题解题步骤

上图展示了通过 API 桥接后,模型逐步推送长答案的实际效果——前端无需等待整篇生成完成即可渲染。

🧩 delta.tool_calls:工具调用如何流式传输

当请求携带 tools 参数且模型决定调用工具时,流式输出就不再是纯文字,而是携带 delta.tool_calls。数据模型定义在 models/models.go:

data: {"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_xxx","type":"function","function":{"name":"get_weather","arguments":"{\"city\": \"北京\"}"}}]},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}

data: [DONE]

背后的原理值得展开讲:Cursor 上游并没有原生的 OpenAI 工具调用,Cursor2API-go 通过内部提示词 + 协议解析器搭了座桥。解析器 CursorProtocolParser 逐段接收上游纯文本增量,识别 <invoke name="...">...</invoke> 标记,将其还原成标准的 ToolCall 结构(含随机生成的 call_ 前缀 ID 和经 json.Compact 压缩的参数字符串)。

整个能力矩阵与边界(如 thinking 模型派生规则)可参阅 docs/API_CAPABILITIES.md。

Cursor2API-go 流式 API 长文本逐步推送演示,展示完整推导过程

🏁 [DONE] 机制:流如何优雅结束

[DONE] 是 OpenAI 流式协议约定的流结束标记,Cursor2API-go 的行为如下:

  1. 正常结束:内部事件通道(channel)关闭时,先补发一个带 finish_reason 的收尾 chunk——普通文本为 stop,发生过工具调用则为 tool_calls(见 StreamChatCompletion),随后由 WriteSSEEvent 写出 data: [DONE]\n\n;
  2. 上游信号:上游 Cursor 的 SSE 流中,<a href="https://link.gitcode.com/i/32f37b6cd85432861fb91e9621621efd" target="_blank">DONE] 或 type: "finish" 事件会触发解析器 flush,把缓冲中的残余内容(如未闭合的思考标签)全部吐出后再收尾(见 [consumeSSE);
  3. 错误结束:流中途出错时,客户端同样会收到 [DONE] 提前结束,完整错误由服务日志与上游错误事件(type: "error")记录。

客户端侧只需一条简单规则:收到 data: [DONE] 即停止读取,并拼接此前所有 delta.content / delta.tool_calls 得到完整结果。

⚠️ 避坑指南:3 个高频问题

① 经过 Nginx 代理时内容被"憋住"一次性输出

服务端已主动设置 X-Accel-Buffering: no 请求头(utils/utils.go)来关闭 Nginx 缓冲。如果你自建代理层,仍需确认 proxy_buffering off; 和足够长的 proxy_read_timeout,流式才不会被中间层攒批。

② 客户端中途断开会怎样?

SafeStreamWrapper(utils/utils.go)会监听 context 取消:客户端断开后立即停止向下游写数据、释放上游连接,不会泄漏 goroutine。它还内置了 panic 恢复——只要响应尚未开始写出,就会返回标准 JSON 错误体,而不是让进程崩溃。

③ 为什么首包只有 role 没有内容?

这是 OpenAI 兼容协议的惯例:首包 delta.role: "assistant" 用于让客户端提前建立消息框架,后续 chunk 只携带增量内容。消费端应忽略空 delta 的 chunk(例如收尾的空 delta)。

✅ 上手自检清单

  • [ ] 请求体中 stream: true,模型名在 GET /v1/models 返回列表内
  • [ ] 终端 curl 使用了 -N 参数,能观察到逐行推送
  • [ ] 事件流以 data: [DONE] 收尾
  • [ ] 工具调用场景中正确拼接了 delta.tool_calls 并处理 finish_reason: "tool_calls"
  • [ ] 反向代理未开启缓冲,超时时间已放宽

掌握以上机制后,你就可以把 Cursor2API-go 当作标准 OpenAI 端点接入任何支持 SSE 流式的前端或框架——逐字输出、工具调用、优雅收尾,一个都不缺。

登录后查看全文
cursor2api-go