这是一份面向可复制的 AgentCF 复现笔记记录了代码/配置/数据/评测的完整落地过程给出从论文到跑通的最短路径并逐条记录我踩过的坑与规避办法。目录一、论文背景与方法1.1 背景动机1.2 方法框架1.3 推断阶段的三种提示策略二、原文结果与贡献2.1 实验与评测设置2.2 主要排名结果2.3 设计选择与消融观察2.4 行为模拟结果2.5 作者自述贡献三、 获取作者代码数据集并配置环境3.1 获取代码与数据集3.2 配置新环境四、实验设置4.1 实验基本设置4.2 优化 CD 数据集上的用户代理和项目代理4.3 评估即交互推理4.4 直接在CD数据集上加载预训练的用户代理和项目代理五、结果复现5.1 指标5.2 简要解读5.3 注意事项6. 复盘与思考6.1 我遇到的问题精简版6.2 我学到的6.3 我的选择清单7、致谢原文地址官方论文地址代码地址官方代码地址一、论文背景与方法1.1 背景动机传统推荐MF/NCF/SASRec 等依赖数值交互点击/评分对复杂偏好与语境表达不足交互与解释能力弱。且现有 “LLM for Rec” 多把 LLM 当打分器/文本特征器但现实里语言相似 ≠ 行为相似如“尿布—啤酒”共现但语义无关。因此需要一种能学行为共现、又保留解释与自我修正的 LLM 推荐范式。原文说法1.2 方法框架从真实时间序列采样成对的正负样本负样本刻意选热门且排在前面制造强干扰。LLM 读取用户短期记忆与两个物品记忆完成二选一并输出简短理由。与真值对照选对就记一条证据选错就触发协作反思只编辑用户短期记忆和正样本物品记忆负样本不改以免影响它在其他用户上的可迁移性最后把旧的短期记忆归档进长期记忆方便后续检索。如此循环若干轮直到与真实一致或达到步数上限用户–物品–用户的链路上会自然形成“偏好传播”后续推断就更贴近真实个性。原文说法记忆设计很朴素但关键用户有一个短期记忆近期偏好易于快速改写和一个长期记忆库历史片段推断时面向候选做相关检索物品有一个统一记忆用标题、类目等身份信息初始化随后持续注入“谁喜欢我”的受众画像。把 embedding 换成“可读可改的语言记忆”训练过程就变成了“可解释、可定位、可修复”的记忆治理。1.3 推断阶段的三种提示策略AgentCF_B基础只用用户短期记忆和候选物品记忆直接排序通用且成本最低。AgentCF_BR检索专长在长期记忆里按候选做检索把“与候选相关的个性化专长片段”并入上下文长期信息很丰富时更有效。AgentCF_BH序列增强在稀疏场景把历史交互过的物品记忆也并入上下文让大模型临时承担轻量的序列建模角色。我复现这套方法看中的价值主要有四点双侧建模把“谁喜欢谁”的关系学得更扎实也更容易解释。不微调 LLM只编辑记忆成本友好且可控。稀疏、冷启动场景下能靠 BH、BR 补上下文鲁棒性不错。每一步都有理由文本与可追溯的记忆改写排错和 AB 调优非常直观。二、原文结果与贡献2.1 实验与评测设置数据Amazon Reviews 的CDs Vinyl与Office Products两个子域各自再划分“稠密/稀疏”两个 100 用户子集用于代理训练与评测。评测留一法最后一条交互为真值主指标NDCG1/5/10每个测试实例重复三次取均值。基线BPR、SASRec同时报告全量训练与采样训练版本、Pop、BM25、以及把 ChatGPT 当零样本排序器的LLMRank。AgentCF 推断配置AgentCF_B只用用户短期记忆Ms_u与候选物品记忆Mi、AgentCF_BR从用户长期记忆Ml_u检索与候选相关的片段M_u^r加入上下文、AgentCF_BH在稀疏场景把历史交互过的物品记忆{M_{i_k}}也纳入上下文用于轻量序列增强。2.2 主要排名结果整体上AgentCF 的三个变体在四个数据集的大多数指标上优于传统 CF/序列模型与零样本 LLM 排序其中基础版B已能稳定越过强基线。当用户长期记忆较为丰富时BR在NDCG5/10上进一步领先因为能把“与候选强相关的历史专长片段”检索进上下文证据更充分。在交互稀疏的场景尤其 OfficeBH优势更明显它让模型在推断时临时承担一小步序列建模用历史物品记忆补足上下文从而显著缓解冷场景下的排名退化。三种配置不是此消彼长而是面向不同数据形态的“即插即用”增强先跑B看长期/序列信息是否充足再决定是否打开R或H。2.3 设计选择与消融观察热门优先的负采样能稳定地区分“流行度驱动”与“个性化驱动”迫使代理依赖个性化记忆而不是走流行度捷径。只编辑用户短期记忆与正样本物品记忆不编辑负样本物品记忆更利于稳定泛化一旦把负样本物品“写黑”它在其他用户上的潜在吸引力会被不必要地削弱。在小样本与高 API 成本约束下采样训练的 BPR/SASRec相比其全量版本明显退化而AgentCF不依赖大批量梯度更新反而能凭“可编辑的语言记忆”保持竞争力。这些设计共同把“学习重心”从参数梯度迁移到“记忆治理”以文本方式记录、对齐与纠错更可审计也更利于排错。2.4 行为模拟结果阅读评论的态度转移用户代理在决策前若先读其他用户评论正评显著提高选择概率负评明显降低选择概率而且更信任“与自己画像更接近的评论者”与真实平台行为一致。新物品的增温新物品代理在进入排序前先与热门物品代理交互一次进行“增温”其后续排序名次会提升说明物品之间发生了“受众画像”的迁移为冷启动提供了无需额外预训练的自然路径。偏好传播可视案例沿“用户—物品—用户”的链路多轮交互后出现风格与情感的逐跳扩散形成可解释的协同信号。2.5 作者自述贡献双边代理建模首次同时把用户与物品建成自治语言代理在同一语言空间里协同刻画双边关系。无微调的学习闭环提出“对比选择 → 与真实对照 → 协作反思”的闭环不改 LLM 权重只对可读可改的语言记忆进行定点编辑从而在语言空间内复现协同过滤。实证与行为证据在真实数据上展示了个性化排名收益并呈现阅读评论的态度转移、物品间增温、偏好随交互传播等类人行为现象支撑智能体在推荐中的可用性与可解释性。贡献的关键词是“记忆、反思、双边”这是把协同过滤的统计本质翻译成一套可解释、可调、可复核的语言流程。三、 获取作者代码数据集并配置环境3.1 获取代码与数据集首先在GitHub上获取源代码并下载测试数据集之后将相应数据集dense 版本放于此目录或在 YAML 中指定绝对路径data_pathdataset/CDs-100-user-dense3.2 配置新环境我的做法是建立一个Conda 独立环境名字就叫agentcf。毕竟以后经常切换多个实验这样做一条命令激活就能复现创建环境并安装依赖conda create-n agentcf python3.11-y conda activate agentcf pip install--upgrade pip pip install-r requirements.txt pip installopenai0.28.1pyyaml pandas numpy tqdm faiss-cpu由于原文需要调用OpenAI的API,需要读者在代码中放入自己的api令牌密钥若怕泄露可以用环境变量读取Dispatches requests to OpenAI API asynchronously. Args: messages_list: List of messages to be sent to OpenAI ChatCompletion API. model: OpenAI model to use. temperature: Temperature to use for the model. max_tokens: Maximum number of tokens to generate. top_p: Top p to use for the model. Returns: List of responses from OpenAI API. 四、实验设置4.1 实验基本设置在 .agentcf/props/AgentCF.yaml 文件中有关于基础实验设置其中embedding_size:64# 推荐侧嵌入维度如与RecBole/模型侧对齐llm_model:gpt-3.5-turbo# 对话式模型用于各类Agent对话/推理llm_temperature:0.2# 训练/生成阶段温度略带随机性利于探索llm_temperature_test:0# 测试/评测阶段温度0保证可复现sample_num:200# 每轮采样的候选成对样本量用户-物品二选一对数api_batch:20# LLM请求的并发/批量大小后端会做节流/聚合chat_api_batch:10# Chat接口批量大小通常低于通用接口evaluation:basic# 评测模式basic / rag / sequential 三选一接下来是用户和物品的agent提示词以及前向反向和评测阶段的prompt这里就不展示了原作者已经给出重点是要将自己的api密钥写入api_key_list:[sk-***]4.2 优化 CD 数据集上的用户代理和项目代理cd agentcf/export api_baseYour openai.api_basepython run.py-m AgentCF-d CDs-100-user-dense--train_batch_size20--eval_batch_size200--max_his_len20--MAX_ITEM_LIST_LENGTH20--epochs1--shuffleFalse--api_batch20--test_onlyFalse关键含义–d CDs-100-user-dense选择数据配置/别名为 CDs-100-user-dense稠密版。通常会映射到 props/CDs-100-user-dense.yaml 和 dataset/CDs-100-user-dense/–test_onlyFalse先训练再评测。如果设为 True则跳过训练、直接用已存在的权重做评测本命令明确是 dense 版本。换成 sparse请同步改 -d/YAML 与 data_path并在文中写清用户数/物品数/交互数差异避免评测协议不一致导致“假偏差”4.3 评估即交互推理cd agentcf/export api_baseYour openai.api_basepython run.py-m AgentCF-d CDs-100-user-dense--train_batch_size20--eval_batch_size200--max_his_len20--MAX_ITEM_LIST_LENGTH20--epochs1--shuffleFalse--api_batch20--test_onlyTrue关键含义–max_his_len20用户历史序列截断到最近 20 条作为代理/模型的输入窗口–test_onlyTrue跳过训练直接做评测/交互推理4.4 直接在CD数据集上加载预训练的用户代理和项目代理cd agentcf/export api_baseYour openai.api_basepython run.py-m AgentCF-d CDs-100-user-dense--train_batch_size20--eval_batch_size200--max_his_len20--MAX_ITEM_LIST_LENGTH20--epochs1--shuffleFalse--api_batch20--test_onlyTrue--loadedTrue--savedFalse--saved_idx1000关键含义–test_onlyTrue只做评估/交互推理不进入训练环节–loadedTrue从磁盘加载预训练好的“用户代理/物品代理状态”–savedFalse本次不保存新的代理状态或权重纯评估–saved_idx1000指定要加载的快照编号/版本号例如第 1000 次保存的代理状态需要和磁盘上已有文件对得上五、结果复现我训练用户代理/物品代理的前期执行过程为接下来就是进行训练与评测5.1 指标Metric135710Recall0.100.360.490.690.98NDCG0.100.24960.3030.3720.45955.2 简要解读Recall10 ≈ 0.98前 10 名基本覆盖目标排序前列稳定。NDCG 随 K 上升从 0.101到 0.459510相关项更集中在 Top-10而非绝对第 1。时间成本约 1h38m 完成一次完整评估符合“用户代理 × 物品代理”的交互式推理特征。5.3 注意事项候选池协议全排序 vs 采样会显著影响 Recall/NDCG切分方式时间切 vs 随机切差异明显在“实验设置”中固定并公开。多 seed当前为单次评估建议 ≥5 个 seed 报均值±方差。预训练代理对齐若加载同域CDs-dense且同模板的预训练代理结果更稳跨域/改模板会引入漂移。6. 复盘与思考这次复现主要是把“工程—协议—评测”三件事对齐。下面只留核心结论便于读者复用。6.1 我遇到的问题精简版①CLI 告警与生效日志提示will not be used in RecBole是 RecBole 不解析-m/-d的常规行为实际由run.py用它们选择 YAML 与数据。通过“已加载的 YAML data_path”日志自证即可。②dense / sparse 的理解与取舍dense过滤后更稠密冷启动少、结果稳sparse更贴近长尾波动大但更接近实战。复现论文用 dense做鲁棒性再跑 sparse。训练在哪个版本评估就用哪个版本避免 ID 映射不一致。③评测协议对齐候选池全排序/采样、切分方式时间/随机、负采样与指标实现需写死在 YAML并在文中公开否则容易出现“假偏差”。④评估与训练的开关--test_onlyTrue只评估False训练后评估。epochs1仅用于冒烟不用于对照。⑤预训练代理加载--loadedTrue --saved_idx…需满足同数据域、同模板、同截断长度否则会维度不匹配或效果漂移。⑥API 端点与并发设置api_baseapi_batch受限流影响需要折中。交互式评估耗时在可接受的 1h 区间。⑦版本与随机性固定仓库 commit、Torch/RecBole/CUDA 版本并保存pip freeze多 seed 报均值±方差。6.2 我学到的协议先于数值候选池、切分、负采样、指标定义不一致任何数值对比都失真。先冒烟再放量用最小配置验证管线通再上完整训练与多 seed。YAML 是“单一事实源”把关键超参与评测项都写进 YAML并在日志中打印方便自证与复刻。同域加载更稳同数据、同模板、同长度的预训练代理能显著节省时间并减少波动。可复制性是第一性版本锁定、日志完整、结果可重跑比单次最好值更有研究价值。6.3 我的选择清单① 复现论文表格使用CDs-100-user-dense评测协议写死跑 ≥5 个 seed保存日志与环境。② 验证鲁棒性在CDs-100-user-sparse复跑同配置关注长尾场景的跌幅。③ 省时评估同域加载预训练代理--loaded --saved_idx评估前核对 ID 映射与模板。小结这次复现把工程脉络与评测协议理顺了对本科阶段的研究实践而言可复制性与自证能力比追求单点分数更重要7、致谢感谢原作者开源代码与配置文件感谢师兄在我复现工作中对我的耐心指点希望这篇复现博客能帮助到更多需要的人。