中文｜ English

Qwen-Agent 是一个基于 Qwen 的指令跟随、工具使用、规划和记忆能力的 LLM 应用开发框架。它还附带了示例应用，如浏览器助手、代码解释器和自定义助手。

入门指南

安装

从 PyPI 安装稳定版本：

pip install -U qwen-agent[rag,code_interpreter]
# 如果不使用 RAG 和代码解释器，可以通过 `pip install -U qwen-agent` 安装最小依赖。

或者，您可以从源代码安装最新的开发版本：

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./[rag,code_interpreter]
# 如果不使用 RAG 和代码解释器，可以通过 `pip install -e ./` 安装最小依赖。

如果需要内置 GUI 支持，请通过以下方式安装可选依赖：

pip install -U qwen-agent[gui,rag,code_interpreter]
# 或从源代码安装：`pip install -e ./[gui,rag,code_interpreter]`

准备：模型服务

您可以使用阿里云的 DashScope 提供的模型服务，或者部署并使用自己的开源 Qwen 模型服务。

如果您选择使用 DashScope 提供的模型服务，请确保将环境变量 DASHSCOPE_API_KEY 设置为您唯一的 DashScope API 密钥。
或者，如果您更喜欢部署和使用自己的模型服务，请按照 Qwen2 的 README 中提供的说明部署兼容 OpenAI 的 API 服务。具体来说，请参考 vLLM 部分了解高吞吐量 GPU 部署，或 Ollama 部分了解本地 CPU（+GPU）部署。

开发您自己的 Agent

Qwen-Agent 提供了原子组件，如 LLM（继承自 class BaseChatModel，并附带函数调用）和工具（继承自 class BaseTool），以及高级组件如 Agent（派生自 class Agent）。

以下示例说明了创建一个能够读取 PDF 文件并使用工具的 agent 的过程，以及如何添加自定义工具：

import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool


# 步骤 1（可选）：添加一个名为 `my_image_gen` 的自定义工具。
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    # `description` 告诉 agent 这个工具的功能。
    description = 'AI 绘画（图像生成）服务，输入文本描述，返回基于文本信息绘制的图像 URL。'
    # `parameters` 告诉 agent 这个工具有哪些输入参数。
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': '所需图像内容的详细描述，使用英语',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # `params` 是 LLM agent 生成的参数。
        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)


# 步骤 2：配置您正在使用的 LLM。
llm_cfg = {
    # 使用 DashScope 提供的模型服务：
    'model': 'qwen-max',
    'model_server': 'dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    # 如果这里没有设置 'api_key'，将使用 'DASHSCOPE_API_KEY' 环境变量。

    # 使用兼容 OpenAI API 的模型服务，如 vLLM 或 Ollama：
    # 'model': 'Qwen2-7B-Chat',
    # 'model_server': 'http://localhost:8000/v1',  # base_url，也称为 api_base
    # 'api_key': 'EMPTY',

    # （可选）LLM 生成的超参数：
    'generate_cfg': {
        'top_p': 0.8
    }
}

# 步骤 3：创建一个 agent。这里我们以 `Assistant` agent 为例，它能够使用工具和读取文件。
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)

# 步骤 4：将 agent 作为聊天机器人运行。
messages = []  # 这里存储聊天历史。
while True:
    # 例如，输入查询"画一只狗并将其旋转 90 度"。
    query = input('用户查询: ')
    # 将用户查询添加到聊天历史中。
    messages.append({'role': 'user', 'content': query})
    response = []
    for response in bot.run(messages=messages):
        # 流式输出。
        print('机器人回复:')
        pprint.pprint(response, indent=2)
    # 将机器人回复添加到聊天历史中。
    messages.extend(response)

除了使用内置的 agent 实现（如 class Assistant）外，您还可以通过继承 class Agent 来开发自己的 agent 实现。请参考 examples 目录以获取更多使用示例。