企业官网建设流程全解析

第一次部署 Qwen-Agent？把 llm_cfg 里 5 个字段逐项讲清，让本地模型跑起来

【免费下载链接】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

刚跑完 examples/assistant_qwen3.py，终端吐出一串 ValueError。别慌，Qwen-Agent 里这类报错九成是 llm_cfg 少填一个字段。这篇把模型部署配置拆成 5 个字段，读完能自己在本地与远程接口间切换。

🔧 先跑通，再讲道理：Qwen-Agent 的 llm_cfg 配置字段逐项说明

最快的路子是先接远程接口，不吃显卡。下面这段贴进去就能启动：

import os from qwen_agent.agents import Assistant llm_cfg = { 'model': 'qwen-plus', 'model_type': 'qwen_dashscope', 'api_key': os.getenv('DASHSCOPE_API_KEY'), } bot = Assistant(llm=llm_cfg) print(list(bot.run(messages=[{'role': 'user', 'content': '一句话介绍自己'}]))[-1])

所有后端的统一入口是get_chat_model，它按model_type查 LLM_REGISTRY 注册表（qwen_agent/llm/init.py 第 61 行）。model_type相当于接口的门牌号，决定这份配置被派给哪个后端类。上面 5 个字段逐个看：

再补一句推断规则。model_type缺省时由 llm/init.py 兜底：模型名含-vl走视觉后端（第 85 行），含qwen走 DashScope（第 95-98 行）。兜底归兜底，生产配置还是建议显式写model_type，别让请求靠字符串匹配被派路。

换个场景，配置怎么动：本地模型路径 vs 远程 API 接口

场景 A：本地跑模型。只动 3 个字段：

- 'model': 'qwen-plus', - 'model_type': 'qwen_dashscope', - 'api_key': os.getenv('DASHSCOPE_API_KEY'), + 'model': './models/Qwen3-4B', + 'model_type': 'transformers', + 'device': 'cuda',

model变成本地目录后，transformers 后端用AutoConfig.from_pretrained从该目录加载（transformers_llm.py 第 54 行）。这里有个坑：切到本地模型时，api_key那行记得删掉，本地加载用不上这个字段。跑之前先验证目录，能打印出 architectures 列表说明目录可用：

python -c "from transformers import AutoConfig; print(AutoConfig.from_pretrained('./models/Qwen3-4B').architectures)"

还有一处联动：transformers 后端读device用的是cfg.get('device', 'cpu')（第 71 行），不写就落在 CPU 上。4B 的模型在 CPU 上慢，但至少不会炸。

场景 B：自部署 vLLM，走 OAI 兼容接口。这个场景下model_type可以省：

- 'model_type': 'qwen_dashscope', - 'api_key': os.getenv('DASHSCOPE_API_KEY'), + 'model': 'Qwen3-32B', + 'model_server': 'http://localhost:8000/v1', + 'api_key': 'EMPTY',

model_server以 http 开头时，llm/init.py 第 77-81 行会自动派给 oai 后端，路由字段不用手写。先验证服务：curl http://localhost:8000/v1/models能列出模型再接线。服务若要鉴权，把'EMPTY'换成真实 key；不写api_key时 oai 后端会回退读OPENAI_API_KEY环境变量（oai.py 第 50 行）。

🚨 报错了，按这个顺序查

别急着改，先看这一行：错误从哪一层抛出来，再定位对应字段。下面 3 行按出现频率排，从上往下查：

实在对不上号，就从model_type和model_server这一对查起。这俩是联动关系，改一不改正，请求就会走到错误的门。

跑通之后：Qwen-Agent 的进阶路径

裸聊跑通后，剩下的都是配置的变体。已经跑通的话，可以试试：

• 给助手挂上工具：看 examples/assistant_qwen3.py 第 64-78 行的tools列表，MCP 服务与 code_interpreter 的写法都在里面。
• 摸清全部模型后端：qwen_agent/llm/ 目录下每个文件一个后端，看@register_llm的装饰器名就是可用的model_type。
• 验证 API 连通性：直接运行 tests/llm/ 下的 test_dashscope.py、test_oai.py，比手写脚本快。

【免费下载链接】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