📖 项目讲解 — Agentic RL × 记忆检索

名词概念速查

本项目涉及的全部名词概念,按 核心架构 / 环境状态 / 记忆池数据 / 奖励设计 / RL 训练 / 评测基线 / 模型工具 / 未落地 分组,每条均注明代码出处。

一、核心架构与概念定位

名词含义(紧扣本项目)出处
Agentic RL 本项目核心范式:学「何时检索记忆」的决策策略 p(a|s),动作 = 检索/克制;区别于学「怎么生成 token」的 RLHF。决策对象是"是否动记忆",不是"下一句话"。
对照:Agentic RL = 外部环境交互 + 语义多档 reward;Reason RL(R1/o1)= 内部推理 + verifiable reward。本项目属于前者。		 docs/agentic_rl_design.md §9、README
A-MEM Agent 背后挂的私有记忆系统,把记忆读写做成基础能力。本项目不学记忆怎么写,只学「什么时候该用它」。 README、frontend/overview.html
RetrievalPolicy 共享检索决策策略(唯一权威定义):3 层 MLP。两个版本——2 动作基线输入 386 维 state → 输出 {0=retrieve, 1=skip}(STATE_DIM=386);3 动作扩展(当前)输入 388 维 → 输出 {0=retrieve, 1=forget, 2=answer}(STATE_DIM_3ACT=388)。网络必须命名为 self.net 以便 checkpoint 严格加载。 src/policies/retrieval_policy.py
MemoryPolicy 6 动作记忆使用策略网络:query embedding + 对 memory embeddings 的 MultiheadAttention + action history LSTM → action logits。 src/policies/memory_policy.py
SimplePolicy 简化 demo 用 3 动作 MLP 策略(输入 query embedding 直接出 logits)。 scripts/run_simple_demo.py
RealMemStore 真实 SBERT embedding 的记忆库,用 np.dot 做 cosine top-k 检索,返回 (idx, text, score)。 src/envs/real_mem_env.py
RealDecisionEnv 1 步决策 bandit 环境:策略决定 retrieve / skip,按终局多档 reward 结算。 src/envs/real_mem_env.py
RealMultiStepEnv 多步检索环境:策略逐轮决策直到 skip 或队列耗尽,是 TRACE λ-return 真正展开的场景。 src/envs/real_mem_env.py、docs §9.5
ActionGuard 在 Harness 层拒绝语义上无意义的检索(已达 max_retrieve / 与上次重复无新证据 / 已全部命中必需记忆仍检索)——对应购物场景"点不存在的商品"。 src/envs/action_guard.py、docs §8.2
MDP 问题的建模形式:State = query + 已检索记忆 + 历史 action + 答案草稿;Action = 6 种;Reward = rubric 评分 − 调用成本。 docs §2.1

二、环境、状态与决策

名词含义(紧扣本项目)出处
state(386 维 / 388 维) 策略输入——2 动作基线:concat(query_emb, [下一候选质量, hit_flag]) = 384 + quality + hit_flag; 3 动作扩展:concat(query_emb, [下一候选质量, 上一步质量, 命中标志, 残留数]) = 388 维, 新增 last_q(retained 栈顶质量,判断"刚拿到的是干扰还是 correct → 要不要 forget")与 retained_count(污染残留量)。 retrieval_policy.py STATE_DIM=386 / STATE_DIM_3ACT=388
quality 下一条候选记忆与 query 的余弦相似度,决定"值不值得检索"。 retrieval_policy.py、real_mem_env.py
hit_flag(命中标志) 已检索集合是否命中 required 的 0/1 标志——「命中即停」可学的关键信号(未命中 state[-1]==0,命中后 ==1)。 real_mem_env.py state()、tests/test_shared.py
命中即停(2 动作基线) 2 动作基线的行为:策略看到 hit_flag=1 就判断"检索够了"并 skip,多步 RL 学会的行为(实测 A 类平均 3.67 步)。 3 动作扩展引入 forget 后不再简单"即停"——先逐条核对,不对的 forget 掉,保留正确记忆才 answer,轨迹更长(A 类平均 7.33 步)。 docs §9.5、§8.7、frontend/overview.html
3 动作 MDP(扩展) 当前设计:{0=retrieve 检索, 1=forget 遗忘, 2=answer 作答}。forget LIFO 弹出 retained 栈顶(-0.2), 实现"先拿错→自我纠错"的清理回路;answer 终止并取 retained 作答题上下文。max_steps=12。 与 2 动作基线的 {retrieve, skip} 是异构动作链——A 类干净最优轨迹 4~10 步,给 TD(λ) 真正信用分配空间。 docs §8.7、real_mem_env_3act.py、train_trace_3act.py
forget(自我纠错) 3 动作 MDP 的关键语义:即使先检索到金融/医疗/旅游/教育干扰记忆,策略靠 last_q 判断不对就 LIFO 弹出清理, 终局 retained 恰为正确记忆才得 +10(有污染残留只得 +7)。忘掉已命中的 correct 则 -8.5(forgot_correct,最严重档)。 业务话术:「犯错但不带错出门」。实测 B 类 50 条测试集 6% 的偶发检索全部被 forget 清理,干净作答 50/50。 docs §8.7、src/rewards/multi_tier_reward.py
A_QUERIES / B_QUERIES 各 15 条的规范评测查询:A 类 = 私有事实(需检索 correct_mem),B 类 = 纯世界知识(应克制)。A 类带 low/mid/high 词汇重叠度分档。 src/envs/real_mem_env.py
域分离 B 类检索候选池只含干扰记忆(DISTRACTOR_MEMORIES),保证"B 检索必拿跨域干扰 → -8.5 误检"的奖励语义成立。 real_mem_env.py、docs §11.1
correct_pos A 类 correct_mem 在多步候选队列中的位置(随机化,防位置泄露,策略必须靠 hit_flag 而非记忆位置)。 real_mem_env.py
candidate_queue 多步环境构建时固定的候选记忆序列(A 类 = distractor×k + correct_mem + distractor…,B 类 = 全干扰),不依赖 embedding 排序。 real_mem_env.py

三、记忆池与数据设计

名词含义(紧扣本项目)出处
CORRECT_MEMORIES / DISTRACTOR_MEMORIES 规范记忆池:15 条软件工程私有记忆 + 15 条金融/医疗/旅游/教育跨域干扰记忆。 src/envs/real_mem_env.py
干扰记忆池 与软件工程 queries 相似度低的无关记忆(冠心病/浅草寺/国债/抑郁症等),故意跨域——检验"克制"而非"乱检索"。 real_mem_env.py、overview.html
统一池(unified pool) CORRECT_MEMORIES + DISTRACTOR_MEMORIES 合并检索,用于 A 类真实 top-1 检索评测。 scripts/compare_direct.py UNIFIED
top-1 命中 检索结果首位文本是否等于目标 correct_mem(多语言模型下 A 类 15/15 命中)。 compare_direct.py、tests/test_shared.py
位置泄露 早期 correct_pos 按 1+(i%3) 周期排布,策略可记忆位置"作弊";已改为随机。 docs §11.3
business_context.json 规范数据文件:业务主体(某互联网公司数据平台部/2024)、5 条业务线、15 条记忆的归属与时间线、A/B 查询描述、8 条 timeline。
业务叙事以此为准,改叙事不动训练文本。		 data/business_context.json、docs §11.5
业务线(business_line) 5 条:data_eng(数据工程)/ algo(算法推荐)/ security(安全合规)/ platform(中台架构)/ eng_eff(工程效能)。 business_context.json
amem_rl_dataset.json 场景数据集:8 个场景 / 31 条记忆,字段含 golden_answer / optimal_actions / required_memories / action_map。 data/amem_rl_dataset.json
action_map 场景数据的动作编号映射:{0:no_op, 1:vector_retrieve, 2:link_expand, 3:answer, 4:forget_old, 5:write_new}。 注意与 3 动作 MDP 的编号是两套体系:这里 forget_old=4(清理旧记忆)、answer=3; 3 动作 MDP 里 forget=1、answer=2。train_sft.py 复用了 0/1/2 三个编号做专家轨迹监督,但语义源自本场景数据。 amem_rl_dataset.json
testset_b_real.json 从 HuggingFace 中文 StackOverflow 构建的独立 B 类评测集(未见过的查询),概念词筛选 + FPS 采样,干扰池 top-1 相似度校准到 0.10~0.35。 scripts/build_testset_b_real.py
数据合成扩池 已落地(2026-08-13):scripts/synthesize_pool.py 用 GLM-4-Flash 把池扩到 ~200 条 (115 correct + 30 同域混淆干扰 + 45 跨域 + 115 A 查询 + 50 B 查询,data/pool_expanded.json); 决策级消融显示 RL≈SFT 第三次证实,扩池未翻转结论。 docs §8.8、overview.html
oracle 上界（任务饱和） 3 动作 MDP 的理论最优 reward:A env = 干净命中终局 reward − (k+1)·retrieve_cost − k·forget_cost (k=correct_pos),B env = 干净作答 +10。核对结果:scripts/oracle_3act.py 显示 RL 与 SFT 都精确触达 avg_R 8.506、总 headroom=0、165/165 env 触及(30 池亦 30/30)——任务被 SFT 行为克隆解到理论最优, RL≈SFT 不是 RL 失败,而是无奖励余量可挖。 docs §8.8、scripts/oracle_3act.py

四、奖励设计

名词含义(紧扣本项目)出处
compute_terminal_reward 根据 TerminalResult 终局状态产出多档 terminal reward 的核心函数。 src/rewards/multi_tier_reward.py
TerminalResult 终局状态 dataclass:category / hit_fraction / answer_correct / terminated_cleanly / max_steps_hit / repeated_loop / wrong_category / required_total。 multi_tier_reward.py
多档 Reward 把单一连续分拆成 9 档(gold 1.0 / valid_alternative 0.55 / partial / early_abstain / premature / max_steps / loop / wrong_retrieval / no_evidence),让 TRACE 拿到有区分度的相对排序信号。 multi_tier_reward.py、docs §8.1
SCALE = 10.0 把 0-1 档位分数统一 ×10 转成 0-10 量纲,对齐四维 rubric 评分。 multi_tier_reward.py
hit_fraction 必需记忆命中比例 0..1,决定 gold / valid_alternative / partial 档位。 multi_tier_reward.py、real_mem_env.py
gold 最高档:A 类命中全部必需记忆且答案正确 = 1.00×10。 multi_tier_reward.py
premature(漏检) 该检索却 0 检索就作答(A 类)= -0.35×10。 multi_tier_reward.py、train_trace_real.py
wrong_category(误检) 检索到完全无关记忆(B 类检索干扰)= -0.85×10。 multi_tier_reward.py
retrieve_cost 每步检索成本惩罚,多步环境默认 0.5/步。 real_mem_env.py RealMultiStepEnv
step_cost 逐步检索成本函数,默认 -cost_lambda*scale*n_retrieve。 multi_tier_reward.py
rubric_score / Rubric 答案质量 1-10 分,终局 reward = rubric_score − λ_call·n_calls − λ_length·len。 docs §2.3、src/rewards/rubric_reward.py

五、RL 方法与训练

名词含义(紧扣本项目)出处
TRACE 借鉴 TRACE 论文的无 Critic 信用分配:冻结参考策略 + TD(λ) λ-return 把稀疏终局奖励展开成每步 dense credit。 src/credit/trace_credit.py、docs §8.3
λ-return(lambda_returns) G[t]=r[t]+γG[t+1] 反向展开 + A[t]=r[t]+γ((1−λ)G[t+1]+λA[t+1]),终局奖励沿轨迹向后传,离终点越近的步骤拿越多信用。 trace_credit.py
trace_advantages λ-return + 组内归一化 (a−mean)/std(GRPO 风格),解决"检索不检索都能答对时绝对 reward 全正、信号消失"。 trace_credit.py、docs §9.5②
trace_loss −Σ(lp_t·adv_t) + kl_coef·KL(π_ref‖π_θ),以参考策略为基线替代 critic。 trace_credit.py、docs §9.5③
冻结参考策略(π_ref) 训练开始时的策略快照(deepcopy/load_state_dict 后冻结),作 KL 锚点 + TRACE 概率提升基线。 trace_credit.py、train_trace_real.py rl_phase
KL 锚点 / kl_coef 约束策略漂移的正则系数(默认 0.05),替代 PPO 的 KL loss。 trace_credit.py、train_trace_real.py
critic-free 不用训练 Value 网络做自举估计,规避长程轨迹上 GAE 不稳定(本项目 GAE 曾 ep1750 崩溃)。 docs §8.3 / §9.5
SFT(阶段一) 专家轨迹多步行为克隆预热(A:retrieve×k→skip;B:一步 skip),给 RL 一个可泛化起点。 scripts/train_sft.py、train_trace_real.py sft_phase
两阶段 SFT → RL 训练 pipeline:Phase1 BC 预热 + Phase2 TRACE 式多步 RL(默认 2000 episodes)。SFT 固定 30 epochs,无收敛判据,BC 后直接进 RL。 train_trace_real.py、docs §8.4
专家轨迹(expert_trajectory) 多步专家决策序列:A 检索到 correct 位置后 skip(k 随机)、B 一步克制。 train_trace_real.py、train_sft.py
Behavior Cloning(BC) 用专家轨迹的 (state, action) 对做交叉熵监督训练。 train_trace_real.py sft_phase、train_sft.py
REINFORCE 早期 demo 用的策略梯度(−(logp·advantage) 配折扣回报−baseline)。 run_simple_demo.py、run_minimal_demo.py
PPO / GAE 设计文档首选/标配方案(PPO 稳定、GAE 曾崩溃被 TRACE 取代),train_ppo.py 仅占位。 docs §4.2 / §9.5、scripts/train_ppo.py
GRPO 组相对策略优化(同 prompt 多 rollout 组内归一化),设计文档备选,其归一化思想被 trace_advantages 采用。 docs §4.2 / §9.5②
长程信用分配 把多步轨迹的单一稀疏终局奖励归因到每一步("哪一步检索/克制带来终局成功")。 docs §9.5
advantage(优势) 每步 TRACE 展开得到的密集优势值,用于 loss = −Σ lp·adv。 trace_credit.py、overview.html
RLVR 与 DeepSeek-R1 verifiable reward 同一思路:用可验证结果替代人类偏好,本项目把"验证"落在每一步决策上。 docs §9.4

六、评测与基线

名词含义(紧扣本项目)出处
NoRet 无检索基线:GLM 直接作答,零工具调用。 scripts/compare_direct.py、export_arena.py
AEE_RG 固定门控基线(固定阈值 g=0.40):quality < AEE_THRESHOLD → retrieve,否则 skip。 compare_direct.py、compare_hard_v4.py
AEE_THRESHOLD = 0.40 固定门控阈值(历史最优),quality 低于它判为"需检索"。 compare_direct.py
TRACE 策略 RL 学习型门控(用 trace_decide 对真实 top-1 检索决策),与 NoRet / AEE_RG 三方对比。 compare_direct.py
glm_answer / glm_judge / glm_call src/utils/glm_client.py 三个核心函数:带重试的 GLM 调用、注入上下文的问答、四维 rubric 0-10 评分(只输出数字)。 src/utils/glm_client.py
GLM-4-Flash 智谱经济模型(openai 兼容,base_url https://open.bigmodel.cn/api/paas/v4),评测端到端作答与评分。 glm_client.py、README
四维 rubric judge 评分维度:相关度(30%) / 准确性(25%) / 完整性(25%) / 深度(20%),综合给 0-10 分。 glm_client.py glm_judge、rubric_reward.py
检索率 每类中 action==R 的占比(评估 A 该检索 / B 该克制)。 compare_direct.py stats_block
Wilcoxon(配对检验) scipy.stats.wilcoxon 对每个系统相对 NoRet 的 Δ 做显著性检验,输出 p 值。 compare_direct.py、compare_hard_v4.py
Cohen's d 配对 Δ 的效应量(mean/pooled_std),在 compare_hard_v4 中报告。 compare_hard_v4.py
正增益 某题系统得分−NoRet>0 的题数比例(如 正增益{n_pos}/{len})。 compare_direct.py
断点续跑(checkpoint) compare 脚本把结果逐条写 JSON,重启时读取已完成的 query 跳过。 compare_direct.py、compare_ultra_hard.py
export_arena / arena_results.json 把对比结果 JSON 转成前端擂台页需要的 {versions, tasks, metrics, config} 结构。 scripts/export_arena.py
版本擂台(arena) 前端对比页,展示 NoRet / AEE_RG / TRACE 三方的成功率/奖励/成本/耗时/工具调用四维排行榜。 frontend/arena.html
training_runs.json 训练结构化日志(run_id/version/episodes/eval_summaries/summary),前端 dashboard 直接读取。 train_trace_real.py、frontend/dashboard.html
run_id 每次训练的唯一标识(如 trace-<unix_ts>)。 train_trace_real.py start_run
success_rate / avg_reward / avg_quality dashboard 的 KPI/对比指标(success 阈值得分≥6.0)。 export_arena.py、dashboard.html

七、模型、工具链与基础设施

名词含义(紧扣本项目)出处
paraphrase-multilingual-MiniLM-L12-v2 384 维多语言 embedding 模型,中文检索可靠(A 类统一池 top-1 15/15),训练/评测/测试三端共用。 docs §11.2、train_trace_real.py
all-MiniLM-L6-v2 英文 embedding 模型,对中文相似度虚高不可靠(A 类 top-1 仅 5/15),已弃用(历史脚本 compare_hard_v4/ultra 仍在用)。 docs §11.2、compare_hard_v4.py
SBERT sentence-transformers 句子向量模型统称(SentenceTransformer.encode(normalize_embeddings=True))。 real_mem_env.py、compare_*.py
余弦相似度 归一化向量 np.dot 计算的相似度,用于检索排序与 quality。 real_mem_env.py RealMemStore.search
embedding(384 维) 文本向量化表示;2 动作基线 state 在其后拼 quality+hit_flag 成 386 维;3 动作扩展再拼 last_q + retained_count 成 388 维。 retrieval_policy.py、configs/default.yaml
ZHIPU_API_KEY / zhipu_key.json 智谱密钥来源:环境变量优先,其次本地密钥文件(已 gitignore)。 glm_client.py get_zhipu_key
HF_ENDPOINT HuggingFace 镜像环境变量(https://hf-mirror.com),训练/评测脚本统一设置。 compare_direct.py、train_trace_real.py
_glm_worker.py GLM 子进程 worker(从 stdin 读 {msgs,temp},stdout 写回答),规避 httpx 线程挂起/线程池死锁。 scripts/_glm_worker.py、compare_ultra_hard.py
serve.py 零依赖静态服务,白名单只暴露两个面板 + 两个数据 JSON,防密钥泄露。 serve.py
checkpoint(trace_policy_real_emb.pt) 训练产物,net.* 键 + strict=True 加载,避免"静默随机策略"。 retrieval_policy.py load_policy、tests/test_shared.py
端到端契约 测试保证 checkpoint 是 386 维 self.net 结构、能被共享策略 strict 加载、A/B 奖励自洽等(2 动作基线契约;tests/test_3act.py 单独覆盖 388 维 / 3 动作契约)。 tests/test_shared.py

八、未出现 / 未落地的术语

以下名词经全面扫描确认未出现在本项目代码/评测中——列在此处以避免误读为已使用。

名词状态出处
pass@k 代码/文档中未出现(无任何 pass@/pass_at_k 命中);评测为单次采样。 —
Function Calling(LLM 工具调用) 代码中未使用(仅 tool_calls 字段,含义是检索动作计数,不是 LLM function calling;glm_client.py 不传 tools 参数)。 —
Qwen3-0.6B / 1.7B 仅在 README「小模型实验」提及,无落地代码。 README
ChromaDB 仅 docs §7 待决策与 train_ppo.py 占位注释提及;实际实现用内存 numpy 检索,未引入。 docs §7
KL Divergence / Win Rate 设计文档 §5 评估指标表列出,但评测脚本未实际实现。 docs §5
DPO 设计文档提到的离线 warm-up 备选,代码中未实现。 docs §4.2
AI 面试官 Agent 复用同一套"何时动记忆"决策底座的第二个应用,尚未落地(experiments/interview_agent 为空)。 README「当前阶段」
Glossary 依据 docs/agentic_rl_design.md 与源码逐条核对;术语定义以代码实际实现为准。
京ICP备2024087118号-1
🎁 大厂面试真题精选 免费领 · 私信「资料」30 秒到手 去小红书领免费资料 →
×