Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,85 @@
+---
+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。
+
+## 底座与训练
+
+- **底座**：`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