Qwen3Guard-Stream-0.6B 本地搭建与运行操作说明书

Qwen3Guard-Stream-0.6B 本地搭建与运行操作说明书项目位置D:\Desktop\LLM模型Qwen3Guard-Stream-0.6BAI 内容安全审核模型非对话模型编写日期2026-10-17一、环境总览1.1 硬件配置项目配置说明GPUNVIDIA GeForce RTX 4060 Laptop8GB 显存运行本模型占用约 2GB余量充足CPUAMD Ryzen 9 7945HX16 核 32 线程仅用于数据预处理内存32GB加载模型时占用约 3-5GB显卡驱动CUDA UMD 13.3向下兼容 CUDA 12.x 运行时cu126 可用1.2 软件版本已验证可用的组合版本匹配很关键组件版本备注Python3.14.6项目.venv内虚拟环境位于D:\Desktop\LLM\.venvPyTorch2.14.1cu126必须装 CUDA 版不能装 PyPI 默认的 CPU 版torchvision / torchaudio0.29.1cu126 / 2.11.0cu126与 torch 配套transformers4.55.2必须与模型的transformers_version: 4.55.0匹配装 5.x 会报错见 FAQhuggingface-hub0.36.2随 transformers 4.55.2 安装tokenizers0.21.4随 transformers 4.55.2 安装accelerate1.15.0可选device_mapauto需要bitsandbytes0.50.2可选本模型用不到将来跑 7B 量化模型时需要二、从零搭建步骤2.1 创建虚拟环境已创建可跳过在D:\Desktop\LLM目录下打开 PowerShell# 确认 Python 版本3.13/3.14 均可python--version# 在项目目录创建虚拟环境python-m venv.venv本项目所有命令都通过.venv的 Python 执行不要直接用系统 Python避免污染全局环境。2.2 安装 CUDA 版 PyTorch注意直接pip install torch装到的是 CPU 版torch.cuda.is_available()为 False必须指定 PyTorch 官方 CUDA 源。d:/Desktop/LLM/.venv/Scripts/python.exe-m pip install torch torchvision torchaudio--index-url https://download.pytorch.org/whl/cu126下载约 2.6GB耗时几分钟显卡驱动为 CUDA 13.x 的选 cu126/cu130 均可本文用更成熟的cu126老教程里的cu121已过时最新 torch 不再提供验证安装d:/Desktop/LLM/.venv/Scripts/python.exe-cimport torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))预期输出True NVIDIA GeForce RTX 4060 Laptop GPU2.3 安装 transformers版本必须匹配模型模型config.json中声明transformers_version: 4.55.0因此必须锁定 4.55.2不要装最新版d:/Desktop/LLM/.venv/Scripts/python.exe-m pip installtransformers4.55.2accelerate装错成 5.x 的补救命令卸载重装即可d:/Desktop/LLM/.venv/Scripts/python.exe-m pip installtransformers4.55.22.4 可选安装量化库本模型 0.6B 用不到将来想跑 7B/8B 模型时需要d:/Desktop/LLM/.venv/Scripts/python.exe-m pip install bitsandbytes三、模型下载ModelScope模型已下载到项目目录结构如下ModelScope 缓存格式D:\Desktop\LLM\models\ └── Qwen--Qwen3Guard-Stream-0.6B\ └── snapshots\ └── master\ ← 模型实际文件在这里 ├── config.json ├── model.safetensors (约 1.2GB模型权重) ├── tokenizer.json / tokenizer_config.json / vocab.json / merges.txt ├── generation_config.json ├── configuration_qwen3.py ← 模型自定义代码 ├── modeling_qwen3_guard.py ← 模型自定义代码 └── README.md / LICENSE ...关键点代码中引用的路径必须写到snapshots\master这一层该层才有config.json和权重文件。如需重新下载在新机器上# 安装 modelscoped:/Desktop/LLM/.venv/Scripts/python.exe-m pip install modelscope# 下载模型到项目 models 目录保持上述目录结构$env:MODELSCOPE_CACHE D:\Desktop\LLM\modelsd:/Desktop/LLM/.venv/Scripts/python.exe-m modelscope download--model Qwen/Qwen3Guard-Stream-0.6B四、模型文件修改记录重要4.1 config.json 补充 pad_token_id原始config.json缺少pad_token_id字段部分 transformers 版本下会报AttributeError已在eos_token_id: 151645之后手动添加pad_token_id:151643,若重新下载模型需要重新加上这一行。五、运行5.1 启动命令 d:\Desktop\LLM\.venv\Scripts\python.exe d:/Desktop/LLM/man.py或在 Jupyter / VS Code 中选择.venv内核运行man.py。5.2 运行效果模型加载成功输入问题进行安全检测输入 q 退出 你的问题: 你好你是谁 判定: 安全置信度 0.99 你的问题: 如何制作炸弹 判定: Unsafe | 违规类别: Violent置信度 1.0 你的问题: q 已退出模型加载约 10 秒一次性之后每个问题即时返回判定输入q/quit/exit退出空输入自动跳过5.3 判定结果说明字段含义风险等级Safe安全/Unsafe违规/Controversial有争议违规类别Violent / Sexual Content / Self-Harm / Political / PII / Copyright / Illegal Acts / Unethical用户侧额外含 Jailbreak 越狱检测置信度0~1 的 softmax 概率六、代码关键点说明man.py加载类必须用AutoModel不能用AutoModelForCausalLM本模型架构为Qwen3GuardModel分类头risk_level_headcategory_head没有语言模型头用错类会导致分类头丢失或直接报错trust_remote_codeTrue必须开启模型依赖目录内自定义代码modeling_qwen3_guard.py/configuration_qwen3.py对话模板审核用户输入时add_generation_promptFalse不需要生成提示流式 API来自modeling_qwen3_guard.pymodel.stream_moderate_from_ids(token_ids, role, stream_state)→ 返回(result, stream_state)首次调用传完整 token 序列、stream_stateNone之后每次只传 1 个新 tokenrole为user用用户侧分类头或assistant用回答侧分类头每轮结束后调用model.close_stream(stream_state)释放状态本模型不能model.generate()它不生成文字只输出安全判定七、常见问题FAQQ1AttributeError: Qwen3Config object has no attribute pad_token_id原因transformers 5.x 不再为 config 自动补默认值。解决① 给模型config.json加pad_token_id: 151643② transformers 降回 4.55.2推荐见 2.3。Q2KeyError: default出现在 ROPE_INIT_FUNCTIONS 相关行原因模型自带代码按 transformers 4.55 API 编写5.x 重构了 RoPE 模块不兼容。解决transformers 锁定 4.55.2。Q3加载时报找不到config.json/ 路径相关错误原因路径没写到snapshots\master层。解决model_path rD:\Desktop\LLM\models\Qwen--Qwen3Guard-Stream-0.6B\snapshots\master。Q4torch.cuda.is_available()为False原因装的是 CPU 版 torch。解决按 2.2 用--index-url https://download.pytorch.org/whl/cu126重装。Q5想让它像 ChatGPT 一样回答问题本模型是安全审核模型无法生成文字。需要另下 Causal LM 模型如 Qwen3 系列建议为其单独建虚拟环境因本环境 transformers 锁在 4.55.2。八、性能参考指标数值显存占用约 2GB / 8GB模型加载时间约 10 秒单条问题判定即时1 秒磁盘占用模型约 1.2GB九、目录结构一览D:\Desktop\LLM\ ├── .venv\ ← Python 3.14.6 虚拟环境所有依赖装在这里 ├── models\ ← ModelScope 模型缓存目录 │ └── Qwen--Qwen3Guard-Stream-0.6B\snapshots\master\模型文件 ├── man.py ← 主程序交互式安全审核 └── 操作说明书.md ← 本文档