Skip to content

MODEL_STANDARDIZATION.md

Latest commit

 

History

History
213 lines (164 loc) · 5.29 KB

MODEL_STANDARDIZATION.md

File metadata and controls

213 lines (164 loc) · 5.29 KB

模型配置标准化 - 完成总结

改进内容

1. 统一模型命名格式

标准格式：provider/model

anthropic/claude-3-5-sonnet-20241022
openai/gpt-4o
gemini/gemini-1.5-pro
openrouter/anthropic/claude-3.5-sonnet

2. 自动格式转换

实现了智能验证器 (config.py:237-279)，支持：

旧格式自动转换

# 冒号格式 → 斜杠格式
"openai:gpt-4o" → "openai/gpt-4o"

自动提供商检测

# 无前缀 → 自动添加提供商
"claude-3-5-sonnet-20241022" → "anthropic/claude-3-5-sonnet-20241022"
"gpt-4o" → "openai/gpt-4o"
"gemini-1.5-pro" → "gemini/gemini-1.5-pro"
"mistral-large" → "mistral/mistral-large"
"qwen-max" → "openai/qwen-max"  # 中文模型，常用自定义端点

智能识别规则

  • Claude 系列：包含 "claude" → anthropic/
  • GPT 系列：包含 "gpt" 或以 "o1"/"o3" 开头 → openai/
  • Gemini 系列：包含 "gemini" → gemini/
  • Mistral 系列：包含 "mistral" → mistral/
  • Llama 系列：包含 "llama" → together_ai/
  • 中文模型：qwen/deepseek → openai/（用于自定义端点）
  • 未知模型：默认 → openai/（用于自定义端点）

大小写不敏感

"CLAUDE-3-5-SONNET" → "anthropic/CLAUDE-3-5-SONNET"
"GPT-4O" → "openai/GPT-4O"

3. 更新配置文件

.env.example

  • 添加详细的提供商列表和示例
  • 包含 OpenRouter 配置
  • 说明自动检测功能

README.md

  • 更新配置示例为标准格式
  • 说明 LLM_API_BASE 可留空

QUICKSTART.md

  • 添加支持格式说明
  • 提供多种配置示例

4. 新增文档

docs/OPENROUTER.md

  • OpenRouter 完整配置指南
  • 常用模型列表
  • 费用和功能说明

5. 测试验证

创建完整的测试套件 (tests/core/test_model_validation.py)：

测试覆盖：

  • ✅ 标准格式（斜杠）
  • ✅ 旧格式转换（冒号）
  • ✅ 自动检测（Claude/GPT/Gemini/Mistral）
  • ✅ O 系列模型（o1/o3）
  • ✅ 中文模型（qwen/deepseek）
  • ✅ 大小写不敏感
  • ✅ 边界情况（空字符串、空格）
  • ✅ 已有前缀不修改
  • ✅ OpenRouter 支持

测试结果：9/9 通过 ✅

向后兼容性

所有改动完全向后兼容：

# 旧配置仍然有效
LLM_MODEL="claude-3-5-sonnet-20241022"  # 自动转换
LLM_MODEL="openai:gpt-4o"  # 自动转换

# 新配置推荐格式
LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"
LLM_MODEL="openai/gpt-4o"

支持的提供商

通过 LiteLLM 支持 100+ 提供商：

提供商 前缀 示例模型
Anthropic anthropic/ claude-3-5-sonnet-20241022
OpenAI openai/ gpt-4o, gpt-4-turbo, o1-preview
Google gemini/ gemini-1.5-pro, gemini-flash
Mistral mistral/ mistral-large-latest
Azure azure/ your-deployment-name
OpenRouter openrouter/ openrouter/anthropic/claude-3.5-sonnet
自定义端点 openai/ 配合 LLM_API_BASE 使用

使用建议

标准配置（推荐）

# Anthropic 直连
LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"
LLM_API_KEY="sk-ant-..."
LLM_API_BASE=""  # 留空使用默认

# OpenAI 直连
LLM_MODEL="openai/gpt-4o"
LLM_API_KEY="sk-..."
LLM_API_BASE=""  # 留空使用默认

OpenRouter 配置

LLM_MODEL="openrouter/anthropic/claude-3.5-sonnet"
LLM_API_KEY="sk-or-v1-..."
LLM_API_BASE="https://openrouter.ai/api/v1"

自定义端点

LLM_MODEL="openai/qwen-max"  # 或任意模型名
LLM_API_KEY="your-key"
LLM_API_BASE="https://your-custom-endpoint.com/v1"

技术细节

验证器实现位置

src/omni_agent/core/config.py:237-279

核心逻辑

  1. 去除首尾空格
  2. 冒号替换为斜杠（兼容旧格式）
  3. 如果已有斜杠，直接返回
  4. 否则根据模型名称自动检测提供商
  5. 大小写不敏感匹配

错误处理

  • 空字符串或纯空格：抛出 ValidationError
  • 未知模型：默认添加 openai/ 前缀（适用于自定义端点）

后续建议

可选增强

  1. 提供商能力检测：检测模型是否支持 tool calling
  2. 动态模型列表：从 LiteLLM 获取支持的模型列表
  3. 配置验证工具：CLI 工具验证配置有效性

使用监控

建议记录：

  • 使用最多的提供商
  • 自动检测的频率
  • 配置错误的类型

相关文件

配置类：

  • src/omni_agent/core/config.py - Settings 类和验证器

配置文件：

  • .env.example - 配置模板
  • docs/OPENROUTER.md - OpenRouter 指南

文档：

  • README.md - 快速开始
  • QUICKSTART.md - 详细配置

测试：

  • tests/core/test_model_validation.py - 单元测试

验证清单

  • 实现模型名称验证器
  • 支持旧格式自动转换
  • 支持自动提供商检测
  • 更新所有配置文件示例
  • 创建 OpenRouter 文档
  • 编写完整测试套件
  • 验证向后兼容性
  • 测试 OpenRouter 配置

结论

模型配置已完全标准化，支持：

  • ✅ 统一的 provider/model 格式
  • ✅ 自动格式转换和提供商检测
  • ✅ 100+ LLM 提供商支持
  • ✅ 完全向后兼容
  • ✅ 详细的文档和示例
  • ✅ 完整的测试覆盖

用户现在可以使用任意格式配置模型，系统会自动标准化为正确格式。