基于Qwen2.5-7B实现工具调用｜Qwen-Agent快速入门实战

基于Qwen2.5-7B实现工具调用｜Qwen-Agent快速入门实战

一、前言：为什么需要智能体框架？

随着大语言模型（LLM）在自然语言理解与生成能力上的持续突破，单纯“问答式”的交互已无法满足复杂场景的需求。真正的AI助手应当具备主动思考、调用外部能力、执行任务并反馈结果的能力——这正是智能体（Agent）的核心价值。

Qwen-Agent 是阿里通义千问团队推出的开源 LLM 应用开发框架，专为Qwen 系列模型设计，支持指令遵循、工具调用、长上下文处理和结构化输出（如 JSON），尤其适合构建具备实际功能的 AI 助手应用。

本文将带你从零开始，使用Qwen2.5-7B-Instruct 模型 + Qwen-Agent 框架，实现一个可调用自定义天气查询工具的智能代理，并深入解析其运行机制与工程实践要点。

✅ 你将掌握： - 如何部署 Qwen2.5-7B 并提供 OpenAI 兼容 API - 如何通过 Qwen-Agent 构建支持工具调用的智能体 - 自定义工具注册与执行流程 - 工具调用过程中的数据流转与模型行为分析

二、技术背景与核心概念

2.1 Qwen2.5 系列模型的技术演进

Qwen2.5 是通义千问团队发布的最新一代大语言模型系列，覆盖 0.5B 到 720B 参数规模。相比 Qwen2，它在多个维度实现了显著提升：

其中，Qwen2.5-7B-Instruct是经过指令微调的 70 亿参数版本，性能均衡、资源消耗适中，非常适合本地部署与轻量级 Agent 开发。

2.2 什么是 Qwen-Agent？

Qwen-Agent 是一个基于 Qwen 模型构建的模块化智能体开发框架，具备以下关键特性：

• 工具调用（Function Calling）：支持自定义 Python 函数作为工具供模型调用
• 代码解释器（Code Interpreter）：内置 Python 执行环境，可用于数学计算、数据分析
• RAG 支持：结合检索增强生成，提升事实准确性
• GUI 支持：集成 Gradio 快速搭建 Web 界面
• 流式响应：支持实时输出，提升用户体验

该框架允许开发者以“积木式”方式组合 LLM、提示词、工具和记忆组件，快速构建面向特定场景的 AI 助手。

三、前置准备：环境搭建与依赖安装

3.1 硬件与系统要求

3.2 下载 Qwen2.5-7B-Instruct 模型

可通过 Hugging Face 或 ModelScope 获取模型权重：

# 方式一：HuggingFace git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct # 方式二：ModelScope（推荐国内用户） pip install modelscope from modelscope.hub.snapshot_download import snapshot_download snapshot_download('qwen/Qwen2.5-7B-Instruct', cache_dir='./models')

模型路径后续用于启动服务，例如：/path/to/Qwen2.5-7B-Instruct

3.3 启动本地推理服务（vLLM）

为提高推理效率，推荐使用vLLM提供 OpenAI 兼容 API 接口：

# 创建虚拟环境 conda create -n qwen-agent python=3.10 conda activate qwen-agent # 安装 vLLM pip install vllm # 启动服务（支持 128K 上下文） python -m vllm.entrypoints.openai.api_server \ --model /path/to/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 9000 \ --max-model-len 131072 \ --enable-auto-tool-call \ --tool-call-parser hermes

🔍 注意：--enable-auto-tool-call和--tool-call-parser hermes是启用函数调用的关键参数，确保模型能正确解析工具调用请求。

此时，模型服务已运行在http://localhost:9000/v1，可通过标准 OpenAI SDK 调用。

四、实战：构建支持工具调用的智能体

4.1 安装 Qwen-Agent 框架

# 安装完整功能包（含 GUI、RAG、代码解释器等） pip install -U "qwen-agent[gui,rag,code_interpreter,python_executor]" # 或从源码安装（便于调试） git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ."[gui,rag,code_interpreter,python_executor]"

同时安装辅助库：

pip install python-dateutil json5

4.2 注册自定义工具：实时天气查询

我们以get_current_weather为例，演示如何将一个普通函数封装为 LLM 可识别的工具。

# -*- coding: utf-8 -*- import json5 from qwen_agent.tools.base import BaseTool, register_tool @register_tool('get_current_weather') class GetCurrentWeather(BaseTool): description = '获取指定城市的当前天气情况' parameters = [ { 'name': 'location', 'type': 'string', 'description': '城市名称，例如：北京、上海、广州', 'required': True } ] def call(self, params: str, **kwargs) -> str: # 解析模型生成的参数 location = json5.loads(params)['location'] print(f'[Tool Called] Location: {location}') # 模拟真实天气服务返回 if location == '广州': return '目前我市多云间晴，局部有阵雨，气温29~32℃，吹轻微的东南风。' elif location == '北京': return '今天北京晴转多云，气温18~25℃，空气质量良好。' else: return f'{location}暂无详细天气信息。'

📌 关键说明：

• @register_tool装饰器自动将类注册到全局工具池
• description和parameters字段用于生成 Tool Schema，供 LLM 理解用途与输入格式
• call()方法接收字符串形式的参数（JSON 格式），需手动解析

4.3 配置 LLM 与创建智能体

接下来配置模型连接信息，并初始化Assistant智能体实例：

# 配置 LLM 连接 llm_cfg = { 'model': '/qwen2.5-7b-instruct', # 模型标识符（任意命名） 'model_server': 'http://localhost:9000/v1', # vLLM 服务地址 'api_key': 'EMPTY', # vLLM 不需要密钥 'generate_cfg': { 'top_p': 0.8, 'temperature': 0.7 } } # 定义系统指令与可用工具 system_instruction = '你是一个乐于助人的AI助手，擅长使用工具获取实时信息。' tools = ['get_current_weather', 'code_interpreter'] # code_interpreter 内置 # 创建智能体 assistant = Assistant( llm=llm_cfg, system_message=system_instruction, function_list=tools )

⚠️ 注意事项： -model_server必须指向正在运行的 vLLM 服务 -function_list中的工具名必须与@register_tool名称一致 -code_interpreter可自动执行 Python 代码片段，常用于数学运算或数据处理

4.4 执行对话与工具调用

最后进行一次完整的对话测试：

if __name__ == '__main__': messages = [ {'role': 'user', 'content': '今天广州的天气怎么样？'} ] print("AI Response:") for res in assistant.run(messages=messages): if len(res) == 3: # 流式输出 content 字段 print(res[2]['content'], end='', flush=True) print() # 换行

✅ 输出示例：

params: {"location": "广州"} 今天广州的天气是多云间晴，局部有阵雨，气温在29到32摄氏度之间。同时，吹的是轻微的东南风。请出门的朋友注意携带雨具，并且注意防晒和补水。

五、深入解析：工具调用的数据流与执行逻辑

5.1 工具调用全过程三阶段

整个工具调用过程可分为三个阶段，对应不同的消息结构：

阶段一：模型决定调用工具

[ { "role": "assistant", "content": "", "function_call": { "name": "get_current_weather", "arguments": "{\"location\": \"广州\"}" } } ]

🧠 模型根据 prompt 和工具 schema 判断应调用哪个工具，并生成结构化参数。

阶段二：执行工具并注入结果

[ { "role": "function", "name": "get_current_weather", "content": "目前我市多云间晴，局部有阵雨，气温29~32℃，吹轻微的东南风。" } ]

🔧 Qwen-Agent 自动调用GetCurrentWeather().call()，并将结果以function角色回传给模型。

阶段三：模型生成最终回复

[ { "role": "assistant", "content": "今天广州的天气是多云间晴……请注意携带雨具。" } ]

💬 模型结合原始问题与工具返回结果，生成自然语言回答。

5.2 数据流转图示

User Input ↓ LLM (Qwen2.5-7B) → 是否需要工具？ ↓ 是 生成 tool_call 请求（JSON） ↓ Qwen-Agent 框架调用对应 .call() 方法 ↓ 获取执行结果（字符串） ↓ 将结果注入 conversation history ↓ LLM 继续生成最终回答 ↓ Return to User

这种“决策→执行→反馈”的闭环机制，构成了智能体的核心工作模式。

六、常见问题与优化建议

6.1 常见错误排查

6.2 性能优化建议

1. 启用量化推理bash # 使用 AWQ 量化（需提前转换） python -m vllm.entrypoints.openai.api_server \ --model /path/to/qwen2.5-7b-instruct-awq \ --quantization awq

2. 限制最大生成长度python llm_cfg['generate_cfg']['max_tokens'] = 512

3. 缓存工具结果（适用于静态数据） ```python from functools import lru_cache

@lru_cache(maxsize=128) def call(self, params: str, **kwargs): ... ```

七、总结与展望

本文完整演示了如何基于Qwen2.5-7B-Instruct + vLLM + Qwen-Agent构建一个支持工具调用的智能体系统，涵盖模型部署、框架集成、自定义工具开发与全流程调试。

✅ 核心收获

• Qwen-Agent 极大地简化了 Agent 开发流程，只需定义工具类即可接入 LLM
• 结构化输出能力强，特别适合生成 JSON 工具调用参数
• 生态整合良好，兼容 vLLM/Ollama/OpenAI API，易于部署上线
• 扩展性强，可轻松集成数据库查询、API 调用、文件处理等企业级功能

🚀 下一步建议

1. 尝试接入真实天气 API（如高德地图、OpenWeatherMap）
2. 结合 RAG 实现文档问答助手
3. 使用code_interpreter实现数学题自动求解
4. 搭建 Gradio GUI 界面，打造可视化交互应用

🔗 相关资源： - Qwen-Agent GitHub - Qwen2.5 官方文档 - vLLM 文档

现在，你已经掌握了构建实用型 AI 助手的核心技能。下一步，不妨尝试让它帮你查快递、写周报、分析 Excel 表格——让 AI 真正“动起来”。