lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
4fc5fb4764bb9e6a1d357babdba241ef60660bdb
nex/openspec/specs/unified-model-id/spec.md
lanyuanxiaoyao 395887667d 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 规范文件
2026-04-21 18:14:10 +08:00

2.5 KiB
Raw Blame History

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
View Git Blame Copy Permalink