15 分钟跑通本地私有 AI 助手：Qwen-Agent 本地化部署完整避坑指南

15 分钟跑通本地私有 AI 助手Qwen-Agent 本地化部署完整避坑指南【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-AgentQwen-Agent 是阿里基于 Qwen 模型开源的 Agent 框架核心能力包括 Function Calling、MCP、代码解释器Code Interpreter和 RAG 文档问答。这篇文章以完全本地为目标模型服务指向你自己部署的 vLLM 或 Ollama全程不调用云端 API数据不出内网。关键词Qwen-Agent 本地化部署、本地模型部署、函数调用、代码解释器、私有化 AI 助手长尾词Qwen-Agent 对接 vLLM、Ollama 本地 Agent 搭建、工具调用 Docker 沙箱、PDF 本地文档问答、自定义工具注册 BaseTool第一步装框架、起服务、出第一句回复这是全文最快的可用路径三小节预计 15 分钟。安装框架1 条命令pip install -U qwen-agent[gui,rag,code_interpreter,mcp]一行装完方括号里的 4 个 extras 分别启用 Gradio 界面、RAG、代码解释器、MCP按需删减。需要改源码的话从源码安装git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent cd Qwen-Agent pip install -e ./[gui,rag,code_interpreter,mcp]起一个本地模型服务二选一方案适用场景启动方式服务地址vLLM有 GPU追求吞吐vllm serve Qwen/Qwen3-8B --port 8000http://localhost:8000/v1OllamaCPUGPU 混合装好即用ollama serveollama pull qwen3:8bhttp://localhost:11434/v1⚠️ 关键避坑用 Qwen3 / QwQ 系列时vLLM不要加--enable-auto-tool-choice参数工具调用解析由框架自己完成两边同时解析会导致工具参数错乱。3 行配置 3 行调用from qwen_agent.agents import Assistant llm_cfg { model: Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, } bot Assistant(llmllm_cfg) messages [{role: user, content: 用一句话说说本地化部署的优势}] for rsp in bot.run(messages): print(rsp)预期结果控制台流式打印模型回复。model_server是 OpenAI 兼容地址api_key本地服务填EMPTY即可。如果报连接错误90% 是端口或模型名写错先看下一节。第二步先验证模型服务再怀疑框架连不通时按下面顺序排查能把框架问题和服务问题分开# 1. 服务是否活着、模型名对不对返回的 model 字段必须和配置一致 curl http://localhost:8000/v1/models# 2. 绕过 Agent 逻辑直接测裸 LLM 通道 from qwen_agent.llm import get_chat_model llm get_chat_model(llm_cfg) print(llm.quick_chat(回复ok两个字母))quick_chat不经过任何工具解析逻辑它能通而 Agent 不通问题就在工具链它也通不了问题就在服务本身。现象大概率原因处理Connection refused服务没起或端口不对检查进程和端口占用404 / model not found模型名与/v1/models返回不一致改配置里的model字段工具不触发启用了 vLLM 自动 tool choice去掉该参数用框架内置解析Qwen3 输出思考混乱思考模式参数没传generate_cfg里加extra_body: {chat_template_kwargs: {enable_thinking: False}}第三步接上代码解释器让它安全跑 Python代码解释器源码在qwen_agent/tools/code_interpreter.py基于 Docker 容器做隔离模型会自主写代码、在沙箱里执行、把结果含图表返回给你。tools [code_interpreter] bot Assistant(llmllm_cfg, function_listtools)两个注意点前置条件是 Docker 已安装并在运行首次调用会构建镜像视网络耗时约 1~3 分钟。官方 README 明确提示容器只挂载了指定工作目录属于基础隔离生产环境要自行加固。问它画出 sin 和 cos 曲线预期几秒内返回一张 matplotlib 生成的图片。第四步20 行代码写一个自定义工具框架里所有工具都继承BaseToolqwen_agent/tools/base.py注册后模型会自动决定何时调用。最小可用示例import datetime import json5 from qwen_agent.tools.base import BaseTool, register_tool register_tool(local_time) class LocalTime(BaseTool): description 获取本机当前时间 parameters {type: object, properties: {}} def call(self, params, **kwargs) - str: return json5.dumps({time: datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S)}, ensure_asciiFalse)bot Assistant(llmllm_cfg, function_list[local_time, code_interpreter])问现在几点了预期模型主动调用local_time并给出本机时间。description和parameters会直接进模型的函数调用提示词写得越具体触发越准。 不想自己写工具时直接接现成的 MCP 服务器tools [{ mcpServers: { sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, test.db] } } }] bot Assistant(llmllm_cfg, function_listtools)依赖uvuv --version检查完整示例参考examples/assistant_mcp_sqlite_bot.py。第五步长文档问答与一键 GUI进阶本地文档 RAG 问答Assistant 原生支持files参数内置 RAG 检索支持 PDF / Word / PPT / TXT / HTMLbot Assistant(llmllm_cfg, files[./local_docs/report.pdf])文档达到百万 token 级时换用examples/assistant_rag.py快速 RAG 方案或examples/parallel_doc_qa.py多 Agent 并行方案官方称两者在 1M 长度的大海捞针测试上优于原生长上下文模型。一行代码出网页界面from qwen_agent.gui import WebUI WebUI(bot).run()⚠️ GUI 基于 Gradio 5要求 Python 3.10。启动后浏览器里可直接传文件、看工具调用过程。多 Agent 协作群聊、路由分发看qwen_agent/agents/group_chat.py和router.py配合examples/group_chat_demo.py跑通。避坑清单部署前对照一遍Qwen3 / QwQvLLM 不加--enable-auto-tool-choice用框架内置解析Qwen3-Coder 相反加--enable-auto-tool-choice --tool-call-parser qwen3_coder并在generate_cfg设use_raw_api: True代码解释器Docker 必须先运行起来首次构建镜像要等 1~3 分钟GUIPython 版本必须 ≥ 3.10生成参数top_p: 0.8是默认推荐值长对话建议设max_input_tokens防止超模型上下文下一步按第一节跑通本地对话后直接运行examples/assistant_qwen3.py里的app_gui()把llm_cfg换成你的本地服务得到带工具调用的网页 Demo照着第四节的LocalTime模板为你自己的业务写第一个自定义工具注册进function_list要评估规划能力用benchmark/deepplanning/里的 shopping / travel 评测脚本跑一轮对比验证你的模型配置是否达到可用水平【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考