Qwen-Agent 本地部署指南：函数调用和代码解释器在自己机器上跑，API 费用为零

Qwen-Agent 本地部署指南：函数调用和代码解释器在自己机器上跑，API 费用为零

【免费下载链接】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

Qwen-Agent 是阿里开源的 Agent 框架，能给你的模型接上函数调用、代码解释器和文档问答。但最有用的是它的另一面：模型服务这一层是完全开放的，你本地起一个 vLLM 服务，整个 Agent 就能离线运行。想象一下：你的合同 PDF 躺在本地硬盘上，不想传到任何云服务器，但你想让它自动读文档、调工具、画图表——这就是 Qwen-Agent 本地部署要解决的事。

看懂 Qwen-Agent：为本地部署而生的 Agent 框架

一句话定位：它把"大模型"和"干活的能力"拆成了两层——模型服务只负责思考和说话，工具层负责真正执行（搜网页、跑代码、读文件），两层通过标准的 OpenAI 接口对接。这就是它能本地部署的原因：你不需要绑死任何云厂商，换掉模型服务地址就行。

它的工具注册机制就像手机装 App：用@register_tool声明一下名字和参数，塞进function_list列表就能用，Agent 自己决定什么时候调。

能力全景，5 秒看完：

• 函数调用（Function Calling）：Agent 自主决定调哪个工具，支持并行调用多个
• 代码解释器：让 Agent 写 Python、在 Docker 沙箱里执行、返回图表
• 文档问答（RAG）：丢给它 PDF/Word/PPT，它读完整份文档回答问题
• MCP 接入：挂外部工具服务器，比如 SQLite、文件系统
• Web GUI：一行代码起 Gradio 聊天页面

从零跑通：最短路径

整个流程三步：装包、起本地模型服务、跑第一个 Agent。

第一步，装依赖。方括号里是功能开关，code_interpreter和rag是你本地部署最常用的两个：

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

第二步，起本地模型服务。用 vLLM（一个专门给大模型做高速推理的本地服务框架）起一个 OpenAI 兼容接口，模型建议从 8B 起步：

vllm serve Qwen/Qwen3-8B --port 8000

注意：Qwen3 系列不要加--enable-auto-tool-choice和--tool-call-parser hermes参数，Qwen-Agent 自己会解析工具调用（Qwen3-Coder 例外）。

第三步，跑第一个 Agent。下面这段把模型指向 localhost，给它挂上代码解释器工具，让它画一张饼图：

from qwen_agent.agents import Assistant llm_cfg = { 'model': 'Qwen3-8B', 'model_server': 'http://localhost:8000/v1', # vLLM 服务地址 'api_key': 'EMPTY', } bot = Assistant(llm=llm_cfg, function_list=['code_interpreter']) messages = [{'role': 'user', 'content': "四个季度营收是 100、200、150、250，画一张饼图"}] for rsp in bot.run(messages): print(rsp[-1]['content'], end='')

怎么算跑通了？终端流式打出分析过程，Agent 自己写代码调用了code_interpreter，工作目录里多出一张能打开的.png饼图。到这一步，一个不花 API 钱的本地 Agent 就有了。

核心能力拆解：三个最常用的本地玩法

让 Agent 自己写代码执行：本地代码解释器

这个能力解决"让模型动手而不是动嘴"的问题：数据分析、画图表、批量处理文件，模型自己生成 Python 并在隔离环境里跑完。

关键就在function_list=['code_interpreter']这一行。它底层是一个 Docker 容器沙箱（源码在qwen_agent/tools/code_interpreter.py），首次使用会自动构建code-interpreter:latest镜像。实际用起来要注意：Docker 必须已安装并在运行，构建镜像那一下可能花几分钟，之后每次会话秒开。

让本地文档开口说话：RAG 文档问答

这个能力解决"文档太长塞不进上下文"的问题：一份几十页的 PDF，你只想问其中第三章讲了什么。

用法比想象中简单——不需要你搭向量库，Assistant直接把文件喂进去：

bot = Assistant(llm=llm_cfg, files=['./report.pdf'])

它会解析文档（PDF/Word/PPT/TXT/HTML 都支持，解析逻辑在qwen_agent/tools/doc_parser.py），然后按检索回答。实际用起来要注意：超长的百万 token 级文档建议改用examples/assistant_rag.py里的 RAG 方案，那是为超长文档专门做的。

写一个自己的工具：十五行插一个插件

这个能力解决"内置工具不够用"的问题：查本地数据库、调公司内部接口，都能包成一个工具让 Agent 调用。

下面是个查本地目录文件内容的最小例子，注册完加进function_list就能用：

from qwen_agent.tools.base import BaseTool, register_tool @register_tool('local_search') class LocalSearch(BaseTool): description = '在本地 docs 目录里模糊搜索文件内容，返回匹配行' parameters = [{'name': 'keyword', 'type': 'string', 'description': '要搜索的关键词', 'required': True}] def call(self, params, **kwargs): import json5, pathlib kw = json5.loads(params)['keyword'] hits = [f'{f}:{line}' for f in pathlib.Path('docs').rglob('*') if f.is_file() for line in f.read_text(errors='ignore').splitlines() if kw in line] return json5.dumps(hits[:20], ensure_ascii=False)

实际用起来要注意：description写得越具体，模型越知道什么时候该调它——这行文字就是模型眼中的工具说明书。

按硬件配置：不同机器怎么选模型

拿不准就按第二行配：8B + vLLM，显存放得下、工具调用够稳，跑顺了再升级。

生成参数在generate_cfg里调，记住三个方向的体感：temperature调小（趋近 0）回答稳定但容易重复，调大（超过 1）容易跑偏；max_new_tokens是输出长度上限，调大了等待时间和显存占用同步涨；top_p控制候选词池大小，0.8 左右是安全值。

踩过的坑：这些才是真会卡住你的

• 症状：Connection refused，连不上 localhost:8000→ vLLM 没起来，或者--port和model_server里的端口对不上 → 先跑curl http://localhost:8000/v1/models确认服务在列模型列表，再回头改地址。
• 症状：模型开始"胡言乱语"式地输出工具调用，Agent 解析不出来→ 起 vLLM 时加了--enable-auto-tool-choice --tool-call-parser hermes，两套解析打架了 → 把这两个参数去掉（Qwen3-Coder 除外，它反而要开）。
• 症状：第一次用 code_interpreter 卡很久或直接报 Docker 错误→ Docker 没装、没运行，或者在等首次构建镜像 →docker ps确认 Docker 活着；首次构建慢就手动预构建一次。
• 症状：模型加载直接 OOM，进程被系统杀掉→ 模型规格超过显存，或 KV cache 被长上下文撑爆 → 换 4B/8B 或上量化版，同时在llm_cfg里设max_input_tokens限制输入长度。
• 症状：几十页的 PDF 一问就超时或答非所问→ 整份文档硬塞进上下文了 → 改用examples/assistant_rag.py的 RAG 方案，按块检索而不是全量投喂。

还能怎么玩：三个进阶方向

• 多 Agent 协作：多个 Agent 分工对话、互相路由，看qwen_agent/multi_agent_hub.py和qwen_agent/agents/group_chat.py。
• MCP 插件生态：挂上 SQLite、文件系统、网页抓取等 MCP 服务器，配置格式见qwen_agent/tools/mcp_manager.py和examples/assistant_mcp_sqlite_bot.py。
• 浏览器端 Agent：项目自带一个 Chrome 扩展 BrowserQwen，把文档问答搬到网页上。

如果你还想改框架源码，clone 仓库（https://gitcode.com/GitHub_Trending/qw/Qwen-Agent）后pip install -e ./装成可编辑模式即可。

到这里，你的 Qwen-Agent 已经完全跑在本地了：模型不出局域网，文档不出硬盘。下一步建议直接打开examples/目录，把assistant_qwen3.py的 GUI 模式（文件末尾的app_gui()）跑起来——一个能点选的聊天页面比终端输出更能让你确认这套东西真的能用。

【免费下载链接】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