【通义千问系列】Qwen-Agent 从入门到精通【持续更新中……】

前言
一、快速开始
- 1-1、介绍
- 1-2、安装
- 1-3、开发你自己的Agent
二、Qwen-Agent的使用和开发过程
- 2-1、Agent
- - 2-1-1、Agent使用
  - 2-1-2、Agent开发
- 2-2、Tool
- - 2-2-1、工具使用
  - 2-2-2、工具开发
- 2-3、LLM
- - 2-3-1、LLM使用
  - 2-3-2、LLM开发
三、基于Qwen-Agent的案例分析
- 3-1、
- 3-2、
总结

前言

Qwen-Agent是一个开发框架。开发者可基于本框架开发Agent应用，充分利用基于通义千问模型（Qwen）的指令遵循、工具使用、规划、记忆能力。本框架也提供了浏览器助手、代码解释器、自定义助手等示例应用。

一、快速开始

1-1、介绍

Qwen-Agent: 是一个开发框架。开发者可基于本框架开发Agent应用，充分利用基于通义千问模型（Qwen）的指令遵循、工具使用、规划、记忆能力。本项目也提供了浏览器助手、代码解释器、自定义助手等示例应用。

在这里插入图片描述

1-2、安装

1、使用pip安装：

pip install -U qwen-agent

2、从Github安装最新版本

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./

1-3、开发你自己的Agent

概述：下面的示例说明了创建一个能够读取PDF文件和利用工具的代理的过程，以及构建自定义工具，以下为详细介绍：

添加一个自定义工具：图片生成工具
使用到的LLM模型配置。
创建Agent，这里我们以“Assistant”代理为例，它能够使用工具和读取文件。
以聊天机器人的形式运行助理。

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

# Step 1 (Optional): Add a custom tool named `my_image_gen`.
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    # The `description` tells the agent the functionality of this tool.
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    # The `parameters` tell the agent what input parameters the tool has.
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # `params` are the arguments generated by the LLM agent.
        prompt = json5.loads(params)['prompt']
        # 对提示词进行URL编码
        prompt = urllib.parse.quote(prompt)
        # 
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)


# Step 2: Configure the LLM you are using.
# 这里是需要配置模型的地方。需要填写模型名字，以及model_server，即模型所在服务器名字，如果没有，也可以考虑使用api_key。
llm_cfg = {
    # Use the model service provided by DashScope:
	# model：模型名称
	# model_server：模型所在的服务器
	# api_key： 所使用到的api-key，可以显示的设置，也可以从环境变量中获取
	
    'model': 'qwen-max',
    'model_server': 'dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    # It will use the `DASHSCOPE_API_KEY' environment variable if 'api_key' is not set here.

    # Use a model service compatible with the OpenAI API, such as vLLM or Ollama:
    # 'model': 'Qwen1.5-7B-Chat',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, also known as api_base
    # 'api_key': 'EMPTY',

    # (Optional) LLM hyperparameters for generation:
    # 用于调整生成参数的可选配置
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Step 3: Create an agent. Here we use the `Assistant` agent as an example, which is capable of using tools and reading files.

# agent的提示词指令
system_instruction = '''You are a helpful assistant.
After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''

# 工具列表，指定Assistant可以访问的工具，一个是自定义的工具，一个是代码执行器
tools = ['my_image_gen', 'code_interpreter']  # `code_interpreter` is a built-in tool for executing code.
# 助理可以读取的文件路径
files = ['./examples/resource/doc.pdf']  # Give the bot a PDF file to read.

# 初始化Assistant
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)

# Step 4: Run the agent as a chatbot.
messages = []  # This stores the chat history.
while True:
    # For example, enter the query "draw a dog and rotate it 90 degrees".
    query = input('user query: ')
    # Append the user query to the chat history.
    messages.append({'role': 'user', 'content': query})
    response = []
    for response in bot.run(messages=messages):
        # Streaming output.
        print('bot response:')
        pprint.pprint(response, indent=2)
    # Append the bot responses to the chat history.
    messages.extend(response)

首先输入任务目标：draw a dog and rotate it 90 degrees
绘制的狗子图片：
结果输出：
Agent处理后的狗子图片展示：

在这里插入图片描述

二、Qwen-Agent的使用和开发过程

2-1、Agent

2-1-1、Agent使用

概述： Qwen-Agent的Agent类集成了工具调用和LLM的接口，不同Agent类的工作流不同。

Qwen-Agent提供一个通用的Agent类，Assistant类，可以处理大多数任务，例如：

它支持角色扮演
它提供了自动规划和工具调用能力
它接受文档输入，并且可以使用集成的RAG策略来解析文档。

案例分析：

import os
from qwen_agent.agents import Assistant
llm_cfg = {'model': 'qwen-max'}
tools = ['image_gen', 'amap_weather']  # image_gen and code_interpreter is a built-in tool in Qwen-Agent
system = 'According to the user\'s request, you first draw a picture and then automatically run code to download the picture ' + \
          'and select an image operation from the given document to process the image'

bot = Assistant(llm=llm_cfg,
                system_message=system,
                function_list=tools,
                files=[os.path.abspath('doc.pdf')])


messages = [{'role': 'user', 'content': 'a cute cat'}]
for response in bot.run(messages=messages):
    print('bot response:', response)

"""Running results：
[
    {'role': 'assistant', 'content': '', 'function_call': {'name': 'my_image_gen', 'arguments': '{"prompt": "a cute cat"}'}},
    {'role': 'function', 'content': '{"image_url": "https://image.pollinations.ai/prompt/a%20cute%20cat"}', 'name': 'my_image_gen'},
    {'role': 'assistant', 'content': "Here is the image of a cute cat based on your description:\n\n![](https://image.pollinations.ai/prompt/a%20cute%20cat)\n\nNow, let's proceed with downloading this image and performing an operation such as flipping it."},
    {'role': 'assistant', 'content': '', 'function_call': {'name': 'code_interpreter', 'arguments': '```py\nfrom PIL import Image\nimport requests\n\n# Downloading the cute cat image\nurl = "https://image.pollinations.ai/prompt/a%20cute%20cat"\nresponse = requests.get(url)\nwith open("cute_cat.jpg", \'wb\') as file:\n    file.write(response.content)\n\n# Flipping the image horizontally\ndef flip_image_horizontally(filename):\n    img = Image.open(filename)\n    flipped_img = img.transpose(Image.FLIP_LEFT_RIGHT)\n    flipped_img.save("flipped_cute_cat.jpg")\n    return flipped_img\n\n# Performing the horizontal flip\nflipped_cat = flip_image_horizontally("cute_cat.jpg")\n```'}},
    {'role': 'function', 'content': 'Finished execution.', 'name': 'code_interpreter'},
    {'role': 'assistant', 'content': 'The image of the cute cat has been downloaded and flipped horizontally. The flipped image has been saved as "flipped_cute_cat.jpg". Since we\'re in a text-based environment, I can\'t display the actual image here, but you can check it out at the location where the script was executed.'}
]
"""

此外我们还提供了一个通用的多代理类:GroupChat类。这个类管理一个agent列表并自动维护它们的语音顺序。这个类的特点包括:

在接收到外部输入后，它自动协调内置代理的说话顺序，并按顺序将它们的响应返回给用户;
Human-in-the-loop:用户也被定义为Agent，群聊可以在必要时请求用户的反馈;
用户可以随时中断群聊。

2-1-2、Agent开发

Demo1： 自定义Agent，一个用于可视化故事讲解的代理，它结合了图像理解和文章撰写的能力，将多模型、多工具的能力集成到一个工作流中。嵌套使用多个Agent。Agent介绍如下：

image_agent：使用Qwen-VL理解图片内容
writing_agent：帮助撰写作文

工作流程以及代码实现：

用户输入：用户提供一组包含图像的消息
图像理解：image-agent 使用qwen-vl-max模型，对图像进行详细描述
撰写文章：根据图像描述，结合知识库撰写完整的叙事故事。
生成结果：最终响应将包括图像描述和叙事故事。


import copy
from typing import Dict, Iterator, List, Optional, Union

# 代理类
from qwen_agent import Agent
# 助理类
from qwen_agent.agents import Assistant
# 基础聊天模型
from qwen_agent.llm import BaseChatModel
# 
from qwen_agent.llm.schema import ContentItem, Message
from qwen_agent.tools import BaseTool

# 继承自Agent基类
class VisualStorytelling(Agent):
    """Customize an agent for writing story from pictures"""
	
	# function_list：可以使用的工具列表，默认为空。
	# llm：指定的语言模型，默认为空。
    def __init__(self,
                 function_list: Optional[List[Union[str, Dict,
                                                    BaseTool]]] = None,
                 llm: Optional[Union[Dict, BaseChatModel]] = None):
        super().__init__(llm=llm)

        # Nest one vl assistant for image understanding
        # 初始化视觉理解Agent
        self.image_agent = Assistant(llm={'model': 'qwen-vl-max'})
		
        # Nest one assistant for article writing
        # 初始化写作Agent
        # 提供指定工具和文件，用于支持写作任务。
        self.writing_agent = Assistant(
            llm=self.llm,
            function_list=function_list,
            system_message='You are a student, first, you need to understand the content of the picture,' +
            'then you should refer to the knowledge base and write a narrative essay of 800 words based on the picture.',
            files=['https://www.jianshu.com/p/cdf82ff33ef8'])
	
	# 定义工作流程，用于处理一组输入消息，生成视觉故事。
    def _run(self,
             messages: List[Message],
             lang: str = 'zh',
             max_ref_token: int = 4000,
             **kwargs) -> Iterator[List[Message]]:
        """Define the workflow"""

        assert isinstance(messages[-1]['content'], list) and any([
            item.image for item in messages[-1]['content']
        ]), 'This agent requires input of images'

        # Image understanding
        new_messages = copy.deepcopy(messages)
        new_messages[-1]['content'].append(
            ContentItem(text='Please provide a detailed description of all the details of this image'))
        response = []
        for rsp in self.image_agent.run(new_messages):
            yield response + rsp
        response.extend(rsp)
        new_messages.extend(rsp)

        # Writing article
        new_messages.append(Message('user', 'Start writing your narrative essay based on the above image content!'))
        for rsp in self.writing_agent.run(new_messages,
                                          lang=lang,
                                          max_ref_token=max_ref_token,
                                          **kwargs):
            yield response + rsp

Demo2： 文档问答Agent，根据给定的参考资料来回答问题。

import copy
from typing import Iterator, List

from qwen_agent import Agent
from qwen_agent.llm.schema import CONTENT, ROLE, SYSTEM, Message

PROMPT_TEMPLATE_ZH = """
请充分理解以下参考资料内容，组织出满足用户提问的条理清晰的回复。
#参考资料：
{ref_doc}

"""

PROMPT_TEMPLATE_EN = """
Please fully understand the content of the following reference materials and organize a clear response that meets the user's questions.
# Reference materials:
{ref_doc}

"""

# 定义了两个语言的系统提示模板（中文和英文），用于引导模型回答问题
# PROMPT_TEMPLATE：根据语言类型返回相应模板
PROMPT_TEMPLATE = {
    'zh': PROMPT_TEMPLATE_ZH,
    'en': PROMPT_TEMPLATE_EN,
}


class DocQA(Agent):
	# messages：用户与助理之间的消息列表。
	# knowledge：参考资料内容，作为系统提示模板的一部分。
	# lang：语言类型，默认为英文（'en'）。
    def _run(self,
             messages: List[Message],
             knowledge: str = '',
             lang: str = 'en',
             **kwargs) -> Iterator[List[Message]]:
        messages = copy.deepcopy(messages)
        system_prompt = PROMPT_TEMPLATE[lang].format(ref_doc=knowledge)
        if messages[0][ROLE] == SYSTEM:
            messages[0][CONTENT] += system_prompt
        else:
            messages.insert(0, Message(SYSTEM, system_prompt))

        return self._call_llm(messages=messages)

2-2、Tool

2-2-1、工具使用

1、工具统一使用.call(params)接口进行调用，您可以在其中为工具传递必要的参数。例如：直接的唤醒一个图片生成工具

from qwen_agent.tools import ImageGen

tool = ImageGen()
res = tool.call(params = {'prompt': 'a cute cat'})
print(res)

2-2-2、工具开发

Qwen-Agent提供了注册工具的机制。例如，要注册您自己的图片生成工具:

指定工具的名称、描述和参数。请注意，传递给@register_tool(‘my_image_gen’)的字符串会自动添加为类的.name属性，并将作为工具的唯一标识符。
实现call(…)函数。

如下为范例：

import urllib.parse
import json5
import json
from qwen_agent.tools.base import BaseTool, register_tool
# Add a custom tool named my_image_gen：
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description':
        'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)

一旦注册了这些工具，就可以像上面提到的那样使用它们。
如果不希望使用注册方法，也可以直接定义工具类，然后将工具对象传递给Agent(未注册的工具不支持传递工具名称或配置文件)。

import urllib.parse
import json5
import json
from qwen_agent.tools.base import BaseTool

class MyImageGen(BaseTool):
    name = 'my_image_gen'
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description':
        'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)

2-3、LLM

目前，Qwen- agent提供了Qwen的DashScope API和OpenAI API，以及Qwen- vl的DashScope API的访问接口。两者都已经支持流式函数调用。

2-3-1、LLM使用

LLM使用get_chat_model(cfg: Optional[Dict] = None) -> BaseChatModel接口统一调用，传入的参数是LLM的配置文件。配置文件格式如下:

model_type:对应于特定的LLM类，是LLM类的注册名，即唯一ID。当使用内置的DashScope和OpenAI API时，该参数可以省略。对于外部注册的LLM类，必须提供此参数来指定类。
model:具体的模型名
model_server:模型服务地址
generate_cfg:模型生成的参数LLM类统一使用

LLM .chat(…)接口生成响应，支持消息列表、函数和其他参数的输入。

from qwen_agent.llm import get_chat_model

llm_cfg = {
            # Use the model service provided by DashScope:
            # 'model_type': 'qwen_dashscope',
            'model': 'qwen-max',
            'model_server': 'dashscope',
            # Use your own model service compatible with OpenAI API:
            # 'model': 'Qwen',
            # 'model_server': 'http://127.0.0.1:7905/v1',
            # (Optional) LLM hyper-paramters:
            'generate_cfg': {
                'top_p': 0.8
            }
          }
llm = get_chat_model(llm_cfg)
messages = [{
    'role': 'user',
    'content': "What's the weather like in San Francisco?"
}]
functions = [{
    'name': 'get_current_weather',
    'description': 'Get the current weather in a given location',
    'parameters': {
        'type': 'object',
        'properties': {
            'location': {
                'type': 'string',
                'description':
                'The city and state, e.g. San Francisco, CA',
            },
            'unit': {
                'type': 'string',
                'enum': ['celsius', 'fahrenheit']
            },
        },
        'required': ['location'],
    },
}]

# The streaming output responses
responses = []
for responses in llm.chat(messages=messages,
                          functions=functions,
                          stream=True):
    print(responses)