企业官网建设流程全解析

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

项目位置：D:\Desktop\LLM
模型：Qwen3Guard-Stream-0.6B（AI 内容安全审核模型，非对话模型）
编写日期：2026-10-17

一、环境总览

1.1 硬件配置

1.2 软件版本（已验证可用的组合，版本匹配很关键）

二、从零搭建步骤

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-c"import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

预期输出：

True NVIDIA GeForce RTX 4060 Laptop GPU

2.3 安装 transformers（版本必须匹配模型）

模型config.json中声明transformers_version: 4.55.0，因此必须锁定 4.55.2，不要装最新版：

d:/Desktop/LLM/.venv/Scripts/python.exe-m pip install"transformers==4.55.2"accelerate

装错成 5.x 的补救命令（卸载重装即可）：

d:/Desktop/LLM/.venv/Scripts/python.exe-m pip install"transformers==4.55.2"

2.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\models"d:/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 判定结果说明

六、代码关键点说明（man.py）

1. 加载类必须用AutoModel，不能用AutoModelForCausalLM

   • 本模型架构为Qwen3GuardModel（分类头：risk_level_head+category_head），没有语言模型头
   • 用错类会导致分类头丢失或直接报错

2. trust_remote_code=True必须开启

   • 模型依赖目录内自定义代码modeling_qwen3_guard.py/configuration_qwen3.py

3. 对话模板：审核用户输入时add_generation_prompt=False（不需要生成提示）

4. 流式 API（来自modeling_qwen3_guard.py）：

   • model.stream_moderate_from_ids(token_ids, role, stream_state)→ 返回(result, stream_state)
   • 首次调用传完整 token 序列、stream_state=None；之后每次只传 1 个新 token
   • role为"user"（用用户侧分类头）或"assistant"（用回答侧分类头）
   • 每轮结束后调用model.close_stream(stream_state)释放状态

5. 本模型不能model.generate()：它不生成文字，只输出安全判定

七、常见问题（FAQ）

Q1：AttributeError: 'Qwen3Config' object has no attribute 'pad_token_id'

原因：transformers 5.x 不再为 config 自动补默认值。
解决：① 给模型config.json加"pad_token_id": 151643；② transformers 降回 4.55.2（推荐，见 2.3）。

Q2：KeyError: 'default'（出现在 ROPE_INIT_FUNCTIONS 相关行）

原因：模型自带代码按 transformers 4.55 API 编写，5.x 重构了 RoPE 模块，不兼容。
解决：transformers 锁定 4.55.2。

Q3：加载时报找不到config.json/ 路径相关错误

原因：路径没写到snapshots\master层。
解决：model_path = r"D:\Desktop\LLM\models\Qwen--Qwen3Guard-Stream-0.6B\snapshots\master"。

Q4：torch.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）。

八、性能参考

九、目录结构一览

D:\Desktop\LLM\ ├── .venv\ ← Python 3.14.6 虚拟环境（所有依赖装在这里） ├── models\ ← ModelScope 模型缓存目录 │ └── Qwen--Qwen3Guard-Stream-0.6B\snapshots\master\（模型文件） ├── man.py ← 主程序（交互式安全审核） └── 操作说明书.md ← 本文档