Qwen-代理
项目介绍
版权所有 2023 Qwen团队，阿里巴巴集团。保留所有权利。
根据Apache许可证第2.0版（“许可证”）获得许可； 除非符合许可证，否则不得使用此文件。 您可以通过以下网址获取许可证副本：
http://www.apache.org/licenses/LICENSE-2.0
除非适用法律要求或书面同意，根据许可证分发的软件 是基于“现状”基础分发的， 不附带任何形式的保证或条件，无论是明示还是暗示。 有关特定权限和限制，请参阅许可证。
中文 ｜ English
<p align="center"> <img src="https://gips1.baidu.com/it/u=2870446620,3941798008&fm=3081&app=3081&f=PNG?w=5444&h=1555" width="400"/> <p> <br> <p align="center"> 💜 <a href="https://chat.qwen.ai/"><b>Qwen Chat</b></a>   |   🤗 <a href="https://huggingface.co/Qwen">Hugging Face</a>   |   🤖 <a href="https://modelscope.cn/organization/qwen">ModelScope</a>   |    📑 <a href="https://qwenlm.github.io/">Blog</a>    ｜   📖 <a href="https://qwen.readthedocs.io/">文档</a> <br> 💬 <a href="https://github.com/QwenLM/Qwen/blob/main/assets/wechat.png">WeChat (微信)</a>   |   🫨 <a href="https://discord.gg/CV4E9rpNSD">Discord</a>   </p>Qwen-Agent 是一个基于 Qwen 的指令跟随、工具使用、规划和记忆能力来开发大模型应用的框架。 它还提供了示例应用程序，如浏览器助手、代码解释器和自定义助手。 目前，Qwen-Agent 担任 Qwen Chat 的后端。
新闻
- 🔥🔥🔥 2025年9月23日：添加了 Qwen3-VL 工具调用演示，支持放大、图像搜索和网络搜索等工具。
- 2025年7月23日：添加了 Qwen3-Coder 工具调用演示；增加了对原生 API 工具调用接口的支持，例如使用 vLLM 内置的工具调用解析。
- 2025年5月1日：添加了 Qwen3 工具调用演示，并添加了 MCP 食谱。
- 2025年3月18日：支持
reasoning_content字段；调整了默认的 函数调用模板，适用于 Qwen2.5 系列通用模型和 QwQ-32B。如果您需要使用旧版本的模板，请参考 示例 传递参数。 - 2025年3月7日：添加了 QwQ-32B 工具调用演示。它支持并行、多步和多轮工具调用。
- 2024年12月3日：升级 GUI 到基于 Gradio 5。注意：GUI 需要 Python 3.10 或更高版本。
- 2024年9月18日：添加了 Qwen2.5-Math 示例，展示了 Qwen2.5-Math 的工具集成推理能力。注意：Python 执行器未沙箱化，仅用于本地测试，不适合生产使用。
快速开始
安装
- 从 PyPI 安装稳定版本：
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# 或者使用 `pip install -U qwen-agent` 来满足最小需求。
# 可选需求，用双括号指定：
# [gui] 用于基于 Gradio 的 GUI 支持；
# [rag] 用于 RAG 支持；
# [code_interpreter] 用于代码解释器支持；
# [mcp] 用于 MCP 支持。
- 或者，您可以从源码安装最新开发版本：
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
# 或者 `pip install -e ./` 来满足最小需求。
准备工作：模型服务
您可以使用阿里云提供的 DashScope 模型服务，或者部署并使用自己的模型服务，使用开源的 Qwen 模型。
-
如果选择使用 DashScope 提供的模型服务，请确保设置环境变量
DASHSCOPE_API_KEY为您唯一的 DashScope API 密钥。 -
如果您更愿意部署并使用自己的模型服务，请按照 Qwen2 的 README 中提供的说明部署与 OpenAI 兼容的 API 服务。 具体而言，查阅 vLLM 部分以进行高吞吐量 GPU 部署，或查阅 Ollama 部分以进行本地 CPU（+GPU）部署。 对于 QwQ 和 Qwen3 模型，建议不要添加
--enable-auto-tool-choice和--tool-call-parser hermes参数，因为 Qwen-Agent 将自行解析来自 vLLM 的工具输出。 对于 Qwen3-Coder，建议启用上述两个参数，使用 vLLM 内置的工具解析，并结合use_raw_api参数 [使用方法](#如何向代理传递 LLM 参数)。
开发自己的代理
Qwen-Agent 提供了原子组件，如 LLM（继承自 class BaseChatModel 并带有 函数调用）和工具（继承自 class BaseTool），以及高级组件如代理（派生自 class Agent）。
以下示例说明了创建一个能够读取 PDF 文件并使用工具的代理的过程，以及如何加入自定义工具：
import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print
# 第一步（可选）：添加一个名为 `my_image_gen` 的自定义工具。
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
# `description` 告诉代理该工具的功能。
description = 'AI 绘画（图像生成）服务，输入文本描述，返回基于文本信息绘制的图像 URL。'
# `parameters` 告诉代理该工具有哪些输入参数。
parameters = [{
'name': 'prompt',
'type': 'string',
'description': '所需图像内容的详细英文描述',
'required': True
}]
def call(self, params: str, **kwargs) -> str:
# `params` 是由 LLM 代理生成的参数。
prompt = json5.loads(params)['prompt']
prompt = urllib.parse.quote(prompt)
return json5.dumps(
{'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
ensure_ascii=False)
# 第二步：配置您正在使用的 LLM。
llm_cfg = {
# 使用 DashScope 提供的模型服务：
'model': 'qwen-max-latest',
'model_type': 'qwen_dashscope',
# 'api_key': 'YOUR_DASHSCOPE_API_KEY',
# 如果这里没有设置 'api_key'，则会使用 `DASHSCOPE_API_KEY` 环境变量。
# 使用与 OpenAI API 兼容的模型服务，如 vLLM 或 Ollama：
# 'model': 'Qwen2.5-7B-Instruct',
# 'model_server': 'http://localhost:8000/v1', # 基础 URL，也称为 api_base
# 'api_key': 'EMPTY',
# （可选）LLM 生成的超参数：
'generate_cfg': {
'top_p': 0.8
}
}
# 第三步：创建一个代理。这里我们以 `Assistant` 代理为例，它可以使用工具并读取文件。
system_instruction = '''在收到用户请求后，你应该：
- 首先绘制一张图片并获取图片 URL，
- 然后运行代码 `request.get(image_url)` 下载图片，
- 最后从给定的文档中选择一个图像操作来处理图片。
请使用 `plt.show()` 显示图片。'''
tools = ['my_image_gen', 'code_interpreter'] # `code_interpreter` 是一个内置工具，用于执行代码。
files = ['./examples/resource/doc.pdf'] # 给机器人一个 PDF 文件来阅读。
bot = Assistant(llm=llm_cfg,
system_message=system_instruction,
function_list=tools,
files=files)
# 第四步：将代理作为聊天机器人运行。
messages = [] # 这里存储聊天历史。
while True:
# 例如，输入查询 "绘制一只狗并将其旋转 90 度"。
query = input('\nuser query: ')
# 将用户查询追加到聊天历史中。
messages.append({'role': 'user', 'content': query})
response = []
response_plain_text = ''
print('bot response:')
for response in bot.run(messages=messages):
# 流式输出。
response_plain_text = typewriter_print(response, response_plain_text)
# 将机器人的响应追加到聊天历史中。
messages.extend(response)
除了使用内置的代理实现如 class Assistant，您还可以通过继承 class Agent 来开发自己的代理实现。
框架还提供了一个方便的 GUI 接口，支持快速部署代理的 Gradio 演示。 例如，在上述情况下，您可以使用以下代码快速启动一个 Gradio 演示：
from qwen_agent.gui import WebUI
WebUI(bot).run() # bot 是在上面代码中定义的代理，这里为了节省空间不再重复定义。
现在您可以在 Web UI 中与代理进行对话。更多使用示例，请参阅 示例 目录。
常见问题解答
如何使用 MCP？
您可以在开源的 MCP 服务器网站 上选择所需的工具，并配置相关环境。
MCP 调用格式示例：
{
"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 使用示例
运行此示例所需的依赖项如下：
# Node.js（从 Node.js 官方网站下载并安装最新版本）
# uv 0.4.18 或更高版本（检查 uv --version）
# Git（检查 git --version）
# SQLite（检查 sqlite3 --version）
# 对于 macOS 用户，可以使用 Homebrew 安装这些组件：
brew install uv git sqlite3
# 对于 Windows 用户，可以使用 winget 安装这些组件：
winget install --id=astral-sh.uv -e
winget install git.git sqlite.sqlite
您有函数调用（又称工具调用）吗？
是的。LLM 类提供了 函数调用。此外，一些代理类也是基于函数调用能力构建的，例如 FnCallAgent 和 ReActChat。
当前默认的工具调用模板原生支持 并行函数调用。
如何向代理传递 LLM 参数？
llm_cfg = {
# 正在使用的模型名称：
'model': 'qwen3-32b',
# 正在使用的模型服务：
'model_type': 'qwen_dashscope',
# 如果这里没有设置 'api_key'，则会默认读取 `DASHSCOPE_API_KEY` 环境变量：
'api_key': 'YOUR_DASHSCOPE_API_KEY',
# 使用与 OpenAI API 兼容的模型服务，如 vLLM 或 Ollama：
# 'model': 'qwen3-32b',
# 'model_server': 'http://localhost:8000/v1', # 基础 URL，也称为 api_base
# 'api_key': 'EMPTY',
# （可选）LLM 超参数：
'generate_cfg': {
# 此参数会影响工具调用解析逻辑，默认值为 False：
# 设置为 True：当内容为 `<think>this is the thought</think>this is the answer`
# 设置为 False：当响应由 reasoning_content 和 content 组成
# 'thought_in_content': True,
# 工具调用模板：默认为 nous（推荐用于 qwen3）：
# 'fncall_prompt_type': 'nous'
# 最大输入长度，如果消息超过此长度将被截断，请根据模型 API 进行调整：
# 'max_input_tokens': 58000
# 将直接传递给模型 API 的参数，如 top_p、enable_thinking 等，根据 API 规范：
# 'top_p': 0.8
# 使用 API 的原生工具调用接口
# 'use_raw_api': True,
}
}
如何对涉及 1M 个 token 的超级长文档进行问答？
我们已经发布了 一个快速 RAG 解决方案，以及 一个昂贵但具有竞争力的代理，用于对超级长文档进行问答。它们已经在两个具有挑战性的基准上超过了原生长上下文模型，同时更加高效，并且在单针“针入草堆”压力测试中完美表现，涉及 1M-token 上下文。详情请参阅 博客。
<p align="center"> <img src="https://gips0.baidu.com/it/u=2522721553,863267645&fm=3081&app=3081&f=PNG?w=2320&h=2620" width="400"/> <p>应用：BrowserQwen
BrowserQwen 是一个基于 Qwen-Agent 构建的浏览器助手。请参阅其 文档 了解详细信息。
免责声明
代码解释器未沙箱化，它会在您的环境中执行代码。请勿要求 Qwen 执行危险任务，也不应直接将代码解释器用于生产目的。