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

这个业务这么做,价值收益是什么?公司为什么做它?

一句话:模型和记忆库都是现成的,缺的只是"要不要查记忆"这一念之差—— 公司投这个项目,是用极小的训练成本(2 参数门控,~2k 参数 MLP,零推理开销),把每次问答的 质量和成本同时压到最优。
直接收益(降本):① 省人工知识获取——新同学 / 跨组问部门事实不用翻 wiki、不用打断资深同事,秒答; ② 省 LLM / 检索调用——该克制时克制,每次世界知识问答少一次检索(少 embedding / 注入 / token); ③ 省返工防误导——B 类误检会灌金融 / 医疗干扰 → 答错 → 返工甚至误导决策。
质量收益(增效):A 类 100% 命中,私有问题不再靠猜,还附上可写进汇报的硬数字 (治理下架 2100 张表月省 12 万 / p99 980→145ms / CTR 3.2%→7.8%);B 类 0 误检,答案干净。 直接提升新同学融入速度和平台汇报 / 决策的数据依据。
组织 / 战略收益:① 知识资产化——部门 2024 全年的经验从"人脑 + 散 wiki"变成会主动回答的资产, 不随人走(离职 / 休假零流失);② 决策底座可复用——"何时动记忆 / 何时该追问"复用到 AI 面试官 Agent, 一次投入多处复用;③ 样板效应——数据平台部自己先落地一个能跑的内部 AI 助手,向全公司证明 AI 在真实内部场景能落地,后续业务线照着复制。
为什么是这个点:RAG 助手"无脑检索会污染、不检索答不出私有问题","要不要查"是唯一真正难、 又影响最大的一环——它决定助手是"演示级"还是"员工天天用"。
诚实注:这是 30 条记忆的 toy 环境,金额 / 效率是方向性示意,不是精确 ROI; 但收益机制是真实的——检索决策的正确性直接乘在每一次问答上。

这个 Agent 具体是怎么被用的?一次完整问答走查

一句话:不是"问一句查一次"的开关,而是多步决策——该检索时逐条核对候选记忆、 不对的 forget 掉、检索错了能自我清理,最后才作答(3 动作 {retrieve, forget, answer})。
完整走查(数据工程师问血缘):① 提问「数据血缘追溯系统依赖哪个开源组件实现?」; ② Agent 检索第一条候选——医疗干扰「冠心病防治」,判断不对 → forget(成本 -0.2); ③ 再检索——「国债发行」,继续 forget;④ 检索到「血缘基于 Apache Atlas 开发,二期跨源异构 MySQL+PostgreSQL+Hive,覆盖率 87%」→ 命中,停止检索,干净上下文作答 → 答对 + 附上覆盖率。 中途拿到的干扰,一条都不会带进答案——forget 就是"犯错但不带错出门"。
角色用法(各自在写周报 / 做汇报 / 评审时秒查硬数字): 数据工程师问血缘 / 慢查询、平台负责人问治理数字(2100 张表月省 12 万)、中台架构师问选型教训、 安全工程师问等保控制域(5 大类 58 项)、算法工程师问获客 ROI(28 元/人 vs 广告 85,ROI 3.04)。
价值账:时间(翻 wiki 几分钟 → 秒答)、成本(B 类独立测试集 3act-RL 检索率 6% → 94% 世界知识问答零检索)、质量(A 命中 100% / 清洁上下文 100%)、风险(forget 恢复把"误检污染" 机制化兜住)。业务数字锚定 data/business_context.json 的 usage / value_ledger,决策数字锚定 data/ablation_3act.json。
诚实注:30 条记忆 toy 环境,金额为方向性示意。

这个项目用的是什么强化学习方法?

TRACE 式策略梯度(借鉴 TRACE 论文,src/credit/trace_credit.py)。不是 PPO——无 critic、无 clip; 用 TD(λ) λ-return(γ=0.99, λ=0.95)把稀疏终局奖励反传成每步 advantage;冻结 SFT 快照 π_ref 做 KL 锚点。 两阶段:SFT 行为克隆预热(交叉熵,固定 30 epochs)→ RL(trace_loss)。
为什么选它:① 策略只是 3 层 MLP(~2k 参数;2 动作基线平均 3.67 步,3 动作扩展平均 7.33 步) ——PPO 的 GAE / clip / 价值网络 / 大 batch 是为 LLM、Atari 那种高维大策略准备的,这里直接策略梯度就稳,纯属多余复杂度; ② 奖励规则可验证(hit_fraction / answer_correct),有 ground truth,不需要训练 reward model; ③ 奖励稀疏(只有终局 ±10),λ-return 递归反传把"哪步检索/克制带来终局成功"算成每步 credit,不需要价值网络(critic-free),少一个网络就少一份估计偏差; ④ 从 SFT 快照起步,KL 锚点(kl_coef=0.05)限制漂移,替代 PPO 的 clip 机制; ⑤ 组内归一化让多步 A 类与一步 B 类的 advantage 可比。
一句话:任务小到不需要 PPO、奖励真到不需要 reward model、稀疏到必须 λ-return——TRACE 是三者的交集。
消融注:30 条查询的小环境里 SFT 已能达成同等训练集结果,RL 的端到端增益不显著 (data/ablation_sft_vs_rl.json)——选 TRACE 是机制完备性;3 动作扩展已把轨迹拉长到 A 类平均 7.33 步(2 动作 4.4),λ-return 的长程信用分配真正展开,但 RL 的超越仍要更大记忆池 (数百条)才能被测出来。

SFT 到 RL 的过渡标准是什么?SFT 训到什么程度会考虑 RL?

没有收敛判据——SFT 固定 30 epochs 交叉熵(训练 acc 通常 95%+),跑完直接进 RL。 消融校准:SFT 行为克隆已编码主要判别——训练查询上 SFT-only 与 RL 结果完全相同 (A 100% / B 0% / avg_R 9.15);RL 在未见查询上做小幅泛化修正(50 条未见概念题检索率 12%→8%, McNemar p=0.50 不显著,见 data/ablation_sft_vs_rl.json)。

该项目做 RL 用什么框架?

纯 PyTorch 手写,无现成 RL 框架(无 RLlib/Stable-Baselines 等)。策略是 3 层 MLP( RetrievalPolicy),损失手写 cross_entropy / trace_loss,优化器 Adam + grad clip 1.0。 依赖清单只有 torch / numpy / sentence-transformers / openai 等。

项目有没有做 pass@k 计算?

没有。评测为单次采样(无 pass@k / pass_at_k 命中),策略决策是确定性的单条轨迹。

怎么调 prompt 的?

Prompt 刻意保持极简(src/utils/glm_client.py):
· 作答(glm_answer):注入检索到的参考信息 + 「请基于参考信息回答,如果没有相关内容则基于你的知识回答」,再接问题;
· 评分(glm_judge):四维 rubric —— 相关度(30%)/ 准确性(25%)/ 完整性(25%)/ 深度(20%),综合 0-10 分,温度 0.1 只输出数字。
决策逻辑全部放在策略网络里,不进 prompt。

Agent RL 与 Reason RL 的区别是什么?

Agent RL(本项目)= 外部环境交互 + 语义多档 reward;Reason RL(R1/o1)= 内部推理 + verifiable reward。 本项目学「何时动记忆」的决策策略,不是生成推理链。

本项目的 Agent Framework 是什么?

没有现成 Agent 框架(无 LangChain / LLamaIndex / AutoGen)。Agent = 自训的 RetrievalPolicy( 3 层 MLP,386 维输入 → {检索/克制});环境、记忆库、奖励、评测全手写;GLM-4-Flash 只做作答与评分,不参与决策循环。

本项目是 ReAct Loop 模式吗?

不是。ReAct = LLM「思考→调工具→观察」的推理循环;本项目的决策者是 MLP,直接对 386 维状态向量输出动作, 训练循环全程不调用 GLM。最接近的类比是自适应检索门控(RAG gating)+ RL 训练门控。

有没有执行 Function Calling?

没有。glm_client.py 不传 tools 参数,GLM 是纯文本问答;代码里的 tool_calls 字段指 检索动作计数,不是 LLM 函数调用。

Rollout / Trajectory 数据采集是怎么做的?

run_episode(scripts/train_trace_real.py):随机抽一个 env,策略逐轮决策 (retrieve=0 / skip=1),每步记 log_prob + ref_log_prob(SFT 快照)+ 即时奖励(-0.5 检索成本), 直到 skip 或队列耗尽给终局多档奖励。采完一条立即 trace_loss 反传更新(在线单轨迹,不存 buffer)。 SFT 阶段则用专家轨迹脚本生成 (state, action) 对做行为克隆。
轨迹具体长这样(state = query_emb(384) + [下一候选质量, hit_flag],动作 0=检索 / 1=克制, real_mem_env.py):
· A 类(correct 排队列第 3 位):检索 →(干扰1, -0.5)→ 检索 →(干扰2, -0.5)→ 检索 →(命中 correct, -0.5, hit_flag 变 1)→ 看到 hit_flag=1 克制 → 终局 +10,合计 8.5;平均 3.67 步 = 命中即停;
· B 类:一步克制 → 终局 +10(误检索干扰则 wrong_category -8.5)。
终止:skip / 队列耗尽;correct 位置训练时随机(1..max_retrieve-1),防背题。

Agent 的核心架构是什么?相比单纯调用大模型 API,解决了哪些问题?

数据流:query → 386 维状态(query_emb + 候选记忆质量 + hit_flag)→ RetrievalPolicy(3 层 MLP)→ {检索/克制} → 检索则注入候选记忆(每步 -0.5), 克制则 GLM 带参考信息作答;终局由 hit_fraction/类别给多档奖励。
相比裸调 API:① 私有记忆缺失(A 类该检索不检索就答不出)→ 学会该检索就检索; ② 跨域干扰污染(无脑 RAG 把金融/医疗干扰灌进答案)→ 学会该克制就克制; ③ 成本与延迟(命中即停,A 类平均 3.67 步);④ 固定阈值门控(AEE_RG 0.40)方向固定、是死的 → 训练的门控是数据驱动的(SFT 起点 + RL 修正;消融显示 RL 修正在小样本上不显著,见 data/ablation_sft_vs_rl.json)。

Function Calling 中如何设计工具描述和参数 Schema 提升调用准确率?

工具描述 = 选对工具:动词开头写清目的 + 写清「何时不该用」(边界)+ 与相邻工具区分 + 语义化命名;
参数 Schema = 填对参数:严格类型 / 枚举 / 范围 + required 显式 + 参数描述写语义·单位·示例 + 参数少而准 + 扁平化;
系统层:工具宁少勿多、temperature 调低、few-shot、建 FC 准确率评测集 A/B 回归。
回扣本项目:本项目不用 FC,检索决策由 RL 训练的门控保证准确率, 规避了 LLM「语义匹配 + 参数编造」的不确定性;若哪天 FC 化,就需按上述原则设计 search_memory 的描述并建评测兜底。

本项目用的是 ReAct 还是 Plan-and-Execute 框架?

都不是——这两个分类都预设「Agent = 会推理/规划的 LLM」,本项目把 LLM 移出了决策循环。
以 A 查询「数据血缘追溯系统依赖哪个开源工具实现？」为例:run_episode 里 obs = [query_emb(384) + quality(0.72) + hit_flag(0)] → 3 层 MLP 直接输出 {retrieve/skip} → 命中后 hit_flag=1 触发 skip,终局 +10。
对比:ReAct 每步让 LLM 写 Thought + 调工具;P&E 先让 LLM 生成多步计划再执行。 本项目既无文本推理、也无计划对象,「该不该查」是网络对状态向量的决策,终止是学出来的(hit_flag 命中即停,A 类平均 3.67 步)。
正确归类:训练的自适应检索门控(adaptive retrieval gating)——把检索决策变成可训练的 MDP 门控, SFT 专家轨迹预热 + TRACE RL(λ-return 反传终局奖励),训练查询上落地 A 命中 100% / B 误检 0% (消融显示 SFT-only 同样达到,RL 的差异在未见查询泛化上且不显著,见 data/ablation_sft_vs_rl.json)。

怎么让模型老老实实调用工具,不瞎编参数?

① 严格 Schema + 只提取不生成:参数写死类型 / enum / 范围,描述写明「参数必须来自对话原文,未提供的不填、不要推测」;参数是提取不是生成;
② 框架层强约束:strict function calling / JSON mode,保证返回一定是合法 JSON 且类型正确;
③ 缺失值兜底:必填参数没出现就让模型不调用或要求澄清,宁缺勿编;
④ 校验 + 重试:调用前 jsonschema.validate,不过就把具体错误回传给模型重试一次;
⑤ 工具描述可判别 + few-shot 意图映射 + temperature 0~0.1 + 工具宁少勿多;
⑥ 建 FC 准确率评测集(工具选择 + 逐参数抽取)回归。
回扣本项目:本项目直接绕开——检索决策不用 FC,参数空间压成 386 维定长向量, MLP 只输出 2 个 logit,没有参数可编。最可靠的防编参是让模型没有参数可编。

工具调用失败、超时了怎么办?

先纠正前提:本项目决策循环里没有会超时的工具调用——检索动作是 MLP 门控输出,执行只是本地 numpy 点积(RealMemStore.search),无网络、物理上不会失败。真正会失败的只有 GLM 作答/评测调用,四层防护:
① 客户端超时:glm_call 单次 timeout=30,请求挂死也有上限(glm_client.py:66);
② 指数退避重试:默认 retries=3,失败后等 3s/6s/9s 重试,幂等调用重试安全(glm_client.py:63-75);
③ 降级 + 断点续跑:评测每个 GLM 块包 try/except,失败记 score=0.0 只打 [WARN], 不拖垮整轮;每条结果立即写 checkpoint,崩了从断点恢复不重头(compare_direct.py:120-152,165); glm_judge 解析不到数字回退 5.0 中性分;
④ 限速防限流:每条间 sleep(0.5),超时很多时候其实是 429 限流。
通用教训:把不可靠调用移出决策热路径(决策走本地计算);有写副作用的工具重试前必须先幂等去重。 五件套 = timeout 卡死 + 退避重试 + 失败降级 + 断点续跑 + 限速。

Agent 已经会规划、调工具、反思,也接了 Memory 和 Evaluator,为什么还要 Agentic RL?

规划/工具/反思/Memory/Evaluator 全是"能力"和"裁判",没有一个是"学习"——Evaluator 只打分, 分打出来就丢掉,没有东西因此变好。
代码证据:compute_terminal_reward(multi_tier_reward.py)产出 ±10/±8.5 的 float,但它没有梯度; SFT 的 F.cross_entropy(logits, by)(train_trace_real.py)梯度只来自专家样例,reward 不出现—— 只有 RL 的 trace_loss 里 -(lp·adv).sum()/T 把 reward 经 λ-return 变成梯度回写策略。没有这一行,Evaluator 就是死成绩单。
RL 的修正有限(消融校准):B 类"检索干扰 -8.5"、A 类每步 -0.5 的奖励确实让策略学到克制与命中即停——但 SFT 行为克隆已编码大部分判别:训练查询上 SFT-only 与 RL 结果完全相同;50 条未见概念题上 SFT-only 检索率 12%、RL 8%(McNemar p=0.50 不显著),且 RL 检索的 4 条 ⊆ SFT 的 6 条。 诚实结论:判别主要来自 SFT + 域分离特征,RL 在本环境只提供小幅且统计上不显著的泛化修正; λ-return 的长程信用分配需更长轨迹 / 更大记忆池才有发挥空间(见 overview"与真实 Agent RL 的四大约束")。 2026-08-13 已把决策链从 2 动作扩成 3 动作(retrieve→forget→answer,A 类干净最优 4~10 步、 平均 7.33 vs 2 动作 4.4,λ-return 终于沿异构长链展开);轨迹拉长后 RL≈SFT 的结论不变, forget 在污染惩罚(+7/干净+10)下真正工作(清洁 15/15、独立 B 测试集干净作答 50/50)。 扩池重训(§8.8)后 RL≈SFT 第三次证实;oracle 上界核对(scripts/oracle_3act.py,零 GLM 成本)进一步说明 不是 RL 失败:RL 与 SFT 都精确触达理论最优 avg_R 8.506、总 headroom=0、165/165 env 触及—— 任务被 SFT 行为克隆解到最优,RL 无奖励余量可挖。 本页 2 动作表述 + 3 动作扩展小节共同构成当前设计;其余各节可复用 3 动作版(见 overview"3 动作 MDP 扩展")。 一句话:系统再完备也没有"学习"这一项,Agentic RL 是唯一让分数变成进步的一环。

本项目的损失函数是什么?

SFT = F.cross_entropy(logits, action);RL = −(lp_t·adv_t).sum()/T + kl_coef·KL(π_ref‖π_θ)。 adv 来自 λ-return(组内归一化)。

信用分配是怎么做的?

critic-free:不用 value 网络自举(GAE 曾在 ep1750 崩溃)。λ-return 把终局奖励沿轨迹反向展开成每步 advantage (G[t]=r[t]+γG[t+1],A[t]=r[t]+γ((1−λ)G[t+1]+λA[t+1])),再组内归一化 (a−mean)/std 解决「检索不检索都能答对、绝对 reward 全正」信号消失的问题。

RL 训练 reward 如何设计?

每步检索成本 -0.5 + 终局多档奖励(SCALE=10): A 类全命中且答对 +10 / A 漏检 -3.5 / B 克制答对 +10 / B 误检 -8.5; 硬门槛 wrong_category / loop / max_steps 直接判负。两个可验证量 = hit_fraction + answer_correct —— 无 RM、无偏好标注,是 RLVR(verifiable reward)思路。多档设计给 TRACE 提供有区分度的相对排序信号。

评测 benchmark 是怎么做的?

scripts/compare_direct.py 三方对比 NoRet / AEE_RG(固定阈值 0.40)/ TRACE: 真实检索(RealMemStore top-1,多语言 embedding 下 A 类统一池 15/15 命中);B 类域分离(候选池只含干扰记忆); 四维 rubric 打分 + Wilcoxon 显著性检验 + 断点续跑。独立 B 类评测集(testset_b_real.json,50 条真实 HF 数据)构建中, 用于验证策略在未见过的查询上的克制泛化。

为何有时不直接用 Rule-based Reward 而要训 Reward Model?(针对 Function Call 等封闭任务)

规则奖励适用于结果可精确验证的封闭任务(格式检查 / pass@k / 终局布尔判定); 当「成功」判定依赖语义质量或中间多步状态时,规则写不全,才需要训 reward model。 本项目用环境语义多档 reward(hit_fraction + answer_correct),可验证、零人工,不需要 reward model。

多步任务中 Agent 陷入循环或偏离目标时,如何设计终止条件与反思机制?本项目怎么体现?

本项目用机制化处理而非 LLM 自我反思,四层:
① 环境终止:skip 结束、候选队列耗尽强制终局、最多 max_retrieve=5;
② 奖励惩罚:硬门槛直接判负——repeated_loop → -6.5、 max_steps_hit → -5.0、wrong_category → -8.5,λ-return 反传惩罚导致循环的步骤;
③ Harness 反思(ActionGuard):机械检测「达上限 / 与上次检索结果相同无新证据 / 已全命中仍检索」并拦下;
④ 状态反思信号:hit_flag + quality 让策略显式知道「查够了没」,学会命中即停(A 类平均 3.67 步)。
效果:策略想循环也循环不起来(Guard 拦)+ 循环了也拿不到正奖励(-6.5)+ 状态里永远有「查够没」提示。

这个项目有什么风险?

结构性风险(直接决定策略是否"是真的"):
① A 类检索泛化未独立验证——独立评测集只覆盖 B 类克制,A 类依赖私有记忆无法从 HF 取;
② 训练 reward 是代理——hit_fraction 代理"能答对",命中≠真答对,训练端未用 GLM judge 真分;
③ 训练/评测检索语义不一致——训练用固定 candidate_queue,评测用真实 top-1。
工程可缓解:记忆池小且手写(已用 GLM 合成扩到 ~200 条,见 §8.8;扩池后 RL≈SFT 结论不变)、 单 embedding 过拟合、judge 噪声、reward hacking、安全/隐私、前端数字过时。 详见 overview.html「局限与下一步 → 风险评估」。

本项目有什么 Bad Case,怎么解决的?

前端页面怎么访问?

本项目自带 python3 -m http.server 8209(或 serve.py 白名单服务 8029),页面: /frontend/dashboard.html(训练总览)、/frontend/arena.html(版本擂台)、 /frontend/overview.html(项目讲解)、/frontend/glossary.html(名词概念)、 /frontend/faq.html(常见问题,本页)。