Qwen-Agent 本地部署：改 1 行配置跑通模型推理
【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent
下载好 Qwen3-4B，本地启动 Qwen-Agent 却加载失败？多半是模型ID（告诉框架去哪儿找模型的路径）还写着公开仓库名。把它改成你电脑上的文件夹路径，一行改完即可跑通本地模型推理。
为什么值得你花 3 分钟
本地模型配置最容易卡的就是"去哪找模型"这一步，而 Qwen-Agent 里它只由一行model字段决定。改对之后，你的 Agent 不依赖 API key 就能对话、调用工具，改完立刻能在终端看到回复验证。适合有 GPU 笔记本或服务器、想离线跑 Qwen 对话、文档问答、图片理解的人。
最快上手：最小可运行路径
三步跑通：
- 先装依赖并拿到模型文件（下载一次即可）：
pip install -U transformers torch # 安装模型加载所需的依赖 huggingface-cli download Qwen/Qwen3-4B --local-dir ./models/Qwen3-4B # 把模型下载到本地文件夹- 新建脚本，写死这份配置：
from qwen_agent.agents import Assistant llm_cfg = { 'model': 'Qwen/Qwen3-4B', # 模型ID：本地部署时改成 './models/Qwen3-4B' 'model_type': 'transformers', # 走 Hugging Face Transformers 本地加载 'device': 'cuda', # 有显卡填 cuda，没有就填 cpu } bot = Assistant(llm=llm_cfg) # 传入配置，加载模型- 发一句话验证：
print(list(bot.run(messages=[{'role': 'user', 'content': '你好，介绍一下自己'}]))[-1])10 秒判断标准：终端打印出模型的自我介绍文本，就说明本地模型加载成功；卡住不动则看下面避坑部分。
💡 路径规则很简单：model既能填 Hugging Face 上的公开名称，也能填本地文件夹路径。填公开名称时框架会自动联网下载，所以首次启动"卡"往往是在下模型。
按需扩展：如果你要……
如果你要处理图片
只换一行model：
'model': 'Qwen/Qwen3-VL-4B', # 换成多模态模型，支持图片理解框架会自动检测模型是否带视觉处理器并启用对应能力，消息里同时传图片和文字即可，效果参考仓库内的多模态问答示例 assistant_qwen3vl.py：
如果你显存只有 6G / 你要换 7B 模型
只动下面这一行（或两行）：
'model': 'Qwen/Qwen3-7B', # 换更大的模型 'device': 'cpu', # 显存不够时降级到 cpu，速度慢但不会崩三个常见场景的差异汇总如下：
| 场景 | 变化的配置行 | 备注 |
|---|---|---|
| 纯文本对话 | 'model': 'Qwen/Qwen3-4B' | 最小显存占用，device可选cuda或cpu |
| 图片理解 | 'model': 'Qwen/Qwen3-VL-4B' | 视觉能力自动开启，无需额外开关 |
| 换 7B 模型 | 'model': 'Qwen/Qwen3-7B' | 4B 能跑 7B 一般需要显存翻倍 |
避坑速查
加载失败：提示找不到模型或文件路径不存在
- 原因：
model填了本地路径但路径不对，或填了公开名称却处于离线环境。 - 解法：路径必须指向包含
config.json的模型文件夹，确认存在后重跑：'model': './models/Qwen3-4B'
显存不足，CUDA out of memory 直接崩
- 原因：7B 模型 fp 精度下显存不够。
- 解法：改一行降级到 CPU，或换回 4B：
'device': 'cpu'
报 ValueError，提示请提供 model
- 原因：配置字典漏写了
model字段，框架在初始化时强制校验（见 transformers_llm.py 第 43 行）。 - 解法：补上
'model': '你的模型ID或路径'再运行。
下一步
配置跑通后，翻一遍 examples/ 目录里的工具调用示例，给本地模型挂上 Function Calling 和 MCP 工具。
【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
