用 Qwen3-30B-A3B-Thinking-2507-AWQ 搭建 Agent:Qwen-Agent + MCP 工具调用实战教程
用 Qwen3-30B-A3B-Thinking-2507-AWQ 搭建 Agent:Qwen-Agent + MCP 工具调用实战教程
Qwen3-30B-A3B-Thinking-2507-AWQ 是 Qwen3 混合专家(MoE)思考模型的 4-bit AWQ 量化版。本教程带你三步搭建一个支持工具调用的 Agent:vLLM 部署推理服务 → 用 Qwen-Agent 接入模型 → 通过 MCP 扩展工具,全程命令可直接复制使用。
为什么选它来做 Agent 🎯
这个模型对"智能体"场景有几个天生的优势,理解后再动手会更明白每一步为什么这么做:
| 特性 | 说明 | 对 Agent 的意义 |
|---|---|---|
| 30.5B 总参 / 3.3B 激活 | MoE 架构,128 个专家中每 token 只激活 8 个 | 推理快、成本低,适合多轮工具调用 |
| 纯思考(Thinking)模式 | 2507 版本强化了推理与工具使用能力 | 复杂任务会先"想清楚"再调工具 |
| 256K 原生上下文 | 支持超长上下文 | 长对话、长文档 Agent 不丢信息 |
| AWQ 4-bit 量化 | 模型文件约 16GB,见 model.safetensors.index.json | 消费级/小集群也能部署 |
| 量化细节 | quant_method: awq、4 bits、group_size 128,配置在 config.json |
部署时注意框架版本 |
💡 Agent 能力官方基准中,BFCL-v3 工具调用得分 72.4、TAU 系列明显领先同档模型(数据见 README.md 的 Performance 表格),这也是官方推荐用它做 Agent 的原因。
第一步:下载模型并部署推理服务 📦
下载模型文件
方式一:用 Hugging Face Hub 一行下载(推荐,支持断点续传):
from huggingface_hub import snapshot_download
snapshot_download('QuantTrio/Qwen3-30B-A3B-Thinking-2507-AWQ', cache_dir="your_local_path")
方式二:直接 git clone 仓库:
git clone https://gitcode.com/hf_mirrors/QuantTrio/Qwen3-30B-A3B-Thinking-2507-AWQ
下载完成后目录中应有 4 个分片权重文件(model-00001-of-00004.safetensors、model-00002-of-00004.safetensors、model-00003-of-00004.safetensors、model-00004-of-00004.safetensors),以及分词器文件 tokenizer.json 和 tokenizer_config.json 等。
最快启动方法:vLLM 单节点部署 ⚡
依赖版本锁定 vllm==0.10.0(见 README.md)。完整启动命令:
CONTEXT_LENGTH=32768
vllm serve \
QuantTrio/Qwen3-30B-A3B-Thinking-2507-AWQ \
--served-model-name Qwen3-30B-A3B-Thinking-2507-AWQ \
--enable-expert-parallel \
--swap-space 16 \
--max-num-seqs 512 \
--max-model-len $CONTEXT_LENGTH \
--max-seq-len-to-capture $CONTEXT_LENGTH \
--gpu-memory-utilization 0.9 \
--tensor-parallel-size 4 \
--trust-remote-code \
--disable-log-requests \
--host 0.0.0.0 \
--port 8000
两个最容易踩的坑:
- 必须加
--enable-expert-parallel:否则专家张量无法被 TP 整除,2 卡 4 卡都要加,少了会直接启动失败。 - 上下文长度:32768 是稳妥起点;显存够的话官方建议 131072 以上,让思考过程有足够的生成空间。
服务启动后,OpenAI 兼容接口位于 http://localhost:8000/v1,供下一步的 Qwen-Agent 调用。
第二步:用 Qwen-Agent 搭建工具调用 Agent 🛠️
Qwen-Agent 内部封装了 Qwen 系列的工具调用模板与解析器,能"代劳"思考内容解析、工具调用格式处理这些繁琐工作,代码量很少。
安装并配置 Agent
pip install qwen-agent
核心代码结构如下(完整示例在 README.md 的 Agentic Use 一节):
from qwen_agent.agents import Assistant
# 1. 指向本地 vLLM 的 OpenAI 兼容接口
llm_cfg = {
'model': 'Qwen3-30B-A3B-Thinking-2507-AWQ',
'model_server': 'http://localhost:8000/v1',
'api_key': 'EMPTY',
'generate_cfg': {
'thought_in_content': True, # 思考内容直接混在 content 里,由 Qwen-Agent 解析
},
}
# 2. 定义可用工具
tools = [
{'mcpServers': {
'time': {
'command': 'uvx',
'args': ['mcp-server-time', '--local-timezone=Asia/Shanghai']
},
'fetch': {
'command': 'uvx',
'args': ['mcp-server-fetch']
}
}},
'code_interpreter', # Qwen-Agent 内置代码解释器
]
# 3. 定义 Agent 并运行
bot = Assistant(llm=llm_cfg, function_list=tools)
messages = [{'role': 'user', 'content': '现在北京时间多少?顺便抓取某网页并总结最新进展'}]
for responses in bot.run(messages=messages):
pass
print(responses)
跑通后你会发现:模型会先输出思考过程,再自动判断该调哪个工具(查时间 / 抓网页 / 执行代码),拿到结果后继续推理,直到给出最终答案——这就是完整的 Agent 循环。
理解 MCP:Agent 的"工具万能插座" 🔌
MCP(Model Context Protocol)让工具以统一协议暴露给模型,不用为每个工具手写解析逻辑。上面的示例里:
time:用uvx mcp-server-time一键拉起的查时间服务器(带时区参数);fetch:uvx mcp-server-fetch提供的网页抓取服务器;code_interpreter:Qwen-Agent 内置工具,用于执行 Python 代码。
三种接入方式可混用:MCP 配置文件、Qwen-Agent 内置工具、自行注册的工具。扩展更多能力时,只需往 mcpServers 里加一条命令即可接入任意 MCP 服务器。
提示:MCP 服务器由
uvx按需在本地拉起,无需额外常驻进程;uvx来自 uv 工具链,pip install uv即可获得。
第三步:采样参数与最佳实践 ⚙️
官方推荐参数(与仓库内 generation_config.json 的默认值一致):
- 采样:
Temperature=0.6、TopP=0.95、TopK=20、MinP=0; - 输出长度:普通查询 32768 tokens;高难度数学/编程任务可放到 81920,给思考留足空间;
- 防重复:
presence_penalty可设在 0~2 之间抑制无限重复,但过大会导致语言混杂; - 多轮对话:历史消息里只保留最终回答,不要带思考内容(官方 Jinja2 模板已自动处理)。
仓库文件速查 📂
| 文件 | 用途 |
|---|---|
| README.md | 部署命令、Qwen-Agent 完整示例、基准数据 |
| config.json | 模型结构:MoE 128 专家、256K 上下文、AWQ 4-bit 量化配置 |
| generation_config.json | 推荐采样参数(temperature/top_p/top_k) |
| model.safetensors.index.json | 权重的分片索引(共约 16GB) |
| tokenizer.json / tokenizer_config.json | 分词器,含思考标签等特殊 token 定义 |
| LICENSE | Apache-2.0 许可证 |
总结 ✅
- 部署:vLLM 0.10.0 +
--enable-expert-parallel,一条命令起服务; - 接入:Qwen-Agent 三行核心代码连上
localhost:8000/v1; - 扩展:MCP 配置文件声明工具,内置
code_interpreter随时可用; - 调优:官方采样参数 + 充足输出长度,即可充分发挥 Thinking 版的推理与工具调用能力。
按这套流程走下来,你得到的是一个能在本地稳定运行、可自由扩展工具的 Agent 底座。接下来可以试试接入数据库、文件系统等自己的 MCP 服务器,把 Agent 能力延伸到自己的工作流里。