新手轻松上手：零基础搭建Qwen智能体指南

本文详细介绍了如何从零开始搭建Qwen-Agent智能体，涵盖环境配置、模型部署、工具调用及多Agent协作等关键步骤，帮助无AI经验的开发者快速上手，实现从环境准备到智能体运行的完整流程。

霍格沃兹软件测试开发

539人浏览 · 2025-09-13 08:00:00

霍格沃兹软件测试开发 · 2025-09-13 08:00:00 发布

你是否曾因认为搭建AI智能体门槛过高而犹豫尝试？事实上，借助Qwen-Agent，即便你没有任何AI开发背景，也能够通过清晰的指引逐步完成从环境准备到智能体运行的整个过程。

本文将用通俗的语言，一步步拆解Qwen-Agent搭建中的每个关键环节。从环境配置到最终启动，每个阶段都配有明确的操作指导，帮助你真正实现从零开始、轻松搭建属于自己的AI智能体。

一、环境准备与安装

首先需要配置基础开发环境：

# 创建并激活conda环境
conda create --name qwen-agent python=3.12
conda activate qwen-agent

# 克隆Qwen-Agent仓库
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent

# 安装核心依赖包
pip install -e ./"[rag,code_interpreter,python_executor]"

确保你的系统满足以下要求：

硬件：推荐配备16GB显存的GPU（如NVIDIA RTX系列）
Python：3.6及以上版本
网络：能够访问GitHub和PyPI仓库

二、模型部署：两种方案选择

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 os
from 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_tool
import json5
import 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或功能到你的智能体中。