尧图网站建设 
Qwen-Agent 本地部署模型教程模型ID配置与最小配置完全指南【免费下载链接】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 助手Qwen-Agent 是个顺手的选择——它是基于 Qwen 3.0 的开源智能体框架内置工具调用、RAG、代码解释器等能力。本地部署时最容易卡住的环节是模型ID配置写在哪个字段、本地路径怎么写、选多大的模型。本文按跑通 → 拆解 → 选型 → 排障的顺序展开三个配置项就能把一个模型接进 Qwen-Agent。三步跑通把本地模型接进助手先不纠结细节直接走一遍最短路径写配置、初始化、验证。第一步准备配置字典。本地部署用 transformers 加载器时最小配置就三个字段llm_cfg { model: Qwen/Qwen3-4B, # 模型IDHF 名称或本地目录路径 model_type: transformers, # 声明用 transformers 本地加载 device: cuda, # 没有 GPU 就写 cpu }第二步把配置传给Assistant的llm参数初始化时就完成了模型加载from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg)第三步发一句话验证。能收到正常回复说明模型ID和设备都没问题messages [{role: user, content: 你好请介绍一下自己}] print(list(bot.run(messagesmessages))[-1])注意device不写时代码里默认落到cpu见qwen_agent/llm/transformers_llm.py第 71 行的cfg.get(device, cpu)首次加载大模型在 CPU 上会非常慢有 NVIDIA 显卡建议显式写cuda。模型ID配置入口三个配置项各管什么配置最终由 LLM 配置模块qwen_agent/llm/transformers_llm.py消费逐字段说明如下。model模型ID与本地模型路径怎么写model是唯一的必填项。源码开头就有硬性校验第 43–44 行if model not in cfg: raise ValueError(Please provide the model id or directory through model in cfg.)漏写model不会静默失败而是直接抛ValueError报错信息本身也告诉你了该填什么。model的值有两种合法写法Hugging Face 模型名形如Qwen/Qwen3-4Borg/仓库名的形式。首次运行时框架会通过AutoConfig.from_pretrained自动拉取权重之后有缓存。本地目录路径模型文件夹的相对或绝对路径如./models/Qwen3-4B。目录里需要包含config.json、权重文件等完整内容用huggingface-cli或 ModelScope 下载后得到的目录即可。本地路径常见错误是写成了权重文件名如model.safetensors而不是目录或者路径层级差了一层导致找不到config.json——排查时先确认os.listdir能看到config.json。model_type声明模型加载器model_type决定配置交给哪个加载器处理。本地部署固定写transformers对应源码文件顶部的register_llm(transformers)注册装饰器。它和qwen_dashscope云端 API 调用等其它取值互斥选错会走完全不同的加载分支。device模型跑在哪个设备上device取值cpu/cudaApple 芯片用mps决定权重加载后放在哪块硬件上。4B 级模型在 8GB 显存的显卡上可以全精度跑7B 及以上更稳妥的做法是配合量化加载见后面排障部分。另外不用手动声明这是文本模型还是多模态模型加载时框架会尝试用AutoProcessor读取处理器如果读出来的是纯 tokenizer 就按纯文本处理否则会开启多模态输入支持源码中的日志会打印Regarding the transformers model as text-only...这类提示可以据此确认识别结果是否符合预期。按任务选模型纯文本还是多模态选型的判断标准只有一个你的任务里要不要看图。你要做什么推荐模型ID仓库内参考示例对话、写作、文档问答等纯文本任务Qwen/Qwen3-4B、Qwen/Qwen3-7Bexamples/assistant_qwen3.py图片理解、视觉问答等多模态任务Qwen/Qwen3-VL-4B、Qwen/Qwen3-VL-7Bexamples/assistant_qwen3vl.py纯文本场景下4B 和 7B 的区别主要在响应速度和复杂推理质量显存宽裕就选 7B。文档问答类任务的运行效果大致如此一旦任务涉及图片输入例如看看这张截图里是什么内容就需要换成 VL 系列模型。此时llm_cfg只需把model换成 VL 模型ID多模态能力由框架自动检测启用参考示例 examples/assistant_qwen3vl.py两个示例文件里还展示了function_list工具的接法跑通最小配置后可以直接在上面加代码解释器、联网搜索等能力。排障手册按报错现象对照模型下载慢怎么办本地网络拉取 HF 权重慢时把下载和运行拆开先在网络条件好的时机用 Hugging Face CLI 下载完整目录再让配置指向本地路径。huggingface-cli download Qwen/Qwen3-4B --local-dir ./models/Qwen3-4Bllm_cfg { model: ./models/Qwen3-4B, model_type: transformers, device: cuda, }之后加载走本地磁盘不再受网络影响离线环境也能运行。显存不足怎么办加载时报CUDA out of memory第一选择是 4 位量化transformers 加载参数支持load_in_4bitTrue需安装bitsandbytes把权重压到 4bit 后显存占用大约减半4B/7B 模型在 8GB 显存上基本能跑起来。如果还紧张按顺序尝试换更小的模型7B → 4B、缩短max_new_tokens限制生成长度、改用devicecpu只适合验证流程速度会明显变慢。模型ID写法不对会报什么错两类报错对号入座ValueError: Please provide the model id or directory throughmodelin cfg.—— 配置里漏写了model字段按前文最小配置补上即可。transformers抛出的模型/仓库找不到错误如ConnectionError、repo id not found一类——model写成了 HF 不存在的名称或本地路径指向了错误的目录。前者核对org/模型名拼写区分大小写后者用ls确认目录下有config.json。接下来可以做什么到这里配置 → 初始化 → 验证的完整链路已经走通三个字段定一个模型一句对话验一次部署。后续可以按需求推进在llm_cfg中调整max_new_tokens等生成参数控制回答长度与速度参考 examples/ 目录里的工具调用示例通过function_list给助手挂上代码解释器、搜索等能力显存允许时换更大的模型或按排障手册里的量化方案让 7B 模型跑进 8GB 显卡。【免费下载链接】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），仅供参考 Qwen-Agent 本地部署模型教程：模型ID配置与最小配置完全指南
Qwen-Agent 本地部署模型教程模型ID配置与最小配置完全指南【免费下载链接】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 助手Qwen-Agent 是个顺手的选择——它是基于 Qwen 3.0 的开源智能体框架内置工具调用、RAG、代码解释器等能力。本地部署时最容易卡住的环节是模型ID配置写在哪个字段、本地路径怎么写、选多大的模型。本文按跑通 → 拆解 → 选型 → 排障的顺序展开三个配置项就能把一个模型接进 Qwen-Agent。三步跑通把本地模型接进助手先不纠结细节直接走一遍最短路径写配置、初始化、验证。第一步准备配置字典。本地部署用 transformers 加载器时最小配置就三个字段llm_cfg { model: Qwen/Qwen3-4B, # 模型IDHF 名称或本地目录路径 model_type: transformers, # 声明用 transformers 本地加载 device: cuda, # 没有 GPU 就写 cpu }第二步把配置传给Assistant的llm参数初始化时就完成了模型加载from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg)第三步发一句话验证。能收到正常回复说明模型ID和设备都没问题messages [{role: user, content: 你好请介绍一下自己}] print(list(bot.run(messagesmessages))[-1])注意device不写时代码里默认落到cpu见qwen_agent/llm/transformers_llm.py第 71 行的cfg.get(device, cpu)首次加载大模型在 CPU 上会非常慢有 NVIDIA 显卡建议显式写cuda。模型ID配置入口三个配置项各管什么配置最终由 LLM 配置模块qwen_agent/llm/transformers_llm.py消费逐字段说明如下。model模型ID与本地模型路径怎么写model是唯一的必填项。源码开头就有硬性校验第 43–44 行if model not in cfg: raise ValueError(Please provide the model id or directory through model in cfg.)漏写model不会静默失败而是直接抛ValueError报错信息本身也告诉你了该填什么。model的值有两种合法写法Hugging Face 模型名形如Qwen/Qwen3-4Borg/仓库名的形式。首次运行时框架会通过AutoConfig.from_pretrained自动拉取权重之后有缓存。本地目录路径模型文件夹的相对或绝对路径如./models/Qwen3-4B。目录里需要包含config.json、权重文件等完整内容用huggingface-cli或 ModelScope 下载后得到的目录即可。本地路径常见错误是写成了权重文件名如model.safetensors而不是目录或者路径层级差了一层导致找不到config.json——排查时先确认os.listdir能看到config.json。model_type声明模型加载器model_type决定配置交给哪个加载器处理。本地部署固定写transformers对应源码文件顶部的register_llm(transformers)注册装饰器。它和qwen_dashscope云端 API 调用等其它取值互斥选错会走完全不同的加载分支。device模型跑在哪个设备上device取值cpu/cudaApple 芯片用mps决定权重加载后放在哪块硬件上。4B 级模型在 8GB 显存的显卡上可以全精度跑7B 及以上更稳妥的做法是配合量化加载见后面排障部分。另外不用手动声明这是文本模型还是多模态模型加载时框架会尝试用AutoProcessor读取处理器如果读出来的是纯 tokenizer 就按纯文本处理否则会开启多模态输入支持源码中的日志会打印Regarding the transformers model as text-only...这类提示可以据此确认识别结果是否符合预期。按任务选模型纯文本还是多模态选型的判断标准只有一个你的任务里要不要看图。你要做什么推荐模型ID仓库内参考示例对话、写作、文档问答等纯文本任务Qwen/Qwen3-4B、Qwen/Qwen3-7Bexamples/assistant_qwen3.py图片理解、视觉问答等多模态任务Qwen/Qwen3-VL-4B、Qwen/Qwen3-VL-7Bexamples/assistant_qwen3vl.py纯文本场景下4B 和 7B 的区别主要在响应速度和复杂推理质量显存宽裕就选 7B。文档问答类任务的运行效果大致如此一旦任务涉及图片输入例如看看这张截图里是什么内容就需要换成 VL 系列模型。此时llm_cfg只需把model换成 VL 模型ID多模态能力由框架自动检测启用参考示例 examples/assistant_qwen3vl.py两个示例文件里还展示了function_list工具的接法跑通最小配置后可以直接在上面加代码解释器、联网搜索等能力。排障手册按报错现象对照模型下载慢怎么办本地网络拉取 HF 权重慢时把下载和运行拆开先在网络条件好的时机用 Hugging Face CLI 下载完整目录再让配置指向本地路径。huggingface-cli download Qwen/Qwen3-4B --local-dir ./models/Qwen3-4Bllm_cfg { model: ./models/Qwen3-4B, model_type: transformers, device: cuda, }之后加载走本地磁盘不再受网络影响离线环境也能运行。显存不足怎么办加载时报CUDA out of memory第一选择是 4 位量化transformers 加载参数支持load_in_4bitTrue需安装bitsandbytes把权重压到 4bit 后显存占用大约减半4B/7B 模型在 8GB 显存上基本能跑起来。如果还紧张按顺序尝试换更小的模型7B → 4B、缩短max_new_tokens限制生成长度、改用devicecpu只适合验证流程速度会明显变慢。模型ID写法不对会报什么错两类报错对号入座ValueError: Please provide the model id or directory throughmodelin cfg.—— 配置里漏写了model字段按前文最小配置补上即可。transformers抛出的模型/仓库找不到错误如ConnectionError、repo id not found一类——model写成了 HF 不存在的名称或本地路径指向了错误的目录。前者核对org/模型名拼写区分大小写后者用ls确认目录下有config.json。接下来可以做什么到这里配置 → 初始化 → 验证的完整链路已经走通三个字段定一个模型一句对话验一次部署。后续可以按需求推进在llm_cfg中调整max_new_tokens等生成参数控制回答长度与速度参考 examples/ 目录里的工具调用示例通过function_list给助手挂上代码解释器、搜索等能力显存允许时换更大的模型或按排障手册里的量化方案让 7B 模型跑进 8GB 显卡。【免费下载链接】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），仅供参考