42 lines
3.6 KiB
Markdown
42 lines
3.6 KiB
Markdown
## 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 需要新增/更新测试
|
||
- **前端**: 本次变更不涉及前端适配，前端后续统一适配
|