Qwen-Agent 模型部署与模型 ID 配置1 个字段、2 种写法、3 处排查点【免费下载链接】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 仓库想跑通第一个对话。这次 Qwen-Agent 模型部署的胜负手就在模型 ID 配置——配置字典里那个model字段填 HuggingFace 模型名会自动下载填本地目录路径则直接加载。漏配或配错Transformers 后端会在初始化时直接抛ValueError权重都轮不到下载路径层级写偏则是在 AutoConfig 加载阶段报出难读的 file-not-found。本文围绕这 1 个字段讲清本地模型加载的全过程。先看见能跑的样子最小可跑配置先跑最短的代码建立成功长什么样的锚点from qwen_agent.agents import Assistant llm_cfg { model: Qwen/Qwen3-4B, model_type: transformers, device: cuda, } bot Assistant(llmllm_cfg) for response in bot.run([{role: user, content: 介绍一下你自己}]): print(response)终端能打印出完整自我介绍说明模型 ID 配置、权重加载、推理链路全部走通。文本版完整示例见 examples/ 目录下图是模型接上代码执行工具后的实际运行效果配置从哪里来model 字段的校验逻辑model为什么必填直接看源码。核心校验逻辑在 qwen_agent/llm/transformers_llm.pyTransformers 后端在__init__开头就拦截if model not in cfg: raise ValueError(Please provide the model id or directory through model in cfg.)它是整条加载链路的入口AutoConfig、AutoProcessor、模型权重全部从这个值读取。缺了它Qwen-Agent 本地模型加载在第一步就断链后续所有对话与工具调用无从谈起。两种写法各有适用时机HuggingFace 模型名如Qwen/Qwen3-4B首次运行自动下载并缓存适合首次上手本地目录路径如./models/Qwen3-4B直接从磁盘加载适合离线环境或下载速度受限的场景。另有一条容易忽略的机制后端不靠你声明文本还是多模态而是看模型自带的 processor 是什么——加载出纯 tokenizer 就按文本模型处理拿到真正的多模态 processor 就自动启用视觉输入多模态模型配置不需要额外字段。换场景就换这一行多模态模型配置示例文本与多模态两种场景的配置差异只有model取值一处llm_cfg { model: Qwen/Qwen2.5-VL-7B-Instruct, model_type: transformers, device: cuda, }调用侧的消息内容从字符串变成列表混入一个image项即可messages [{role: user, content: [{image: pic.png}, {text: 图里是什么}]}]官方对照示例examples/assistant_qwen3.py文本与 examples/assistant_qwen3vl.py视觉默认还挂了image_zoom_in_tool缩放工具。跑不通时先查这三处下载、显存、路径按出现频率排好的排查清单下载不完整或路径写偏报错提到config.json或 not found 时先ls ./models/Qwen3-4B确认目录里有config.json和权重文件路径末尾不要多斜杠。显存不足加载阶段CUDA out of memory说明模型规格超过显存。当前 Transformers 后端没有暴露量化开关正解是换小一号的模型或走预量化的 OpenVINO 后端导出方式见 qwen_agent/llm/openvino.py 的注释。设备写法错误device支持cpu/cuda/mps没有 GPU 时不要硬编码cuda。下载太慢可用官方 CLI 提前拉取再把本地路径填进modelhuggingface-cli download Qwen/Qwen3-4B --local-dir ./models/Qwen3-4B继续往下挖三个进阶入口调参用generate_cfg子字典控制max_new_tokens后端默认 2048生成长度、随机种子都在这里调接工具Function Calling 与 MCP 的完整用法在 examples/ 目录这是把单模型助手变成能干活的 Agent 的关键一步换模型参考 HuggingFace 上 Qwen 官方模型列表替换 Transformers 模型配置里的model值即可其余字段不用动。【免费下载链接】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），仅供参考