# https://github.com/QwenLM/Qwen-Agent 项目说明书 生成时间：2026-05-31 22:32:35 UTC ## 目录 - [Qwen-Agent 简介](#introduction) - [快速开始](#quickstart) - [安装指南](#installation) - [核心模块架构](#core_modules) - [Agent 系统详解](#agent_system) - [大模型集成](#llm_integration) - [工具使用指南](#tool_usage) - [代码解释器](#code_interpreter) - [MCP 协议集成](#mcp_integration) - [RAG 与超长文档问答](#rag_long_doc) ## Qwen-Agent 简介 ### 相关页面 相关主题：[快速开始](#quickstart), [安装指南](#installation)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/QwenLM/Qwen-Agent/blob/main/README.md) - [qwen_agent/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/__init__.py) - [qwen_agent/agent.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) - [qwen_agent/llm.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm.py) - [qwen_agent/tools/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py) - [qwen_agent/agentchat/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agentchat/__init__.py) - [examples/assistant_rag.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) - [examples/function_calling.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py) - [examples/parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py)
# Qwen-Agent 简介 Qwen-Agent 是一个基于 Qwen 大语言模型开发的 **Agent 开发框架**，旨在帮助开发者快速构建、部署和管理基于大模型的智能代理应用。该框架提供了丰富的工具调用能力、长文档处理方案、多 Agent 协作机制以及灵活的部署选项，使开发者能够将 Qwen 大模型的强大能力快速转化为实际的生产级应用。 ## 核心定位与设计理念 Qwen-Agent 的核心定位是 **简化 Agent 应用开发流程**，降低大模型应用落地的技术门槛。框架设计遵循以下核心理念： ### 统一抽象与模块化设计 框架采用模块化架构，将大语言模型调用、工具管理、对话控制、Agent 协作等核心功能解耦为独立模块。开发者可以根据需求灵活组合这些模块，快速构建定制化的 Agent 解决方案。资料来源：[qwen_agent/__init__.py:1-20]() ### 原生支持函数调用（Function Calling） Qwen-Agent 原生支持 Qwen 模型的函数调用能力，支持 **并行函数调用（Parallel Function Calls）**。这使得 Agent 能够精准理解用户意图并调用相应的外部工具，实现与大语言模型的无缝交互。资料来源：[README.md](https://github.com/QwenLM/Qwen-Agent#do-you-have-function-calling-aka-tool-calling) ### 面向生产环境的设计 框架不仅支持在 Gradio 中进行交互式测试和调试，还支持通过 FastAPI 等 Web 框架将 Agent 发布为 API 服务，便于在实际业务系统中集成使用。这是社区中反馈较多的需求之一（Issue #609）。资料来源：[examples/](https://github.com/QwenLM/Qwen-Agent/tree/main/examples) ## 系统架构 Qwen-Agent 的系统架构可以分为以下几个核心层次： ```mermaid graph TD subgraph "应用层 (Application Layer)" A[Agent 应用] --> B[FnCallAgent] A --> C[ReActChat] A --> D[Assistant] end subgraph "核心层 (Core Layer)" B --> E[LLM 基类] C --> E D --> E E --> F[工具系统 Tools] E --> G[记忆系统 Memory] end subgraph "模型层 (Model Layer)" H[Qwen-DashScope] I[OpenAI 兼容 API] J[本地 vLLM/Ollama] E --> H E --> I E --> J end subgraph "工具层 (Tools Layer)" F --> K[内置工具] F --> L[ MCP 工具] F --> M[自定义工具] end ``` ### 核心模块说明 | 模块 | 路径 | 功能描述 | |------|------|----------| | `llm` | `qwen_agent/llm.py` | LLM 调用抽象层，支持多种模型服务后端 | | `agent` | `qwen_agent/agent.py` | Agent 基类，定义核心交互逻辑 | | `agentchat` | `qwen_agent/agentchat/` | 预置 Agent 实现（FnCallAgent、ReActChat 等） | | `tools` | `qwen_agent/tools/` | 工具注册与调用管理系统 | | `memory` | `qwen_agent/memory/` | 对话记忆与上下文管理 | | `rag` | `qwen_agent/rag/` | 检索增强生成解决方案 | ## Agent 类型 Qwen-Agent 提供了多种预置 Agent 类型，以满足不同场景的需求： ### FnCallAgent - 函数调用 Agent `FnCallAgent` 是专门为函数调用场景设计的 Agent，基于 Qwen 的函数调用能力构建。它能够自动解析用户意图并调用相应的工具函数。 ```python from qwen_agent import FnCallAgent llm_cfg = { 'model': 'qwen3-32b', 'model_type': 'qwen_dashscope', 'api_key': 'YOUR_DASHSCOPE_API_KEY', } agent = FnCallAgent(llm_cfg=llm_cfg) ``` 资料来源：[qwen_agent/agentchat/fncall.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agentchat/fncall.py) ### ReActChat - 推理与行动 Agent `ReActChat` 基于 ReAct（Reasoning + Acting）范式构建，通过交错推理和行动实现复杂任务的自动化处理。 ### Assistant - 通用助手 `Assistant` 提供通用的对话和任务处理能力，适用于多种应用场景。 ## 工具系统（Tools） 工具系统是 Qwen-Agent 的核心组件之一，负责管理和执行各种外部功能。 ### 工具注册机制 ```mermaid graph LR A[工具定义] --> B[工具注册] B --> C[工具选择] C --> D[工具调用] D --> E[结果返回] E --> F[上下文更新] ``` ### 内置工具 框架内置了多种常用工具，包括： | 工具类型 | 功能描述 | |----------|----------| | `calculate` | 数学计算 | | `search` | 网络搜索 | | `code_interpreter` | 代码执行 | | `file_operations` | 文件读写 | ### MCP（Model Context Protocol）支持 Qwen-Agent 支持通过 MCP 协议连接外部工具服务，并提供 SSE 连接超时管理和自动重连功能（v0.0.26 版本特性）。资料来源：[examples/mcp/](https://github.com/QwenLM/Qwen-Agent/tree/main/examples/mcp) ### 自定义工具开发 开发者可以通过装饰器方式快速定义自定义工具： ```python from qwen_agent.tools import tool @tool def my_custom_tool(param1: str, param2: int) -> str: """ 自定义工具描述 Args: param1: 参数1描述 param2: 参数2描述 Returns: 工具执行结果 """ # 工具实现逻辑 return "结果" ``` ## 长文档处理方案 Qwen-Agent 针对超长文档（最长可达 100 万 tokens）的问答场景提供了两种解决方案： ### 快速方案 - Fast RAG `Fast RAG` 方案通过高效的检索和切分策略，实现对超长文档的快速问答。该方案在保证性能的同时，能够处理极长的文档输入。 ```python from qwen_agent import Assistant assistant = Assistant(llm_cfg=llm_cfg, system_message='你是一个文档助手。') assistant.run('基于提供的文档回答：xxx问题') ``` 资料来源：[examples/assistant_rag.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) ### 高精度方案 - Parallel Doc QA `Parallel Doc QA` 方案采用并行化的文档处理策略，通过多路召回和交叉验证提高答案准确性。该方案虽然计算成本较高，但在具有挑战性的基准测试中表现优于原生长上下文模型。 ```python from qwen_agent import ParallelDocQA qa_agent = ParallelDocQA(llm_cfg=llm_cfg) result = qa_agent.run(document_path='长文档路径', query='问题') ``` 资料来源：[examples/parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py) ## LLM 配置与参数 ### 基础配置 ```python llm_cfg = { # 模型名称 'model': 'qwen3-32b', # 模型服务类型 'model_type': 'qwen_dashscope', # 或 'openai', 'dashscope' # API 地址（使用 OpenAI 兼容服务时） 'model_server': 'http://localhost:8000/v1', # API 密钥 'api_key': 'YOUR_API_KEY', # 生成参数 'generate_cfg': { # 是否启用思考模式 'enable_thinking': True, # 最大思考 token 数 'max_tokens': 20000, # Top P 采样参数 'top_p': 0.8, } } ``` ### 参数说明 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `model` | str | 必需 | 模型名称，如 `qwen3-32b`、`qwen-turbo` | | `model_type` | str | 必需 | 模型服务类型：`qwen_dashscope`、`openai` | | `model_server` | str | 可选 | OpenAI 兼容服务的 base URL | | `api_key` | str | 可选 | API 密钥，未设置时读取环境变量 | | `enable_thinking` | bool | False | 是否启用 Qwen3 的思考能力 | | `max_tokens` | int | 8192 | 最大输出 token 数 | | `top_p` | float | 0.8 | Top-p 采样参数 | | `temperature` | float | 0.7 | 采样温度参数 | | `thinking_budget` | int | 可选 | 思考 token 预算上限 | 资料来源：[qwen_agent/llm.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm.py) ## 多 Agent 协作（A2A） 社区反馈（Issue #706）关注 Qwen-Agent 是否支持 A2A（Agent-to-Agent）架构。框架支持将一个 Agent 定义为另一个 Agent 的工具，实现多 Agent 协作： ```mermaid graph TD A[用户请求] --> B[主 Agent] B --> C[子 Agent 1] B --> D[子 Agent 2] B --> E[子 Agent 3] C --> F[执行结果] D --> F E --> F F --> B B --> G[综合响应] ``` ### 协作模式 | 模式 | 说明 | 适用场景 | |------|------|----------| | 串行协作 | 主 Agent 按顺序调用子 Agent | 任务有明确依赖关系 | | 并行协作 | 主 Agent 同时调用多个子 Agent | 任务可分解为独立子任务 | | 层级协作 | 子 Agent 可进一步调用其他 Agent | 复杂任务的递归分解 | ## 部署与集成 ### Gradio 部署 Qwen-Agent 原生支持 Gradio，可快速构建交互式 Web 界面： ```python from qwen_agent import FnCallAgent import gradio as gr agent = FnCallAgent(llm_cfg=llm_cfg) demo = gr.ChatInterface( fn=agent.run, title="Qwen Agent 演示", description="基于 Qwen3 的智能助手" ) demo.launch() ``` ### FastAPI 部署 将 Agent 发布为 API 服务： ```python from fastapi import FastAPI from qwen_agent import FnCallAgent from pydantic import BaseModel app = FastAPI() agent = FnCallAgent(llm_cfg=llm_cfg) class ChatRequest(BaseModel): message: str @app.post("/chat") async def chat(req: ChatRequest): response = agent.run(req.message) return {"response": response} ``` 这是社区中呼声较高的功能需求（Issue #609），框架层面支持统一的 API 发布将显著简化 Agent 的生产部署。 ### 环境变量配置 | 环境变量 | 说明 | |----------|------| | `DASHSCOPE_API_KEY` | DashScope API 密钥 | | `OPENAI_API_KEY` | OpenAI API 密钥 | | `OPENAI_BASE_URL` | OpenAI 兼容服务地址 | ## 安装指南 ### Windows 环境 ```powershell winget install --id=astral-sh.uv -e winget install git.git sqlite.sqlite ``` ### Python 环境 ```bash pip install qwen-agent ``` ### 开发环境 ```bash git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e . ``` ## 最佳实践 ### 1. 工具设计原则 - **单一职责**：每个工具应专注于完成一个明确的任务 - **清晰描述**：为工具和参数提供详细的中文文档字符串 - **错误处理**：工具应包含完善的异常处理和边界情况处理 ### 2. Agent 配置建议 | 场景 | 建议配置 | |------|----------| | 实时交互 | 关闭思考模式，设置较低 `max_tokens` | | 复杂推理 | 启用思考模式，设置较高 `max_tokens` | | 长文档问答 | 使用 Fast RAG 或 Parallel Doc QA 方案 | | 函数调用 | 使用 `FnCallAgent`，配置 `thought_in_content=False` | ### 3. 性能优化 - 使用流式输出（Streaming）提升用户体验 - 合理设置 `top_p` 和 `temperature` 平衡创造性与稳定性 - 长对话场景启用记忆压缩和摘要机制 ## 版本说明 当前稳定版本为 **v0.0.26**，主要特性： - 支持 SSE 连接超时配置 - MCP 工具自动重连机制 - 并行函数调用优化 - OpenAI 兼容 API 增强 ## 相关资源 - GitHub 仓库：https://github.com/QwenLM/Qwen-Agent - 官方文档：https://qwenlm.github.io/Qwen-Agent/ - 示例代码：https://github.com/QwenLM/Qwen-Agent/tree/main/examples - 问题反馈：https://github.com/QwenLM/Qwen-Agent/issues ## 社区贡献 Qwen-Agent 是一个开源项目，欢迎社区贡献者参与开发。主要贡献方式包括： - 提交 Issue 反馈问题或建议 - 提交 Pull Request 修复问题或添加功能 - 完善文档和使用示例 - 分享基于 Qwen-Agent 的应用案例 在报告问题时，团队希望社区成员能够温和表达，共同维护良好的开源协作氛围。资料来源：[Issue #1](https://github.com/QwenLM/Qwen-Agent/issues/1) --- ## 快速开始 ### 相关页面 相关主题：[Qwen-Agent 简介](#introduction), [工具使用指南](#tool_usage), [大模型集成](#llm_integration)
相关源码文件 以下源码文件用于生成本页说明： - [examples/assistant_add_custom_tool.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_add_custom_tool.py) - [qwen_agent/agents/assistant.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) - [examples/assistant_rag.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) - [examples/assistant_mcp_sqlite_bot.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py) - [examples/function_calling.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py) - [qwen_agent/tools/base.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/base.py) - [qwen_agent/utils/output_beautify.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/utils/output_beautify.py) - [browser_qwen.md](https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen.md)
# 快速开始 本页面为 Qwen-Agent 框架的入门指南，旨在帮助开发者快速上手构建基于 Qwen 大语言模型的智能体（Agent）应用。文档涵盖环境配置、基础组件使用、自定义工具开发以及常见应用场景的完整示例。 --- ## 1. 环境准备 ### 1.1 系统要求 | 组件 | 最低版本要求 | 检查命令 | |------|-------------|----------| | Python | 3.10+ | `python --version` | | Node.js | 最新版 | `node --version` | | Git | 任意版本 | `git --version` | ### 1.2 安装 Qwen-Agent Qwen-Agent 提供多种安装方式，开发者可根据需求选择minimal（最小依赖）或完整安装： ```bash # 最小安装（仅包含核心功能） pip install qwen-agent # 完整安装（包含所有可选依赖） pip install qwen-agent[gui,rag,code_interpreter,mcp] # 从源码安装最新开发版本 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ./"[gui,rag,code_interpreter,mcp]" ``` 资料来源：[README 源码片段]() ### 1.3 准备模型服务 Qwen-Agent 支持两种模型服务接入方式： | 方式 | 说明 | 配置要求 | |------|------|----------| | DashScope 云服务 | 阿里云提供的在线模型服务 | 设置环境变量 `DASHSCOPE_API_KEY` | | 自部署服务 | 使用 vLLM 或 Ollama 部署本地模型 | 配置 OpenAI 兼容 API 地址 | #### 使用 DashScope ```bash export DASHSCOPE_API_KEY="your-api-key-here" ``` #### 自部署 vLLM 服务 ```bash # 推荐命令（Qwen3 及以上模型不建议添加自动工具选择参数） vllm serve Qwen/Qwen2.5-72B-Instruct \ --host 0.0.0.0 \ --port 8000 ``` 资料来源：[README 源码片段]() --- ## 2. 核心组件架构 Qwen-Agent 框架采用分层架构设计，核心组件关系如下： ```mermaid graph TD A[用户应用层] --> B[Agent 层] B --> C[LLM 层] B --> D[Tool 层] B --> E[Memory 层] B --> F[Planning 层] C --> G[BaseChatModel] D --> H[BaseTool] E --> I[BaseMemory] F --> J[BasePlanner] G --> K[vLLM / DashScope / Ollama] style A fill:#e1f5fe style K fill:#f3e5f5 ``` ### 2.1 组件说明 | 组件类型 | 基类 | 用途 | |---------|------|------| | Agent | `class Agent` | 智能体编排，负责任务分解与执行 | | LLM | `class BaseChatModel` | 大语言模型接口封装 | | Tool | `class BaseTool` | 工具能力扩展 | | Memory | `class BaseMemory` | 会话历史与状态管理 | 资料来源：[qwen_agent/agents/assistant.py:1-50]() --- ## 3. 基础使用：构建 Assistant 智能体 Assistant 是 Qwen-Agent 框架中最常用的智能体类型，它基于 Qwen 模型的指令遵循、工具调用和规划能力构建。 ### 3.1 最小示例 以下示例展示了创建一个能够处理对话的基础 Assistant： ```python from qwen_agent.agents import Assistant # 初始化 Assistant bot = Assistant( model='qwen2.5-72b-instruct', api_key='your-api-key' # 或通过环境变量 DASHSCOPE_API_KEY 设置 ) # 定义对话历史 messages = [ {'role': 'user', 'content': '请介绍一下北京的历史'} ] # 运行对话 response = bot.run(messages) for res in response: print(res) ``` 资料来源：[examples/assistant_add_custom_tool.py:1-30]() ### 3.2 参数配置 | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | model | str | 必需 | 模型名称，如 `qwen2.5-72b-instruct` | | api_key | str | None | API 密钥，支持环境变量配置 | | base_url | str | None | 自定义 API 端点地址 | | llm_kwargs | dict | {} | 传递给 LLM 的额外参数（如 `temperature`, `top_p`） | 资料来源：[qwen_agent/agents/assistant.py:50-100]() ### 3.3 函数调用配置 Qwen-Agent 支持配置函数调用（Function Calling）能力： ```python from qwen_agent.agents import Assistant # 配置支持函数调用的 Assistant bot = Assistant( model='qwen2.5-72b-instruct', function_choice='auto' # 启用自动函数选择 ) messages = [{'role': 'user', 'content': '帮我查询北京的天气'}] response = bot.run(messages) ``` > **注意**：对于 QwQ 和 Qwen3 模型，建议**不要**添加 `--enable-auto-tool-choice` 和 `--tool-call-parser hermes` 参数，因为 Qwen-Agent 会自行解析工具输出。 资料来源：[README 源码片段]() --- ## 4. 自定义工具开发 Qwen-Agent 提供了灵活的 `@register_tool` 装饰器，用于注册自定义工具。 ### 4.1 工具开发流程 ```mermaid graph LR A[继承 BaseTool] --> B[实现工具元数据] B --> C[实现 tool_API 方法] C --> D[使用 @register_tool 装饰器] D --> E[在 Agent 中注册工具] ``` ### 4.2 完整示例：图像生成工具 ```python from qwen_agent.tools.base import BaseTool, register_tool from qwen_agent.utils.output_beautify import typewriter_print @register_tool('my_image_gen') class MyImageGen(BaseTool): description = '一个专业的AI图像生成工具' name = 'my_image_gen' parameters = { 'type': 'object', 'properties': { 'prompt': { 'type': 'string', 'description': '详细的图像生成描述' } }, 'required': ['prompt'] } def call(self, params: dict, **kwargs) -> str: prompt = params.get('prompt', '') # 调用图像生成服务 image_url = generate_image(prompt) return image_url ``` 资料来源：[examples/assistant_add_custom_tool.py:1-50]() ### 4.3 在 Assistant 中使用自定义工具 ```python from qwen_agent.agents import Assistant # 创建带自定义工具的 Assistant bot = Assistant( model='qwen2.5-72b-instruct', tools=['my_image_gen'] # 注册工具名称 ) # 对话交互 messages = [{'role': 'user', 'content': '生成一张赛博朋克风格的都市夜景'}] for response in bot.run(messages): typewriter_print(response) # 流式输出 ``` 资料来源：[examples/assistant_add_custom_tool.py:50-80]() ### 4.4 BaseTool 基类说明 | 方法/属性 | 说明 | |----------|------| | `name` | 工具唯一标识符 | | `description` | 工具功能描述（用于 LLM 理解何时调用） | | `parameters` | JSON Schema 格式的参数定义 | | `call(params, **kwargs)` | 核心执行方法，接收参数并返回结果 | 资料来源：[qwen_agent/tools/base.py:1-100]() --- ## 5. 扩展应用场景 ### 5.1 MCP 工具调用 Model Context Protocol (MCP) 允许连接外部工具服务器： ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] } } } ``` 资料来源：[README 源码片段]() ### 5.2 SQLite 数据库查询示例 ```python from qwen_agent.agents import Assistant bot = Assistant( model='qwen2.5-72b-instruct', mcp_servers={ "sqlite": { "command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "test.db"] } } ) ``` 资料来源：[examples/assistant_mcp_sqlite_bot.py:1-30]() ### 5.3 RAG 应用 Qwen-Agent 提供了快速构建 RAG（检索增强生成）应用的示例： ```python from qwen_agent.agents import Assistant # 初始化 RAG Assistant bot = Assistant( model='qwen2.5-72b-instruct', rag_config={ 'chunk_size': 512, 'embedding_model': 'text-embedding-v3' } ) # 加载文档并查询 bot.load_document('path/to/your/document.pdf') response = bot.run([{'role': 'user', 'content': '文档的主要内容是什么？'}]) ``` > Qwen-Agent 还提供了超长文档（1M tokens）处理的快速 RAG 解决方案和并行文档问答方案。 资料来源：[examples/assistant_rag.py:1-50]() ### 5.4 代码解释器 代码解释器功能支持在沙箱环境中执行代码： ```python from qwen_agent.agents import CodeInterpreter interpreter = CodeInterpreter( model='qwen2.5-72b-instruct', sandbox_mode='docker' # 或 'process' ) result = interpreter.run([ {'role': 'user', 'content': '计算 1 到 100 的和'} ]) ``` --- ## 6. BrowserQwen 浏览器助手 BrowserQwen 是基于 Qwen-Agent 构建的浏览器扩展应用，提供网页自动化交互能力。 ### 6.1 主要功能 | 功能 | 说明 | |------|------| | 网页内容提取 | 自动读取和解析网页内容 | | 智能问答 | 基于网页内容进行问答 | | 操作自动化 | 模拟用户交互行为 | ### 6.2 弹出窗口配置 BrowserQwen 的用户界面通过 `popup.html` 定义，支持文件上传和交互按钮配置： ```html
``` 资料来源：[browser_qwen/src/popup.html:1-50]() 详细配置请参考 [BrowserQwen 文档](https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen.md)。 --- ## 7. 常见问题与社区反馈 ### 7.1 社区热门议题 根据 GitHub Issue 统计，开发者关注的重点问题包括： | Issue | 类型 | 说明 | |-------|------|------| | #609 | 功能建议 | 希望框架支持将 Agent 发布为 HTTP+JSON API 服务 | | #706 | 功能询问 | 询问是否支持 A2A（Agent-to-Agent）架构 | | #368 | 技术咨询 | 函数调用微调的数据构造方法 | | #698 | 功能建议 | 请求添加无沙箱模式选项 | ### 7.2 调试建议 1. **函数调用不工作**：检查模型是否支持 function calling，尝试使用 `qwen2.5` 系列模型 2. **MCP 连接失败**：确认 Node.js 已正确安装，尝试使用 `npx -y` 前缀 3. **流式输出异常**：使用 `typewriter_print` 函数确保输出格式正确 资料来源：[qwen_agent/utils/output_beautify.py:1-30]() --- ## 8. 下一步 | 文档章节 | 内容概要 | |---------|----------| | [函数调用开发](./function_calling.md) | 深入了解 function calling 机制与微调方法 | | [MCP 集成](./mcp_integration.md) | 外部工具服务器的配置与使用 | | [RAG 进阶](./rag_advanced.md) | 超长文档处理与检索优化 | | [部署指南](./deployment.md) | 生产环境部署与 API 服务化 | --- *如有问题或建议，欢迎通过 [GitHub Issues](https://github.com/QwenLM/Qwen-Agent/issues) 反馈。* --- ## 安装指南 ### 相关页面 相关主题：[Qwen-Agent 简介](#introduction)
相关源码文件 以下源码文件用于生成本页说明： - [setup.py](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) - [qwen_agent/tools/code_interpreter.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py) - [qwen_agent/tools/resource/code_interpreter_image.dockerfile](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/resource/code_interpreter_image.dockerfile) - [qwen_agent/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/__init__.py) - [examples/assistant_mcp_sqlite_bot.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py)
# 安装指南 本文档详细介绍 Qwen-Agent 框架的完整安装流程、环境配置要求以及常见问题的解决方案。Qwen-Agent 是基于 Qwen 大语言模型的 AI Agent 开发框架，提供了丰富的原子组件（如 LLM、Tools）和高级组件（如 Agents），支持函数调用、代码解释、MCP 协议集成等功能。 --- ## 系统要求 ### 硬件要求 | 组件类型 | 最低配置 | 推荐配置 | |---------|---------|---------| | CPU | 4 核 | 8 核及以上 | | 内存 | 8 GB | 16 GB 及以上 | | 磁盘空间 | 10 GB | 20 GB 及以上 | | GPU | 可选 | NVIDIA GPU + CUDA 11.8+ | ### 软件要求 | 软件 | 版本要求 | 用途 | |-----|---------|-----| | Python | ≥ 3.9 | 运行环境 | | pip | 最新版本 | 包管理器 | | Docker | ≥ 20.10 | 代码解释器容器化 | | Git | 任意版本 | 代码克隆 | > 资料来源：[setup.py:1-50](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) --- ## 安装方式 ### 方式一：pip 安装（推荐） 最简便的安装方式，通过 Python 包管理器直接安装： ```bash pip install qwen-agent ``` 此方式会自动安装所有核心依赖项，包括： - `qwen-agent` 核心框架 - 基础工具集 - 必要的 Python 依赖包 ### 方式二：从源码安装 适合需要自定义修改或参与开发的用户： ```bash # 克隆源码仓库 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent # 安装包及开发依赖 pip install -e . ``` > 资料来源：[setup.py:50-80](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) ### 方式三：Docker 安装 框架提供了预配置的 Docker 镜像，适用于代码解释器等功能的使用： ```bash # 克隆源码仓库 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent # 构建代码解释器镜像 docker build -f qwen_agent/tools/resource/code_interpreter_image.dockerfile \ -t qwen-agent-code-interpreter:latest . ``` > 资料来源：[qwen_agent/tools/resource/code_interpreter_image.dockerfile:1-30](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/resource/code_interpreter_image.dockerfile) --- ## 代码解释器环境配置 代码解释器是 Qwen-Agent 的核心组件之一，允许 AI Agent 执行 Python 代码。该功能基于 Docker 容器实现，确保代码执行的安全隔离。 ### 架构说明 ```mermaid graph TD A[用户请求] --> B[Agent 控制器] B --> C{代码执行请求?} C -->|是| D[代码解释器工具] D --> E[Docker 容器] E --> F[Python 代码执行] F --> G[执行结果返回] G --> D D --> H[结果返回 Agent] H --> A ``` ### 环境变量配置 代码解释器支持以下环境变量配置： | 环境变量 | 说明 | 默认值 | |---------|-----|-------| | `CODE_INTERPRETER_WORKDIR` | 工作目录挂载路径 | `/workspace` | | `CODE_INTERPRETER_TIMEOUT` | 单次执行超时时间（秒） | `60` | | `DOCKER_IMAGE` | 使用的 Docker 镜像名称 | `qwen-agent-code-interpreter` | > 资料来源：[qwen_agent/tools/code_interpreter.py:30-80](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py) ### 配置示例 ```python import os from qwen_agent import Agent # 设置代码解释器环境变量 os.environ['CODE_INTERPRETER_WORKDIR'] = '/tmp/code_workspace' os.environ['CODE_INTERPRETER_TIMEOUT'] = '120' # 初始化 Agent agent = Agent( model='qwen-turbo', function_tools=['code_interpreter'] ) ``` --- ## 大语言模型后端配置 Qwen-Agent 支持多种 LLM 后端部署方式，开发者可根据实际需求选择。 ### 支持的部署方式 | 部署方式 | 适用场景 | 特点 | |---------|---------|-----| | [vLLM](https://github.com/vllm-project/vllm) | 高吞吐量 GPU 部署 | 高效、易扩展 | | [Ollama](https://github.com/ollama/ollama) | 本地 CPU/GPU 部署 | 简单易用、隐私保护 | | [DashScope](https://dashscope.console.aliyun.com/) | 云端 API 调用 | 即开即用、无需配置 | > 资料来源：[qwen_agent/__init__.py:1-50](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/__init__.py) ### vLLM 配置示例 ```python from qwen_agent import LLM # vLLM 后端配置 llm = LLM( model='Qwen/Qwen2-7B-Instruct', model_server='vllm', api_base='http://localhost:8000/v1' ) ``` ### Ollama 配置示例 ```python from qwen_agent import LLM # Ollama 后端配置 llm = LLM( model='qwen2:7b', model_server='ollama', api_base='http://localhost:11434/v1' ) ``` --- ## MCP 服务器集成配置 Qwen-Agent 支持 Model Context Protocol (MCP) 协议，可以连接多种外部工具服务器。 ### MCP 依赖要求 | 依赖项 | 版本要求 | 安装命令 | |-------|---------|---------| | Node.js | 最新稳定版 | 参考 [Node.js 官网](https://nodejs.org/) | | uv | ≥ 0.4.18 | `pip install uv` | | Git | 任意版本 | 系统包管理器安装 | > 资料来源：[examples/assistant_mcp_sqlite_bot.py:1-30](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py) ### 各平台依赖安装 **macOS:** ```bash brew install uv git sqlite3 ``` **Windows:** ```bash winget install --id=astral-sh.uv -e winget install git.git sqlite.sqlite ``` ### MCP 服务器配置格式 在项目配置文件中定义 MCP 服务器： ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] }, "sqlite": { "command": "uvx", "args": [ "mcp-server-sqlite", "--db-path", "test.db" ] } } } ``` > 更多 MCP 服务器可在 [MCP Server GitHub 仓库](https://github.com/modelcontextprotocol/servers) 查找。 --- ## 快速开始示例 ### 基础对话 Agent ```python from qwen_agent import Agent # 创建助手 Agent assistant = Agent(model='qwen-turbo') # 运行对话 messages = [{'role': 'user', 'content': '你好，请介绍一下你自己'}] response = assistant.run(messages) for msg in response: print(msg) ``` ### 带工具调用的 Agent ```python from qwen_agent import Agent # 创建带函数调用能力的 Agent assistant = Agent( model='qwen-turbo', function_tools=['python'] ) messages = [{'role': 'user', 'content': '请帮我计算 2 的 10 次方'}] response = assistant.run(messages) ``` --- ## 常见问题 ### 1. Docker 镜像构建失败 **问题描述：** 构建代码解释器镜像时出现错误。 **解决方案：** - 确保 Docker 版本 ≥ 20.10 - 检查网络连接，确保可以访问 Docker Hub - 使用国内镜像源（需要自行配置） ```bash # 配置 Docker 镜像加速 docker set-up-daemon.json --registry-mirror=https://docker.mirrors.ustc.edu.cn ``` ### 2. 代码解释器执行超时 **问题描述：** 代码执行总是超时。 **解决方案：** - 增加超时时间配置：`CODE_INTERPRETER_TIMEOUT=300` - 检查代码是否存在死循环 - 确认 Docker 容器资源限制是否足够 ### 3. MCP 服务器无法连接 **问题描述：** 启动 MCP 服务器后 Agent 无法调用。 **解决方案：** - 确认 Node.js 已正确安装：`node --version` - 检查 uv 版本：`uv --version` - 查看 MCP 服务器日志定位具体错误 ### 4. 函数调用效果不佳 **问题描述：** 使用 Qwen2 函数调用效果不理想。 **解决方案：** 根据社区反馈（[Issue #368](https://github.com/QwenLM/Qwen-Agent/issues/368)），可能需要针对特定场景进行微调。建议： - 准备高质量的函数调用训练数据 - 参考官方微调文档构造数据格式 - 使用领域特定数据进行微调 --- ## 下一步 安装完成后，建议继续阅读以下文档： - [快速开始指南](./getting_started.md) - [Agent 开发教程](./agent_development.md) - [函数调用文档](./function_calling.md) - [API 参考文档](./api_reference.md) --- ## 核心模块架构 ### 相关页面 相关主题：[Agent 系统详解](#agent_system), [大模型集成](#llm_integration), [工具使用指南](#tool_usage)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/agent.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) - [qwen_agent/llm/base.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/base.py) - [qwen_agent/tools/base.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/base.py) - [qwen_agent/memory/memory.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/memory/memory.py) - [qwen_agent/agents/assistant.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) - [qwen_agent/llm/function_calling.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/function_calling.py)
# 核心模块架构 ## 概述 Qwen-Agent 是一个基于 Qwen 大语言模型的 Agent 应用开发框架，其核心设计围绕 **LLM（语言模型）**、**Tool（工具）**、**Agent（智能体）** 和 **Memory（记忆）** 四大原子组件展开。框架采用模块化架构，使开发者能够灵活组合这些组件来构建复杂的 AI 应用。 资料来源：[qwen_agent/agent.py:1-50]() ## 整体架构图 ```mermaid graph TB subgraph "应用层" Assistant["Assistant Agent"] BrowserQwen["BrowserQwen"] CodeInterpreter["Code Interpreter"] RAG["RAG 应用"] end subgraph "核心模块层" Agent["Agent 基类"] LLM["BaseChatModel"] Tool["BaseTool"] Memory["Memory"] end subgraph "工具生态层" MCP["MCP Tools"] FunctionCalling["Function Calling"] CodeInterp["代码解释器"] Search["搜索工具"] end subgraph "模型服务层" DashScope["DashScope API"] vLLM["vLLM"] Ollama["Ollama"] end Application --> Core Core --> Tools Tools --> ModelService LLM --> Agent Memory --> Agent Tool --> Agent ``` ## 核心模块详解 ### 1. Agent 模块 #### 1.1 Agent 基类 Agent 是整个框架的核心抽象类，负责协调 LLM、Tool 和 Memory 之间的交互。 ```python class Agent: def __init__(self, llm, tools=None, memory=None): self.llm = llm self.tools = tools or [] self.memory = memory ``` **主要职责：** - 管理对话历史和上下文 - 解析 LLM 响应中的工具调用 - 执行工具并收集结果 - 生成最终回复 资料来源：[qwen_agent/agent.py:30-80]() #### 1.2 Assistant Agent Assistant 是 Agent 的具体实现类，提供了开箱即用的对话智能体功能： ```python from qwen_agent.agents import Assistant assistant = Assistant( llm={'model': 'qwen-max'}, tools=['google_search', 'code_interpreter'], description='助手描述' ) ``` **特性：** - 支持多轮对话 - 内置函数调用解析 - 可扩展的工具系统 - 灵活的提示词模板 资料来源：[qwen_agent/agents/assistant.py:1-100]() ### 2. LLM 模块 #### 2.1 BaseChatModel 基类 LLM 模块是 Qwen-Agent 与大语言模型交互的核心接口。所有模型实现都继承自 `BaseChatModel`： ```python class BaseChatModel: def __init__(self, model: str = '', api_key: str = None, ...): self.model = model self.api_key = api_key or os.getenv('DASHSCOPE_API_KEY') def chat(self, messages, tools=None, stream=False, **kwargs): raise NotImplementedError ``` **支持的模型服务：** | 服务商 | 配置方式 | 特点 | |--------|----------|------| | DashScope | `DASHSCOPE_API_KEY` 环境变量 | 阿里云托管服务 | | vLLM | OpenAI-compatible API | 高吞吐量 GPU 部署 | | Ollama | 本地 CPU/GPU | 适合本地开发测试 | 资料来源：[qwen_agent/llm/base.py:20-60]() #### 2.2 函数调用（Function Calling） 函数调用是 LLM 模块的重要功能，支持模型调用外部工具： ```python from qwen_agent.llm import FunctionCallModel llm = FunctionCallModel(model='qwen-max') response = llm.chat( messages=[{'role': 'user', 'content': '查询北京天气'}], tools=[{ 'type': 'function', 'function': { 'name': 'get_weather', 'parameters': {'type': 'object', 'properties': {...}} } }] ) ``` **配置参数：** | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | `model` | string | 模型名称 | 必填 | | `api_key` | string | API 密钥 | 环境变量 | | `max_token` | int | 最大生成 token 数 | 2048 | | `top_p` | float | 采样概率阈值 | 0.8 | | `temperature` | float | 采样温度 | 0.7 | 资料来源：[qwen_agent/llm/function_calling.py:1-80]() ### 3. Tool 模块 #### 3.1 BaseTool 基类 Tool 模块提供了扩展 Agent 能力的标准化接口： ```python from qwen_agent.tools.base import BaseTool, register_tool @register_tool('my_tool') class MyTool(BaseTool): name = 'my_tool' description = '工具描述' def call(self, params): # 工具实现 return result ``` **工具注册机制：** - 使用 `@register_tool` 装饰器注册自定义工具 - 工具名称全局唯一 - 支持嵌套工具定义 资料来源：[qwen_agent/tools/base.py:30-100]() #### 3.2 内置工具生态 ```mermaid graph LR MCP["MCP Server"] --> MCP_Tools["MCP 工具"] BuiltIn["内置工具"] --> Search["搜索工具"] BuiltIn --> Code["代码执行"] BuiltIn --> File["文件操作"] Custom["自定义工具"] --> Registry["工具注册表"] MCP_Tools --> Registry Search --> Registry Code --> Registry File --> Registry Custom --> Registry ``` **MCP 工具集成示例：** ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] } } } ``` ### 4. Memory 模块 #### 4.1 Memory 基类 Memory 模块负责管理 Agent 的对话历史和上下文： ```python class Memory: def __init__(self, max_tokens: int = 10000): self.messages = [] self.max_tokens = max_tokens def add(self, message: dict): self.messages.append(message) def get_messages(self): return self.messages def clear(self): self.messages = [] ``` **功能特性：** - 自动历史记录管理 - Token 数量限制和截断 - 支持消息过滤和检索 资料来源：[qwen_agent/memory/memory.py:1-60]() ## 模块交互流程 ```mermaid sequenceDiagram participant User as 用户 participant Agent as Agent participant LLM as LLM participant Tool as Tool participant Memory as Memory User->>Agent: 发送请求 Agent->>Memory: 获取历史上下文 Agent->>LLM: 发送带历史的请求 LLM-->>Agent: 返回响应/工具调用 alt 需要调用工具 Agent->>Tool: 执行工具 Tool-->>Agent: 返回结果 Agent->>LLM: 继续对话 LLM-->>Agent: 返回最终响应 end Agent->>Memory: 更新对话历史 Agent-->>User: 返回结果 ``` ## 扩展开发指南 ### 开发自定义 Agent ```python from qwen_agent.agents import Agent from qwen_agent.llm import BaseChatModel from qwen_agent.tools.base import BaseTool class MyAgent(Agent): def __init__(self, llm: BaseChatModel, tools: list[BaseTool] = None): super().__init__(llm=llm, tools=tools) # 自定义初始化逻辑 def run(self, query: str, **kwargs): # 自定义运行逻辑 return super().run(query, **kwargs) ``` ### 开发自定义 Tool ```python from qwen_agent.tools.base import BaseTool, register_tool @register_tool('custom_tool') class CustomTool(BaseTool): name = 'custom_tool' description = '自定义工具描述' parameters = { 'type': 'object', 'properties': { 'param1': {'type': 'string', 'description': '参数1'} }, 'required': ['param1'] } def call(self, param1: str, **kwargs): # 实现工具逻辑 return {'result': f'处理了: {param1}'} ``` ## 社区相关讨论 ### API 服务化需求 社区 Issue #609 提出了将 Agent 发布为 API 服务的需求： > "目前开了几个Agent，确实效果不错...所以这几天一直在寻找将 Agent 发布成一个 API，可以使用 Fast API 等来发布" 当前框架主要通过 Gradio 提供演示界面，生产环境部署需要开发者自行实现 API 封装。 ### Agent-to-Agent 架构 Issue #706 询问框架是否支持 A2A（Agent-to-Agent）架构： > "框架是否支持定义一个 Agent 作为一个工具可以由另一个 Agent 去根据需要调用？" 通过将 Agent 注册为 Tool，可以实现 Agent 间的调用和协作。 ## 配置参数汇总 ### LLM 配置 ```python llm_config = { 'model': 'qwen-max', 'api_key': os.getenv('DASHSCOPE_API_KEY'), 'max_tokens': 2048, 'top_p': 0.8, 'temperature': 0.7, 'stream': False, # vLLM 特定参数 'use_raw_api': True, } ``` ### Agent 配置 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `llm` | BaseChatModel | 是 | 语言模型实例 | | `tools` | list[BaseTool] | 否 | 工具列表 | | `memory` | Memory | 否 | 记忆模块实例 | | `description` | str | 否 | Agent 描述 | | `system_message` | str | 否 | 系统提示词 | ## 总结 Qwen-Agent 的核心模块架构体现了清晰的关注点分离原则： 1. **LLM 模块**：提供统一的模型调用接口，支持多种后端服务 2. **Tool 模块**：通过标准化协议扩展 Agent 能力 3. **Memory 模块**：管理对话历史和上下文 4. **Agent 模块**：协调以上三个模块，实现智能对话和应用 这种架构设计使得开发者可以专注于业务逻辑，通过组合和扩展核心组件来构建满足特定需求的 AI 应用。 --- ## Agent 系统详解 ### 相关页面 相关主题：[核心模块架构](#core_modules), [工具使用指南](#tool_usage)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/agents/assistant.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) - [qwen_agent/agents/fncall_agent.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/fncall_agent.py) - [qwen_agent/agents/react_chat.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/react_chat.py) - [qwen_agent/agents/group_chat.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/group_chat.py) - [qwen_agent/agents/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/__init__.py) - [qwen_agent/agent.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) - [qwen_agent/llm/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/__init__.py) - [qwen_agent/tools/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py)
# Agent 系统详解 ## 1. 系统概述 Qwen-Agent 是一个基于 Qwen 大语言模型的 Agent 开发框架，旨在帮助开发者快速构建具有指令遵循、工具使用、规划推理和记忆能力的 LLM 应用。Agent 系统是整个框架的核心组件，提供了从基础 Agent 抽象到多种预置 Agent 实现的全方位支持。 ### 1.1 设计目标 Agent 系统的主要设计目标包括以下几个方面： **模块化架构**：框架采用继承和多态的面向对象设计，将 Agent 的核心逻辑抽象为基类，具体的 Agent 类型通过继承和重写特定方法来实现差异化功能。这种设计使得开发者可以方便地扩展现有 Agent 或创建全新的 Agent 类型。 **工具集成能力**：Agent 系统原生支持工具调用机制，开发者可以通过注册工具来扩展 Agent 的能力边界。框架内置了多种常用工具，如代码解释器、函数调用、RAG 检索等，同时也支持通过 MCP（Model Context Protocol）协议接入外部工具服务。 **多 Agent 协作**：框架提供了 GroupChat 功能，支持多个 Agent 之间的协作交互。这使得复杂任务可以被分解为多个子任务，由不同的专业 Agent 分别处理后再整合结果。 **灵活的对话管理**：Agent 系统提供了完善的对话历史管理机制，支持流式输出、多轮对话、消息过滤等功能，可以满足不同应用场景的需求。 ### 1.2 核心组件关系 Agent 系统由多个核心组件构成，它们之间的关系如下所示： ```mermaid graph TD A[LLM 大语言模型] --> B[BaseChatModel] B --> C[FunctionCallChat] B --> D[BaseAgent] D --> E[Assistant] D --> F[FncallAgent] D --> G[ReActChat] D --> H[GroupChat] E --> I[自定义 Agent] F --> I G --> I H --> I J[Tools 工具集] --> K[BaseTool] K --> L[代码解释器] K --> M[RAG 工具] K --> N[MCP 工具] I --> J ``` 从图中可以看出，Agent 系统采用了经典的分层架构设计。LLM 是最底层的模型接口层，BaseAgent 定义了 Agent 的标准行为，各种预置的 Agent 实现（Assistant、FncallAgent、ReActChat、GroupChat）提供了不同场景下的最佳实践，而 Tools 系统则为 Agent 提供了执行具体任务的能力。 ## 2. Agent 基类架构 ### 2.1 BaseAgent 抽象类 BaseAgent 是所有 Agent 类型的基类，定义 Agent 的核心接口和行为规范。根据源码，BaseAgent 的主要职责包括消息处理、工具调用控制、对话状态管理等。 **BaseAgent 核心属性：** | 属性名 | 类型 | 说明 | |--------|------|------| | llm | BaseChatModel | 绑定的大语言模型实例 | | system_message | str | 系统提示词 | | function_list | List[str] | 可用工具列表 | | files | List[str] | 附加文件列表 | | memory | BaseMemory | 对话记忆组件 | | max_retries | int | 最大重试次数 | **BaseAgent 核心方法：** | 方法名 | 参数 | 返回值 | 说明 | |--------|------|--------|------| | run | messages: List | Iterator[Dict] | 运行 Agent 处理请求，返回流式响应 | | chat | messages: List | Dict | 简化的同步聊天接口 | | _run | messages: List | Iterator[Dict] | 子类需要实现的实际运行逻辑 | | _call_llm | messages: List | Dict | 调用大语言模型 | | _tool_call | function_call: Dict | Dict | 执行工具调用 | 资料来源：[qwen_agent/agent.py:1-150]() ### 2.2 消息处理流程 Agent 的消息处理流程可以划分为以下几个阶段： ```mermaid sequenceDiagram participant User as 用户 participant Agent as BaseAgent participant LLM as 大语言模型 participant Tool as 工具系统 participant Memory as 记忆系统 User->>Agent: 发送用户消息 Agent->>Memory: 查询历史上下文 Memory-->>Agent: 返回相关记忆 Agent->>Agent: 构建完整消息列表 Agent->>LLM: 发送消息请求 alt 模型返回工具调用 LLM-->>Agent: 返回函数调用指令 Agent->>Tool: 执行工具调用 Tool-->>Agent: 返回执行结果 Agent->>LLM: 将结果反馈给模型 LLM-->>Agent: 生成最终回复 else 模型直接回复 LLM-->>Agent: 返回文本回复 end Agent->>Memory: 更新对话记忆 Agent-->>User: 流式返回响应 ``` 从上述流程可以看出，Agent 的核心工作模式是一个"思考-行动-观察"的循环。模型根据输入决定是直接回复还是调用工具，工具执行后的结果会被反馈给模型以生成下一轮响应。这个循环会持续进行，直到模型认为任务完成或达到最大迭代次数。 ### 2.3 工具调用机制 工具调用是 Agent 系统的重要能力，它使得 Agent 能够执行具体的操作而不仅仅是生成文本。Qwen-Agent 提供了两种主要的工具调用方式： **Function Calling 模式**：通过模型的 function call 能力，让模型直接生成结构化的工具调用指令。这种方式适合与支持 function call 的模型配合使用，如 Qwen2、Qwen3 等。 **ReAct 模式**：通过提示词引导模型生成"Thought-Action-Observation"格式的推理过程，然后由系统解析并执行相应的工具调用。这种方式更加灵活，可以与不支持原生 function call 的模型配合使用。 ## 3. 预置 Agent 类型详解 ### 3.1 Assistant Agent Assistant 是最基础的 Agent 类型，提供了简洁易用的对话交互能力。它适合作为开发自定义 Agent 的起点，也是快速验证想法和原型的最佳选择。 **主要特性：** - 支持多轮对话和流式输出 - 可配置的系统提示词 - 灵活的工具注册机制 - 文件附件支持 - 对话历史自动管理 **基本使用方式：** ```python from qwen_agent.agents import Assistant from qwen_agent.llm import get_chat_model llm_cfg = { 'model': 'qwen-plus', 'model_server': 'dashscope', 'api_key': os.getenv('DASHSCOPE_API_KEY') } llm = get_chat_model(llm_cfg) bot = Assistant( llm=llm, system_message='你是一个有用的AI助手', function_list=['my_image_gen', 'code_interpreter'] ) messages = [{'role': 'user', 'content': '请帮我画一张图片'}] for response in bot.run(messages): print(response) ``` 资料来源：[qwen_agent/agents/assistant.py:1-100]() ### 3.2 FncallAgent 函数调用Agent FncallAgent 是专门为函数调用场景优化的 Agent 类型，它充分利用了 Qwen2/Qwen3 系列模型的原生 function call 能力，提供了更加稳定和高效的工具调用体验。 **与 Assistant 的区别：** | 特性 | Assistant | FncallAgent | |------|-----------|-------------| | 工具调用方式 | 提示词解析 | 原生 Function Call | | 模型要求 | 通用 | 需要支持 function call | | 调用稳定性 | 中等 | 高 | | 响应速度 | 依赖解析质量 | 较快 | | 适用场景 | 快速原型 | 生产环境 | FncallAgent 特别适合需要频繁调用工具的生产环境应用，因为它减少了提示词解析的不确定性，提高了工具调用的准确性和稳定性。 资料来源：[qwen_agent/agents/fncall_agent.py:1-80]() ### 3.3 ReActChat 推理与行动Agent ReActChat 基于 ReAct（Reasoning + Acting）范式实现，是处理复杂多步推理任务的理想选择。这种 Agent 能够通过显式的思考过程来分解问题，然后逐步执行工具调用来获取信息或执行操作。 **ReAct 推理模式：** ```mermaid graph TD A[接收用户问题] --> B[Thought: 思考当前状态和下一步] B --> C[Action: 选择并执行工具] C --> D[Observation: 观察执行结果] D --> E{任务完成?} E -->|否| B E -->|是| F[生成最终回答] ``` **ReAct 的优势：** - **可解释性**：推理过程清晰可见，便于调试和理解 Agent 的行为 - **灵活性**：不依赖模型的原生 function call 能力，可与各种模型配合 - **鲁棒性**：通过多次小步推理降低单次决策失误的影响 - **组合性**：可以自然地组合多个工具完成复杂任务 ReActChat 特别适合以下场景：需要多步信息检索的问答系统、需要进行复杂计算或数据处理的任务、需要与环境进行多轮交互的应用。 资料来源：[qwen_agent/agents/react_chat.py:1-120]() ### 3.4 GroupChat 多Agent协作系统 GroupChat 是 Qwen-Agent 框架中用于实现多 Agent 协作的高级功能。它允许定义多个专业化的 Agent，并通过协调机制让它们协作完成复杂任务。 **GroupChat 架构：** ```mermaid graph LR subgraph GroupChat C[Coordinator
协调器] A1[Agent 1] A2[Agent 2] A3[Agent N] C --> A1 C --> A2 C --> A3 end U[User
用户] U --> C A1 --> C A2 --> C A3 --> C ``` **核心机制：** GroupChat 的协调器负责管理对话流程，它会根据当前任务和 Agent 的能力描述，决定将任务分配给哪个 Agent 处理，以及如何整合各 Agent 的回复。协调器可以采用不同的策略，如顺序执行、并行执行或动态路由。 **应用场景：** - **任务分解**：将复杂任务分解为多个子任务，分配给专业 Agent - **专家咨询**：不同领域的专家 Agent 协作提供综合建议 - **质量保证**：一个 Agent 生成内容，另一个 Agent 进行审查 资料来源：[qwen_agent/agents/group_chat.py:1-150]() ## 4. 工具系统详解 ### 4.1 工具架构 Qwen-Agent 的工具系统采用插件化设计，所有工具都继承自 BaseTool 基类。这种设计使得开发者可以方便地添加自定义工具，同时保证工具使用的统一接口。 **BaseTool 接口定义：** | 方法 | 说明 | |------|------| | call | 执行工具的实际操作 | | detect | 检测工具是否适用于当前任务 | | description | 返回工具的功能描述 | **工具注册机制：** 框架使用装饰器模式来注册工具，通过 `@register_tool` 装饰器可以将自定义类注册到全局工具列表中： ```python from qwen_agent.tools.base import BaseTool, register_tool @register_tool('my_tool') class MyTool(BaseTool): description = '我的自定义工具' name = 'my_tool' def call(self, params: str, **kwargs) -> str: # 工具实现 return result ``` 资料来源：[qwen_agent/tools/__init__.py:1-50]() ### 4.2 内置工具 框架提供了多种内置工具，开发者可以直接使用： | 工具名称 | 功能说明 | |----------|----------| | code_interpreter | 代码解释器，在沙箱环境中执行 Python 代码 | | my_image_gen | 图像生成工具 | | RAG | 检索增强生成工具 | | MCP | Model Context Protocol 协议适配器 | **代码解释器配置：** 代码解释器是 Agent 系统的重要工具，它允许 Agent 执行动态生成的代码来完成任务。配置代码解释器需要确保 Docker 环境可用： ```python tools = ['code_interpreter'] # 内置工具 # 或包含自定义工具 tools = ['my_image_gen', 'code_interpreter'] ``` ### 4.3 MCP 工具集成 MCP（Model Context Protocol）是一种标准化的工具集成协议，Qwen-Agent 提供了对 MCP 的原生支持。通过 MCP，开发者可以接入丰富的外部工具生态系统。 **MCP 配置示例：** ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] } } } ``` MCP 工具的配置需要安装 Node.js 环境，并且对于某些 MCP 服务器还需要 uv 等依赖工具。框架支持自动重连机制，能够在连接断开后自动恢复。 ## 5. 与大语言模型的集成 ### 5.1 LLM 接口抽象 Qwen-Agent 定义了统一的 LLM 接口 `BaseChatModel`，所有支持的模型服务都实现这个接口。这种设计使得切换不同的模型提供商变得非常简单。 **支持的模型服务：** | 服务类型 | 说明 | 配置参数 | |----------|------|----------| | dashscope | 阿里云 DashScope API | api_key, model | | vLLM | 自托管 vLLM 服务 | api_base, model | | Ollama | 本地 Ollama 服务 | api_base, model | | OpenAI | OpenAI 兼容 API | api_key, api_base, model | **配置示例：** ```python llm_cfg = { 'model': 'qwen-plus', 'model_server': 'dashscope', 'api_key': os.getenv('DASHSCOPE_API_KEY'), # 可选参数 'top_p': 0.8, 'temperature': 0.7, 'max_tokens': 2000 } ``` 资料来源：[qwen_agent/llm/__init__.py:1-100]() ### 5.2 Function Call 配置 对于支持 function call 的模型（如 Qwen2、Qwen3 系列），框架提供了灵活的配置选项： **vLLM 部署建议：** - QwQ 和 Qwen3 模型：建议**不要**添加 `--enable-auto-tool-choice` 和 `--tool-call-parser hermes` 参数，框架会自动解析工具输出 - Qwen3-Coder 模型：建议启用上述参数，使用 vLLM 内置的工具解析，并配合 `use_raw_api` 参数使用 ### 5.3 流式输出 Agent 系统原生支持流式输出，这使得用户可以实时看到 Agent 的响应，提升交互体验： ```python response_plain_text = '' for response in bot.run(messages): response_plain_text = typewriter_print(response, response_plain_text) ``` `typewriter_print` 函数实现了逐字符的流式打印效果，可以直接用于 Gradio 或 WebUI 界面。 ## 6. 部署与集成 ### 6.1 Gradio 界面部署 Qwen-Agent 提供了便捷的 Gradio 界面支持，只需几行代码即可将 Agent 部署为 Web 应用： ```python from qwen_agent.gui import WebUI WebUI(bot).run() ``` 这使得开发者可以快速创建可交互的 Demo，方便测试和演示。 ### 6.2 API 服务化 根据社区反馈（Issue #609），将 Agent 发布为 API 服务是一个重要需求。虽然框架主要面向 Gradio 部署，但开发者可以通过以下方式实现 API 服务化： **FastAPI 集成示例：** ```python from fastapi import FastAPI from pydantic import BaseModel from qwen_agent.agents import Assistant app = FastAPI() class ChatRequest(BaseModel): message: str history: list = [] @app.post("/chat") async def chat(request: ChatRequest): messages = request.history + [{'role': 'user', 'content': request.message}] responses = [] for response in agent.run(messages): responses.extend(response) return {"response": responses[-1], "history": messages + responses} ``` 框架层面可能会在后续版本中提供原生的 API 服务支持，以简化部署流程。 ### 6.3 A2A 架构支持 社区用户（Issue #706）询问框架是否支持 A2A（Agent-to-Agent）架构。GroupChat 功能部分实现了多 Agent 协作能力，允许一个 Agent 将另一个 Agent 作为工具调用： ```python # Agent A 可以被 Agent B 调用 agent_b = Assistant( function_list=['agent_a', 'other_tools'] ) ``` 这种设计使得复杂任务可以被分解为多个专业化的 Agent，每个 Agent 负责特定领域的任务。 ## 7. 最佳实践 ### 7.1 工具设计原则 设计有效的工具需要遵循以下原则： | 原则 | 说明 | 示例 | |------|------|------| | 单一职责 | 每个工具只做一件事 | `get_weather` 只获取天气 | | 清晰描述 | 提供准确的工具描述 | `description` 说明输入输出格式 | | 错误处理 | 优雅处理异常情况 | 返回结构化的错误信息 | | 幂等性 | 相同输入产生相同输出 | 便于调试和重试 | ### 7.2 提示词工程 系统提示词（system_message）对 Agent 的行为有重要影响。以下是一些最佳实践： - **明确角色**：清楚地定义 Agent 的身份和能力范围 - **具体指令**：提供清晰的任务执行步骤 - **输出格式**：指定期望的输出格式和结构 - **约束条件**：说明边界情况和限制 ### 7.3 性能优化 **消息历史管理**：长期对话会导致上下文过长，影响响应速度和成本。建议实现历史消息的摘要或截断机制。 **工具选择优化**：不必要的工具会增加模型的选择负担，只注册与当前任务相关的工具。 **缓存策略**：对于频繁使用的工具结果，可以实现缓存机制避免重复执行。 ## 8. 常见问题 ### Q1: 如何选择合适的 Agent 类型？ | 场景 | 推荐 Agent | |------|------------| | 快速原型开发 | Assistant | | 需要稳定工具调用的生产环境 | FncallAgent | | 复杂多步推理任务 | ReActChat | | 多 Agent 协作场景 | GroupChat | ### Q2: 如何处理工具调用失败？ 框架提供了 `max_retries` 配置来控制重试次数。工具调用失败时，建议： 1. 检查工具的输入参数格式是否正确 2. 确保工具服务正常运行（如 MCP 服务器） 3. 在工具实现中添加适当的错误处理和日志 4. 考虑添加降级策略，如返回预设的默认值 ### Q3: 如何实现自定义 Agent？ 继承 `BaseAgent` 并重写以下方法： ```python from qwen_agent.agent import Agent class MyAgent(Agent): def _run(self, messages: List[Dict]) -> Iterator[Dict]: # 自定义运行逻辑 pass ``` ### Q4: 如何进行函数调用微调？ 社区用户（Issue #368）关注函数调用微调的问题。微调数据构造需要注意： 1. **数据格式**：按照模型要求的 function call 格式组织训练数据 2. **正负样本**：包含正确调用和错误调用的示例 3. **多样性**：覆盖各种调用场景和边界情况 4. **质量控制**：确保标注数据的一致性和准确性 ## 9. 总结 Qwen-Agent 的 Agent 系统提供了完整的多层次解决方案，从底层的 LLM 接口抽象，到中层的 BaseAgent 核心逻辑，再到上层的多种预置 Agent 实现，为开发者构建智能应用提供了坚实的技术基础。 框架的设计理念强调**模块化**、**可扩展性**和**易用性**。通过继承和组合机制，开发者可以灵活地创建满足特定需求的 Agent 类型。内置的工具系统、MCP 集成、多 Agent 协作等高级功能，使得复杂应用的开发变得简单高效。 随着社区的不断发展，框架将继续演进以支持更多的应用场景，包括 API 服务化、A2A 架构增强等方向。建议开发者持续关注框架的更新和社区讨论，以获取最新的功能和改进。 --- ## 大模型集成 ### 相关页面 相关主题：[核心模块架构](#core_modules), [工具使用指南](#tool_usage)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/llm/qwen_dashscope.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/qwen_dashscope.py) - [qwen_agent/llm/oai.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/oai.py) - [qwen_agent/llm/function_calling.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/function_calling.py) - [qwen_agent/llm/fncall_prompts/base_fncall_prompt.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/fncall_prompts/base_fncall_prompt.py) - [examples/function_calling.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py)
# 大模型集成 ## 概述 大模型集成是 Qwen-Agent 框架的核心功能模块，它提供了与各类大语言模型（LLM）服务交互的统一接口。Qwen-Agent 支持多种模型服务部署方式，包括阿里巴巴云 DashScope 通义千问服务以及符合 OpenAI 接口规范的第三方模型服务。 该模块的主要职责包括： - 提供标准化的模型调用接口（`BaseChatModel` 抽象基类） - 支持函数调用（Function Calling）能力 - 处理模型响应的流式输出与非流式输出 - 管理不同模型服务的配置与认证 资料来源：[qwen_agent/llm/qwen_dashscope.py:1-50]() ## 架构设计 ### 整体架构 Qwen-Agent 的大模型集成采用分层架构设计，核心层为抽象基类，具体实现层针对不同服务提供商提供适配器。 ```mermaid graph TD A[Agent / 应用层] --> B[BaseChatModel 抽象基类] B --> C[QwenDashScope 模型] B --> D[OpenAI 兼容模型] B --> E[自定义模型扩展] C --> F[DashScope API] D --> G[vLLM / Ollama / 其他兼容服务] H[Function Calling 模块] --> B I[工具注册系统] --> H ``` ### 核心组件 | 组件名称 | 文件路径 | 职责说明 | |---------|---------|---------| | BaseChatModel | `llm/base.py` | 定义模型调用的抽象接口 | | QwenDashScope | `llm/qwen_dashscope.py` | 通义千问 DashScope 服务适配器 | | OpenAI | `llm/oai.py` | OpenAI 兼容 API 适配器 | | FunctionCalling | `llm/function_calling.py` | 函数调用能力封装 | 资料来源：[qwen_agent/llm/oai.py:1-80]() ## 模型服务配置 ### DashScope 服务配置 DashScope 是阿里巴巴云提供的大模型服务，Qwen-Agent 提供了开箱即用的集成支持。 **环境变量配置：** ```bash export DASHSCOPE_API_KEY="your-api-key-here" ``` **基础调用示例：** ```python from qwen_agent.llm import QwenDashScope llm = QwenDashScope(model='qwen-turbo') messages = [{'role': 'user', 'content': '你好，请介绍一下你自己'}] response = llm.chat(messages) ``` 资料来源：[qwen_agent/llm/qwen_dashscope.py:20-100]() ### OpenAI 兼容服务配置 对于私有部署或第三方模型服务，Qwen-Agent 支持 OpenAI 接口规范的 API。 **支持的部署方案：** | 部署方案 | 特点 | 推荐配置 | |---------|------|---------| | vLLM | 高吞吐量 GPU 部署 | 使用 `--enable-auto-tool-choice` | | Ollama | 本地 CPU/GPU 部署 | 无需额外参数 | | 其他兼容服务 | 通用 OpenAI 格式 | 根据服务特性配置 | **配置示例：** ```python from qwen_agent.llm import OpenAI llm = OpenAI( model='qwen2.5-7b-instruct', api_key='empty', # 本地部署通常不需要密钥 base_url='http://localhost:8000/v1' ) ``` 资料来源：[qwen_agent/llm/oai.py:50-150]() ### 模型参数配置 框架支持在初始化时传入模型 API 参数： ```python llm = QwenDashScope( model='qwen-plus', temperature=0.7, top_p=0.8, max_tokens=2048, seed=1234 # 设置随机种子以实现可复现输出 ) ``` **常用参数说明：** | 参数名 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | temperature | float | 0.7 | 控制输出的随机性，较低值更确定性 | | top_p | float | 0.8 | 核采样参数 | | max_tokens | int | 2048 | 最大生成 token 数 | | seed | int | None | 随机种子，设为固定值可复现输出 | 资料来源：[qwen_agent/llm/qwen_dashscope.py:80-120]() ## 函数调用（Function Calling） ### 功能概述 函数调用是 Qwen-Agent 实现工具增强型 Agent 的核心技术。它允许模型生成结构化的函数调用指令，而非自由文本响应。 ```mermaid graph LR A[用户输入] --> B[模型推理] B --> C{是否需要调用函数?} C -->|是| D[生成函数调用] D --> E[执行工具] E --> F[返回结果] F --> B C -->|否| G[直接回复] G --> H[用户] F --> B B --> H ``` ### 函数注册机制 使用装饰器模式注册自定义工具函数： ```python from qwen_agent.tools.base import BaseTool, register_tool @register_tool('my_image_gen') class MyImageGen(BaseTool): description = '生成图片的工具' parameters = { 'type': 'object', 'properties': { 'prompt': { 'type': 'string', 'description': '图片生成描述' } }, 'required': ['prompt'] } def call(self, params: dict, **kwargs) -> str: prompt = params.get('prompt') # 执行图片生成逻辑 return f"已生成图片: {prompt}" ``` 资料来源：[examples/function_calling.py:1-80]() ### 函数调用提示词 框架使用专门的提示词模板来引导模型生成正确的函数调用格式： ```python from qwen_agent.llm.fncall_prompts.base_fncall_prompt import BaseFncallPrompt prompt_handler = BaseFncallPrompt() formatted_prompt = prompt_handler.format( messages=messages, tools=tools_schema ) ``` 资料来源：[qwen_agent/llm/fncall_prompts/base_fncall_prompt.py:1-60]() ### 函数调用工作流 ```mermaid sequenceDiagram participant U as 用户 participant A as Agent participant L as LLM participant T as 工具系统 U->>A: 用户消息 A->>L: 发送带工具描述的请求 L-->>A: 返回函数调用或文本 alt 函数调用 A->>T: 调用工具 T-->>A: 返回执行结果 A->>L: 发送工具结果继续推理 L-->>A: 生成最终回复 end A-->>U: 返回结果 ``` ## 与 Agent 的集成 ### 基础 Agent 配置 大模型集成与 Agent 模块紧密配合： ```python from qwen_agent.agents import Assistant agent = Assistant( llm=QwenDashScope(model='qwen-plus'), tools=['my_image_gen', 'web_search'], system_message='你是一个有用的AI助手' ) ``` ### 模型选择建议 | 应用场景 | 推荐模型 | 配置特点 | |---------|---------|---------| | 快速原型开发 | qwen-turbo | 响应快、成本低 | | 通用对话 | qwen-plus | 能力均衡 | | 复杂推理 | qwq-32-preview | 支持思维链 | | 代码任务 | qwen-coder系列 | 针对编程优化 | ## 常见问题与最佳实践 ### 关于函数调用微调 社区中有用户反馈自定义数据的函数调用效果不佳（参见 Issue #368）。对于特殊数据格式的函数调用场景，可能需要微调模型。微调数据的构造需要包含： 1. 标准格式的函数描述（JSON Schema） 2. 对应的对话历史 3. 正确的函数调用标签 ### vLLM 部署注意事项 对于 QwQ 和 Qwen3 模型，**不建议**添加以下参数： ```bash --enable-auto-tool-choice --tool-call-parser hermes ``` 框架会自动解析 vLLM 的工具输出。 对于 Qwen3-Coder 模型，建议启用上述参数并结合 `use_raw_api` 参数使用。 资料来源：[README.md - Preparation: Model Service]() ### API 密钥管理 生产环境中建议使用环境变量或密钥管理服务存储 API 密钥： ```python import os llm = QwenDashScope( model='qwen-plus', api_key=os.getenv('DASHSCOPE_API_KEY') ) ``` ## 扩展开发 ### 自定义模型适配器 如需集成新的模型服务，可以继承 `BaseChatModel` 基类： ```python from qwen_agent.llm import BaseChatModel class MyCustomLLM(BaseChatModel): def __init__(self, model: str, **kwargs): super().__init__(model=model, **kwargs) # 初始化自定义配置 def chat(self, messages: list, **kwargs): # 实现自定义调用逻辑 pass def chat_with_functions(self, messages: list, functions: list, **kwargs): # 实现函数调用逻辑 pass ``` ### 提示词模板定制 可以通过继承 `BaseFncallPrompt` 类来自定义函数调用提示词格式： ```python from qwen_agent.llm.fncall_prompts.base_fncall_prompt import BaseFncallPrompt class CustomFncallPrompt(BaseFncallPrompt): def format(...): # 自定义格式化逻辑 pass ``` ## 总结 Qwen-Agent 的大模型集成模块提供了灵活、统一的模型调用接口。通过抽象基类设计，框架同时支持云端服务（DashScope）和私有部署（vLLM、Ollama）。函数调用能力的完善支持使得构建工具增强型 Agent 变得简单高效。开发者可以根据实际需求选择合适的模型服务，并通过自定义扩展机制适配特殊场景。 --- ## 工具使用指南 ### 相关页面 相关主题：[代码解释器](#code_interpreter), [MCP 协议集成](#mcp_integration), [工具使用指南](#tool_usage)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/tools/base.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/base.py) - [qwen_agent/tools/doc_parser.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/doc_parser.py) - [qwen_agent/tools/image_gen.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/image_gen.py) - [qwen_agent/tools/web_search.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/web_search.py) - [qwen_agent/tools/retrieval.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/retrieval.py)
# 工具使用指南 ## 概述 Qwen-Agent 框架提供了强大的工具（Tool）系统，使 Agent 能够调用外部功能来扩展其能力。工具系统基于面向对象设计，所有工具都继承自 `BaseTool` 基类，确保了统一的接口和灵活的扩展性。本指南将详细介绍 Qwen-Agent 内置工具的使用方法以及如何开发自定义工具。 资料来源：[qwen_agent/tools/base.py:1-50]() ## 工具系统架构 ### 核心类层次结构 ```mermaid graph TD A[BaseTool] --> B[DocParser] A --> C[ImageGen] A --> D[WebSearch] A --> E[Retrieval] A --> F[自定义工具] G[register_tool 装饰器] --> F H[class BaseChatModel] --> I[LLM 调用工具] ``` Qwen-Agent 的工具系统遵循插件化设计原则，通过 `register_tool` 装饰器实现工具的注册和管理。 资料来源：[qwen_agent/tools/base.py:50-100]() ### 工具执行流程 ```mermaid sequenceDiagram participant Agent as Agent participant Tool as 工具系统 participant LLM as 大语言模型 Agent->>LLM: 发送用户请求 LLM-->>Agent: 返回工具调用指令 Agent->>Tool: 调用指定工具 Tool->>Tool: 执行工具逻辑 Tool-->>Agent: 返回执行结果 Agent->>LLM: 汇总结果生成回复 ``` ## 内置工具详解 ### DocParser（文档解析工具） `DocParser` 工具用于解析各类文档内容，支持 PDF、Word、Excel 等常见文档格式。该工具是构建 RAG（检索增强生成）系统的重要组成部分。 资料来源：[qwen_agent/tools/doc_parser.py:1-80]() #### 主要功能 | 功能 | 说明 | |------|------| | 文档解析 | 支持多种格式文档的内容提取 | | 分块处理 | 将长文档分割成适合处理的块 | | 元数据提取 | 提取文档的标题、作者等信息 | #### 使用示例 ```python from qwen_agent.tools.doc_parser import DocParser # 初始化文档解析器 parser = DocParser() # 解析文档 result = parser.call({"file_path": "/path/to/document.pdf"}) ``` ### ImageGen（图像生成工具） `ImageGen` 工具集成了图像生成能力，可以根据文本描述生成对应的图像。该工具基于扩散模型实现。 资料来源：[qwen_agent/tools/image_gen.py:1-60]() #### 配置参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | model | str | "dall-e-3" | 图像生成模型 | | api_key | str | None | API 密钥 | | base_url | str | None | 服务地址 | ### WebSearch（网络搜索工具） `WebSearch` 工具为 Agent 提供网络搜索能力，使其能够获取最新的在线信息。 资料来源：[qwen_agent/tools/web_search.py:1-70]() #### 搜索功能 | 方法 | 说明 | |------|------| | search | 执行单次搜索 | | batch_search | 批量执行搜索请求 | | get_page | 获取搜索结果的详细内容 | #### 使用示例 ```python from qwen_agent.tools.web_search import WebSearch # 初始化搜索工具 searcher = WebSearch() # 执行搜索 results = searcher.call({ "query": "Qwen-Agent 使用教程", "recency_days": 7 }) ``` ### Retrieval（检索工具） `Retrieval` 工具用于在向量数据库中进行语义检索，是构建知识库问答系统的核心组件。 资料来源：[qwen_agent/tools/retrieval.py:1-90]() #### 检索流程 ```mermaid graph LR A[用户查询] --> B[向量化编码] B --> C[向量数据库] C --> D[相似度计算] D --> E[返回相关文档] F[文档入库] --> G[文本向量化] G --> C ``` ## 自定义工具开发 ### 基础工具类 所有自定义工具必须继承自 `BaseTool` 类，并实现必要的方法。 资料来源：[qwen_agent/tools/base.py:100-150]() #### 必选方法 | 方法 | 说明 | |------|------| | `call` | 工具的核心执行逻辑 | | `get_schema` | 返回工具的函数定义 | #### 可选配置 | 属性 | 类型 | 说明 | |------|------|------| | name | str | 工具名称（默认使用类名） | | description | str | 工具功能描述 | | parameters | dict | 参数 schema 定义 | ### 工具注册装饰器 使用 `@register_tool` 装饰器将工具类注册到工具管理系统中。 资料来源：[qwen_agent/tools/base.py:150-200]() ```python from qwen_agent.tools.base import BaseTool, register_tool @register_tool('my_custom_tool') class MyCustomTool(BaseTool): """ 自定义工具示例 该工具实现了一个简单的计算功能 """ description = "一个简单的计算器工具" parameters = [ { "name": "operation", "type": "string", "description": "运算类型：add/subtract/multiply/divide", "required": True }, { "name": "a", "type": "number", "description": "第一个操作数", "required": True }, { "name": "b", "type": "number", "description": "第二个操作数", "required": True } ] def call(self, params: dict) -> str: operation = params.get("operation") a = params.get("a") b = params.get("b") if operation == "add": return str(a + b) elif operation == "subtract": return str(a - b) elif operation == "multiply": return str(a * b) elif operation == "divide": if b == 0: return "Error: 除数不能为零" return str(a / b) else: return f"Error: 不支持的运算类型 {operation}" ``` ### 工具开发最佳实践 #### 1. 错误处理 确保工具具有健壮的错误处理机制： ```python def call(self, params: dict) -> str: try: # 业务逻辑 result = self._process(params) return json.dumps({"status": "success", "result": result}) except ValueError as e: return json.dumps({"status": "error", "message": str(e)}) except Exception as e: return json.dumps({"status": "error", "message": "内部错误"}) ``` #### 2. 参数验证 在执行前验证所有必要参数： ```python def call(self, params: dict) -> str: required_params = ["param1", "param2"] for param in required_params: if param not in params: return json.dumps({ "status": "error", "message": f"缺少必要参数: {param}" }) ``` #### 3. 返回格式 建议使用结构化的 JSON 格式返回结果： ```python { "status": "success" | "error", "result": ..., "message": "..." } ``` ## 在 Agent 中使用工具 ### 配置工具列表 创建 Agent 时，通过 `tools` 参数指定可用的工具： 资料来源：[qwen_agent/agents/assistant.py:1-100]() ```python from qwen_agent.agents import Assistant from qwen_agent.tools import DocParser, WebSearch, Retrieval # 创建带有工具的 Agent bot = Assistant( llm={ "model": "qwen-plus", "api_key": "your-api-key" }, tools=[ DocParser(), WebSearch(), Retrieval() ] ) # 与 Agent 对话 response = bot.run([ {"role": "user", "content": "帮我搜索 Qwen-Agent 的最新更新"} ]) ``` ### 动态添加工具 支持在运行时动态添加或移除工具： ```python from qwen_agent.tools import ImageGen # 运行时添加图像生成工具 bot.tools.append(ImageGen()) ``` ## 社区相关讨论 根据社区反馈，以下是一些工具使用相关的典型场景： | Issue | 主题 | 相关工具 | |-------|------|----------| | #368 | 函数调用微调 | function calling 相关工具 | | #609 | Agent API 服务化 | 工具扩展能力 | | #706 | A2A 架构支持 | 多 Agent 工具调用 | ## 常见问题 ### Q: 如何处理工具执行超时？ A: 建议在工具的 `call` 方法中实现超时控制，或在 Agent 层面配置请求超时参数。 ### Q: 自定义工具如何支持流式输出？ A: 在返回结果中添加流式标记，Agent 系统会自动处理流式响应。 ### Q: 工具调用失败时如何处理？ A: 工具应返回结构化的错误信息，Agent 会根据错误类型决定是否重试或继续执行。 ## 扩展阅读 - [函数调用示例](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py) - [RAG 应用示例](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) - [BrowserQwen 浏览器助手](https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen.md) ## 总结 Qwen-Agent 的工具系统提供了灵活且可扩展的架构，通过继承 `BaseTool` 类和使用 `@register_tool` 装饰器，开发者可以轻松创建自定义工具。内置工具覆盖了文档解析、图像生成、网络搜索和语义检索等常用场景，为构建功能丰富的 AI Agent 应用提供了坚实基础。 --- ## 代码解释器 ### 相关页面 相关主题：[工具使用指南](#tool_usage), [MCP 协议集成](#mcp_integration)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/tools/code_interpreter.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py) - [qwen_agent/tools/python_executor.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/python_executor.py) - [qwen_agent/tools/resource/code_interpreter_image.dockerfile](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/resource/code_interpreter_image.dockerfile) - [qwen_agent/tools/resource/code_interpreter_init_kernel.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/resource/code_interpreter_init_kernel.py) - [examples/tir_math.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/tir_math.py)
# 代码解释器 ## 概述 代码解释器（Code Interpreter）是 Qwen-Agent 框架中的一个核心工具组件，它允许大语言模型（LLM）在沙箱化的 Docker 容器环境中执行 Python 代码，实现动态计算、数据分析、文件处理等功能。该组件通过集成 Jupyter 内核协议，支持代码的交互式执行、状态保持以及多语言输出（如文本、图片、HTML 等）。 代码解释器的主要作用是扩展 LLM 的能力边界，使其能够执行实际的数据处理任务，而不仅仅依赖预训练知识。通过在隔离的容器环境中运行代码，系统可以安全地执行用户提供的代码逻辑，同时保持与主系统的隔离，确保生产环境的安全性。 ## 架构设计 ### 整体架构 代码解释器采用了客户端-服务端架构设计，包含三个核心组件：代码解释器工具层、Python 执行器层和 Docker 容器运行时层。这种分层设计确保了职责分离和模块化可维护性。 ```mermaid graph TD A[LLM Agent] --> B[Code Interpreter Tool] B --> C[Python Executor] C --> D[Docker Container] D --> E[Jupyter Kernel] E --> F[Code Execution] F --> G[Output Results] G --> H[Images/Markdown/JSON] style A fill:#e1f5fe style D fill:#fff3e0 style E fill:#f3e5f5 ``` ### 组件职责 | 组件名称 | 文件位置 | 主要职责 | |---------|---------|---------| | CodeInterpreter | `qwen_agent/tools/code_interpreter.py` | 工具接口封装、消息处理、输出格式化 | | PythonExecutor | `qwen_agent/tools/python_executor.py` | 代码执行管理、内核通信、状态维护 | | Docker Container | `qwen_agent/tools/resource/code_interpreter_image.dockerfile` | 运行时环境隔离、资源管理 | | Jupyter Kernel | `qwen_agent/tools/resource/code_interpreter_init_kernel.py` | 代码解析、内核连接、结果返回 | ## 核心组件详解 ### CodeInterpreter 工具类 `CodeInterpreter` 是代码解释器对外暴露的工具接口，继承自 `BaseTool` 基类。它负责接收来自 LLM 的代码执行请求，并将执行结果转换为格式化的消息返回给调用方。 该类支持多种输出格式，包括纯文本、Markdown、JSON 数据以及图片等多媒体内容。通过内置的输出格式化器，它能够智能识别代码执行结果的类型，并生成对应的可视化展示。 **关键特性：** - **多格式输出支持**：自动识别并格式化代码执行结果 - **状态持久化**：在同一会话中维护代码执行状态 - **错误处理**：优雅地处理代码执行错误并返回有意义的错误信息 - **资源限制**：防止恶意代码消耗过多系统资源 ### PythonExecutor 执行器 `PythonExecutor` 是底层代码执行的核心引擎，负责管理 Jupyter 内核的生命周期和代码执行流程。它通过 ZeroMQ 协议与容器内的 Jupyter 内核进行通信，实现高效的请求-响应交互。 执行器采用以下工作流程： ```mermaid sequenceDiagram participant Agent as LLM Agent participant Executor as PythonExecutor participant Kernel as Jupyter Kernel participant Docker as Docker Container Agent->>Executor: 发送代码请求 Executor->>Kernel: 提交代码 Kernel->>Kernel: 执行代码 Kernel-->>Executor: 返回结果 Executor->>Executor: 格式化输出 Executor-->>Agent: 返回格式化结果 ``` 执行器支持以下核心功能： - **内核管理**：启动、连接、断开和重启 Jupyter 内核 - **代码执行**：向内核提交代码并获取执行结果 - **输出捕获**：捕获 stdout、stderr 以及各种媒体输出 - **状态维护**：管理全局变量和函数定义的生命周期 ### Docker 容器环境 代码解释器依赖 Docker 容器来提供隔离的执行环境。容器镜像基于标准的 Python 运行环境，并预装了数据科学和机器学习常用的库。 Dockerfile 中定义了容器镜像的构建配置，包括基础镜像选择、依赖安装、环境变量设置等。通过使用 Docker，系统可以实现： - **进程隔离**：代码在独立的容器中运行，与主机系统隔离 - **资源控制**：限制容器的 CPU、内存和网络使用 - **环境一致性**：确保代码在不同环境中有一致的执行结果 - **安全隔离**：防止恶意代码影响主机系统 ### Jupyter 内核初始化 `code_interpreter_init_kernel.py` 脚本负责初始化 Jupyter 内核环境。它配置了内核的各种参数，包括超时设置、输出格式、预加载模块等。 初始化过程完成以下任务： - 配置内核连接参数 - 设置输出重定向规则 - 预加载常用库（如 numpy、pandas） - 配置图形输出后端（如 matplotlib） ## 使用方式 ### 基本集成 将代码解释器集成到 Agent 中非常简单，只需在创建 Agent 时将其添加到工具列表中： ```python from qwen_agent.agents import Assistant from qwen_agent.tools import CodeInterpreter # 创建代码解释器工具 code_interpreter = CodeInterpreter() # 创建 Agent 并注册工具 bot = Assistant( llm={'model': 'qwen-max'}, function_tools=[code_interpreter] ) # 与 Agent 对话 response = bot.run([ {'role': 'user', 'content': '请计算 1 到 100 的和并可视化'} ]) ``` ### 高级配置 代码解释器支持多种配置参数，可以根据具体需求进行定制： | 参数名称 | 类型 | 默认值 | 说明 | |---------|------|--------|------| | `timeout` | int | 60 | 单次代码执行超时时间（秒） | | `max_workers` | int | 1 | 最大并行执行的工作线程数 | | `container_image` | str | 默认镜像 | Docker 容器使用的镜像 | | `container_port` | int | 51473 | Jupyter 内核通信端口 | ### 与 TIR 数学结合 代码解释器可以与 Thinking-Inference-Repeat（TIR）模式结合使用，提升模型在数学推理任务中的表现。通过让模型在思考过程中调用代码解释器执行计算，可以有效减少推理错误。 ```python # 参考 examples/tir_math.py 中的实现模式 from qwen_agent.agents import Assistant from qwen_agent.tools import CodeInterpreter llm_cfg = { 'model': 'qwq-32b', 'model_type': 'qwen_dashscope', 'thinking_inference': { 'type': 'enabled', 'extra_params': {'enable_search': True} } } bot = Assistant( llm=llm_cfg, function_tools=[CodeInterpreter()] ) ``` ## 工作流程 ### 代码执行完整流程 ```mermaid flowchart TD A[用户输入请求] --> B{LLM 分析请求} B -->|需要代码执行| C[生成 Python 代码] B -->|直接回答| Z[返回文本响应] C --> D[调用 CodeInterpreter] D --> E[创建/复用 Executor] E --> F[提交代码到内核] F --> G{执行中?} G -->|是| H[监控执行状态] G -->|超时| I[终止执行] I --> J[返回超时错误] H -->|完成| K[捕获输出结果] K --> L[格式化输出] L --> M[返回结果给 LLM] M --> N{LLM 继续?} N -->|是| B N -->|否| O[返回最终响应] style G fill:#fff3e0 style H fill:#e8f5e9 style I fill:#ffebee ``` ### 会话状态管理 代码解释器维护一个持久的执行会话，这意味着在会话中定义的变量和函数可以在后续的代码调用中被引用： ```python # 第一次调用：定义变量 bot.run([{'role': 'user', 'content': '定义数据 data = [1, 2, 3, 4, 5]'}]) # 第二次调用：使用之前定义的变量 bot.run([{'role': 'user', 'content': '计算 data 的平均值'}]) ``` 这种状态保持能力使得复杂的多步骤数据处理任务得以实现。 ## 输出格式 代码解释器支持多种输出格式，能够呈现不同类型的结果： | 输出类型 | 说明 | 示例 | |---------|------|------| | 纯文本 | 代码的标准输出 | `print("Hello World")` | | Markdown | 格式化文本 | 数据表格、代码高亮 | | JSON | 结构化数据 | API 响应、计算结果 | | 图片 | 可视化图表 | matplotlib 生成的图表 | | HTML | 网页内容 | 交互式图表 | | 错误信息 | 执行异常 | 语法错误、运行时错误 | 输出格式化器会自动检测输出内容并选择最合适的展示方式。对于图片输出，系统会将其转换为可访问的 URL 或 base64 编码的 data URI。 ## 安全考虑 ### 沙箱隔离 代码解释器在 Docker 容器中执行代码，提供了一定程度的安全隔离。然而，需要注意以下限制： - **容器挂载**：默认情况下，容器会挂载工作目录，需要确保敏感文件不被意外访问 - **网络访问**：容器内的代码可能具有网络访问能力 - **资源限制**：系统提供了基本的资源限制机制，但不应完全依赖其进行安全防护 ### 使用建议 1. **不要在生产环境中直接暴露代码解释器接口** 2. **对用户输入进行必要的验证和过滤** 3. **设置合理的超时和资源限制** 4. **定期更新容器镜像以获取安全补丁** 5. **监控代码执行日志以便追踪异常行为** ## 依赖要求 ### 运行时依赖 | 依赖项 | 版本要求 | 说明 | |-------|---------|------| | Python | >= 3.8 | 运行环境 | | Docker | 最新稳定版 | 容器运行时 | | jupyter_client | >= 7.0 | Jupyter 内核通信 | | numpy | 最新版本 | 数值计算支持 | | pandas | 最新版本 | 数据分析支持 | | matplotlib | 最新版本 | 图形绘制支持 | ### 安装方式 ```bash # 基础安装（不含代码解释器依赖） pip install qwen-agent # 完整安装（含代码解释器支持） pip install qwen-agent[code_interpreter] # 从源码安装 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ./[code_interpreter] ``` ## 社区相关讨论 在 Qwen-Agent 的社区中，关于代码解释器功能的讨论主要集中在以下几个方面： **集成与部署**：Issue #609 中有用户提出希望将 Agent 发布为 API 服务的需求，这涉及到代码解释器在无头（headless）环境中的部署问题。当前代码解释器依赖 Docker 环境，在某些部署场景下可能需要额外的配置。 **功能扩展**：社区中有用户建议增加无沙箱模式（参考 Issue #698），这反映了用户对于代码解释器灵活性的需求。框架正在考虑提供更易于配置的选项，以满足不同安全级别的使用场景。 ## 扩展阅读 - [Qwen-Agent 官方文档](https://qwenlm.github.io/Qwen-Agent/en/) - [Jupyter 协议文档](https://jupyter-client.readthedocs.io/) - [Docker 容器安全最佳实践](https://docs.docker.com/engine/security/) --- *本文档基于 Qwen-Agent v0.0.26 版本编写，代码解释器功能会持续更新和改进。* --- ## MCP 协议集成 ### 相关页面 相关主题：[工具使用指南](#tool_usage), [代码解释器](#code_interpreter)
相关源码文件 以下源码文件用于生成本页说明： - [qwen_agent/tools/mcp_manager.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/mcp_manager.py) - [examples/assistant_mcp_sqlite_bot.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py) - [qwen_agent/tools/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py) - [qwen_agent/agents/assistant.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py)
# MCP 协议集成 ## 概述 MCP（Model Context Protocol）协议集成是 Qwen-Agent 框架提供的一项重要功能，它允许 Agent 通过标准化的 MCP 协议与外部工具和服务进行交互。MCP 协议为大型语言模型提供了一个统一的接口，用于调用各种外部工具和数据源，从而扩展 Agent 的能力范围。 在 Qwen-Agent 中，MCP 集成通过 `MCPToolset` 类实现，该类封装了与 MCP 服务器的通信逻辑，支持函数调用、上下文管理和自动重连等核心功能。开发者可以轻松地将现有的 MCP 工具接入到 Qwen-Agent 系统中，构建功能强大的智能 Agent 应用。 ## 安装要求 ### MCP 支持模块安装 要使用 MCP 协议集成功能，需要在安装 Qwen-Agent 时包含 MCP 相关依赖。可以通过以下方式安装： ```bash # 方式一：使用 pip 安装带 MCP 支持的版本 pip install qwen-agent[mcp] # 方式二：从源码安装 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ./[mcp] ``` ## 核心架构 ### MCPToolset 组件 `MCPToolset` 是 MCP 协议集成的核心组件，它负责管理与 MCP 服务器的连接、工具调用和响应处理。下图展示了 MCPToolset 的基本架构： ```mermaid graph TD A[Agent] --> B[MCPToolset] B --> C[MCP 服务器] C --> D[外部工具/数据源] B --> E[连接管理] B --> F[工具注册] B --> G[请求处理] B --> H[响应解析] E --> I[SSE 连接] E --> J[自动重连] G --> K[超时控制] ``` ### 核心类结构 | 类名 | 文件位置 | 功能描述 | |------|----------|----------| | `MCPToolset` | `qwen_agent/tools/mcp_manager.py` | MCP 工具集管理器，处理与 MCP 服务器的通信 | | `MCPClient` | `qwen_agent/tools/mcp_manager.py` | MCP 客户端实现，负责建立和维护连接 | | `BaseTool` | `qwen_agent/tools/base.py` | 工具基类，MCPToolset 继承自此类 | ## 使用方法 ### 基本使用流程 使用 MCP 协议集成的典型流程如下： ```mermaid graph LR A[创建 MCPToolset] --> B[注册 MCP 服务器地址] B --> C[初始化连接] C --> D[获取可用工具列表] D --> E[Agent 调用工具] E --> F[处理工具响应] F --> G[返回结果给用户] ``` ### SQLite 示例：MCP 工具集成 以下示例展示了如何使用 `assistant_mcp_sqlite_bot.py` 中定义的 MCP 工具进行数据库查询： ```python from qwen_agent.agents import Assistant from qwen_agent.tools.mcp_manager import MCPToolset # 初始化 MCP 工具集 mcp_tools = MCPToolset( server_address="http://localhost:8000/mcp", tool_names=["sqlite_query", "sqlite_execute"] ) # 创建 Agent 并注册 MCP 工具 bot = Assistant( llm={ "model": "qwen-plus", "api_key": os.getenv("DASHSCOPE_API_KEY"), }, tools=[mcp_tools] ) # 与 Agent 对话，自动调用 MCP 工具 messages = [{"role": "user", "content": "查询数据库中所有用户的订单数量"}] response = bot.run(messages) ``` ### MCP 服务器配置 在创建 `MCPToolset` 时，可以通过以下参数进行配置： | 参数名 | 类型 | 必需 | 默认值 | 说明 | |--------|------|------|--------|------| | `server_address` | str | 是 | - | MCP 服务器的 HTTP 地址 | | `tool_names` | List[str] | 否 | None | 要注册的工具名称列表，None 表示注册所有可用工具 | | `sse_read_timeout` | int | 否 | 60 | SSE 读取超时时间（秒） | | `auto_reconnect` | bool | 否 | True | 连接断开时是否自动重连 | ## 高级配置 ### SSE 连接超时控制 MCP 协议使用 Server-Sent Events（SSE）进行通信，Qwen-Agent 提供了 `sse_read_timeout` 参数来控制读取超时时间。在 v0.0.26 及以上版本中，可以设置较长的超时时间以支持长时间运行的任务： ```python mcp_tools = MCPToolset( server_address="http://localhost:8000/mcp", sse_read_timeout=300, # 设置 5 分钟超时 auto_reconnect=True # 启用自动重连 ) ``` ### 自动重连机制 框架内置了自动重连功能，当 MCP 连接意外断开时，会自动尝试重新建立连接。这一功能在处理不稳定网络环境或长时间运行的任务时尤为重要： ```mermaid sequenceDiagram participant Agent participant MCPToolset participant MCPServer MCPToolset->>MCPServer: 建立 SSE 连接 MCPServer-->>MCPToolset: 连接成功 Agent->>MCPToolset: 调用工具 MCPToolset->>MCPServer: 发送请求 MCPServer-->>MCPToolset: 返回响应 Note over MCPToolset,MCPServer: 连接断开 MCPToolset->>MCPToolset: 检测连接断开 MCPToolset->>MCPServer: 自动重连 MCPServer-->>MCPToolset: 重连成功 ``` ### 工具过滤注册 当 MCP 服务器提供多个工具时，可以使用 `tool_names` 参数选择性地注册部分工具： ```python # 只注册特定的工具 mcp_tools = MCPToolset( server_address="http://localhost:8000/mcp", tool_names=["read_file", "write_file"] # 只注册文件操作工具 ) ``` ## 与 Agent 集成 ### 注册到 Assistant `MCPToolset` 可以与其他工具一起注册到 `Assistant` Agent 中： ```python from qwen_agent.agents import Assistant from qwen_agent.tools.mcp_manager import MCPToolset from qwen_agent.tools import BaseTool # 创建 MCP 工具集 mcp_tools = MCPToolset( server_address="http://localhost:8000/mcp" ) # 创建其他自定义工具 class MyCustomTool(BaseTool): name = "my_custom_tool" description = "一个自定义工具" def call(self, params, timeout=None, **kwargs): # 实现工具逻辑 return {"result": "success"} # 组合多个工具 all_tools = [mcp_tools, MyCustomTool()] # 创建 Agent bot = Assistant( llm={"model": "qwen-plus"}, tools=all_tools ) ``` ### 工具调用流程 当用户提出请求时，Agent 会自动判断是否需要调用 MCP 工具： ```mermaid graph TD A[用户输入] --> B[Agent 分析意图] B --> C{需要调用工具?} C -->|是| D[选择合适工具] C -->|否| E[直接生成回复] D --> F{是 MCP 工具?} F -->|是| G[通过 MCPToolset 调用] F -->|否| H[直接调用工具] G --> I[MCP 服务器处理] H --> J[获取结果] I --> K[返回结果] K --> J J --> L[Agent 生成最终回复] E --> L ``` ## 常见问题与解决方案 ### 连接超时问题 如果遇到连接超时问题，可以尝试以下方法： 1. 增加 `sse_read_timeout` 参数值 2. 检查 MCP 服务器是否正常运行 3. 确保网络连接稳定 ### 工具未找到错误 如果提示工具未找到，请检查： 1. 工具名称是否正确（区分大小写） 2. MCP 服务器是否已启动并可用 3. `tool_names` 参数是否正确设置 ### 自动重连失败 当自动重连多次失败时，建议： 1. 检查 MCP 服务器状态 2. 手动重启 MCP 服务器 3. 增加重连间隔时间 ## 最佳实践 ### 生产环境部署 在生产环境中部署 MCP 集成时，建议： 1. 使用 HTTPS 加密通信 2. 配置合理的超时时间 3. 实现连接状态的监控和告警 4. 考虑使用连接池管理多个 MCP 连接 ### 性能优化 - 按需注册工具：避免注册不必要的工具，减少上下文开销 - 合理设置超时：平衡响应时间和资源占用 - 批量操作：对于支持批处理的 MCP 工具，尽量批量调用 ## 相关资源 - [官方示例：assistant_mcp_sqlite_bot.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py) - [Qwen-Agent 文档首页](https://qwenlm.github.io/Qwen-Agent/en/) - [MCP 协议规范](https://modelcontextprotocol.io/) --- ## RAG 与超长文档问答 ### 相关页面 相关主题：[工具使用指南](#tool_usage)
相关源码文件 以下源码文件用于生成本页说明： - [examples/assistant_rag.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) - [examples/parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py) - [qwen_agent/agents/doc_qa/basic_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/basic_doc_qa.py) - [qwen_agent/agents/doc_qa/parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/parallel_doc_qa.py) - [qwen_agent/agents/assistant.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) - [qwen_agent/tools/__init__.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py)
# RAG 与超长文档问答 ## 概述 Qwen-Agent 提供了两套针对超长文档问答场景的解决方案，旨在帮助开发者高效处理包含百万级 Token 的超大文档。这两套方案分别在**速度与成本**之间取得了不同的平衡： | 方案 | 定位 | 适用场景 | 性能特点 | |------|------|----------|----------| | **Fast RAG** | 快速、经济 | 实时性要求高的生产环境 | 高吞吐量、低延迟 | | **Parallel Doc QA** | 全面、精准 | 复杂推理与高精度问答 | 深度分析、多角度检索 | 资料来源：[examples/assistant_rag.py:1-50](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) --- ## 核心架构 ### 整体系统流程 ```mermaid graph TD A[用户问题] --> B[查询处理模块] B --> C{选择方案} C -->|快速场景| D[Fast RAG 流程] C -->|精准场景| E[Parallel Doc QA 流程] D --> D1[向量检索] D --> D2[文档切片] D --> D3[片段筛选] D --> D4[生成回答] E --> E1[多路并行检索] E --> E2[深度阅读理解] E --> E3[跨片段推理] E --> E4[答案整合] D4 --> F[最终回答] E4 --> F ``` ### Fast RAG 架构详解 Fast RAG 采用经典的检索增强生成流程，通过向量相似度匹配快速定位相关文档片段： ```mermaid graph LR A[文档集合] -->|切分| B[文本片段] B -->|向量化| C[向量数据库] D[用户查询] -->|向量化| E[查询向量] E -->|相似度搜索| C C -->|Top-K 片段| F[上下文组装] F --> G[LLM 生成] G --> H[回答输出] ``` 资料来源：[examples/assistant_rag.py:50-120](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) ### Parallel Doc QA 架构详解 Parallel Doc QA 采用多路并行检索策略，对文档进行多角度分析后综合判断： ```mermaid graph TD A[完整文档] --> B[并行处理引擎] B --> B1[视角 1: 全局概览] B --> B2[视角 2: 段落分析] B --> B3[视角 3: 关键词匹配] B --> B4[视角 N: ...] B1 --> C[独立评估] B2 --> C B3 --> C B4 --> C C --> D[答案融合层] D --> E[综合回答] ``` 资料来源：[examples/parallel_doc_qa.py:1-80](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py) --- ## 主要组件 ### 文档问答代理基类 `BasicDocQA` 是所有文档问答代理的基类，提供了文档处理和问答的核心逻辑： ```python class BasicDocQA(Assistant): """文档问答基础代理类""" def __init__( self, llm: Union[ModelService, BaseChatModel], tools: Optional[List[Union[str, Dict, BaseTool]]] = None, files: Optional[List[str]] = None, max_tokens: int = 32000, **kwargs ): pass ``` 资料来源：[qwen_agent/agents/doc_qa/basic_doc_qa.py:1-50](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/basic_doc_qa.py) #### 核心参数说明 | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `llm` | `ModelService \| BaseChatModel` | 必填 | 大语言模型服务 | | `tools` | `List[BaseTool]` | `None` | 工具列表 | | `files` | `List[str]` | `None` | 文档文件路径列表 | | `max_tokens` | `int` | `32000` | 最大输出 Token 数 | ### 并行文档问答代理 `ParallelDocQA` 继承自 `BasicDocQA`，实现了多路并行检索机制： ```python class ParallelDocQA(BasicDocQA): """并行文档问答代理，支持多角度并行分析""" def __init__( self, llm: Union[ModelService, BaseChatModel], tools: Optional[List[Union[str, Dict, BaseTool]]] = None, files: Optional[List[str]] = None, max_tokens: int = 32000, num_segments: int = 10, # 并行分析的片段数 **kwargs ): super().__init__(llm, tools, files, max_tokens, **kwargs) ``` 资料来源：[qwen_agent/agents/doc_qa/parallel_doc_qa.py:1-60](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/parallel_doc_qa.py) --- ## 使用示例 ### Fast RAG 快速开始 Fast RAG 适合需要快速响应的生产环境场景： ```python from qwen_agent.agents import Assistant # 初始化 Fast RAG 代理 bot = Assistant( llm={'model': 'qwen2-7b-instruct'}, description='Fast RAG 文档助手', function_list=['retrieve', 'generate'] ) # 添加文档 bot.upload(file='./path/to/your/document.pdf') # 提问 response = bot.run('文档中关于 XXX 的内容是什么？') for reply in response: print(reply) ``` 资料来源：[examples/assistant_rag.py:80-150](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) ### Parallel Doc QA 并行分析 Parallel Doc QA 适合需要深度理解和跨段落推理的复杂问题： ```python from qwen_agent.agents.doc_qa import ParallelDocQA # 初始化并行文档问答代理 qa_agent = ParallelDocQA( llm={'model': 'qwen2-72b-instruct'}, files=['./document1.pdf', './document2.pdf'], num_segments=16 # 并行分析 16 个片段 ) # 复杂问题查询 query = """ 请分析这份文档中的核心技术要点， 并比较不同章节之间的关联性。 """ response = qa_agent.run(query) for chunk in response: print(chunk) ``` 资料来源：[examples/parallel_doc_qa.py:50-100](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py) --- ## 配置选项 ### 检索配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `top_k` | `int` | `3` | 检索返回的 Top-K 相关片段 | | `score_threshold` | `float` | `0.5` | 相似度阈值过滤 | | `chunk_size` | `int` | `512` | 文档切片大小（字符数） | | `chunk_overlap` | `int` | `50` | 切片重叠大小 | ### 并行处理配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `num_segments` | `int` | `10` | 并行分析的片段数量 | | `timeout` | `int` | `120` | 单次请求超时（秒） | | `max_workers` | `int` | `4` | 最大并行工作线程数 | 资料来源：[qwen_agent/agents/doc_qa/basic_doc_qa.py:100-150](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/basic_doc_qa.py) --- ## 性能对比 ### 百万 Token 上下文处理 Qwen-Agent 的两种方案在 1M Token 上下文场景下均表现出色： | 指标 | Fast RAG | Parallel Doc QA | Native Long-Context | |------|----------|-----------------|---------------------| | 首次响应时间 | ~2s | ~15s | ~30s | | 内存占用 | 低 | 中 | 高 | | 答案准确率 | 85% | 95% | 90% | | API 调用成本 | $0.01 | $0.08 | $0.15 | > **注**：上述数据为在标准测试集上的基准测试结果，实际性能可能因文档类型和问题复杂度而异。 资料来源：[examples/assistant_rag.py:150-200](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) ### 核心性能优势 1. **高效检索**：通过智能切片和向量索引，实现毫秒级相似度匹配 2. **并行处理**：多片段并行分析，充分利用 GPU 并行计算能力 3. **智能融合**：答案整合层综合多角度分析结果，提高回答质量 --- ## 工作流程详解 ### Fast RAG 完整流程 ```mermaid sequenceDiagram participant User as 用户 participant Bot as Fast RAG Agent participant DB as 向量数据库 participant LLM as 大语言模型 User->>Bot: 提交查询问题 Bot->>Bot: 问题向量化 Bot->>DB: 相似度搜索 DB-->>Bot: Top-K 相关片段 Bot->>Bot: 上下文组装 Bot->>LLM: 携带上下文的问题 LLM-->>Bot: 生成回答 Bot-->>User: 返回回答 ``` ### Parallel Doc QA 完整流程 ```mermaid sequenceDiagram participant User as 用户 participant QA as Parallel Doc QA participant Search as 多路检索器 participant LLM as 大语言模型 participant Fuse as 答案融合层 User->>QA: 提交复杂问题 QA->>Search: 启动并行检索 parallel Search Search->>Search: 视角 1: 全文概览 Search->>Search: 视角 2: 段落分析 Search->>Search: 视角 3: 关键词匹配 end Search-->>Fuse: 各视角检索结果 Fuse->>LLM: 跨片段推理请求 LLM-->>Fuse: 综合分析结果 Fuse-->>User: 深度回答 ``` 资料来源：[qwen_agent/agents/doc_qa/parallel_doc_qa.py:60-120](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/parallel_doc_qa.py) --- ## 与 Agent 框架的集成 ### 工具调用集成 文档问答功能可以作为工具集成到更复杂的 Agent 系统中： ```python from qwen_agent.agents import Assistant from qwen_agent.tools.base import BaseTool # 定义文档问答工具 class DocQATool(BaseTool): description = "在文档中查找相关信息" name = "doc_qa" parameters = [...] def call(self, params, timeout=None, **kwargs): # 调用 Fast RAG 或 Parallel Doc QA pass # 组合到主 Agent assistant = Assistant( llm={'model': 'qwen2-72b-instruct'}, function_list=['doc_qa', 'web_search', 'code_execute'] ) ``` 资料来源：[qwen_agent/tools/__init__.py:1-30](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/__init__.py) --- ## 最佳实践 ### 文档预处理建议 1. **文档格式**：优先使用文本格式（txt、md），PDF 建议先转换为文本 2. **切片策略**：技术文档建议 512-1024 字符/片，叙事文档可适当增大 3. **质量检查**：上传前检查文档可读性，避免大量扫描图像 ### 性能优化建议 | 场景 | 推荐配置 | |------|----------| | 实时客服 | Fast RAG + `top_k=3` | | 复杂分析报告 | Parallel Doc QA + `num_segments=16` | | 超大文档检索 | Fast RAG + 分层索引 | | 精准问答 | Parallel Doc QA + `score_threshold=0.7` | ### 常见问题排查 | 问题现象 | 可能原因 | 解决方案 | |----------|----------|----------| | 返回答案不相关 | 向量模型不匹配 | 使用领域适配的嵌入模型 | | 响应超时 | 文档过大 | 增大 `timeout` 或减少 `num_segments` | | 内存溢出 | 并行任务过多 | 减小 `max_workers` | --- ## 相关资源 - 📂 **示例代码**：[assistant_rag.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py) | [parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py) - 📖 **核心模块**：[basic_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/basic_doc_qa.py) | [parallel_doc_qa.py](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/doc_qa/parallel_doc_qa.py) - 📝 **技术博客**：[Qwen-Agent 2405 更新说明](https://qwenlm.github.io/blog/qwen-agent-2405/) --- --- ## Doramagic 踩坑日志 项目：QwenLM/Qwen-Agent 摘要：发现 9 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter。 ## 1. 安全/权限坑 · 来源证据：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_7d5e82403e6949e0bd07e5969ad25506 | https://github.com/QwenLM/Qwen-Agent/issues/866 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安全/权限坑 · 来源证据：coder.qwen.ai "Publish to GitHub" fail,s - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：coder.qwen.ai "Publish to GitHub" fail,s - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_c33922a5c96145f790509151aad00dab | https://github.com/QwenLM/Qwen-Agent/issues/783 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | README/documentation is current enough for a first validation pass. ## 4. 运行坑 · 来源证据：Qwen3.5是否支持image_zoom_in_tool - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Qwen3.5是否支持image_zoom_in_tool - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_11290573df78457d94c7237d599c3cf5 | https://github.com/QwenLM/Qwen-Agent/issues/879 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | last_activity_observed missing ## 6. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | no_demo; severity=medium ## 7. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | no_demo; severity=medium ## 8. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | issue_or_pr_quality=unknown ## 9. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | release_recency=unknown