Qwen 家族最佳实践

如何在 QitOS 中用 native tool-call lane 运行 Qwen 与 qwen-plus。

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

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

native tool calls -> Decision.act(...) -> tool execution
fallback: json_decision_v1 -> xml_decision_v1 -> react_text_v1

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

​

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

现在 qwen family preset 会把三件事绑定在一起：

• tool schema 默认通过 api_parameter 交付
• 如果 endpoint 返回了 tool_calls，优先走 native lane
• 文本协议链继续保留，作为稳定 fallback

所以 default_protocol 仍然是 json_decision_v1，但对 Qwen 来说，它现在更准确的角色是文本 fallback，而不是最优路径本身。

​

什么时候会命中 native lane

QitOS 会在以下条件同时满足时优先走 native lane：

• 模型被解析为 qwen family preset
• harness metadata 中 native_tool_call_preferred = true
• OpenAI-compatible 响应里确实带有 tool_calls

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

​

为什么不直接照搬 Qwen-Agent 的 sentinel prompt

官方 Qwen-Agent 为“不提供原生 tool channel 的 Qwen chat 接口”设计了一套专门的 function-calling prompt。

QitOS 在 OpenAI-compatible 的 Qwen 路径里不直接照搬它，原因是：

• OpenAI-compatible serving 已经提供结构化的 tool_calls
• 保留结构化信息比先序列化回文本再解析更干净
• 这样做也更容易被未来其他支持 native tool calls 的家族复用

换句话说：

• Qwen-Agent 解决的是更一般的 “Qwen chat interface” 问题
• QitOS 这里解决的是 “同一个 harness 层里如何优先用好 OpenAI-compatible served Qwen” 的问题

​

推荐的 qwen-plus 运行方式

建议直接用旗舰 example：

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

你应该能看到 harness 摘要里有这些字段：

• family_preset: qwen
• tool_delivery: api_parameter
• native_tool_call_preferred: True
• decision_lane_preference: native_tool_calls

​

如何在 qita 里确认

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

• family preset
• prompt protocol
• tool delivery
• decision_source
• native_tool_call_used
• native_tool_call_fallback_reason

如果 endpoint 没有返回原生 tool calls，QitOS 仍然会继续运行，但 trace 中会明确告诉你它为什么回退到了 parser lane。