> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 用预设切换模型家族

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

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

## Step 1 — 用预设构建模型

最快的方式是使用 `build_model_for_preset`：

```python theme={null}
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 — 用不同家族运行同一个智能体

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

```python theme={null}
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()` 创建自定义副本：

```python theme={null}
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 查看所有可用预设：

```bash theme={null}
qit bench presets
```

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

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

```bash theme={null}
qit bench list
```

## Step 5 — 在 qita 中对比运行

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

```bash theme={null}
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 切换工作流：

```bash theme={null}
# 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. 框架后备值

<CardGroup cols={2}>
  <Card title="家族预设概念" icon="cube" href="/zh/concepts/family-presets">
    理解每个预设字段的含义
  </Card>

  <Card title="模型家族矩阵" icon="table" href="/zh/reference/model-family-matrix">
    查看全部 10 个内建预设及其默认值
  </Card>

  <Card title="新增家族预设" icon="plus" href="/zh/guides/add-a-family-preset">
    为 QitOS 增加新的模型家族
  </Card>

  <Card title="可观测性" icon="chart-line" href="/zh/guides/observability">
    了解预设元信息如何出现在追踪记录中
  </Card>
</CardGroup>