docs: 添加 openspec 变更记录，归档已完成变更并添加 unified-model-id 提案
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 跨协议响应转换支持 model 覆写
|
||||
|
||||
ConversionEngine SHALL 在跨协议响应转换时支持 model 字段覆写。
|
||||
|
||||
#### Scenario: ConvertHttpResponse 接收 modelOverride 参数
|
||||
|
||||
- **WHEN** 调用 `ConvertHttpResponse` 时传入 `modelOverride` 参数（跨协议场景，非空字符串）
|
||||
- **THEN** SHALL 在解码上游响应到 canonical 后，将 `Model` 字段设为 `modelOverride`
|
||||
- **THEN** SHALL 使用覆写后的 canonical 编码为客户端协议格式
|
||||
|
||||
#### Scenario: modelOverride 为空
|
||||
|
||||
- **WHEN** 调用 `ConvertHttpResponse` 时 `modelOverride` 为空字符串
|
||||
- **THEN** SHALL NOT 覆写 canonical 的 Model 字段，保持上游原始值
|
||||
|
||||
#### Scenario: Chat 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Chat 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
#### Scenario: Embedding 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Embedding 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalEmbeddingResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
#### Scenario: Rerank 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Rerank 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalRerankResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
### Requirement: 跨协议流式转换支持 model 覆写
|
||||
|
||||
ConversionEngine SHALL 在跨协议流式转换时支持 model 字段覆写。
|
||||
|
||||
#### Scenario: CreateStreamConverter 接收 modelOverride 参数
|
||||
|
||||
- **WHEN** 调用 `CreateStreamConverter` 时传入 `modelOverride` 参数（跨协议场景）
|
||||
- **THEN** SHALL 在流式 canonical 事件中将 `Model` 字段设为 `modelOverride`
|
||||
|
||||
### Requirement: TargetProvider 字段语义
|
||||
|
||||
TargetProvider 的 ModelName 字段 SHALL 存储上游供应商的模型名称（即 `model_name` 字段值），语义保持不变。
|
||||
|
||||
#### Scenario: encoder 使用 TargetProvider.ModelName
|
||||
|
||||
- **WHEN** 协议适配器编码请求时
|
||||
- **THEN** SHALL 使用 `TargetProvider.ModelName` 作为发给上游的 `model` 字段值（值为路由结果中的 model_name）
|
||||
@@ -0,0 +1,13 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: models 表 schema 变更
|
||||
|
||||
系统 SHALL 通过迁移脚本重建 models 表结构（服务未上线，无需考虑数据迁移）。
|
||||
|
||||
#### Scenario: 迁移后 models 表结构
|
||||
|
||||
- **WHEN** 执行迁移
|
||||
- **THEN** SHALL 先 DROP 已有的 models 表（无旧数据）
|
||||
- **THEN** SHALL CREATE 新的 models 表，包含字段：id（TEXT PRIMARY KEY）、provider_id（TEXT NOT NULL）、model_name（TEXT NOT NULL）、enabled（INTEGER DEFAULT 1）、created_at（DATETIME）
|
||||
- **THEN** SHALL 存在 UNIQUE(provider_id, model_name) 约束
|
||||
- **THEN** SHALL 存在 FOREIGN KEY (provider_id) REFERENCES providers(id) ON DELETE CASCADE
|
||||
105
openspec/changes/unified-model-id/specs/model-management/spec.md
Normal file
105
openspec/changes/unified-model-id/specs/model-management/spec.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 创建模型配置
|
||||
|
||||
网关 SHALL 允许为供应商创建新的模型配置。
|
||||
|
||||
#### Scenario: 使用有效数据创建模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带有效的模型数据（provider_id, model_name），不提供 id 字段
|
||||
- **THEN** 网关 SHALL 自动生成 UUID 作为模型 id
|
||||
- **THEN** 网关 SHALL 在数据库中创建新的模型记录
|
||||
- **THEN** 网关 SHALL 返回创建的模型，状态码为 201
|
||||
- **THEN** 模型 SHALL 默认启用
|
||||
- **THEN** 返回的模型 SHALL 包含 `unified_id` 字段，值为 `{provider_id}/{model_name}`
|
||||
|
||||
#### Scenario: 使用不存在的供应商创建模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带不存在的 provider_id
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示供应商不存在
|
||||
|
||||
#### Scenario: 创建重复模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带已存在的 provider_id + model_name 组合
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
- **THEN** 错误 SHALL 指示该供应商下已存在相同模型
|
||||
|
||||
### Requirement: 列出所有模型
|
||||
|
||||
网关 SHALL 允许获取所有模型配置。
|
||||
|
||||
#### Scenario: 成功列出模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 GET 请求
|
||||
- **THEN** 网关 SHALL 返回所有模型的列表
|
||||
- **THEN** 每个模型 SHALL 包含 id, provider_id, model_name, unified_id, enabled, created_at
|
||||
|
||||
**变更说明：** 响应新增 unified_id 字段，移除旧语义的 id 自定义输入。
|
||||
|
||||
### Requirement: 按供应商列出模型
|
||||
|
||||
网关 SHALL 允许获取特定供应商的模型。
|
||||
|
||||
#### Scenario: 列出存在供应商的模型
|
||||
|
||||
- **WHEN** 向 `/api/models?provider_id=<provider_id>` 发送 GET 请求
|
||||
- **THEN** 网关 SHALL 返回指定供应商的模型列表
|
||||
- **THEN** 每个模型 SHALL 包含 unified_id 字段
|
||||
|
||||
### Requirement: 更新模型配置
|
||||
|
||||
网关 SHALL 允许更新现有模型配置。
|
||||
|
||||
#### Scenario: 使用有效数据更新模型
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 PUT 请求，携带有效的模型数据
|
||||
- **THEN** 网关 SHALL 更新数据库中的模型记录
|
||||
- **THEN** 网关 SHALL 返回更新后的模型
|
||||
- **THEN** 返回的模型 SHALL 包含更新后的 unified_id
|
||||
|
||||
#### Scenario: 更新模型为重复组合
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 PUT 请求，更新 provider_id 或 model_name 导致与已有记录重复
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
|
||||
### Requirement: 删除模型配置
|
||||
|
||||
网关 SHALL 允许删除模型配置。
|
||||
|
||||
#### Scenario: 删除存在的模型
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 DELETE 请求，携带有效的模型 ID
|
||||
- **THEN** 网关 SHALL 删除模型记录
|
||||
- **THEN** 网关 SHALL 返回状态码 204 (No Content)
|
||||
|
||||
### Requirement: 使用 service 层处理业务逻辑
|
||||
|
||||
Handler SHALL 通过 ModelService 处理业务逻辑。
|
||||
|
||||
#### Scenario: 调用 service 方法
|
||||
|
||||
- **WHEN** handler 收到请求
|
||||
- **THEN** SHALL 调用对应的 ModelService 方法（Create、Get、List、Update、Delete）
|
||||
- **THEN** SHALL 使用 domain.Model 类型
|
||||
- **THEN** Create 时 SHALL 调用 `uuid.New()` 生成 id
|
||||
|
||||
#### Scenario: 供应商验证和唯一性校验
|
||||
|
||||
- **WHEN** 创建或更新模型
|
||||
- **THEN** SHALL 在 service 层验证供应商存在
|
||||
- **THEN** SHALL 在 service 层验证 provider_id + model_name 联合唯一
|
||||
|
||||
### Requirement: 使用 repository 层访问数据
|
||||
|
||||
Service SHALL 通过 ModelRepository 访问数据。
|
||||
|
||||
#### Scenario: 联合查询
|
||||
|
||||
- **WHEN** service 需要按 provider 和 model_name 查询模型
|
||||
- **THEN** SHALL 调用 `FindByProviderAndModelName(providerID, modelName)` 方法
|
||||
|
||||
#### Scenario: 查询所有启用模型
|
||||
|
||||
- **WHEN** proxy handler 需要聚合模型列表
|
||||
- **THEN** SHALL 调用 `ListEnabled()` 方法，返回所有 enabled 的模型（关联 enabled 的供应商）
|
||||
@@ -0,0 +1,71 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 模型详情路径识别
|
||||
|
||||
Anthropic 适配器 SHALL 正确识别包含统一模型 ID 的模型详情路径。
|
||||
|
||||
#### Scenario: 含斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/anthropic/claude-3-opus`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 含多段斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/azure/deployments/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 模型列表路径不受影响
|
||||
|
||||
- **WHEN** 路径为 `/v1/models`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModels`
|
||||
|
||||
### Requirement: 提取统一模型 ID
|
||||
|
||||
Anthropic 适配器 SHALL 从路径中提取统一模型 ID。
|
||||
|
||||
#### Scenario: 标准路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/anthropic/claude-3-opus")`
|
||||
- **THEN** SHALL 返回 `"anthropic/claude-3-opus"`
|
||||
|
||||
#### Scenario: 复杂路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/azure/accounts/org/models/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"azure/accounts/org/models/gpt-4"`
|
||||
|
||||
#### Scenario: 非模型详情路径
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models")`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 从请求体提取 model
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 从请求体中提取 model 值。
|
||||
|
||||
#### Scenario: Chat 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeChat)`，body 为 `{"model":"anthropic/claude-3-opus","messages":[...]}`
|
||||
- **THEN** SHALL 返回 `"anthropic/claude-3-opus"`
|
||||
|
||||
#### Scenario: 无 model 字段
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, ifaceType)`，body 中不含 model 字段
|
||||
- **THEN** SHALL 返回空字符串，不返回错误
|
||||
|
||||
### Requirement: 最小化改写请求体 model 字段
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写请求体中的 model 字段，其余字段保持原始 bytes。
|
||||
|
||||
#### Scenario: 请求体 model 改写（统一 ID → 上游名）
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "claude-3-opus-20240229", InterfaceTypeChat)`
|
||||
- **THEN** SHALL 将请求体中 model 字段替换为 `"claude-3-opus-20240229"`，其余字段原样保留
|
||||
|
||||
### Requirement: 最小化改写响应体 model 字段
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写响应体中的 model 字段，其余字段保持原始 bytes。请求体和响应体的 model 字段位置可能不同，各自独立实现。
|
||||
|
||||
#### Scenario: 响应体 model 改写（上游名 → 统一 ID）
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "anthropic/claude-3-opus", InterfaceTypeChat)`
|
||||
- **THEN** SHALL 将响应体中 model 字段替换为 `"anthropic/claude-3-opus"`，其余字段原样保留
|
||||
@@ -0,0 +1,89 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 模型详情路径识别
|
||||
|
||||
OpenAI 适配器 SHALL 正确识别包含统一模型 ID 的模型详情路径。
|
||||
|
||||
#### Scenario: 含斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/openai/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 含多段斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/azure/accounts/org-123/models/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 模型列表路径不受影响
|
||||
|
||||
- **WHEN** 路径为 `/v1/models`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModels`
|
||||
|
||||
### Requirement: 提取统一模型 ID
|
||||
|
||||
OpenAI 适配器 SHALL 从路径中提取统一模型 ID。
|
||||
|
||||
#### Scenario: 标准路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/openai/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
#### Scenario: 复杂路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/azure/accounts/org/models/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"azure/accounts/org/models/gpt-4"`
|
||||
|
||||
#### Scenario: 非模型详情路径
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models")`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 从请求体提取 model
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 从请求体中提取 model 值。
|
||||
|
||||
#### Scenario: Chat 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeChat)`，body 为 `{"model":"openai/gpt-4","messages":[...]}`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
#### Scenario: Embedding 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeEmbeddings)`，body 为 `{"model":"openai/text-embedding-3","input":"text"}`
|
||||
- **THEN** SHALL 返回 `"openai/text-embedding-3"`
|
||||
|
||||
#### Scenario: 无 model 字段
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, ifaceType)`，body 中不含 model 字段
|
||||
- **THEN** SHALL 返回空字符串，不返回错误
|
||||
|
||||
### Requirement: 最小化改写请求体 model 字段
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写请求体中的 model 字段，其余字段保持原始 bytes。
|
||||
|
||||
#### Scenario: 请求体 model 改写（统一 ID → 上游名）
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeChat)`，body 为 `{"model":"openai/gpt-4","messages":[...],"some_param":"value"}`
|
||||
- **THEN** SHALL 返回 `{"model":"gpt-4","messages":[...],"some_param":"value"}`
|
||||
- **THEN** 除 model 外的字段 SHALL 保持原始 bytes 不变
|
||||
|
||||
#### Scenario: 不同 InterfaceType 的请求改写
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeEmbeddings)`
|
||||
- **THEN** SHALL 按 Embedding 接口的请求体 model 字段位置进行改写
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeRerank)`
|
||||
- **THEN** SHALL 按 Rerank 接口的请求体 model 字段位置进行改写
|
||||
|
||||
### Requirement: 最小化改写响应体 model 字段
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写响应体中的 model 字段，其余字段保持原始 bytes。请求体和响应体的 model 字段位置可能不同，各自独立实现。
|
||||
|
||||
#### Scenario: 响应体 model 改写（上游名 → 统一 ID）
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "openai/gpt-4", InterfaceTypeChat)`，body 为上游 Chat 响应
|
||||
- **THEN** SHALL 将 model 字段替换为 `"openai/gpt-4"`，其余字段原样保留
|
||||
|
||||
#### Scenario: 不同 InterfaceType 的响应改写
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "openai/gpt-4", InterfaceTypeEmbeddings)`
|
||||
- **THEN** SHALL 按 Embedding 接口的响应体 model 字段位置进行改写
|
||||
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 创建供应商配置
|
||||
|
||||
网关 SHALL 允许通过管理 API 创建新的供应商配置。
|
||||
|
||||
#### Scenario: 使用有效数据创建供应商
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带有效的供应商数据（id, name, api_key, base_url, protocol）
|
||||
- **THEN** 网关 SHALL 在数据库中创建新的供应商记录
|
||||
- **THEN** 网关 SHALL 返回创建的供应商，状态码为 201
|
||||
- **THEN** 供应商 SHALL 默认启用
|
||||
- **THEN** protocol 字段 SHALL 默认为 "openai"
|
||||
|
||||
#### Scenario: 使用重复 ID 创建供应商
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带已存在的 ID
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
|
||||
#### Scenario: 创建供应商时缺少必需字段
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，缺少必需字段（id, name, api_key 或 base_url）
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示缺少哪些字段
|
||||
|
||||
#### Scenario: 创建供应商时 ID 包含非法字符
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，id 包含非 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示 id 仅允许字母、数字、下划线
|
||||
|
||||
#### Scenario: 创建供应商时 ID 过长
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，id 长度超过 64
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 供应商 ID 校验
|
||||
|
||||
创建供应商时，SHALL 对 `id` 字段进行字符集校验。
|
||||
|
||||
#### Scenario: 合法字符集
|
||||
|
||||
- **WHEN** 创建供应商，id 仅包含 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** SHALL 校验通过
|
||||
|
||||
#### Scenario: 非法字符
|
||||
|
||||
- **WHEN** 创建供应商，id 包含 `-`、`.`、`/`、空格、中文等非 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
|
||||
#### Scenario: 长度限制
|
||||
|
||||
- **WHEN** 创建供应商，id 长度超过 64
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
|
||||
### Requirement: 模型创建校验
|
||||
|
||||
创建模型时，SHALL 对 `provider_id` + `model_name` 进行联合唯一性校验。
|
||||
|
||||
#### Scenario: 正常创建
|
||||
|
||||
- **WHEN** 创建模型，provider_id 存在且 provider_id + model_name 组合唯一
|
||||
- **THEN** SHALL 校验通过
|
||||
|
||||
#### Scenario: 联合唯一冲突
|
||||
|
||||
- **WHEN** 创建模型，provider_id + model_name 组合已存在
|
||||
- **THEN** SHALL 返回 409 错误
|
||||
|
||||
#### Scenario: model_name 为空
|
||||
|
||||
- **WHEN** 创建模型，未提供 model_name
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
@@ -0,0 +1,79 @@
|
||||
## ADDED 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`
|
||||
@@ -0,0 +1,123 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 代理请求路由
|
||||
|
||||
ProxyHandler SHALL 使用统一模型 ID 路由所有代理请求。
|
||||
|
||||
#### Scenario: 提取统一模型 ID
|
||||
|
||||
- **WHEN** 收到 Chat、Embeddings 或 Rerank 接口的 POST 请求（含请求体）
|
||||
- **THEN** SHALL 调用客户端协议 adapter 的 `ExtractModelName(body, ifaceType)` 提取 model 值
|
||||
- **THEN** SHALL 调用 `ParseUnifiedModelID` 解析得到 providerID 和 modelName
|
||||
- **THEN** SHALL 调用 `RoutingService.RouteByModelName(providerID, modelName)` 路由
|
||||
|
||||
#### Scenario: GET 请求或无请求体
|
||||
|
||||
- **WHEN** 收到 GET 请求或请求体为空
|
||||
- **THEN** SHALL 返回错误响应，状态码为 400，提示缺少 model 字段
|
||||
|
||||
#### Scenario: 无效的统一模型 ID
|
||||
|
||||
- **WHEN** 请求体中 `model` 字段不是有效的统一模型 ID 格式
|
||||
- **THEN** SHALL 返回错误响应，状态码为 400
|
||||
|
||||
#### Scenario: 模型不存在
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，数据库中找不到对应的 provider_id + model_name 组合
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的模型 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 供应商已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的供应商 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
### Requirement: 同协议 Smart Passthrough
|
||||
|
||||
当客户端协议与供应商协议相同时，ProxyHandler SHALL 使用 Smart Passthrough 处理 Chat、Embedding、Rerank 请求。
|
||||
|
||||
#### Scenario: 同协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为非流式请求
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteRequestModelName(body, modelName, ifaceType)` 将请求体中 model 从统一 ID 改写为上游模型名
|
||||
- **THEN** SHALL 构建 URL 和 Headers（同当前透传逻辑）
|
||||
- **THEN** SHALL 发送改写后的请求体到上游
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteResponseModelName(resp.Body, unifiedModelID, ifaceType)` 将响应中 model 从上游名改写为统一 ID
|
||||
- **THEN** SHALL NOT 对 body 做全量 decode → encode，保持未改写字段的原始 bytes
|
||||
|
||||
#### Scenario: 同协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 对请求体做 `RewriteRequestModelName` 改写 model 字段
|
||||
- **THEN** SHALL 逐 SSE chunk 调用 `RewriteResponseModelName` 改写响应中 model 字段
|
||||
- **THEN** SHALL NOT 对 chunk 做全量 decode → encode
|
||||
|
||||
#### Scenario: Smart Passthrough 保真性
|
||||
|
||||
- **WHEN** 客户端发送含未知参数的请求（如 `{"model":"openai/gpt-4","some_new_param":"value"}`）
|
||||
- **THEN** 上游 SHALL 收到 `{"model":"gpt-4","some_new_param":"value"}`
|
||||
- **THEN** `some_new_param` SHALL 保持原始值不变，不丢失、不改变类型
|
||||
|
||||
### Requirement: 跨协议完整转换
|
||||
|
||||
当客户端协议与供应商协议不同时，ProxyHandler SHALL 使用全量转换路径。
|
||||
|
||||
#### Scenario: 跨协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 != 供应商协议
|
||||
- **THEN** SHALL 走 `ConvertHttpRequest` 全量转换，encoder 中 provider.ModelName 覆盖 model
|
||||
- **THEN** SHALL 走 `ConvertHttpResponse` 全量转换，modelOverride 参数覆写 canonical.Model
|
||||
|
||||
#### Scenario: 跨协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 != 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 走 `CreateStreamConverter` 全量转换，modelOverride 参数覆写流式 canonical 事件中的 Model
|
||||
|
||||
### Requirement: 模型列表本地聚合
|
||||
|
||||
ProxyHandler SHALL 从数据库聚合返回模型列表，不再透传上游。
|
||||
|
||||
#### Scenario: GET /v1/models
|
||||
|
||||
- **WHEN** 收到 `GET /{protocol}/v1/models` 请求
|
||||
- **THEN** SHALL 从数据库查询所有 enabled 的模型（关联 enabled 的供应商）
|
||||
- **THEN** SHALL 组装 `CanonicalModelList`，每个模型的 ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 无可用模型
|
||||
|
||||
- **WHEN** 数据库中没有 enabled 的模型
|
||||
- **THEN** SHALL 返回空列表
|
||||
|
||||
### Requirement: 模型详情本地查询
|
||||
|
||||
ProxyHandler SHALL 从数据库查询返回模型详情，不再透传上游。
|
||||
|
||||
#### Scenario: GET /v1/models/{unified_id}
|
||||
|
||||
- **WHEN** 收到 `GET /{protocol}/v1/models/{provider_id}/{model_name}` 请求
|
||||
- **THEN** SHALL 调用 adapter 的 `ExtractUnifiedModelID` 提取统一模型 ID
|
||||
- **THEN** SHALL 解析统一模型 ID 得到 providerID 和 modelName
|
||||
- **THEN** SHALL 从数据库查询对应的模型和供应商
|
||||
- **THEN** SHALL 组装 `CanonicalModelInfo`，ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 模型详情不存在
|
||||
|
||||
- **WHEN** 统一模型 ID 对应的模型不存在或已禁用
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
### Requirement: 统计记录
|
||||
|
||||
ProxyHandler SHALL 使用 providerID 和 modelName 记录使用统计。
|
||||
|
||||
#### Scenario: 异步记录统计
|
||||
|
||||
- **WHEN** 代理请求成功完成
|
||||
- **THEN** SHALL 异步调用 `StatsService.Record(providerID, modelName)`
|
||||
@@ -0,0 +1,16 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用统计记录统一模型标识
|
||||
|
||||
系统 SHALL 使用 providerID 和 modelName（上游模型名）记录使用统计。
|
||||
|
||||
#### Scenario: 代理请求统计记录
|
||||
|
||||
- **WHEN** 代理请求成功完成
|
||||
- **THEN** SHALL 记录 provider_id 和 model_name 到 usage_stats 表（参数来自路由结果）
|
||||
- **THEN** SHALL 异步执行，不阻塞响应
|
||||
|
||||
#### Scenario: 查询统计
|
||||
|
||||
- **WHEN** 查询统计数据
|
||||
- **THEN** 支持按 provider_id 和 model_name 过滤
|
||||
Reference in New Issue
Block a user