model card

README.md

@@ -0,0 +1,173 @@
+---
+license: other
+license_name: encoder-guard-non-commercial-1.0
+license_link: https://huggingface.co/louivis/encoder-guard-int8/blob/main/LICENSE
+base_model: Qwen/Qwen3Guard-Stream-0.6B
+library_name: verdict
+pipeline_tag: text-classification
+language:
+  - zh
+  - en
+tags:
+  - content-moderation
+  - safety
+  - text-classification
+  - encoder
+  - qwen3
+  - bidirectional
+  - tc260
+  - pii
+  - int8
+  - quantized
+---
+
+# Encoder-Guard v3 int8（int8 量化版）
+
+[louivis/encoder-guard](https://huggingface.co/louivis/encoder-guard)（v3，fp16）的 **int8 量化版本**：
+backbone 权重量化为对称 per-row int8（体积 1.1 GB → **0.57 GB**），11 个分类头与阈值与 v3 **逐字节相同**
+（`heads.safetensors`、`threshold.json` 的 sha256 与 v3 一致）。
+
+> ⚠️ **这是分类器，不是 chat 模型。** 不支持 Ollama / vLLM / llama.cpp 的 chat 或 generate 接口，
+> 也不产出自然语言。请用 [verdict](https://github.com/vislee/verdict) 引擎或自行实现前向。
+
+## 与 v3（fp16）的差异
+
+| | v3（fp16 包） | **int8 包（本版本）** |
+|---|---|---|
+| backbone 精度 | fp16 | **int8（对称 per-row 量化）** |
+| `backbone/model.safetensors` 体积 | 1.1 GB | **0.57 GB**（−48%） |
+| 分类头 / 阈值 | — | **与 v3 逐字节相同**（sha256 一致） |
+| 推理内存（t8 负载 RSS） | 3.37 GB | **1.37 GB（−59%）**，W8A8 实验路径约 0.8 GB |
+| CPU 延迟（M4 Max，t8） | 19.9 ms | **19.0 ms（hybrid 默认）**；W8A8 实验路径 9.4 ms |
+| Metal | — | 与 fp16 持平（F16-adopt 通路） |
+
+## 引擎加载方式（verdict）
+
+verdict 引擎加载 int8 包时默认走 **i8→F16 arena 混合（hybrid）**：加载期 int8 → F16 反量化 arena
+（0.88 GB），复用既有 fp16 计算内核；embed 走查表精确反量化；T>24 时才惰性构建 F32 arena。
+
+数值与判定面（verdict 引擎验证）：
+
+- 逐层差分（diff-check）：反量化路径 max|Δ| ≤ 1e-4；**hybrid 全 29 层 Δ/rms ≤ 6.4e-3**（门禁 1e-2）。
+- 判定面门禁（stream 300 条，hybrid vs 反量化基准）：**全头 0 翻转**（safety logit |Δ| mean 2.3e-4 / max 1.5e-2）。
+- `VD_I8_W8A8=1` 为**实验开关**（W8A8 sdot 直连，最快但激活量化噪声致判定面翻转 ~5%，
+  safety 翻转 14/300），**仅供非判定敏感负载使用**。
+
+**需要支持 int8 包加载的 verdict 引擎版本**（2026-11 之后的 [verdict](https://github.com/vislee/verdict) main；
+旧版引擎无法加载 int8 包）。
+
+## 架构
+
+```
+输入文本 (≤512 tokens)
+   │ tokenizer (Qwen3, vocab 151936)
+   ▼
+Qwen3Guard-Stream-0.6B backbone（int8 权重，去 causal mask → 全可见双向注意力，无 KV cache）
+   │ final RMSNorm → mean-pool
+   ▼
+共享 FFN → 11 个分类头（sigmoid，logit 域阈值判定）
+```
+
+关键改造：**去掉 causal mask**（`is_decoder=false`, `use_cache=false`），
+使每个 token 都能看到全序列；**mean-pool 后接分类头**，答案空间封闭（~160 个固定标签位），
+不需要语言生成能力。int8 版仅量化 backbone 权重，改造点与 v3 相同。
+
+## 11 个分类头
+
+| 轨道 | 头 | 维度 | 体系 |
+|---|---|---|---|
+| 整体判定 | `safety` | 1 | logit 域阈值（规避 sigmoid 饱和） |
+| 放行闸门 | `safety_release` | 1 | 可放行置信度，`release_gate=0.9416` |
+| 内容安全 | `tc260_major` / `tc260_minor` | 5 / 31 | TC260-003《生成式人工智能服务安全基本要求》附录 A |
+| 大模型安全 | `lm_major` / `lm_minor` | 10 / 54 | LM01–LM10 大模型安全检测项 |
+| 个人信息 | `pii_major` / `pii_minor` | 7 / 10 | GB/T 35273-2020（头出数字码 1–10） |
+| 数据分级 | `dc_type` / `dc_level` / `dc_minor` | 4 / 3 / 36 | GB/T 43697-2024（4 大类 + 核心/重要/一般 + 36 子类） |
+
+分类头与阈值的训练、评测详情见 [louivis/encoder-guard](https://huggingface.co/louivis/encoder-guard)
+（v3 与 v2 在分类轨完全一致，v3 的 safety 轨评测同样适用于本包——hybrid 判定面 0 翻转）。
+
+## 文件
+
+| 文件 | 说明 |
+|---|---|
+| `backbone/model.safetensors` | Qwen3Guard-Stream-0.6B backbone，**int8（对称 per-row 量化）**，0.57 GB |
+| `backbone/config.json` | 架构配置（`is_decoder=false`） |
+| `backbone/tokenizer.json` | Qwen3 tokenizer（vocab 151936） |
+| `heads.safetensors` | 11 个分类头权重，fp32，652 KB（**与 v3 逐字节相同**） |
+| `threshold.json` | 阈值 + per-head temperature + ECE（**与 v3 逐字节相同**） |
+| `model_config.json` | 头维度声明 |
+| `data_card.json` | 训练数据与超参记录 |
+| `train_log.jsonl` | 20 epoch 训练日志 |
+
+## 使用
+
+```bash
+# 1. 拉取权重（HF / ModelScope / GitHub Release 自动回退）
+hf download louivis/encoder-guard-int8 --repo-type model \
+  --local-dir model/encoder-guard-int8
+
+# 2. 构建引擎（需支持 int8 包的版本，2026-11 之后）
+git clone https://github.com/vislee/verdict && cd verdict && make
+
+# 3. 推理（默认 i8→F16 hybrid）
+./verdict -m model/encoder-guard-int8 -t "要审核的文本" --text
+./verdict -m model/encoder-guard-int8 --batch input.jsonl --batch-out pred.jsonl
+
+# 实验开关：W8A8 sdot 直连（最快，但判定面翻转 ~5%，仅供非判定敏感负载）
+VD_I8_W8A8=1 ./verdict -m model/encoder-guard-int8 --device cpu --stream < input.txt
+```
+
+`--batch` 输入 JSONL 每行需含 `"prompt"` 键（写 `"text"` 会静默输出空文件）。
+
+## 校验
+
+```
+sha256(backbone/model.safetensors) = 354dc5f733d600a6a9ede69513e63854ba83abbfaf112d2ae147e7fb69c079a5
+sha256(heads.safetensors)          = 7549e611eaa8c44e4fe5b034b0059b31b660311f1c92a6ca08e72f00a6e09c85
+sha256(threshold.json)             = b4ebfc837e5f0d1b6a0b834997ee69e342a1504dd1d1b98799ea0e234a0a52eb
+```
+
+heads 与 threshold 的 sha256 与 v3 完全相同（同一份头与阈值）；仅 backbone 为 int8 重新量化。
+
+## 已知限制
+
+继承 [louivis/encoder-guard](https://huggingface.co/louivis/encoder-guard) 的全部已知限制
+（最大 512 token、空输入输出 `prob=nan`、`dc_type` 较弱、PII 轨协议瓶颈、非中英文泛化未验证），另有：
+
+- **需要新版 verdict 引擎**（2026-11 之后）才能加载 int8 包；旧版引擎请用 fp16 包。
+- **勿对判定敏感负载开启 `VD_I8_W8A8=1`**：W8A8 激活量化噪声会翻转约 5% 的判定
+  （默认 hybrid 路径无此问题，判定面 0 翻转）。
+- 大 T（>24 token）首次前向会惰性构建约 2.3 GB F32 arena；纯小 T 负载整程不构建。
+
+## 许可与归属
+
+本模型为**分组件许可**作品，不同组成部分适用不同条款（完整条款见仓库内 `LICENSE`）：
+
+| 组成部分 | 文件 | 许可 |
+|---|---|---|
+| backbone 权重 | `backbone/model.safetensors`、`tokenizer.json` 等 | **Apache-2.0**（源自 Qwen；int8 量化版本） |
+| 分类头与训练产物 | `heads.safetensors`、`threshold.json`、`model_config.json` 等 | **Encoder-Guard Non-Commercial License 1.0**（禁止商业使用） |
+| 模型卡与文档 | `README.md` 等 | CC BY-NC 4.0 |
+
+- 基座：[Qwen/Qwen3Guard-Stream-0.6B](https://huggingface.co/Qwen/Qwen3Guard-Stream-0.6B)（Apache-2.0）
+- 修改内容：去除 causal mask 改为双向注意力、移除 KV cache、mean-pool 后接 11 个分类头、
+  backbone 权重对称 per-row int8 量化。原始基座的生成式 LM head 未使用。
+- 推理引擎：[verdict](https://github.com/vislee/verdict)（MIT）
+
+依据 Apache-2.0 第 4 条，本模型作为衍生作品分发时随附 `LICENSE-APACHE-2.0` 全文，
+并保留上述声明与修改说明（第 4(a)(b) 条）。分类头与训练产物另受非商业条款约束。
+
+**商业授权**：如需商业使用，请通过 [Hugging Face @louivis](https://huggingface.co/louivis)
+或 [GitHub Issues](https://github.com/vislee/verdict/issues) 联系作者取得书面授权。
+
+## 引用
+
+```bibtex
+@misc{encoder-guard-v3-int8,
+  title  = {Encoder-Guard v3 int8: Discriminative Content Safety Classifier (int8-quantized backbone)},
+  author = {Lee, Louivis},
+  year   = {2026},
+  note   = {Qwen3Guard-Stream-0.6B backbone (int8), 11 classification heads},
+  url    = {https://huggingface.co/louivis/encoder-guard-int8}
+}
+```