用预设切换模型家族

使用家族预设让同一个智能体在 Qwen、Kimi、DeepSeek 等模型家族之间切换——无需重写智能体代码。

家族预设（预配置的模型家族默认值）让你只需极少代码改动就能切换模型家族。本教程展示如何构建可在多个家族上运行的智能体、如何覆盖预设、以及如何在 qita 中对比结果。

​

Step 1 — 用预设构建模型

最快的方式是使用 build_model_for_preset：

from qitos.harness import build_model_for_preset

llm = build_model_for_preset(
    model_name="Qwen/Qwen3-8B",
    api_key="sk-...",
    base_url="https://api.siliconflow.cn/v1/",
)

它会返回一个已应用 Qwen 家族预设的完整模型对象——正确的协议、解析器、工具交付模式和上下文窗口。

​

Step 2 — 用不同家族运行同一个智能体

核心要点：智能体代码不变，只有模型构造变化：

from qitos.harness import build_model_for_preset

configs = [
    ("qwen", "Qwen/Qwen3-8B", "https://api.siliconflow.cn/v1/"),
    ("kimi", "moonshot-v1-128k", "https://api.moonshot.ai/v1/"),
    ("deepseek", "deepseek-chat", "https://api.deepseek.com/v1/"),
]

for family_id, model_name, base_url in configs:
    llm = build_model_for_preset(
        model_name=model_name,
        api_key="sk-...",
        base_url=base_url,
    )
    # agent = MyAgent(llm=llm, ...)
    # result = agent.run(task="...", max_steps=20)

每次 build_model_for_preset 调用都会解析对应家族的正确协议、解析器、工具交付和上下文策略。

​

Step 3 — 覆盖预设

当内建预设不完全符合需求时，用 preset.override() 创建自定义副本：

from dataclasses import replace
from qitos.harness import resolve_family_preset

qwen = resolve_family_preset("qwen")

# 扩展 Qwen 预设：更大的上下文窗口和不同的步数预算
custom_qwen = qwen.override(
    context_policy=replace(qwen.context_policy, context_window_hint=256_000),
    recommended_max_steps=50,
    notes="Extended context variant for long-horizon tasks",
)

override() 返回一个新的 FamilyPreset 实例——原始预设不会被修改。

​

Step 4 — 查看可用预设

用 CLI 查看所有可用预设：

qit bench presets

输出表格包含每个预设的 ID、协议、工具交付模式、上下文窗口和推荐模型。

也可以列出可用的基准测试：

qit bench list

​

Step 5 — 在 qita 中对比运行

用不同家族跑完同一个任务后，启动 qita 对比：

qita board --logdir runs

在面板视图中，选择两个运行并点击 Compare，可以看到：

• 每次运行使用的协议
• 解析器和工具交付模式
• 步数、token 用量和费用
• 运行在哪里产生分歧

这让不同预设如何影响智能体行为变得一目了然。

​

推荐默认值

黄金预设（Qwen、Kimi、MiniMax、gpt-oss、Gemma 4）包含研究基线的推荐默认值：

字段	默认值	含义
recommended_max_steps	30	建议的单次运行步数预算
recommended_max_tokens	500,000	建议的总 token 预算
recommended_retry_budget	3	每步最大 critic 重试次数
recommended_temperature	0.2	默认采样温度

这些值仅供参考——引擎不会自动应用它们。可以作为你自己实验的起点。

​

命令行切换模式

examples/real/claude_code_agent.py 示例展示了完整的 CLI 切换工作流：

# Qwen
python examples/real/claude_code_agent.py \
  --model-family qwen \
  --model-name Qwen/Qwen3-8B \
  --base-url https://api.siliconflow.cn/v1/

# Kimi
python examples/real/claude_code_agent.py \
  --model-family kimi \
  --model-name kimi-k2-0905-preview \
  --base-url https://api.moonshot.ai/v1

# DeepSeek
python examples/real/claude_code_agent.py \
  --model-family deepseek \
  --model-name deepseek-chat \
  --base-url https://api.deepseek.com/v1

模型配置的优先级顺序：

1. 显式命令行参数
2. 环境变量（QITOS_MODEL_FAMILY、QITOS_MODEL、OPENAI_BASE_URL）
3. 家族预设默认值
4. 框架后备值

家族预设概念

理解每个预设字段的含义

模型家族矩阵

查看全部 10 个内建预设及其默认值

新增家族预设

为 QitOS 增加新的模型家族

可观测性

了解预设元信息如何出现在追踪记录中