Qwen-Agent 本地部署教程Transformers 加载模型并完成首次对话【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.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.10GUI 非本教程必需。框架本体安装 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(llmllm_cfg, nameLocal Assistant) messages [{role: user, content: 用一句话介绍你自己}] for chunk in bot.run(messagesmessages): # 流式输出 print(chunk, end, flushTrue)关键行说明model_type: transformers决定由哪个加载器处理模型。该值对应注册在 transformers_llm.py 中的Transformers类它会读取模型的 Hugging Face 配置自动判断是纯文本模型还是视觉模型再把权重加载到指定设备。device指定张量运行设备。缺省时默认cpu见源码中.to(cfg.get(device, cpu))4B 参数模型在 CPU 上可以对话只是速度慢。bot.run(messagesmessages)输入为消息列表role/content结构返回生成器逐块产出回答方便打字机式打印。提示首次运行会从缓存目录加载权重并初始化 tokenizer耗时取决于硬件属正常现象。切换不同场景三种用法的配置差异同一套代码框架下切换场景通常只改llm_cfg的几个字段。场景model_type需要填写的字段说明本地纯文本模型transformersmodel、device进程内加载权重无需服务本地视觉模型transformersmodel、device换 VL 模型即可加载器自动启用视觉输入OpenAI 兼容服务vLLM/Ollama 等省略model、model_server、api_key由外部服务承载模型客户端轻量场景 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 兼容接口oaiapi_key也可改由环境变量提供。更多组合见 examples/ 下的assistant_qwen3.py、assistant_qwen3vl.py。排障现象 → 原因 → 处理现象原因处理ValueError: Please provide the model id or directory through model in cfg.llm_cfg缺少model字段补上model填模型名或本地目录路径ImportError: Could not import classes from transformers...未安装 transformers 库执行pip install -U transformers配置加载阶段直接报错model指向的本地目录不存在或不是完整模型目录缺 config 等文件核对路径未下载完的模型用huggingface-cli download补全后再试⚠️ CUDA OOM / 内存不足模型权重与中间张量超出设备显存把device改为cpu或换小参数模型大模型建议改用 vLLM/SGLang 起服务走场景 2回答含工具调用文本但工具未执行服务端启用了原生工具解析与框架内置解析冲突Qwen3 系列按 README 建议不要加--enable-auto-tool-choice、--tool-call-parser hermes由框架自行解析延伸阅读examples/可运行的完整示例含工具调用、MCP、浏览器助手等qwen_agent/llm/各 LLM 后端实现base.py定义了统一的chat接口qwen_agent/agents/assistant.pyAssistant 的实现展示 RAG 知识如何拼入提示词qwen_agent/tools/内置工具集合function_list可直接引用其中注册名把llm_cfg中的model、model_type、device三处按硬件与模型类型填对Assistant 就能完成加载与对话后续扩展工具、RAG 都基于同一个字典继续叠加。【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考