目录
- 前言
- 一、快速开始
- 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\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)
2-3-2、LLM开发
Qwen-Agent提供llm注册机制。在LLM基类中，实现了统一的LLM .chat(…)接口。新注册的llm只需要实现三个特定的功能:
- 非流式的生成接口;
- 流式生成接口(如果LLM本身不支持流生成，非流结果可以包装到生成器中返回);
- 一个函数调用接口。
如果新注册的LLM不支持函数调用，它可以继承Qwen-Agent中实现的BaseFnCallModel类。这个类通过包装一个类似于ReAct的工具调用提示符，实现了基于通用会话接口的函数调用。
三、基于Qwen-Agent的案例分析
3-1、
3-2、
参考文章：
Qwen-Agent ： GitHub官网.
Qwen-Agent 文档
总结
会调用工具的Agent太炫酷啦。🐏
