跳转到主要内容

​
概述

Shannon 根据以下因素自动为每个任务选择最佳 LLM 模型：
  1. 任务复杂度（在分解期间分析）
  2. 显式层级请求（model_tier 参数）
  3. 模型/提供商覆盖（model_override、provider_override）
  4. 优先级排名（在 config/models.yaml 中定义）
  5. 预算约束和 token 限制
本指南解释模型选择的工作原理以及如何控制它。

​
模型层级

Shannon 将模型组织成三个层级：
层级目标使用率特征成本范围
Small50%快速、成本优化、基础推理$0.0001-0.0002/1K 输入
Medium40%平衡能力/成本$0.002-0.006/1K 输入
Large10%重度推理、复杂任务$0.02-0.025/1K 输入
注意: 百分比是目标分布，不是强制配额。实际使用取决于您的工作负载。

​
选择流程

模型选择流程

​
优先级排名

在每个层级内，模型按优先级排名（数字越小 = 优先级越高）。Shannon 按优先级顺序尝试模型，直到成功。 来自 config/models.yaml 的示例: 
model_tiers:
  small:
    providers:
      - provider: openai
        model: gpt-5-nano-2025-08-07
        priority: 1  # 首先尝试
      - provider: anthropic
        model: claude-haiku-4-5-20251001
        priority: 2  # OpenAI 失败时的回退
      - provider: xai
        model: grok-3-mini
        priority: 3  # xAI 默认小型模型
      - provider: xai
        model: grok-4-fast-non-reasoning
        priority: 4  # 备选快速模型
回退行为:
  • 如果优先级 1 失败（速率限制、API 错误），Shannon 尝试优先级 2
  • 继续直到模型成功或所有选项耗尽
  • 失败记录到编排器日志

​
参数优先级

当多个参数指定模型选择时，优先级为：
  1. model_override（最高优先级）→ 强制特定模型
  2. provider_override → 限制为一个提供商的模型
  3. model_tier → 使用请求的层级
  4. 自动检测复杂度（最低优先级）→ 默认行为

​
顶层参数 vs 上下文参数

顶层参数总是覆盖上下文参数： 
{
  "query": "分析数据",
  "model_tier": "large",           // 顶层（胜出）
  "context": {
    "model_tier": "small"           // 上下文（被忽略）
  }
}

​
使用示例

​
自动选择（默认）

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -d '{"query": "2+2 是多少？"}'
Shannon 分析复杂度 → 选择小型层级 → 使用 gpt-5-nano-2025-08-07（优先级 1）

​
强制特定层级

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -d '{
    "query": "复杂分析任务",
    "model_tier": "large"
  }'
使用大型层级 → gpt-5.1-2025-11-01（大型层级中的优先级 1）

​
覆盖到特定模型

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -d '{
    "query": "分析",
    "model_override": "claude-sonnet-4-5-20250929"
  }'
强制使用 Anthropic Claude Sonnet，忽略层级/优先级。

​
强制提供商

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -d '{
    "query": "分析",
    "model_tier": "medium",
    "provider_override": "anthropic"
  }'
使用中型层级但仅 Anthropic 模型 → claude-sonnet-4-5-20250929

​
Python SDK 示例

from shannon import Shannon

client = Shannon(api_key="sk_test_123456")

# 自动选择
task = client.tasks.submit(query="简单任务")

# 强制层级
task = client.tasks.submit(
    query="复杂分析",
    model_tier="large"
)

# 强制模型
task = client.tasks.submit(
    query="研究任务",
    model_override="gpt-5.1-2025-11-01"
)

# 强制提供商 + 层级
task = client.tasks.submit(
    query="分析",
    model_tier="medium",
    provider_override="openai"
)

​
成本优化策略

​
1. 从小型开始，必要时升级

# 首先尝试小型层级
task = client.tasks.submit(query="分析 Q4 数据", model_tier="small")
status = client.tasks.get(task.task_id)

# 如果结果不满意，使用大型层级重试
if not_satisfactory(status.result):
    task = client.tasks.submit(query="深度分析 Q4 数据", model_tier="large")

​
2. 提供商特定优化

# 对批量任务使用更便宜的提供商
for item in bulk_data:
    client.tasks.submit(
        query=f"总结 {item}",
        model_tier="small",
        provider_override="deepseek"  # 比 OpenAI 便宜
    )

​
3. 基于会话的升级

session_id = "analysis-session-123"

# 从小型模型开始
client.tasks.submit(
    query="初步分析",
    session_id=session_id,
    model_tier="small"
)

# 使用更大的模型跟进（继承上下文）
client.tasks.submit(
    query="更深入的见解",
    session_id=session_id,
    model_tier="large"
)

​
研究分层模型架构

Shannon v0.3.0 新增。该功能在研究工作流中相比统一使用大型模型可实现 50-70% 的成本降低。
Shannon 的研究工作流会自动为不同执行阶段分配不同的模型层级，仅在质量最关键的环节使用昂贵的模型。

​
工作原理

研究阶段默认层级角色原因
探索 / 研究 Agentsmallresearch_agent信息收集以广度为导向，小型模型足够且性价比高
综合 / 最终输出large（可配置）synthesis_agent组合和推理研究结果需要更强大的模型
快速策略smallquick_research_agent强制使用小型模型并行执行，最大化速度

​
配置

综合阶段的层级可通过任务请求中的 synthesis_model_tier 或 config/shannon.yaml 进行配置： 
# config/shannon.yaml
research:
  default_research_tier: small       # 探索 Agent 的层级
  synthesis_model_tier: large        # 最终综合的层级
也可以按请求覆盖： 
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" \
  -d '{
    "query": "研究 LLM 缩放定律的影响",
    "strategy": "research",
    "context": {
      "synthesis_model_tier": "medium"
    }
  }'

​
快速研究策略

quick 策略强制所有研究 Agent 使用小型模型并行运行，优先考虑速度和成本而非深度： 
task = client.tasks.submit(
    query="快速概述最近的 ML 论文",
    strategy="quick"  # 并行执行、小型模型、quick_research_agent 角色
)

​
成本对比

示例：5 个 Agent 的研究工作流
方案模型使用预估成本
统一 large5 x large~$0.50
分层（v0.3.0）4 x small + 1 x large~$0.15-0.25
快速策略5 x small（并行）~$0.05
结果：分层架构实现 50-70% 成本降低，同时保持综合质量。

​
复杂度分析

Shannon 使用多个因素分析任务复杂度：
  • 查询长度和具体性
  • 识别的子任务数量
  • 工具使用要求
  • 所需的上下文深度
  • 推理强度（关键词如”分析”、“比较”、“综合”）
复杂度阈值（可配置）：
  • < 0.3 → 小型层级（简单问答、基础任务）
  • 0.3 - 0.7 → 中型层级（多步骤、中等推理）
  • > 0.7 → 大型层级（复杂研究、重度推理）

​
监控与调试

​
检查使用了哪个模型

TASK_ID="task-abc123"
curl http://localhost:8080/api/v1/tasks/$TASK_ID \
  -H "X-API-Key: sk_test_123456" | jq '{model_used, provider, usage}'
响应： 
{
  "model_used": "gpt-5-nano-2025-08-07",
  "provider": "openai",
  "usage": {
    "total_tokens": 245,
    "input_tokens": 150,
    "output_tokens": 95,
    "estimated_cost": 0.000053
  }
}

​
Prometheus 指标

# 按层级的模型使用
shannon_llm_requests_total{tier="small"}
shannon_llm_requests_total{tier="medium"}
shannon_llm_requests_total{tier="large"}

# 提供商分布
shannon_llm_requests_total{provider="openai"}
shannon_llm_requests_total{provider="anthropic"}

# 层级漂移（当请求的层级不可用时）
shannon_tier_drift_total{requested="large", actual="medium"}

​
编排器日志

docker compose -f deploy/compose/docker-compose.yml logs orchestrator | grep "Model selected"
查找：
  • "Model selected: gpt-5-nano-2025-08-07 (small tier, priority 1)"
  • "Falling back to priority 2: claude-haiku-4-5-20251001"
  • "Falling back to priority 3: grok-3-mini (xAI)"
  • "Tier override: user requested large → using gpt-5.1-2025-11-01"

​
配置

模型层级和优先级在 config/models.yaml 中定义： 
model_tiers:
  small:
    providers:
      - provider: openai
        model: gpt-5-nano-2025-08-07
        priority: 1
      - provider: anthropic
        model: claude-haiku-4-5-20251001
        priority: 2

selection_strategy:
  mode: priority  # priority | round-robin | least-cost
  fallback_enabled: true
  max_retries: 3
选择模式:
  • priority（默认）：按优先级顺序尝试模型
  • round-robin：在相同优先级的模型之间均匀分配负载
  • least-cost：始终选择层级中最便宜的模型

​
故障排除

​
问题：选择了错误的层级

症状: 任务使用中型层级，但您期望小型 解决方案:
  1. 在请求中显式设置 model_tier: "small"
  2. 检查编排器日志中的复杂度分数
  3. 验证查询未触发复杂度启发式（避免”深度分析”等词）

​
问题：未使用特定模型

症状: 请求 model_override: "gpt-5-pro" 但获得不同的模型 解决方案:
  1. 验证模型在 config/models.yaml 的 model_catalog 下
  2. 检查 .env 中是否设置了提供商的 API 密钥
  3. 验证模型 ID 使用规范名称（非别名）
  4. 检查编排器日志中的回退消息

​
问题：成本过高

症状: 成本高于预期 解决方案:
  1. 通过 Prometheus 检查实际层级分布
  2. 在请求中添加显式 model_tier: "small"
  3. 检查 shannon_tier_drift_total 是否有不需要的升级
  4. 在 .env 中设置 MAX_COST_PER_REQUEST 以强制预算

​
问题：速率限制

症状: 频繁的 429 错误，缓慢的回退级联 解决方案:
  1. 向层级优先级列表添加更多提供商
  2. 启用 round-robin 模式以分配负载
  3. 增加受影响提供商的 RATE_LIMIT_WINDOW
  4. 考虑更便宜的提供商（DeepSeek、Groq）作为回退

​
最佳实践

  1. 默认自动选择: 让 Shannon 的复杂度分析工作
  2. 谨慎覆盖: 仅在必要时使用 model_override
  3. 从小型开始: 为成本敏感的工作负载设置 model_tier: "small"
  4. 监控分布: 通过指标跟踪层级使用情况
  5. 配置回退: 确保每个层级有 3+ 个提供商
  6. 测试优先级顺序: 验证您首选的模型是优先级 1
  7. 预算执行: 设置 MAX_COST_PER_REQUEST 以确保安全

​
相关文档

模型 API

列出可用模型和定价

提交任务

使用模型参数提交任务

配置

环境变量和 YAML 配置

成本跟踪

查看模型使用和成本