常见问题与排障

本页聚焦开发者在接入、调试和部署 OpenTrans 时最常见的问题。

转换报错

unsupported protocol

原因：

• source 或 target 传了未支持的协议名

处理方式：

• 使用 SDK 常量，如 opentrans.ProtocolOpenAI
• 服务接口里确认 source / target 使用小写协议名

当前支持值：

• openai
• responses
• claude
• gemini

body is required

原因：

• Web 服务接口没有传 body
• POST body 为空
• GET 场景没有传 body= 或 body_b64=

处理方式：

• POST /convert 直接发送 JSON body
• GET /api/convert 使用 body 或 body_b64

JSON 解析失败

原因：

• 输入不是源协议要求的 JSON 结构
• 流式事件把完整 SSE 帧误传给了 body 转换函数

处理方式：

• 对普通请求/响应，传完整 JSON body
• 对流式事件，传单个事件 payload，或使用 ginx.ConvertStreamEventBody

转换结果和预期不一致

工具调用字段丢失或不完整

先确认：

• 是否属于当前协议矩阵已支持的工具调用能力
• 是否使用了正确的源协议对象类型

建议：

• 先查阅 协议支持矩阵
• 再用 标准化模型 检查中间结构是否已经保留字段

provider 特有字段没有原样保留

这是预期范围内的情况。OpenTrans 当前优先保证跨协议稳定的公共能力，高级字段通常通过：

• Metadata
• Extra

进行保留，而不是承诺逐字段一比一映射。

Gin 中间件问题

中间件后面读不到原始请求体

这是因为请求体已经被转换并回填。后续 handler 读取到的是转换后的请求体，不是原始 body。

如果你需要同时保留原始 body，建议在进入 OpenTrans 前自己先备份一份字节流。

流式输出没被转换

先检查：

• 是否使用了 ginx.ConvertStreamEventBody
• handler 是否输出的是 SSE
• 是否在上游直接写出并提前结束了响应

SSE 行格式不稳定

当前中间件已经支持：

• CRLF
• 多行 data:
• event: / id: / comment 透传

如果你依赖更复杂的 provider 私有流式语义，建议切到 NormalizeStreamEvent / MarshalStreamEvent 做手动控制。

Web 服务问题

本地启动后访问不到页面

检查：

1. 是否成功执行 go run ./services/opentransd/cmd/opentransd
2. 端口是否被占用
3. 是否显式设置了 PORT

默认端口为 8080。

分享链接太长

OpenTrans 已经优先使用 body_b64 形式避免大量 URL 转义，但如果输入内容本身很大，链接仍然可能很长。

建议：

• 大 payload 优先使用 POST
• 分享调试样例时尽量保留最小可复现输入

文档站点问题

本地文档起不来

执行：

cd website
npm install
npm run dev

如果 node_modules 损坏，可删除后重装。

构建失败

执行：

cd website
npm run build

重点检查：

• Markdown 链接是否写错
• 新增页面是否同步加入导航
• 页面里的 fenced code block 是否闭合

接入建议

如果你在排障时不确定问题出在协议哪一层，可以按这个顺序定位：

1. 先验证源 body 是否符合源协议
2. 再验证 Normalize* 后的标准化结构是否符合预期
3. 最后验证 Marshal* 到目标协议时是否出现信息损失

这种分层排障方式通常比直接盯着最终输出更快。