从零开始使用Qwen2.5-7B｜构建支持工具调用的AI代理

一、学习目标与技术背景

随着大语言模型（LLM）在自然语言理解与生成能力上的持续突破，AI代理（Agent）正成为连接模型能力与真实世界应用的关键桥梁。一个具备工具调用（Tool Usage）能力的AI代理，不仅能回答问题，还能主动执行操作——如查询天气、运行代码、访问数据库等，从而真正实现“智能体”的闭环交互。

本文将带你从零开始搭建一个基于 Qwen2.5-7B-Instruct 模型的支持工具调用的AI代理系统，使用阿里开源框架Qwen-Agent实现完整的本地部署与功能扩展。你将掌握：

如何部署 Qwen2.5-7B 模型并提供 OpenAI 兼容 API 接口
如何安装和配置 Qwen-Agent 框架
如何定义自定义工具并让模型自动调用
工具调用过程中的数据流解析与调试技巧

✅最终成果：你可以向AI提问“今天广州天气如何？”，它会自动调用你编写的get_current_weather函数返回实时信息，并以自然语言组织回复。

二、前置准备：环境与资源清单

2.1 硬件与软件要求

类别	要求
GPU 显存	至少 24GB（推荐 3090/4090 或 A10G），7B 模型需量化加载时可降低至 16GB
显卡数量	单卡即可运行（FP16精度）
CUDA 版本	≥ 12.1
Python 版本	3.10+
操作系统	Linux（CentOS 7 / Ubuntu 20.04+）

2.2 所需组件概览

组件	作用
`Qwen2.5-7B-Instruct`	主语言模型，负责推理与决策
`vLLM`或`llama.cpp`	提供高性能推理服务，暴露`/v1/chat/completions`接口
`Qwen-Agent`	AI代理框架，支持工具注册、规划、记忆等功能
`Gradio`（可选）	快速构建Web界面

三、部署Qwen2.5-7B模型服务

要让 Qwen-Agent 调用模型，首先需要启动一个本地的模型推理服务。我们推荐使用vLLM，因其对 Qwen 系列支持良好且性能优异。

3.1 安装 vLLM

pip install vLLM

注意：确保你的 PyTorch 和 CUDA 驱动版本兼容。建议使用torch==2.1.2+cu121。

3.2 启动模型服务

假设你已通过 ModelScope 或 Hugging Face 下载了模型权重到/models/Qwen2.5-7B-Instruct目录：

python -m vllm.entrypoints.openai.api_server \ --model /models/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 9000 \ --tensor-parallel-size 1 \ --dtype auto \ --max-model-len 131072 \ --enable-auto-tool-choice \ --tool-call-parser hermes

🔍 参数说明： ---enable-auto-tool-choice：启用自动工具选择功能 ---tool-call-parser hermes：使用 Hermes 解析器处理 JSON 结构化输出（适配 Qwen 的 tool call 格式）

服务启动后，默认监听http://localhost:9000/v1，完全兼容 OpenAI API 协议。

四、安装与配置 Qwen-Agent 框架

4.1 创建虚拟环境并安装依赖

conda create -n qwen-agent python=3.10 conda activate qwen-agent # 安装完整功能包（含GUI、RAG、代码解释器） pip install -U "qwen-agent[gui,rag,code_interpreter,python_executor]" pip install python-dateutil

💡 若仅需核心功能，可用最小安装：bash pip install -U qwen-agent

4.2 验证安装

运行以下命令查看是否成功导入：

from qwen_agent.agents import Assistant print("Qwen-Agent installed successfully!")

无报错即表示安装成功。

五、编写支持工具调用的AI代理程序

我们将分三步构建一个能调用“获取天气”功能的AI助手。

5.1 步骤一：定义自定义工具

创建文件weather_tool.py，注册一个名为get_current_weather的工具：

# -*- coding: utf-8 -*- from qwen_agent.tools.base import BaseTool, register_tool import json5 @register_tool('get_current_weather') class GetCurrentWeather(BaseTool): description = '获取指定城市的当前天气情况' parameters = [ { 'name': 'location', 'type': 'string', 'description': '城市名称，例如：北京、上海、广州', 'required': True } ] def call(self, params: str, **kwargs) -> str: # 解析 LLM 生成的参数 try: args = json5.loads(params) location = args.get('location', '').strip() except Exception as e: return f'参数解析失败: {str(e)}' # 模拟不同城市的天气响应 weather_data = { '广州': '目前我市多云间晴，局部有阵雨，气温29~32℃，吹轻微的东南风。', '北京': '今日晴转多云，空气质量良，气温18~25℃，适宜户外活动。', '上海': '阴天，偶有小雨，气温22~27℃，出行请带伞。', '深圳': '雷阵雨，气温28~33℃，伴有短时强降水，请注意防范。' } return weather_data.get(location, f'抱歉，暂未获取{location}的天气数据。')

⚠️ 注意事项： -@register_tool装饰器必须存在，用于被框架识别 -parameters字段需符合 OpenAPI 规范，否则无法正确生成函数调用请求 - 返回值应为字符串格式的结果，便于后续模型整合

5.2 步骤二：配置LLM连接参数

在主程序中设置模型服务地址：

llm_cfg = { 'model': '/models/Qwen2.5-7B-Instruct', # 模型标识符（任意命名） 'model_server': 'http://localhost:9000/v1', # vLLM 提供的服务端点 'api_key': 'EMPTY', # vLLM 不需要密钥 'generate_cfg': { 'top_p': 0.8, 'temperature': 0.7, 'max_tokens': 8192 } }

5.3 步骤三：构建AI代理并运行对话

完整脚本如下（保存为agent_with_weather.py）：

# -*- coding: utf-8 -*- import sys from qwen_agent.agents import Assistant from weather_tool import GetCurrentWeather # 导入自定义工具类 # LLM 配置（同上） llm_cfg = { 'model': '/models/Qwen2.5-7B-Instruct', 'model_server': 'http://localhost:9000/v1', 'api_key': 'EMPTY', 'generate_cfg': {'top_p': 0.8} } # 初始化助手代理 system_instruction = '你是一个乐于助人的AI助手，擅长使用工具获取实时信息。' tools = ['get_current_weather', 'code_interpreter'] # 注册工具名 assistant = Assistant( llm=llm_cfg, system_message=system_instruction, function_list=tools ) if __name__ == '__main__': # 用户输入 query = '今天广州天气怎么样？出门需要带伞吗？' messages = [{'role': 'user', 'content': query}] print("AI 正在思考...\n") full_response = "" for res in assistant.run(messages=messages): if len(res) == 3: content = res[2]['content'] full_response += content print(content, end='', flush=True) print("\n\n✅ 回答完成。")

六、运行结果与调用流程分析

执行命令：

python agent_with_weather.py

输出示例：

AI 正在思考... params: {"location": "广州"} 今天广州的天气是多云间晴，局部有阵雨，气温在29到32摄氏度之间，吹的是轻微的东南风。记得出门携带雨具哦！ ✅ 回答完成。

6.1 工具调用全过程拆解

整个交互过程分为三个阶段，对应三条消息流转：

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

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

📌 Qwen2.5-7B 判断用户问题是关于天气的，且需要外部数据，于是触发工具调用。

阶段2：执行本地函数并返回结果

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

🧠 Qwen-Agent 自动调用GetCurrentWeather.call()方法并将结果注入上下文。

阶段3：模型整合信息生成最终回复

{ "role": "assistant", "content": "今天广州的天气是多云间晴，局部有阵雨……记得出门携带雨具哦！" }

✅ 模型结合原始问题与工具返回内容，生成人性化、有建议性的回答。

七、常见问题与解决方案

问题	原因	解决方案
报错`ModuleNotFoundError: No module named 'qwen_agent'`	环境未激活或安装失败	确认 conda 环境激活，重新安装
模型不调用工具，直接猜测答案	工具描述不清或参数格式错误	检查`description`和`parameters`是否清晰规范
vLLM 启动失败，显存不足	FP16 加载仍超限	使用`--quantization awq`或`gptq`量化加载
工具调用后无响应	函数抛出异常未捕获	在`call()`中添加 try-except 并返回友好提示
中文乱码或编码错误	文件未声明 UTF-8 编码	添加`# -- coding: utf-8 --`头部声明

八、进阶技巧与最佳实践

8.1 支持更多工具类型

你可以轻松扩展其他工具，例如：

search_internet: 调用 SerpAPI 搜索网页
execute_sql: 连接数据库执行查询
send_email: 发送邮件通知
translate_text: 多语言翻译服务

只需继承BaseTool并注册即可。

8.2 启用代码解释器（Code Interpreter）

Qwen-Agent 内置了安全沙箱化的代码执行能力，可用于数学计算、数据分析等场景：

tools = ['code_interpreter'] messages = [ {'role': 'user', 'content': '画一个正弦函数图像，x范围是0到4π'} ]

自动生成 Python 代码并渲染图表，无需额外开发！

8.3 构建 Web 界面（Gradio GUI）

添加 GUI 支持非常简单：

from qwen_agent.gui import WebUI WebUI(assistant).run(server_port=7860)

访问http://localhost:7860即可进入图形化聊天界面。

九、总结与下一步建议

✅ 本文核心收获

成功部署了Qwen2.5-7B-Instruct + vLLM的高性能推理服务
使用Qwen-Agent框架构建了一个支持工具调用的 AI 代理
实现了自定义工具注册、调用与结果融合的完整链路
掌握了工具调用的数据结构与调试方法

🚀 下一步学习路径建议

方向	推荐动作
多工具协同	让模型同时调用天气 + 地图 API 推荐出行路线
RAG 增强	接入本地知识库，提升专业领域问答准确率
Agent 规划能力	尝试`Planner`类型代理，实现复杂任务分解
生产级部署	使用 FastAPI + Docker 封装成微服务
性能优化	对模型进行 AWQ/GPTQ 量化，降低显存占用