## 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、RewriteResponseModelName - `protocol-adapter-anthropic`: isModelInfoPath 适配含 `/` 路径、新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName - `request-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 需要新增/更新测试 - **前端**: 本次变更不涉及前端适配,前端后续统一适配