用预设切换模型家族

家族预设（预配置的模型家族默认值）让你只需极少代码改动就能切换模型家族。本教程展示如何构建可在多个家族上运行的智能体、如何覆盖预设、以及如何在 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 用量和费用
运行在哪里产生分歧

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

字段	默认值	含义
`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

模型配置的优先级顺序：

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

家族预设概念

理解每个预设字段的含义

模型家族矩阵

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

新增家族预设

为 QitOS 增加新的模型家族

可观测性

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

Documentation Index

​Step 1 — 用预设构建模型

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

​Step 3 — 覆盖预设

​Step 4 — 查看可用预设

​Step 5 — 在 qita 中对比运行

​推荐默认值

​命令行切换模式