feat: Module C v5/v6 training complete, ablations, SOTA baselines, paper updates

- Module C: BC+PPO training v5/v6 done; eval results in experiments/eval_intervention_v{5,6}.json - Reward: v5 label-aligned constrained reward (code/src/rl/reward.py) - Ablations: Module B (history_r, response_only, full) + Module C (wo_category_reward) - SOTA baselines: WildGuard and ShieldGemma2b eval scripts and results - Paper: update sections 05–08 (Module B/C description, experiments table, discussion) - Docs: add record.md (change log), update state.md and exp.md; retire change.md - Tools: add html-to-ppt utilities and run_shieldgemma2b.sh - Configs: add ablation YAML configs for Module B and C - Cleanup: remove stale reference/ PNG screenshots Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-20 14:24:09 +08:00
parent 6d61a950f1
commit 52ba43f08d
55 changed files with 8239 additions and 1244 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,19 +1,10 @@
-# CompanionGuard-RL — 项目宪法
+# CompanionGuard-RL

-> **目标期刊**：SCI Q1/Q2（Information Processing & Management / Expert Systems with Applications）
-> 这份文件是所有 AI 助手会话的首要参考，优先级高于任何对话中的临时指令。
+为 AI 情感陪伴场景构建**检测 + 干预**一体化安全流水线，目标期刊 SCI Q1/Q2（IP&M / ESWA）。

 ---

-## 项目目标
-
-为 AI 情感陪伴场景构建**检测 + 干预**一体化安全流水线，解决两个核心缺口：
-1. 现有 guard 模型（Llama Guard、WildGuard）只检测、不干预——不知道该对高风险输出做什么
-2. 通用安全模型对伴侣特有风险（依赖强化、孤立强化、浪漫化、危机不响应）系统性漏检
-
---
-
-## 架构
+## 系统架构

 ```
 输入 X = (Persona P, History H, User u_t, AI Response r_t)
@@ -30,93 +21,132 @@
   a_t ∈ {PASS, WARN, REWRITE, REJECT, CRISIS}
 ```

+**Module B frozen**：已达 binary_f1=0.9995，不再迭代。
+
 ---

-## 模块状态
+## 不变量

-| 模块 | 状态 | 关键指标 |
+违反这些规则会导致训练崩溃或结果在概念上错误，**不得绕过**。
+
+| 规则 | 原因 |
+|------|------|
+| `obs_dim = 2065` 固定 | `1+5+10+1024+1024+1`，改动导致维度不匹配崩溃 |
+| 状态向量用 `det_l_risk`，不用 GT `l_risk` | GT 在部署时不可得；用 GT 导致 train/eval 不一致，指标虚高 |
+| Module C 训练只能单 GPU（`--num_processes=1`） | RTX 5090 上 `torch.distributed.barrier()` 触发 CUDA illegal memory access |
+| BC 阶段 tensor 保持 CPU 直到 `accelerator.prepare()` | `DataLoader(pin_memory=True)` 不支持 CUDA tensor |
+| Module B 权重 frozen，不参与 Module C 训练 | 检测器是 offline 预处理阶段，不是可微组件 |
+
+---
+
+## 行为准则
+
+### 结果异常：立即暂停并报告
+- 任何运行结果与预期明显不符（指标异常高/低、loss 不收敛、输出格式错误）→ 立即停止后续步骤，说明异常现象，不得假设"可能正常"后继续
+- eval 数字在两次运行间出现差异 → 先找原因，不得直接取较好的那次结果
+- 代码修改后指标反而大幅提升 → 优先怀疑 data leakage 或 bug，而非庆祝
+
+### 不可逆操作：执行前明确确认
+- 删除或覆盖任何文件（checkpoints、experiments/*.json、data/processed/）→ 必须先告知用户将要做什么，得到确认后再执行
+- 服务器上的写入 / 覆盖操作 → 操作前说明目标路径和影响范围
+- 重新训练 Module B → 需明确讨论（权重 1.35GB、GPU 数十小时，论文结果依赖 frozen 权重）
+
+### 范围纪律：只做被要求的
+- 修复 bug 时不顺手重构周边代码
+- 改一处配置时不改动其他超参数
+- 不引入未被要求的功能、抽象或依赖
+
+### 研究诚信
+- 论文中的数字必须可追溯到具体实验文件（experiments/*.json）和 checkpoint，不得凭记忆或估算填写
+- `experiments/` 下的历史结果文件只读；需更新结果时生成新文件（如 `eval_intervention_v5.json`），不覆盖旧文件
+- 数据集 v4（`data/processed/CompanionRisk-Bench/`）已冻结，不得修改任何样本
+- 报告结果时不选择性省略不利指标（当前 action_accuracy、crisis_precision 未达标，必须如实陈述）
+
+### 基础设施变动：立即记录
+服务器修复、重置、存储重挂载等事件发生后，必须同步更新以下内容，**不得拖到下次出问题才修**：
+- `state.md` 服务器速查表（SSH 命令、认证方式、存储 UUID、代理端口）
+- `record.md` 补变更条目（变了什么、影响哪些文件、教训）
+- 所有含绝对路径的 config 文件（`configs/intervention_config.yaml`、`configs/detector_config_server.yaml`）——先在服务器上确认新路径，再同步本地
+
+典型触发场景：存储 UUID 变更、SSH 密钥更换、代理端口变化、Python 环境路径变化。
+
+### 歧义：询问而非假设
+- 当操作会影响实验结果或论文内容，且需求存在歧义时，先问清楚再动手
+
+---
+
+## 论文论点
+
+**核心主张**：现有 guard 模型（Llama Guard、WildGuard）只检测不干预，且对 companion-specific 风险系统性漏检。CompanionGuard-RL 在检测基础上学习分级干预动作。
+
+**三个贡献**：
+1. CompanionRisk-Bench（9,896 样本）+ 10 类风险分类体系
+2. Module B：上下文感知检测器，binary_f1=0.9995，FNR=0
+3. Module C：RL 自适应干预策略，safety_recall=1.0（rule baseline 0.908）
+
+**当前 limitation**（不能回避，在 discussion 节正面陈述）：
+- action_accuracy=0.575（目标 ≥0.70），L1 过激主因
+- crisis_precision=0.421（目标 ≥0.80），R1 样本稀少主因
+
+---
+
+## 文档导航
+
+| 文件 | 内容 | 何时查阅 |
 |------|------|---------|
-| 数据集 CompanionRisk-Bench v4 | ✅ | 9,896 样本，14 标签全覆盖（train 6,926 / dev 1,484 / test 1,486） |
-| Module B 检测器 v4 | ✅ | binary_f1=**0.9995**, FNR=0.00%, level_weighted_f1=0.559 |
-| Module B 泛化验证 | ✅ | human subset binary_f1=0.9848，无同源过拟合 |
-| Module C v3（当前） | ⚠️ | safety_recall=1.0 ✅，over_refusal=0.004 ✅，action_accuracy=**0.575** ❌，crisis_precision=**0.421** ❌ |
-| Module C v5（下一步） | 🔄 | reward 重写 + 环境修复，**见 `change.md` 完整路线** |
-| 论文写作 | 🔄 | LaTeX 框架已搭建（`paper/`），方法节完整，结果节等 v5 + SOTA baseline |
+| `state.md` | 当前模块状态、v5 执行计划、训练命令 | 每次开始工作前 |
+| `record.md` | 历史变更、bug 修复记录、完整实验结果 | 需要了解某个决策来龙去脉时 |
+| `exp.md` | 环境问题与解决方案（NCCL、PyYAML、依赖等） | 遇到运行时错误时 |

-> **Module C 尚未完成**。v3 的 action_accuracy 和 crisis_precision 均未达标，需要按 `change.md` 执行 v5。
-> **投稿前必补实验**：① Llama Guard v2 / WildGuard 评估（Module B SOTA 对标）；② LLM-as-judge baseline（Module C）；③ 消融实验（BC-only / 无 CrossAttention）。
+**更新规则**：代码改动 → `state.md` + `record.md`；环境/崩溃问题 → `exp.md`；架构或不变量变化 → `CLAUDE.md`；**服务器基础设施变动**（UUID、认证、代理）→ `state.md` + `record.md` + `CLAUDE.md` 服务器节。

 ---

-## Red Lines（关键规则，违反必出 bug）
+## 代码结构

-| # | 规则 | 违反后果 |
-|---|------|---------|
-| 1 | **PyYAML 陷阱**：配置文件 lr 必须写 `0.001`，禁止写 `1e-3` | PyYAML 6.x 将 `1e-3` 解析为字符串，训练静默失败 |
-| 2 | **NCCL 环境变量**：RTX 5090 训练必须加 `NCCL_SHM_DISABLE=1 NCCL_P2P_DISABLE=1` | NCCL 通信报错崩溃 |
-| 3 | **Module C 只能单 GPU**：PPO 阶段禁止多卡 | `torch.distributed.barrier()` 在 RTX 5090 引发 CUDA illegal memory access |
-| 4 | **状态向量用 `det_l_risk`**：preprocessing.py 和 evaluate.py 必须用检测器预测的风险等级，不能用 ground truth `l_risk` | train/eval 不一致，指标虚高 |
-| 5 | **obs_dim = 2065 固定**：`[d_score(1) + l_risk_onehot(5) + c_primary_probs(10) + e_H_pool(1024) + e_P_pool(1024) + t_norm(1)]` | 维度不匹配崩溃 |
-| 6 | **BC 阶段用 CPU tensor 再构建 DataLoader**：`pin_memory=True` 要求 CPU tensor | RuntimeError: cannot pin cuda tensor |
-
---
-
-## 文件地图
-
-### 项目级（根目录）
-| 文件 | 用途 |
-|------|------|
-| `state.md` | 当前进度快照（最新） |
-| `change.md` | **Module C v5 完整技术路线**（待执行，含 13 项任务） |
-| `exp.md` | 踩坑经验库（12 类，排查问题先查这里） |
-| `experiments/eval_intervention_v3.json` | Module C 当前最佳结果（论文参考基准） |
-| `experiments/eval_intervention_v4.json` | v3 重跑确认（数字相同，验证可复现） |
-| `docs/` | 研究文档（研究框架、数据集设计、前期报告） |
-| `paper/` | **论文 LaTeX 源码**（主框架已就绪，见 state.md §八） |
-
-### 代码级（code/）
-| 路径 | 用途 |
-|------|------|
-| `code/src/models/detector.py` | Module B 主模型 |
-| `code/src/models/intervention_agent.py` | Module C Actor-Critic（obs_dim=2065→256→5） |
-| `code/src/rl/reward.py` | 多目标奖励（**v5 需重写**） |
-| `code/src/rl/companion_env.py` | 离线 RL 环境（**v5 需修复类别信号**） |
-| `code/src/utils/preprocessing.py` | build_obs_vector（**必须用 det_l_risk**） |
-| `code/configs/intervention_config.yaml` | Module C 训练配置 |
-| `code/checkpoints/detector/best.pt` | Module B 最优权重（1.35GB，**frozen**） |
-| `code/checkpoints/intervention/final_v2.pt` | Module C v3 权重（5MB，当前最佳） |
-
---
-
-## 服务器速查
-
-| | 服务器 1（主训练） | 服务器 2（当前使用） |
-|--|--|--|
-| SSH | `ssh -p 20083 root@10.82.3.180` | `ssh -p 20060 root@10.82.3.180` |
-| 密码 | `m2dGcwyrhI` | `zwfn65xjTY` |
-| Python 环境 | `/opt/conda/envs/dlapo-py310-cu128/bin` | `$PROJ/../env/dlapo-py310-cu128/bin` |
-| GPU | 4 × RTX 5090 32GB | 2 × RTX 5090 32GB |
-
-**服务器 1 $PROJ**：`/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL`
-**服务器 2 $PROJ**：`/root/siton-data-740d234e02d749f08fe5347b0c74c49f/zsy/my-reasearch/companionguard-rl`
-**MacBERT（两台）**：`$PROJ/../macbert-large`（服务器 2 在 `../zsy/macbert-large`）
-
-### 上传代码（本地 → 服务器）
-```powershell
-scp -P 20083 -r `
-  D:\Myresearch\CompanionGuard-RL\code\src `
-  D:\Myresearch\CompanionGuard-RL\code\scripts `
-  D:\Myresearch\CompanionGuard-RL\code\configs `
-  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/
+```
+code/
+├── src/
+│   ├── models/detector.py            # Module B（frozen）
+│   ├── models/intervention_agent.py  # Module C Actor-Critic
+│   ├── rl/reward.py                  # v5 label-aligned constrained reward
+│   ├── rl/companion_env.py           # 单步 MDP 离线环境
+│   ├── rl/ppo_trainer.py             # PPO 训练器
+│   └── utils/preprocessing.py       # build_obs_vector（用 det_l_risk）
+├── scripts/
+│   ├── train_intervention.py         # BC + PPO 主训练脚本
+│   └── evaluate.py                   # 多基线评估（支持 --bc-ckpt ablation）
+├── configs/
+│   └── intervention_config.yaml      # 训练配置（use_wandb: false）
+└── tests/
+    ├── test_reward_v5.py
+    └── test_intervention_metrics.py
 ```

-### 取回结果（服务器 → 本地）
-```powershell
-scp -P 20083 -r `
-  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/experiments `
-  D:\Myresearch\CompanionGuard-RL\
+---
+
+## 服务器

-scp -P 20083 -r `
-  root@10.82.3.180:/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL/checkpoints `
-  D:\Myresearch\CompanionGuard-RL\code\
+```
+# 连接（别名或完整命令）
+ssh server5090
+ssh -p 20083 -i C:/Users/张思远/.ssh/ai_tunnel_key root@10.82.3.180
+
+# 路径
+$PROJ   = /root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL
+MacBERT = $PROJ/../macbert-large
+Python  = /opt/conda/envs/dlapo-py310-cu128/bin/
+GPU     = 4 × RTX 5090 32GB
+
+# 认证
+密钥文件: C:\Users\张思远\.ssh\ai_tunnel_key  (ED25519，2026-05-19 配置)
+SSH config 别名: ~/.ssh/config → Host server5090
+
+# 代理（服务器无外网，使用本地隧道转发）
+服务器内 http_proxy=http://127.0.0.1:7890  用于 pip/curl
+验证隧道: netstat -tlnp | grep 7890  → 应有 127.0.0.1:7890 LISTEN
+
+# 存储 UUID（服务器修复/重置后可能变更，需同步更新 configs/ 绝对路径）
+当前 UUID: siton-data-2849d4ce327c4ccfb233ce33868fe7fe  (2026-05-19 起)
+旧 UUID:   siton-data-740d234e02d749f08fe5347b0c74c49f  (已失效)
 ```