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-Agent想让大模型不只是聊天而是真正调用工具、执行代码、读懂你本地的 PDFQwen-Agent 正是为此设计的 Agent 开发框架基于通义千问模型内置函数调用Function Calling、代码解释器、RAG 文档问答和 MCP 工具接入。下文带你完成安装、接入本地模型服务并逐一跑通这三个核心能力同时给出配置选型和高频报错的解决办法。项目速览这是什么适合谁Qwen-Agent 是 Qwen Chat 的后端框架定位为原子组件 智能体的两层结构底层提供 LLM 类继承BaseChatModel统一实现流式函数调用和 Tool 类继承BaseTool上层提供Assistant、FnCallAgent、ReActChat等可直接使用的 Agent也允许继承Agent基类自研智能体。它适合已有模型服务云端 API 或 vLLM/Ollama 本地部署、想快速把工具 知识 模型拼成可运行应用的开发者。核心能力清单能力说明入口函数调用流式工具调用默认模版支持并行调用qwen_agent/llm/function_calling.py代码解释器Docker 沙箱内执行 Python 并返回结果/图表qwen_agent/tools/code_interpreter.pyRAG 文档问答PDF/Word/PPT/TXT/HTML 检索问答无需手搭向量库examples/assistant_rag.pyMCP 接入直接声明mcpServers复用开源 MCP Serverqwen_agent/tools/mcp_manager.pyGradio WebUI一行代码给任意 Agent 套上对话界面qwen_agent/gui/web_ui.py环境准备安装 Qwen-Agent 并验证模型服务环境要求Python 3.8若启用 Gradio GUI 需 3.10启用代码解释器需本机安装并启动 DockerMCP 示例需要 Node.js 和uv。安装框架按需选择可选依赖四个 extras 可自由组合pip install -U qwen-agent[rag,code_interpreter,gui,mcp] # 只需函数调用能力时最小安装即可pip install -U qwen-agent准备模型服务二选一云端配置环境变量DASHSCOPE_API_KEYDashScope 提供的 Qwen 服务本地用 vLLM 或 Ollama 起一个 OpenAI 兼容接口例如vllm serve Qwen/Qwen3-8B --port 8000。运行最小示例验证全链路from qwen_agent.agents import Assistant llm_cfg { # 本地 vLLM 服务云端改为 model: qwen-plus-latest, model_type: qwen_dashscope model: Qwen/Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, } bot Assistant(llmllm_cfg) messages [{role: user, content: 用一句话解释什么是 Function Calling}] for response in bot.run(messages): print(response)成功标志终端流式打印出模型的中文回答而非报错或空输出说明安装 → 模型服务 → Agent整条链路已通。若报连接类错误先用curl http://localhost:8000/v1/models确认 vLLM 服务在跑。核心功能一函数调用与自定义工具注册原理Assistant内部通过 LLM 的函数调用接口与工具循环协作——模型输出工具名和参数框架执行对应BaseTool.call()再把结果喂回模型继续推理默认模版原生支持并行工具调用。自建工具只需一个装饰器注册。import json5 import urllib.parse from qwen_agent.agents import Assistant from qwen_agent.tools.base import BaseTool, register_tool register_tool(my_weather) class MyWeather(BaseTool): description 查询指定城市的实时天气 parameters [{ name: city, type: string, description: 城市名, required: True }] def call(self, params: str, **kwargs) - str: city json5.loads(params)[city] # LLM 生成的参数是 JSON 字符串 return json5.dumps({city: city, temperature: 22, unit: Celsius}, ensure_asciiFalse) bot Assistant(llmllm_cfg, function_list[my_weather]) for r in bot.run([{role: user, content: 北京现在多少度}]): print(r)效果模型会自动发起my_weather(city北京)调用并基于返回值作答整个过程在bot.run()一次调用内完成。完整参考见 examples/function_calling.py它演示了从get_chat_model直接流式调用函数接口的最底层形态。核心功能二代码解释器让 Agent 在 Docker 沙箱里跑代码定位内置的code_interpreter工具让模型根据场景自主写 Python在本地 Docker 容器隔离执行支持生成图表并回传结果。注意它只做目录挂载和基础沙箱隔离生产环境仍需谨慎。配置与调用bot Assistant(llmllm_cfg, function_list[code_interpreter]) messages [{role: user, content: 统计 [1,2,3,10,100] 的均值并画一张柱状图展示}] for response in bot.run(messages): # 流式打印中间步骤Action/Action Input/Observation和最终结论 print(response)⚠️ 使用前必须确保 Docker 已安装并处于运行状态docker ps无报错首次运行会拉取并构建镜像耗时取决于网络。效果模型会输出 Thought → Actioncode_interpreter→ 执行代码 → Observation执行输出与图表→ 最终回答的完整推理链。下面是框架在真实问答中调用代码解释器绘制饼图的运行效果核心功能三RAG 长文档问答PDF 直接丢给 Agent定位超长文档塞不进上下文、也不值得手搭向量库时Qwen-Agent 的 RAG 方案直接解决——Assistant支持在消息里携带file字段框架自动完成文档解析、分块与检索问答支持 PDF/Word/PPT/TXT/HTML。from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg, nameAssistant, description基于 RAG 检索回答支持 PDF/Word/PPT/TXT/HTML) messages [{role: user, content: [ {text: 这篇论文的主要贡献是什么}, {file: https://arxiv.org/pdf/1706.03762.pdf} # 本地文件路径同样有效 ]}] for rsp in bot.run(messages): print(rsp)效果模型给出基于文档内容的结论性回答如提出基于注意力机制的 Transformer 架构不含循环与卷积并在百万字级大海捞针单针查询测试中保持正确检索。对更高准确度的长文档场景可改用并行子 Agent 方案见 examples/parallel_doc_qa.py。配置对比与选型模型服务和解析器怎么选组合适用场景资源开销推荐度DashScopeqwen-plus/qwen-max快速验证、无 GPU 环境按量付费零硬件投入⭐⭐⭐⭐⭐入门首选本地 vLLM Qwen3-8B/32B隐私敏感、高并发服务单卡 16GB8B 可更低⭐⭐⭐⭐⭐生产推荐本地 Ollama个人机器轻跑、无 CUDA 环境CPUGPU 混合吞吐较低⭐⭐⭐演示可用vLLM Qwen3-Coder use_raw_api代码类任务、需要原生工具解析同上按模型大小⭐⭐⭐⭐Coder 场景关键差异在工具调用解析方式QwQ/Qwen3 系列请不要给 vLLM 加--enable-auto-tool-choice和--tool-call-parser hermes由 Qwen-Agent 内置的nous模版自行解析Qwen3-Coder 则相反应开启服务原生解析并配合generate_cfg中的use_raw_api: True。另外generate_cfg还支持max_input_tokens做输入截断、thought_in_content控制思考内容解析位置。避坑指南五个高频问题现象 1本地模型能对话但从不触发工具调用。原因所用模型不具备指令遵循/工具调用能力或解析模版不匹配。 解决换 Qwen3/QwQ 系列指令模型确认 Qwen3 不加 vLLM 解析参数见上一节Coder 模型改用use_raw_api: True。现象 2启用code_interpreter后执行报错或长时间无响应。原因Docker 未安装/未启动或首次构建镜像仍在进行。 解决先执行docker ps确认守护进程存活首次运行耐心等待镜像构建完成后续秒级启动。现象 3安装[gui]extras 后报 pydantic 版本冲突。原因Gradio 版本兼容性问题setup.py 中pydantic2.9.2、gradio5.23.1是写死的精确版本。 解决避免在同一环境混装其他锁定 pydantic 大版本的小工具必要时为 GUI 单独建虚拟环境GUI 还需 Python ≥ 3.10。现象 4api_key未设置时报鉴权错误。原因model_type: qwen_dashscope时框架读取DASHSCOPE_API_KEY环境变量而model_server指向本地服务时api_key可填EMPTY两者配置方式不同。 解决本地部署务必显式写model_serverapi_key: EMPTY不要把云端配置直接照搬。现象 5MCP 工具不生效。原因缺少 Node.js/uv或mcpServers的 command/args 写错。 解决按uv --version、node -v检查依赖参照 examples/assistant_mcp_sqlite_bot.py 核对mcpServers声明格式。进阶玩法三个值得落地的组合MCP 代码解释器 本地模型在function_list里同时声明mcpServers如 sqlite、fetch和code_interpreterAgent 即可查数据库 → 跑分析 → 出图表全离线闭环数据不出本机。Gradio WebUI 一步上线对任意配好的 Agent 执行WebUI(bot).run()立刻获得带输入建议、文件上传的对话界面适合内网快速演示与试用代码见 qwen_agent/gui/web_ui.py。长文档双方案先试Assistant内置 RAG 验证效果准确度不足时切到ParallelDocQA并行子 Agent 方案examples/parallel_doc_qa.py以更高推理成本换取更准的超长文档问答。总结与下一步本地部署的关键不在框架而在OpenAI 兼容服务 model_server配置这一对组合vLLM/Ollama 皆可接入函数调用是骨架自定义工具 一个register_tool类 清晰的description/parameters代码解释器提供安全执行层RAG 提供文档理解层两者叠加即覆盖数据分析 知识问答两大落地场景工具调用解析器、Docker 依赖、GUI 版本锁定是三大坑源对照避坑节可快速定位。下一步学习路径通读 examples/ 目录下的各场景脚本对照 qwen_agent/llm/ 与 qwen_agent/tools/ 两个源码目录理解 LLM 与工具抽象需要跑 Agent 效果评测时参考 benchmark/ 下的 DeepPlanning 基准脚本。【免费下载链接】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），仅供参考
Qwen-Agent 本地部署与核心功能实战：函数调用、代码解释器、长文档问答一篇跑通
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-Agent想让大模型不只是聊天而是真正调用工具、执行代码、读懂你本地的 PDFQwen-Agent 正是为此设计的 Agent 开发框架基于通义千问模型内置函数调用Function Calling、代码解释器、RAG 文档问答和 MCP 工具接入。下文带你完成安装、接入本地模型服务并逐一跑通这三个核心能力同时给出配置选型和高频报错的解决办法。项目速览这是什么适合谁Qwen-Agent 是 Qwen Chat 的后端框架定位为原子组件 智能体的两层结构底层提供 LLM 类继承BaseChatModel统一实现流式函数调用和 Tool 类继承BaseTool上层提供Assistant、FnCallAgent、ReActChat等可直接使用的 Agent也允许继承Agent基类自研智能体。它适合已有模型服务云端 API 或 vLLM/Ollama 本地部署、想快速把工具 知识 模型拼成可运行应用的开发者。核心能力清单能力说明入口函数调用流式工具调用默认模版支持并行调用qwen_agent/llm/function_calling.py代码解释器Docker 沙箱内执行 Python 并返回结果/图表qwen_agent/tools/code_interpreter.pyRAG 文档问答PDF/Word/PPT/TXT/HTML 检索问答无需手搭向量库examples/assistant_rag.pyMCP 接入直接声明mcpServers复用开源 MCP Serverqwen_agent/tools/mcp_manager.pyGradio WebUI一行代码给任意 Agent 套上对话界面qwen_agent/gui/web_ui.py环境准备安装 Qwen-Agent 并验证模型服务环境要求Python 3.8若启用 Gradio GUI 需 3.10启用代码解释器需本机安装并启动 DockerMCP 示例需要 Node.js 和uv。安装框架按需选择可选依赖四个 extras 可自由组合pip install -U qwen-agent[rag,code_interpreter,gui,mcp] # 只需函数调用能力时最小安装即可pip install -U qwen-agent准备模型服务二选一云端配置环境变量DASHSCOPE_API_KEYDashScope 提供的 Qwen 服务本地用 vLLM 或 Ollama 起一个 OpenAI 兼容接口例如vllm serve Qwen/Qwen3-8B --port 8000。运行最小示例验证全链路from qwen_agent.agents import Assistant llm_cfg { # 本地 vLLM 服务云端改为 model: qwen-plus-latest, model_type: qwen_dashscope model: Qwen/Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, } bot Assistant(llmllm_cfg) messages [{role: user, content: 用一句话解释什么是 Function Calling}] for response in bot.run(messages): print(response)成功标志终端流式打印出模型的中文回答而非报错或空输出说明安装 → 模型服务 → Agent整条链路已通。若报连接类错误先用curl http://localhost:8000/v1/models确认 vLLM 服务在跑。核心功能一函数调用与自定义工具注册原理Assistant内部通过 LLM 的函数调用接口与工具循环协作——模型输出工具名和参数框架执行对应BaseTool.call()再把结果喂回模型继续推理默认模版原生支持并行工具调用。自建工具只需一个装饰器注册。import json5 import urllib.parse from qwen_agent.agents import Assistant from qwen_agent.tools.base import BaseTool, register_tool register_tool(my_weather) class MyWeather(BaseTool): description 查询指定城市的实时天气 parameters [{ name: city, type: string, description: 城市名, required: True }] def call(self, params: str, **kwargs) - str: city json5.loads(params)[city] # LLM 生成的参数是 JSON 字符串 return json5.dumps({city: city, temperature: 22, unit: Celsius}, ensure_asciiFalse) bot Assistant(llmllm_cfg, function_list[my_weather]) for r in bot.run([{role: user, content: 北京现在多少度}]): print(r)效果模型会自动发起my_weather(city北京)调用并基于返回值作答整个过程在bot.run()一次调用内完成。完整参考见 examples/function_calling.py它演示了从get_chat_model直接流式调用函数接口的最底层形态。核心功能二代码解释器让 Agent 在 Docker 沙箱里跑代码定位内置的code_interpreter工具让模型根据场景自主写 Python在本地 Docker 容器隔离执行支持生成图表并回传结果。注意它只做目录挂载和基础沙箱隔离生产环境仍需谨慎。配置与调用bot Assistant(llmllm_cfg, function_list[code_interpreter]) messages [{role: user, content: 统计 [1,2,3,10,100] 的均值并画一张柱状图展示}] for response in bot.run(messages): # 流式打印中间步骤Action/Action Input/Observation和最终结论 print(response)⚠️ 使用前必须确保 Docker 已安装并处于运行状态docker ps无报错首次运行会拉取并构建镜像耗时取决于网络。效果模型会输出 Thought → Actioncode_interpreter→ 执行代码 → Observation执行输出与图表→ 最终回答的完整推理链。下面是框架在真实问答中调用代码解释器绘制饼图的运行效果核心功能三RAG 长文档问答PDF 直接丢给 Agent定位超长文档塞不进上下文、也不值得手搭向量库时Qwen-Agent 的 RAG 方案直接解决——Assistant支持在消息里携带file字段框架自动完成文档解析、分块与检索问答支持 PDF/Word/PPT/TXT/HTML。from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg, nameAssistant, description基于 RAG 检索回答支持 PDF/Word/PPT/TXT/HTML) messages [{role: user, content: [ {text: 这篇论文的主要贡献是什么}, {file: https://arxiv.org/pdf/1706.03762.pdf} # 本地文件路径同样有效 ]}] for rsp in bot.run(messages): print(rsp)效果模型给出基于文档内容的结论性回答如提出基于注意力机制的 Transformer 架构不含循环与卷积并在百万字级大海捞针单针查询测试中保持正确检索。对更高准确度的长文档场景可改用并行子 Agent 方案见 examples/parallel_doc_qa.py。配置对比与选型模型服务和解析器怎么选组合适用场景资源开销推荐度DashScopeqwen-plus/qwen-max快速验证、无 GPU 环境按量付费零硬件投入⭐⭐⭐⭐⭐入门首选本地 vLLM Qwen3-8B/32B隐私敏感、高并发服务单卡 16GB8B 可更低⭐⭐⭐⭐⭐生产推荐本地 Ollama个人机器轻跑、无 CUDA 环境CPUGPU 混合吞吐较低⭐⭐⭐演示可用vLLM Qwen3-Coder use_raw_api代码类任务、需要原生工具解析同上按模型大小⭐⭐⭐⭐Coder 场景关键差异在工具调用解析方式QwQ/Qwen3 系列请不要给 vLLM 加--enable-auto-tool-choice和--tool-call-parser hermes由 Qwen-Agent 内置的nous模版自行解析Qwen3-Coder 则相反应开启服务原生解析并配合generate_cfg中的use_raw_api: True。另外generate_cfg还支持max_input_tokens做输入截断、thought_in_content控制思考内容解析位置。避坑指南五个高频问题现象 1本地模型能对话但从不触发工具调用。原因所用模型不具备指令遵循/工具调用能力或解析模版不匹配。 解决换 Qwen3/QwQ 系列指令模型确认 Qwen3 不加 vLLM 解析参数见上一节Coder 模型改用use_raw_api: True。现象 2启用code_interpreter后执行报错或长时间无响应。原因Docker 未安装/未启动或首次构建镜像仍在进行。 解决先执行docker ps确认守护进程存活首次运行耐心等待镜像构建完成后续秒级启动。现象 3安装[gui]extras 后报 pydantic 版本冲突。原因Gradio 版本兼容性问题setup.py 中pydantic2.9.2、gradio5.23.1是写死的精确版本。 解决避免在同一环境混装其他锁定 pydantic 大版本的小工具必要时为 GUI 单独建虚拟环境GUI 还需 Python ≥ 3.10。现象 4api_key未设置时报鉴权错误。原因model_type: qwen_dashscope时框架读取DASHSCOPE_API_KEY环境变量而model_server指向本地服务时api_key可填EMPTY两者配置方式不同。 解决本地部署务必显式写model_serverapi_key: EMPTY不要把云端配置直接照搬。现象 5MCP 工具不生效。原因缺少 Node.js/uv或mcpServers的 command/args 写错。 解决按uv --version、node -v检查依赖参照 examples/assistant_mcp_sqlite_bot.py 核对mcpServers声明格式。进阶玩法三个值得落地的组合MCP 代码解释器 本地模型在function_list里同时声明mcpServers如 sqlite、fetch和code_interpreterAgent 即可查数据库 → 跑分析 → 出图表全离线闭环数据不出本机。Gradio WebUI 一步上线对任意配好的 Agent 执行WebUI(bot).run()立刻获得带输入建议、文件上传的对话界面适合内网快速演示与试用代码见 qwen_agent/gui/web_ui.py。长文档双方案先试Assistant内置 RAG 验证效果准确度不足时切到ParallelDocQA并行子 Agent 方案examples/parallel_doc_qa.py以更高推理成本换取更准的超长文档问答。总结与下一步本地部署的关键不在框架而在OpenAI 兼容服务 model_server配置这一对组合vLLM/Ollama 皆可接入函数调用是骨架自定义工具 一个register_tool类 清晰的description/parameters代码解释器提供安全执行层RAG 提供文档理解层两者叠加即覆盖数据分析 知识问答两大落地场景工具调用解析器、Docker 依赖、GUI 版本锁定是三大坑源对照避坑节可快速定位。下一步学习路径通读 examples/ 目录下的各场景脚本对照 qwen_agent/llm/ 与 qwen_agent/tools/ 两个源码目录理解 LLM 与工具抽象需要跑 Agent 效果评测时参考 benchmark/ 下的 DeepPlanning 基准脚本。【免费下载链接】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），仅供参考