Qwen-Agent 本地部署教程：Transformers 加载模型并完成首次对话

Qwen-Agent 本地部署教程：Transformers 加载模型并完成首次对话

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent

本教程演示在 Qwen-Agent 中用 transformers 加载本地 Qwen 模型并完成首次对话。内容覆盖环境安装、完整配置、文本/视觉模型切换与常见报错处理，面向具备基础 Python 能力的读者，无需 GPU 也能按步骤跑通。

开始前：环境检查清单

• Python 环境：普通部署需 Python 3.9+；若还要使用 Gradio 图形界面，README 要求 Python 3.10+（GUI 非本教程必需）。
• 框架本体：安装 PyPI 上的qwen-agent，按需勾选可选组件：

# [rag] 文档检索 / [code_interpreter] 代码执行 / [mcp] 模型上下文协议 pip install -U "qwen-agent[rag,code_interpreter,mcp]"

• 模型加载库：本教程走 transformers 路线，需额外安装：

pip install -U transformers torch

提示：若只想调用托管服务，可跳过模型下载，参考「切换不同场景」第 3 行。

• 模型获取：两种方式任选。已下载的模型直接填入本地文件夹路径；未下载的可用官方 CLI 提前拉到本地：

huggingface-cli download Qwen/Qwen3-4B --local-dir ./models/Qwen3-4B

• 必须知道的核心概念：传给 Agent 的llm_cfg就是一个普通字典，用来声明"用哪个模型、从哪加载、跑在什么设备上"；其中model字段（模型名或本地路径）是 transformers 路线的必填项，其余可按需省略。

首次运行的完整配置

下面这段代码可直接保存为.py文件运行，跑通"加载本地模型 → 提问 → 流式打印回答"的完整链路：

import torch from qwen_agent.agents import Assistant # 通用 Agent，内置工具调用与文档检索 # 模型配置：model 填 Hugging Face 模型名或已下载的本地目录 llm_cfg = { 'model': './models/Qwen3-4B', 'model_type': 'transformers', # 使用本地 transformers 库加载 'device': 'cuda' if torch.cuda.is_available() else 'cpu', } bot = Assistant(llm=llm_cfg, name='Local Assistant') messages = [{'role': 'user', 'content': '用一句话介绍你自己'}] for chunk in bot.run(messages=messages): # 流式输出 print(chunk, end='', flush=True)

关键行说明：

• 'model_type': 'transformers'：决定由哪个加载器处理模型。该值对应注册在 transformers_llm.py 中的Transformers类，它会读取模型的 Hugging Face 配置，自动判断是纯文本模型还是视觉模型，再把权重加载到指定设备。
• 'device'：指定张量运行设备。缺省时默认'cpu'（见源码中.to(cfg.get('device', 'cpu'))），4B 参数模型在 CPU 上可以对话，只是速度慢。
• bot.run(messages=messages)：输入为消息列表（role/content结构），返回生成器，逐块产出回答，方便打字机式打印。

提示：首次运行会从缓存目录加载权重并初始化 tokenizer，耗时取决于硬件，属正常现象。

切换不同场景：三种用法的配置差异

同一套代码框架下，切换场景通常只改llm_cfg的几个字段。

场景 1：本地视觉模型—— 只改model一行，其余不变：

llm_cfg = {'model': 'Qwen/Qwen3-VL-4B', 'model_type': 'transformers', 'device': 'cuda'}

原理：Transformers加载 processor 时若发现不是纯 tokenizer，就自动开启多模态输入能力，无需手动声明。

场景 2：接入已部署的 OpenAI 兼容服务：

llm_cfg = { 'model': 'Qwen3-8B', # 服务侧部署的模型名 'model_server': 'http://localhost:8000/v1', 'api_key': 'EMPTY', # 本地服务可填 EMPTY，或用 OPENAI_API_KEY 环境变量 }

提示：不写model_type时框架默认走 OpenAI 兼容接口（oai），api_key也可改由环境变量提供。更多组合见 examples/ 下的assistant_qwen3.py、assistant_qwen3vl.py。

排障：现象 → 原因 → 处理

延伸阅读

• examples/：可运行的完整示例，含工具调用、MCP、浏览器助手等
• qwen_agent/llm/：各 LLM 后端实现，base.py定义了统一的chat接口
• qwen_agent/agents/assistant.py：Assistant 的实现，展示 RAG 知识如何拼入提示词
• qwen_agent/tools/：内置工具集合，function_list可直接引用其中注册名

把llm_cfg中的model、model_type、device三处按硬件与模型类型填对，Assistant 就能完成加载与对话，后续扩展工具、RAG 都基于同一个字典继续叠加。

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent