> ## 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 家族最佳实践

> 如何在 QitOS 中用原生工具调用通道运行 Qwen 与 qwen-plus。

在 QitOS 里，Qwen 已经不再只是默认走 JSON 的普通家族。

对于 OpenAI-compatible 的 Qwen 端点，QitOS 现在优先采用这条链路：

```text theme={null}
原生工具调用 -> Decision.act(...) -> 工具执行
后备：json_decision_v1 -> xml_decision_v1 -> react_text_v1
```

这和 Qwen-Agent 的精神是一致的：如果后端干净地暴露了函数调用，就应该优先利用它。

## v0.4 之后实际改变了什么

现在 `qwen` 家族预设（preset，预配置的模型家族默认值）会把三件事绑定在一起：

* 工具模式默认通过 `api_parameter` 交付
* 如果端点返回了 `tool_calls`，优先走原生通道
* 文本协议链继续保留，作为稳定后备

所以默认协议（protocol，模型输出的格式契约）仍然是 `json_decision_v1`，但对 Qwen 来说，它现在更准确的角色是**文本后备**，而不是最优路径本身。

## 什么时候会命中原生通道

QitOS 会在以下条件同时满足时优先走原生通道：

* 模型被解析为 `qwen` 家族预设
* 适配层（harness，负责将协议、传输层、工具交付等组合在一起的模型适配层）元数据中 `native_tool_call_preferred = true`
* OpenAI-compatible 响应里确实带有 `tool_calls`

只要其中任意一个条件不满足，QitOS 就会自动回退到原来的解析器链。

## 为什么不直接照搬 Qwen-Agent 的哨兵提示词

官方 Qwen-Agent 为不提供原生工具通道的 Qwen 聊天接口设计了一套专门的函数调用提示词。

QitOS 在 OpenAI-compatible 的 Qwen 路径里**没有照搬**它，原因是：

* OpenAI-compatible 服务已经提供结构化的 `tool_calls`
* 保留结构化信息比先序列化回文本再解析更干净
* 这样做也更容易被未来其他支持原生工具调用的家族复用

换句话说：

* Qwen-Agent 解决的是更一般的 Qwen 聊天接口问题
* QitOS 这里解决的是同一个适配层里如何优先用好 OpenAI-compatible 托管 Qwen 的问题

## 推荐的 `qwen-plus` 运行方式

建议直接用旗舰示例：

```bash theme={null}
export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

python examples/real/claude_code_agent.py \
  --model-family qwen \
  --model-name qwen-plus \
  --print-harness
```

你应该能看到适配层摘要里有这些字段：

* `family_preset: qwen`
* `tool_delivery: api_parameter`
* `native_tool_call_preferred: True`
* `decision_lane_preference: native_tool_calls`

## 如何在 qita 里确认

打开 `qita` 后，重点看这些字段：

* 家族预设
* 提示词协议
* 工具交付方式
* 决策来源
* `native_tool_call_used`
* `native_tool_call_fallback_reason`

如果端点没有返回原生工具调用，QitOS 仍然会继续运行，但追踪记录（trace）中会明确告诉你它为什么回退到了解析器（parser，将原始模型输出解析为 Decision 的组件）通道。