3.6 KiB
3.6 KiB
Why
当前网关直接透传上游供应商的原始模型名称（如 gpt-4、claude-3-opus），无法在多供应商场景下唯一标识一个模型。不同供应商可能存在同名模型，客户端无法区分应路由到哪个供应商。网关作为屏蔽供应商差异的统一入口，需要定义自有的模型标识体系，让客户端通过统一的 model ID 访问任意供应商的模型，同时拦截 /v1/models 等模型查询接口，聚合所有供应商的模型信息返回。
What Changes
- BREAKING: 引入统一模型 ID 格式
provider_id/model_name（如openai/gpt-4），所有代理接口（Chat、Embeddings、Rerank）的model字段必须使用此格式 - BREAKING:
models表主键id改为 UUID 自动生成（不再由用户提供），model_name字段语义保持不变（存储上游供应商模型名称），新增UNIQUE(provider_id, model_name)联合唯一约束 - BREAKING:
provider_id限制为[a-zA-Z0-9_]+字符集，禁止特殊字符 GET /v1/models改为从数据库聚合返回所有已启用模型，不再透传到上游供应商GET /v1/models/{unified_id}改为从数据库查询返回模型详情，不再透传到上游供应商- 同协议透传改为 Smart Passthrough：通过
json.RawMessage最小化改写 model 字段，保持其余参数完全保真 - 跨协议转换路径：通过 canonical 层面 modelOverride 参数覆写响应 model 字段
- 管理 API (
/api/models) 请求体字段适配，响应中新增unified_id字段 - 新增
pkg/modelid工具包，提供统一模型 ID 的解析、格式化、校验 - ProtocolAdapter 接口新增
ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName方法，协议无关地处理 model 字段
Capabilities
New Capabilities
unified-model-id: 统一模型 ID 的解析、格式化、校验工具包，以及provider_id字符集约束
Modified Capabilities
model-management: 模型表结构调整（id 改 UUID 自动生成、新增联合唯一约束），CRUD 接口字段变更（创建不再提供 id）provider-management: provider_id 创建时增加字符集校验（[a-zA-Z0-9_]+）unified-proxy-handler: 统一模型 ID 解析路由、Models/ModelInfo 接口改为本地聚合、同协议 Smart Passthrough、跨协议 modelOverride 覆写conversion-engine: 跨协议场景下 ConvertHttpResponse 支持 model 覆写参数protocol-adapter-openai: isModelInfoPath 适配含/路径、新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelNameprotocol-adapter-anthropic: isModelInfoPath 适配含/路径、新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelNamerequest-validation: provider_id 字符集校验规则、模型创建校验适配database-migration: models 表 schema 变更迁移（DROP + CREATE 重建）usage-statistics: 明确统计记录使用 providerID + modelName 的上游模型名
Impact
- 数据库: models 表 schema 变更（DROP + CREATE 重建）
- API 兼容性: 代理接口 model 字段格式为 BREAKING CHANGE，需客户端适配
- 管理 API:
/api/models请求体变更（创建不再提供 id，自动生成 UUID），响应新增 unified_id 字段 - 代码模块: domain、repository、service、handler、conversion、adapter 层均有改动
- 测试: routing service、proxy handler、adapter、model handler 需要新增/更新测试
- 前端: 本次变更不涉及前端适配，前端后续统一适配