标准化模型

OpenTrans 对外统一暴露三类核心标准化结构：

• Request
• Response
• StreamEvent

它们的设计目标不是完全复制某一家 provider 的协议，而是提供一套足够稳定、适合工程整合的中间表示。

Request

Request 表示统一后的请求结构。

type Request struct {
	Model       string
	Messages    []Message
	Temperature *float64
	TopP        *float64
	MaxTokens   *int
	Stream      bool
	Tools       []Tool
	Metadata    map[string]any
	Extra       map[string]any
}

字段说明

字段	含义	说明
Model	目标模型名	例如 gpt-4.1-mini
Messages	统一消息数组	多轮上下文主入口
Temperature	采样温度	可为空
TopP	nucleus sampling 参数	可为空
MaxTokens	最大输出 token 数	可为空
Stream	是否流式输出	对应多数 provider 的 stream 开关
Tools	工具定义数组	用于函数/工具调用
Metadata	通用元信息	适合附加内部系统字段
Extra	未标准化扩展字段	适合暂存 provider 特有能力

Message

type Message struct {
	Role    string
	Content []ContentPart
	Name    string
}

常见 Role：

• system
• user
• assistant
• tool

ContentPart

ContentPart 是请求消息、响应输出和流式增量共用的统一内容单元。

type ContentPart struct {
	Type      string
	Text      string
	ImageURL  string
	MIMEType  string
	Data      string
	CallID    string
	Name      string
	Arguments json.RawMessage
	Result    json.RawMessage
}

常见类型

Type	用途	常用字段
text	文本内容	Text
image_url	图片 URL 输入	ImageURL
image_base64	Base64 图片输入	MIMEType、Data
tool_call	工具调用	CallID、Name、Arguments
tool_result	工具结果	CallID、Name、Result

Tool

type Tool struct {
	Name        string
	Description string
	Parameters  json.RawMessage
}

说明：

• Parameters 通常承载 JSON Schema 风格结构
• OpenTrans 主要保证工具定义能参与跨协议转换，不承诺完全复制 provider 私有扩展字段

Response

Response 表示统一后的非流式响应：

type Response struct {
	ID         string
	Model      string
	Role       string
	Output     []ContentPart
	StopReason string
	Usage      *Usage
	Metadata   map[string]any
	Extra      map[string]any
}

字段说明

字段	含义
ID	响应 ID
Model	返回模型名
Role	通常为 assistant
Output	统一输出内容
StopReason	停止原因
Usage	token 使用量
Metadata	通用元信息
Extra	未标准化扩展字段

Usage

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}

说明：

• 不同 provider 的 usage 命名不同，OpenTrans 会尽量归并到统一字段
• 某些 provider 如果缺少对应值，字段可能为零值

StreamEvent

StreamEvent 表示统一后的流式事件结构：

type StreamEvent struct {
	ID         string
	Model      string
	Type       string
	Role       string
	Delta      *ContentPart
	StopReason string
	Usage      *Usage
	Sequence   int
	Metadata   map[string]any
}

内置事件类型

• response_start
• content_delta
• response_stop
• usage

设计说明

• Delta 用于描述流式增量内容
• Sequence 可用于表达事件顺序，但不是所有 provider 都会稳定提供
• Metadata 用来保留一些中间层或 provider 附带信息

为什么要有 Metadata 和 Extra

OpenTrans 的目标不是把所有 provider 全部压成最小公共子集，否则很多工程信息会在转换过程中丢失。

因此：

• Metadata 更适合业务层附加信息
• Extra 更适合暂存未标准化协议字段

如果你正在做产品级网关，这两个字段通常会非常有用。

推荐使用方式

如果你需要：

• 做路由判断
• 插入日志
• 统一审计
• 改写工具定义
• 增补内部字段

建议使用 Normalize* -> 操作标准化结构 -> Marshal* 这一条链路。