Qwen-Agent使用指南：一步步打造智能AI代理

By /

作为一名热衷于AI开发的程序员，我最近深入研究了阿里巴巴开源的 Qwen-Agent 框架。这是一个基于 Qwen3 大语言模型的开发框架，专为构建智能AI代理设计，支持指令跟随、工具调用、规划和记忆功能。无论是想开发一个网页摘要助手、代码解释器，还是自定义工具的智能代理，Qwen-Agent 都能帮你快速上手。这篇博客将详细介绍 Qwen-Agent 的使用方法，包括环境配置、代码示例和实际应用场景，还会分享一些实用技巧和注意事项。

什么是 Qwen-Agent？

Qwen-Agent 是阿里巴巴云开发的开源框架，用于基于 Qwen 系列模型（如 Qwen3）构建 LLM（大语言模型）应用。它提供了模块化的组件，包括：

  • LLM 核心：支持 Qwen3 的指令跟随和工具调用能力。
  • 工具集成：内置工具如代码解释器（Code Interpreter）、RAG（检索增强生成）和浏览器助手。
  • 代理功能：支持多步骤规划、上下文记忆和复杂任务处理。
  • 灵活部署：可通过 DashScope API、OpenAI 兼容 API 或本地部署（如 vLLM、Ollama）运行。

Qwen-Agent 的亮点在于简化了工具调用和代理开发的复杂性，开发者无需手动处理 JSON 格式的函数调用，框架内部封装了模板和解析器。它还支持 Gradio 界面，方便快速测试和部署。以下是我的实际使用步骤和体验。

参考来源：Qwen-Agent 官方文档

前置条件：准备工作

在开始之前，确保你的开发环境满足以下要求：

  • 操作系统：Linux（推荐 Ubuntu 20.04+）、Windows（需 WSL2）或 macOS。
  • Python 版本：3.10 或更高。
  • 硬件：建议配备 NVIDIA GPU（如 RTX 3090 或 A100）以加速推理，CPU 也可运行但效率较低。
  • 存储空间：至少 50GB 磁盘空间（用于模型和依赖）。
  • 网络：若使用 DashScope API，需科学上网；本地部署则无需。

步骤 1：安装 Qwen-Agent

  1. 克隆 Qwen-Agent 仓库
    打开终端，运行以下命令获取最新代码：bashgit clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent
  2. 安装依赖
    使用 pip 安装 Qwen-Agent 及其可选组件。完整安装包括 GUI、RAG、代码解释器和 MCP 支持：bashpip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"如果只需要基本功能，可用：bashpip install -U qwen-agent
  3. 验证安装
    运行以下命令检查是否安装成功：bashpython -c "import qwen_agent; print(qwen_agent.__version__)"截至 2025 年 6 月，最新版本为 0.0.27。

注意：安装 GUI 需要 Python 3.10+，否则会报错。若遇到依赖冲突，建议创建虚拟环境：

bash

python -m venv qwen-env
source qwen-env/bin/activate  # Linux/macOS
qwen-env\Scripts\activate     # Windows

步骤 2：配置 Qwen3 模型

Qwen-Agent 需要连接到 Qwen3 模型，支持云端 API 或本地部署。以下是两种常见配置方式：

方法 1：使用 DashScope API

  1. 注册 DashScope 账号，获取 API 密钥。
  2. 设置环境变量：bashexport DASHSCOPE_API_KEY=your_api_key
  3. 配置 LLM：pythonllm_cfg = { 'model': 'qwen-max', 'model_server': 'dashscope', 'api_key': os.getenv('DASHSCOPE_API_KEY') }

方法 2：本地部署 Qwen3

使用 Ollama 或 vLLM 在本地运行 Qwen3 模型。以 Ollama 为例：

  1. 安装 Ollama（参考 Ollama 官网）。
  2. 下载 Qwen3 模型（推荐 Qwen3-8B，适合 16GB VRAM）：bashollama run qwen3:8b
  3. 配置 LLM：pythonllm_cfg = { 'model': 'qwen3:8b', 'model_server': 'http://localhost:11434/v1', 'api_key': 'EMPTY' }

注意：国际用户可能因区域限制无法直接使用 DashScope，建议通过 OpenRouter 或本地部署。

步骤 3：构建简单 AI 代理

以下是一个使用 Qwen-Agent 构建网页摘要代理的示例，展示工具调用和代理功能。

  1. 创建 Python 文件
    创建 qwen_agent_demo.py，添加以下代码：pythonimport os from qwen_agent.agents import Assistant # 配置 LLM llm_cfg = { 'model': 'qwen3:8b', 'model_server': 'http://localhost:11434/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.8} } # 定义工具 tools = ['code_interpreter'] # 内置代码解释器 # 初始化代理 bot = Assistant(llm=llm_cfg, function_list=tools) # 运行代理 messages = [{'role': 'user', 'content': '总结 https://qwenlm.github.io/blog/ 的最新动态'}] for response in bot.run(messages=messages): print('Bot response:', response)
  2. 运行代码
    确保 Ollama 服务已启动，运行：bashpython qwen_agent_demo.py输出将显示 Qwen3 对网页内容的总结，可能包括 Qwen3 的最新功能更新，如工具调用或长上下文支持。

步骤 4：添加自定义工具

Qwen-Agent 支持自定义工具调用，例如生成图片或查询实时数据。以下是一个添加图片生成工具的示例：

  1. 定义自定义工具
    修改 qwen_agent_demo.py，添加自定义工具：pythonimport json import urllib.parse from qwen_agent.tools.base import BaseTool, register_tool @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 = json.loads(params)['prompt'] prompt = urllib.parse.quote(prompt) return json.dumps({'image_url': f'https://image.pollinations.ai/prompt/{prompt}'}) # 更新工具列表 tools = ['my_image_gen', 'code_interpreter'] bot = Assistant(llm=llm_cfg, function_list=tools)
  2. 测试工具
    修改输入：pythonmessages = [{'role': 'user', 'content': '生成一张 futuristic city 的图片'}]运行后，代理会调用 my_image_gen 工具，输出图片 URL。

步骤 5：部署 Gradio 界面

Qwen-Agent 支持 Gradio 界面，方便测试和展示：

  1. 确保安装 GUI 依赖
    已在上一步安装 qwen-agent[gui]。
  2. 运行 Gradio 界面
    创建 qwen_gui.py：pythonfrom qwen_agent.gui import WebUI bot = Assistant(llm=llm_cfg, function_list=['code_interpreter']) ui = WebUI(bot) ui.run()
  3. 访问本地 URL（通常为 http://127.0.0.1:7860），即可通过浏览器与代理交互。

实际应用场景

Qwen-Agent 适合以下场景：

  • 网页摘要：如上例，结合 RAG 工具提取网页内容并总结。
  • 代码助手：使用代码解释器执行 Python 代码，适合数据分析或自动化脚本。
  • 多步骤任务：如规划旅行，代理可分解任务、调用 API 查询航班和酒店。
  • 长上下文处理：支持 1M 令牌上下文，适合分析长文档或多轮对话。

注意事项与优化建议

  1. 常见错误：
    • MCP 初始化失败：检查 JSON 格式和工具配置是否正确。
    • 上下文溢出：Qwen3 默认支持 32,768 令牌，超长输入需截断或使用 1M 模型。
    • API 限制：国际用户可能需 OpenRouter 替代 DashScope。
  2. 优化性能：
    • 使用 vLLM 加速推理，推荐 GPU 环境。
    • 调整 top_p 和 temperature 参数，思考模式建议 Temperature=0.6, TopP=0.95。
    • 定期更新 Qwen-Agent，最新版本支持 Qwen3 工具调用优化。
  3. 安全提示：
    • 代码解释器非沙盒环境，避免执行危险代码。
    • 本地部署更安全，保护数据隐私。

Qwen-Agent 与 AI 代理开发的未来

Qwen-Agent 的模块化设计和强大的工具调用能力让它在 AI 代理开发中脱颖而出。未来，随着 Qwen3 模型的优化（如 1M 上下文支持和 MoE 模型效率提升），Qwen-Agent 可能在以下领域有更大突破：

  • 企业自动化：结合 MCP 接入 200+ 数据源，构建财务分析或客服代理。
  • 多模态应用：集成 Qwen2.5-VL 处理图像和文本，开发多模态助手。
  • 本地化部署：随着硬件优化（如 Intel Open聒web:15⁊。

通过以上步骤，你可以用 Qwen-Agent 快速构建一个功能强大的 AI 代理，无论是网页摘要、代码执行还是自定义工具，都能高效实现。Qwen-Agent 的易用性和灵活性让它成为开发者打造智能助手的理想选择。想尝试更多功能？不妨探索 Qwen-Agent 的 GitHub 仓库 或加入 Qwen 社区讨论！

有任何 Qwen-Agent 使用问题，欢迎留言分享你的经验或疑问，咱们一起解决！

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *