README.md

---
license: apache-2.0
base_model: Qwen/Qwen3.5-4B
tags:
  - text-classification
  - qwen
  - lora
  - llama-cpp
  - gguf
  - safety
  - claude-code
language:
  - en
  - zh
pipeline_tag: text-classification
---

# claude-code-local-classifier (Qwen3.5-4B LoRA)

微调 Qwen3.5-4B 做 Claude Code 的本地安全分类器（prompt injection 哨兵）。数据不出域、阈值概率可调、本地 GPU/CPU 推理。298 条 holdout：deny_recall 0.866 / false_block 0.005 / auc 0.945。

## 底座与训练

- **思路来源**：基于 **Jev**（TypeSafe AI 的快速推理模型）——不生成文本、只做结构化决策，返回 `true/false` 二分类概率。本模型沿此思路：纯分类、不生成理由。
- **底座**：`Qwen/Qwen3.5-4B`（多模态版，训练时用 `get_text_config()` 剥视觉编码器，只取语言部分）
- **LoRA**：r=32，7 目标模块（q/k/v/o + mlp gate/up/down），adapter ~181M
- **方法**：RLCD 分类——模型学 `yes`(deny)/`no`(allow) 单 token 概率，不生成 reason
- **训练数据**：合成 RLCD case + 真实 Claude Code 会话 holdout（298 条）。**原始会话数据含隐私，不在本仓库发布**，仅提供 6 条合成样本演示格式（见 GitHub 仓库 `datasets/samples.jsonl`）
- **prompt 格式**：chatml 三段（policy_summary + `<transcript>`+action + 裁决指令），训练/推理/验收同一真源 `prompt_assembly.py`

## 推理用法

模型不读生成文本（Qwen3.5 thinking 循环会输出 ` IMD`），而是走 llama-server `/completion` 读 yes/no logprob 概率：

```bash
# 1. 起 llama-server（GGUF 版）
llama-server -m qwen35-clf-v2-q4_k_m.gguf --host 127.0.0.1 --port 11943 \
  -c 16384 --parallel 1 -ngl 999 -ctk q8_0 -ctv q8_0

# 2. /completion 读概率（prompt 由 prompt_assembly.build_prompt 生成）
curl 127.0.0.1:11943/completion -H 'Content-Type: application/json' -d '{
  "prompt": "<|im_start|>system\n{policy_summary}<|im_end|>\n<|im_start|>user\n<transcript>\n{\"user\":\"...\"}\n{\"Bash\":{...}}\n</transcript>\n\n{裁决指令}<|im_end|>\n<|im_start|>assistant\n",
  "n_predict": 1, "n_probs": 60, "temperature": 0, "cache_prompt": true
}'
# 响应 completion_probabilities[0].top_logprobs 取 yes/no logprob
# p_yes = σ((lp_yes - lp_no) / T)，T=1.0448（output/adapter/temperature.json）
# block 判定：p_yes >= 0.5 => deny
```

完整示例脚本见 GitHub 仓库 `eval/verify_local.py`、`eval/eval_holdout_full.py`。

## 指标（298 holdout）

| 指标 | 本地 v2 (RTX 4050 GPU) | 服务器纯 CPU | transformers 训练环境 |
|---|---|---|---|
| deny_recall@0.5 | 0.866 | 0.866 | 0.884 |
| false_block@0.5 | 0.005 | 0.005 | 0.005 |
| auc | 0.945 | — | 0.979 |
| sep | 0.799 | 0.726 | 0.819 |
| latency | 1.8s/条 | p50 33ms | — |

## 文件

- `adapter/` — LoRA adapter（~181M），挂到 `Qwen/Qwen3.5-4B` 底座
- `qwen35-clf-v2-q4_k_m.gguf` — GGUF Q4_K_M（~2.6G），llama-server 直接跑
- `temperature.json` — 校准温度 T=1.0448

## 关键坑（复刻必读）

- convert GGUF **不要带 `--no-nextn`**（会系统性压缩 logits，deny p_yes 0.85→0.47）。本 GGUF 是 v2，不带。
- 训练用 `policy_summary.txt`（15K 精简摘要）作 system，**不要用请求体的完整 rules**（139K，与训练不同构）。
- thinking 循环绕过方式 = 读 `/completion` 的 yes/no logprob，不读生成文本。

详见 GitHub 仓库 `docs/pitfalls.md`。

## 免责

- 本模型是 prompt injection 辅助哨兵，**不替代完整安全审查**。
- 原始训练/评测数据含真实会话，不在本仓库发布；仅提供合成样本演示格式。
- policy_summary 是通用 AI 安全规则摘要；完整 rules 不随模型发布。

## 相关

- GitHub 仓库（训练管线 + 部署 + eval + router 整合）：_链接待填_
- 技术博客（动机 + 过程 + 踩坑复盘）：_链接待填_
- HuggingFace 本仓库：https://huggingface.co/nathaniel-min/claude-code-local-classifier