产品概览
OpenTrans 是什么
OpenTrans 是一个面向开发者的多协议 LLM 适配层，核心目标是把不同 provider 的请求体、响应体和流式事件收敛到统一的工程接口里，再按目标协议输出。
当前已接入的协议包括：
- OpenAI Chat Completions
- OpenAI Responses
- Anthropic Claude Messages
- Google Gemini GenerateContent
OpenTrans 适合作为以下系统中的协议层：
- API 网关
- 兼容层
- 代理层
- 模型路由层
- 多 provider 切换层
- 日志、审计、缓存前置层
它解决的核心问题
在真实项目里，不同模型供应商通常会带来三类成本：
- 请求结构不一致
- 响应结构和流式事件格式不一致
- 工具调用、图片输入、usage 字段和高级参数的兼容成本高
OpenTrans 通过“协议 -> 标准化中间结构 -> 协议”的三段式设计，把这些差异约束到一套统一模型里，让业务层尽量不用感知 provider 的外层协议细节。
你可以怎样接入
OpenTrans 主要提供三条接入路径：
1. Body -> Body 转换
适合直接处理原始 HTTP 请求体或响应体：
go
out, err := opentrans.ConvertRequestBody(body, opentrans.ProtocolOpenAI, opentrans.ProtocolClaude)
resp, err := opentrans.ConvertResponseBody(body, opentrans.ProtocolClaude, opentrans.ProtocolOpenAI)
evt, err := opentrans.ConvertStreamEventBody(body, opentrans.ProtocolResponses, opentrans.ProtocolClaude)适用场景：
- 反向代理
- API 网关
- 协议桥接服务
- 兼容层
2. 标准化中间结构接入
适合在中间层插入自己的业务逻辑：
go
req, err := opentrans.NormalizeRequest(opentrans.ProtocolOpenAI, body)
out, err := opentrans.MarshalRequest(req, opentrans.ProtocolClaude)适用场景：
- 路由策略
- 风控和安全审查
- 统一日志
- request/response 重写
- provider 特有字段透传
3. Provider 结构体直转
如果你的项目已经在使用 provider struct，而不是原始 []byte，可以直接走结构体入口：
go
req, err := opentrans.NormalizeOpenAIChatCompletionParams(openaiReq)
resp, err := opentrans.NormalizeClaudeMessage(claudeResp)
evt, err := opentrans.NormalizeResponsesStreamEvent(responsesEvt)适用场景：
- SDK 内部集成
- 已有 typed client
- 测试和 benchmark
- 避免额外 JSON 往返
仓库结构
仓库当前分为三层：
pkg/opentrans: SDK 核心实现services/opentransd: 可直接部署的 HTTP/Web 服务website: 官方文档站点
其中：
- 根目录
opentrans.go负责统一对外暴露公开 API pkg/opentrans/internal/providers/*负责协议适配实现pkg/opentrans/ginx提供 Gin 中间件封装
适用边界
OpenTrans 当前优先覆盖“跨协议稳定且常见”的能力：
- 文本消息
- 多轮对话
- 基础工具调用
- 图片输入
- 非流式响应
- SSE 文本增量事件
当前仍建议单独处理的部分包括：
- 高度 provider-specific 的高级字段
- 完整多模态输出协议
- 非标准流式控制语义
下一步阅读建议
如果你是第一次接入，建议按这个顺序阅读：