你是否曾觉得搭建 AI 智能体门槛太高而望而却步？其实，Qwen-Agent 的搭建并没有想象中复杂——即使你没有 AI 开发经验，也能跟着清晰的步骤完成从环境准备到智能体运行的全流程。
本文将用直白的语言拆解 Qwen-Agent 搭建的每一个关键步骤，从环境准备到最终启动，每一步都有明确指引，帮你真正实现"从 0 到 1"搞定 Qwen-Agent 搭建。
测试开发全景图：人工智能测试、智能驱动、自动化、测试开发、左移右移与DevOps的持续交付
一、环境准备与安装
首先需要配置基础开发环境：
# 创建并激活conda环境conda create --name qwen-agent python=3.12conda activate qwen-agent
# 克隆Qwen-Agent仓库git clone https://github.com/QwenLM/Qwen-Agent.gitcd Qwen-Agent
# 安装核心依赖包pip install -e ./"[rag,code_interpreter,python_executor]"
复制代码
确保你的系统满足以下要求：
二、模型部署：两种方案选择
Qwen-Agent 支持两种模型服务对接方式：
方案一：使用阿里云 DashScope 服务（推荐新手）
# 文本模型配置llm_cfg = { 'model': 'qwen-plus-2025-01-25', 'model_type': 'qwen_dashscope', 'api_key': '你的API密钥', # 请在阿里云平台申请 'generate_cfg': {'top_p': 0.8}}
复制代码
方案二：本地部署开源模型（需要更多资源）
# 本地文本模型配置llm_cfg = { 'model': 'Qwen/Qwen2.5-14B-Instruct', 'model_server': 'http://127.0.0.1:9995/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.9}}
# 多模态模型配置llm_cfg_vl = { 'model': 'Qwen/Qwen2-VL-7B-Instruct', 'model_server': 'http://127.0.0.1:9993/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.9}}
复制代码
三、第一个智能体应用：RAG 示例
下面我们创建一个能够处理文档问答的智能体：
from qwen_agent.agents import Assistant
# 配置LLM模型llm_cfg = { 'model': 'Qwen/Qwen2.5-14B-Instruct', 'model_server': 'http://127.0.0.1:9995/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.9}}
def test(): # 初始化助手 bot = Assistant(llm=llm_cfg) # 构建消息：用户查询+文档文件 messages = [ {'role': 'user', 'content': [ {'text': '介绍图一'}, {'file': '/path/to/your/document.pdf'} # 替换为你的文档路径 ]} ] # 运行智能体并获取响应 for rsp in bot.run(messages): print(rsp)
if __name__ == '__main__': test()
复制代码
这个示例展示了 Qwen-Agent 的文档理解能力——它能读取 PDF 文件内容并回答相关问题。
四、工具调用：扩展智能体能力
Qwen-Agent 的强大之处在于能调用各种工具。以下是天气预报助手的示例：
import osfrom qwen_agent.agents import Assistant
# 设置高德地图API密钥（需要自行申请）os.environ['AMAP_TOKEN'] = '你的高德API密钥'
# 模型配置llm_cfg = { 'model': 'Qwen/Qwen2.5-14B-Instruct', 'model_server': 'http://127.0.0.1:9995/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.9}}
# 定义系统指令system_instruction = ( '你扮演一个天气预报助手，你具有查询天气和画图能力。' '你需要查询相应地区的天气，然后调用画图工具绘制一张城市的图。')
# 创建智能体bot = Assistant( llm=llm_cfg, system_message=system_instruction, function_list=['weather_query', 'image_gen'] # 天气查询和图像生成工具)
复制代码
这样创建的智能体能够查询真实天气数据并生成相应的可视化结果。
五、多 Agent 路由：处理复杂任务
对于复杂任务，可以使用多 Agent 协作系统：
from qwen_agent.agents import Assistant, ReActChat, Router
# 文本模型配置llm_cfg = {...}
# 多模态模型配置llm_cfg_vl = {...}
def init_agent_service(): tools = ['image_gen', 'code_interpreter'] # 创建多模态助手 bot_vl = Assistant( llm=llm_cfg_vl, name='多模态助手', description='可以理解图像内容。', function_list=tools ) # 创建工具助手 bot_tool = ReActChat( llm=llm_cfg, name='工具助手', description='可以使用画图工具和运行代码来解决问题', function_list=tools, ) # 创建路由器，管理多个智能体 bot = Router( llm=llm_cfg, agents=[bot_vl, bot_tool], ) return bot
复制代码
这种架构允许系统自动选择最合适的智能体处理不同任务，比如图像理解类任务路由到多模态助手，工具使用类任务路由到工具助手。
六、自定义工具开发
你还可以创建自己的工具：
from qwen_agent.tools.base import BaseTool, register_toolimport json5import urllib.parse
@register_tool('my_image_gen')class MyImageGen(BaseTool): description = 'AI绘画服务，输入文本描述，返回基于文本信息绘制的图像URL。' parameters = [{ 'name': 'prompt', 'type': 'string', 'description': '期望的图像内容的详细描述', 'required': True }]
def call(self, params: str, **kwargs) -> str: 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)
复制代码
自定义工具通过继承 BaseTool 类并实现 call 方法，可以集成任何 API 或功能到你的智能体中。
七、常见问题与解决
环境配置问题：确保使用 Python 3.12 版本，避免版本兼容性问题
API 密钥错误：如果使用 DashScope 服务，确保 API 密钥正确配置
模型加载失败：检查模型路径和网络连接，确保能正常访问模型服务
工具调用失败：确认工具已正确注册，参数格式符合要求
八、进一步学习方向
成功搭建基础智能体后，你可以进一步探索：
结语
通过本文的指导，你应该已经成功搭建了第一个 Qwen-Agent 智能体。从环境配置到智能体开发，整个流程其实并不复杂，关键是一步步跟着操作。
Qwen-Agent 作为一个功能强大且灵活的框架，为开发者提供了构建 AI 智能体的全套工具。无论你是想开发简单的问答机器人，还是构建复杂的多模态应用系统，Qwen-Agent 都能提供良好的支持。
现在就开始你的 AI 智能体开发之旅吧！如果有任何问题，欢迎在评论区留言讨论。
测试开发全景图：人工智能测试、智能驱动、自动化、测试开发、左移右移与DevOps的持续交付
评论