1
0

feat: 实现统一模型 ID 机制

实现统一模型 ID 格式 (provider_id/model_name),支持跨协议模型标识和 Smart Passthrough。

核心变更:
- 新增 pkg/modelid 包:解析、格式化、校验统一模型 ID
- 数据库迁移:models 表使用 UUID 主键 + UNIQUE(provider_id, model_name) 约束
- Repository 层:FindByProviderAndModelName、ListEnabled 方法
- Service 层:联合唯一校验、provider ID 字符集校验
- Conversion 层:ExtractModelName、RewriteRequestModelName/RewriteResponseModelName 方法
- Handler 层:统一模型 ID 路由、Smart Passthrough、Models API 本地聚合
- 新增 error-responses、unified-model-id 规范

测试覆盖:
- 单元测试:modelid、conversion、handler、service、repository
- 集成测试:统一模型 ID 路由、Smart Passthrough 保真性、跨协议转换
- 迁移测试:UUID 主键、UNIQUE 约束、级联删除

OpenSpec:
- 归档 unified-model-id 变更到 archive/2026-04-21-unified-model-id
- 同步 11 个 delta specs 到 main specs
- 新增 error-responses、unified-model-id 规范文件
This commit is contained in:
2026-04-21 18:14:10 +08:00
parent 7f0f831226
commit 395887667d
73 changed files with 3360 additions and 1374 deletions

View File

@@ -0,0 +1,85 @@
# Unified Model ID
## Purpose
定义统一模型 ID 的格式、解析、格式化和校验规则,确保跨协议的模型标识一致性。
## Requirements
### Requirement: 解析统一模型 ID
系统 SHALL 提供 `ParseUnifiedModelID` 函数,将 `provider_id/model_name` 格式的字符串解析为独立的 providerID 和 modelName。
#### Scenario: 标准格式解析
- **WHEN** 传入 `"openai/gpt-4"`
- **THEN** SHALL 返回 providerID=`"openai"`, modelName=`"gpt-4"`
#### Scenario: model_name 含斜杠的解析
- **WHEN** 传入 `"azure/accounts/org-123/models/gpt-4"`
- **THEN** SHALL 在第一个 `/` 处分割,返回 providerID=`"azure"`, modelName=`"accounts/org-123/models/gpt-4"`
#### Scenario: 缺少分隔符
- **WHEN** 传入不含 `/` 的字符串(如 `"gpt-4"`
- **THEN** SHALL 返回错误
#### Scenario: 空字符串
- **WHEN** 传入空字符串
- **THEN** SHALL 返回错误
#### Scenario: 只有分隔符
- **WHEN** 传入 `"/model"``"provider/"``"/"`
- **THEN** SHALL 返回错误
#### Scenario: providerID 不符合字符集
- **WHEN** 传入 `"open-ai/gpt-4"``"open.ai/gpt-4"``"供应商/gpt-4"`providerID 含非 `[a-zA-Z0-9_]` 字符)
- **THEN** SHALL 返回错误
### Requirement: 格式化统一模型 ID
系统 SHALL 提供 `FormatUnifiedModelID` 函数,将 providerID 和 modelName 组合格式化为统一模型 ID。
#### Scenario: 格式化
- **WHEN** 传入 providerID=`"openai"`, modelName=`"gpt-4"`
- **THEN** SHALL 返回 `"openai/gpt-4"`
### Requirement: 校验供应商 ID
系统 SHALL 提供 `ValidateProviderID` 函数,校验 providerID 仅包含字母、数字、下划线。
#### Scenario: 合法 ID
- **WHEN** 传入 `"openai"`, `"deep_seek"`, `"provider01"`, `"OpenAI"`
- **THEN** SHALL 校验通过
#### Scenario: 含非法字符
- **WHEN** 传入含 `-``.``/`、空格、中文等非 `[a-zA-Z0-9_]` 字符的 ID
- **THEN** SHALL 返回错误
#### Scenario: 空字符串或过长
- **WHEN** 传入空字符串
- **THEN** SHALL 返回错误
- **WHEN** 传入超过 64 个字符的 ID
- **THEN** SHALL 返回错误
### Requirement: 校验统一模型 ID
系统 SHALL 提供 `IsValidUnifiedModelID` 函数,判断字符串是否为合法的统一模型 ID 格式。
#### Scenario: 合法 ID
- **WHEN** 传入 `"openai/gpt-4"`
- **THEN** SHALL 返回 `true`
#### Scenario: 非法 ID
- **WHEN** 传入不含 `/` 的字符串、空字符串、providerID 不符合 `[a-zA-Z0-9_]+` 的字符串
- **THEN** SHALL 返回 `false`