memory-organ-trainer

# Memory Organ Module — 自动训练技能 ## 路由决策表 | 用户意图 | 执行命令 | 前置条件 | |----------|---------|---------| | "初始化项目" / "setup" / "检查环境" | `python scripts/check_env.py` → `python scripts/setup_project.py` | 无 | | "生成训练数据" / "generate data" | `python scripts/generate_data.py [--num-profiles N] [--sessions-per-user M]` | 项目已初始化 | | "开始训练" / "train" / "全阶段训练" | `python scripts/run_training.py --phase all` | 数据已生成 | | "只训练融合" / "phase a" | `python scripts/run_training.py --phase a` | 数据已生成 | | "只训练写入门控" / "phase b" | `python scripts/run_training.py --phase b` | Phase A checkpoint 存在 | | "端到端微调" / "phase c" | `python scripts/run_training.py --phase c` | Phase B checkpoint 存在 | | "评估" / "evaluate" | `python scripts/run_eval.py` | checkpoint 存在 | | "evaluate autoregressive" / "check AR metrics" / "AR 评估" | `python scripts/run_eval.py --metric ar` | checkpoint 存在 | | "演示" / "demo" / "对话测试" | `python scripts/run_demo.py` | checkpoint 存在 | | "执行睡眠整合" / "sleep consolidation" | 调用 `SleepConsolidation.run()` | MemoryStore 已初始化 | | "执行遗忘规则" / "forget gate" | 调用 `MemoryStore.apply_forget_rules()` | MemoryStore 已初始化 | | "检查数据完整性" / "verify data" | 读取 `data/stats.json`，检查 `write_target_coverage >= 0.99` | 数据已生成 | | "全流程" / "一键完成" | 按序执行以下所有步骤 | 无 | ## 全流程执行步骤（一键模式） 按顺序执行，每步完成后调用 `#tool:vscode_askQuestions` 确认继续： ### Step 1: 环境检查 ```bash python scripts/check_env.py ``` 若出现阻断性错误（缺包、磁盘不足），先修复再继续。 ### Step 2: 项目初始化 ```bash python scripts/setup_project.py ``` ### Step 3: 生成训练数据 ```bash python scripts/generate_data.py --num-profiles 100 --sessions-per-user 5 --output-dir data/ ``` 完成后读取 `data/stats.json` 并报告统计摘要。 - 检查 `write_target_coverage >= 0.99`（若 < 0.95 应警告并重新生成） - 确认 `write_turns` / `total_turns` 比例在 10%-20% 合理范围内 ### Step 4: 执行训练 ```bash python scripts/run_training.py --config config/default_config.yaml --phase all ``` 监控输出：若 loss 出现 NaN，停止并报告；若训练正常，报告最终 loss 摘要。 ### Step 5: 评估（诚实评估门 — TF + AR 双指标） ```bash python scripts/run_eval.py --checkpoint latest --metric all python scripts/run_eval.py --checkpoint latest --metric ar ``` 读取 `outputs/eval_report.json`，报告各指标。 **诚实评估规范**： - 同时展示 TF (Teacher-Forcing) 和 AR (Autoregressive) 指标，清楚标注 `[TF]` / `[AR]` - AR 指标是唯一真实指标，TF 指标仅作训练过程参考 - 若 AR 指标与 TF 指标偏差 > 50%，**标红警告**："⚠️ 评估可能不可靠 — TF/AR 偏差过大" - PASS/FAIL 门控阈值：记忆召回 > 70%，已知数据：AR ReadGate 激活阈值待降低优化 - 回归检测：与上次最优指标比较，>10% 回归则报警（历史存储于 `outputs/metric_history.json`） **已知 AR-ReadGate 失效问题**： v2.0.3 实测中 ReadGate 在 AR 模式激活率为 0（阈值小面积为 0.3，实际输出约 0.05~0.25）。Memory Influence KL=3.66 确认记忆确实影响 prefill 分布。BLEU/ROUGE/Token Diversity 偏低是 AR ReadGate 激活阈值面题，非模型失败。评估时请注明此背景。 ### Step 6: 推理演示 ```bash python scripts/run_demo.py --non-interactive ``` 报告演示通过率。 ## 新增组件使用规范 ### P2 — 遗忘机制 **ForgetGate 启发式规则**（MemoryStore 内置，无训练成本）： ```python # 在推理 / 睡眠整合时调用 stats = store.apply_forget_rules( strength_threshold=0.05, # 衰减到此值以下 → 软删除 cosine_merge_threshold=0.95, # 两条记忆 cosine > 此值 → 合并保留较强者 max_age_days=30.0, # 从未被访问且超过30天 → 软删除 ) ``` **LambdaNet 可学习衰减**（`src/memory/lambda_net.py`）： - 将 `LambdaNet` 实例加入 optimizer，传入 `MemoryStore.search(lambda_net=...)` 即可启用 MLP λ - 不传入时退化为固定 `decay_lambda=1e-6`（向后兼容） ### P3 — 睡眠整合周期 ```python from src.memory.sleep_consolidation import SleepConsolidation sleep = SleepConsolidation(store, session_interval=50) # 每次对话结束后 tick，满 50 次自动触发 stats = sleep.tick() # 立即强制触发 stats = sleep.run() ``` `SleepStats` 包含：`clusters_merged`、`low_utility_deleted`、`forget_rule_*` 三项计数。 ### P4 — SessionState 内部记忆 - 由 `MemoryAugmentedModel` 内部自动管理，训练时无需额外操作 - `forward()` 不需要 `user_id_strings` 参数（已移除多用户隔离） - session 结束时手动调用 `model.session_state.reset()` 清零状态 - 如需禁用（回退到纯外部记忆）：`MemoryAugmentedModel(enable_session_state=False)` - **SessionState 已纳入 checkpoint 保存/加载**，跨训练阶段状态不丢失 ### Phase A/C 全局 memory bank - Phase A（记忆融合）和 Phase C（端到端微调）使用跨 profile 全局 memory bank - 每个 epoch 开始时随机 shuffle 并采样 `global_memory_bank_size`（默认200）条向量 - 提升检索任务难度，避免 per-batch 小 bank 导致的过拟合 - 在训练日志中查找 `[GlobalBank] N vectors from M profiles` 确认生效 - Phase B（写入门控）继续使用 per-batch 小 bank，确保精确 GT 对齐 - 配置项：`training.global_memory_bank_size`（见 `config/default_config.yaml`） ## 错误处理 | 错误现象 | 可能原因 | 解决方案 | |---------|---------|---------| | `ValueError: encoder_model=None 时默认不允许...` | 构建 MemoryDataset 未传入 encoder_model | 传入 `encoder_model=model.base_model` 或 `debug_mode=True`（仅调试） | | `write_target_coverage < 0.95` | conversation_generator 生成数据有问题 | 重新生成数据，检查 should_write=True 的 turn 是否有 write_target_memory_index | | PPL 评估中 `encoder_model=None` ValueError | evaluate.py 未传入 encoder | 已在 evaluate.py 中修复，传入 model.base_model | | TF 指标优秀但 AR 指标极差（偏差 > 50%） | 训练-推理分布漂移 | 检查 Scheduled Sampling 是否启用；验证 prefill-once 融合；运行 `--metric ar` 确认 | | AR Token Diversity < 0.1 | 退化为重复 token | 检查 temperature/top_p 参数；确认 repetition_penalty > 1.0 | | **CUDA out of memory** | Qwen2.5-3B bf16 显存占用约 6 GB，评估区段各需独立进程 | 评估使用 `--metric` 单项分批运行；`BATCH_SIZE=2`；添加 `torch.no_grad()` | | `NativeCommandError`（Windows Tee-Object） | PowerShell 管道 stderr 冲突 | 使用 `Start-Process -WindowStyle Hidden -RedirectStandardOutput log -RedirectStandardError err` | ### MemoryFusion 双路融合 `MemoryFusion.forward()` 新增 `session_state` 可选参数： - 传入时同时融合外部记忆（cross-attention）和 session 状态（门控注入） - 不传入时（`None`）退化为纯外部记忆模式，向后兼容 Phase A/B 训练 ## 错误处理规范 - **ModuleNotFoundError**: 运行 `pip install -r requirements.txt` 重试 - **CUDA out of memory**: 自动降低 batch_size（16→8→4）重试 - **FileNotFoundError（数据文件）**: 提示用户先执行 Step 3 生成数据 - **FileNotFoundError（checkpoint）**: 提示用户先执行 Step 4 训练 - **loss = NaN**: 检查 `config.py` 中 `LR` 是否过大，建议降至 `1e-5` - **WriteGate F1 < 30%**: 检查 `losses.py` 中 `pos_weight` 是否为 6.0（已默认修复） - **OMP Error #137（Windows）**: 在命令前设置 `$env:OMP_NUM_THREADS="1"` 限制线程数 ## 用户确认规范 每个步骤完成后，必须调用 `#tool:vscode_askQuestions` 询问用户是否继续。 在执行任何新步骤前，先从 `projectmd/newFramework.md` 读取对应该步骤的最新架构说明。