Qwen 家族最佳实践

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

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

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

原生工具调用 -> 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 运行方式

建议直接用旗舰示例：

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 的组件）通道。