---

[!IMPORTANT] 🔥 最新消息!!!

• [2025/07] 我们提供了一个快速入门脚本，让使用MemAgent变得极其简单，请参阅下方的快速入门部分。
• [2025/06] 我们发布了RL-MemAgent-14B和RL-MemAgent-7B模型，在350万 token 上下文的任务中实现了几乎无损的性能。

---

📖引言

我们提出了一种全新的长上下文处理框架——MemAgent，它通过端到端的强化学习直接优化长上下文任务，而无需改变底层模型架构。MemAgent展现了卓越的长上下文能力，能够在3.5万文本上训练的8K上下文基础上，外推至350万的问答任务，性能损失低于5%，并在51.2万 RULER 测试中达到95%以上的准确率。

亮点：

• 🚀 新型记忆机制 引入了MemAgent架构，能够在固定上下文窗口内处理任意长度的输入，突破了传统上下文窗口长度的限制。
• ⚡ 线性时间复杂度 打破了长文本处理中的计算瓶颈，实现了资源消耗与文本长度的线性增长。
• 🎯 强化学习驱动的外推 通过MemAgent架构的强化学习训练，使模型能够在外推至更长文本时保持极低的性能下降。

多轮强化学习框架

我们使用可验证奖励的强化学习（RLVR）来训练MemAgent，并扩展了DAPO算法，以支持多轮独立于上下文的对话中代理工作流的端到端优化。

结果

RL-MemAgent在超长上下文处理中表现出色：

• 14B模型： 在350万 token 的任务中性能下降不到5.5%，实现了真正的无损外推。
• 7B模型： 在最长上下文中仅出现11%的性能下降，显著优于现有的长上下文模型。

快速入门

quickstart.py 提供了一种简单的方式来开始使用MemAgent，既支持本地部署，也支持与在线模型服务的集成。

vLLM 本地部署

1. 启动 vllm 服务器：

   vllm serve BytedTsinghua-SIA/RL-MemoryAgent-14B --tensor_parallel_size 2
   

2. 运行 quickstart.py：

   python quickstart.py --model BytedTsinghua-SIA/RL-MemoryAgent-14B
   

在线 LLM 服务

对于在线 LLM 服务，您需要将模型端点和 API 密钥配置为环境变量。

例如，gpt-4o-2024-11-20：

• 普通在线服务：只需使用 https://{endpoint}。
• Azure OpenAI：使用格式 https://{endpoint}/openai/deployments/gpt-4o-2024-11-20。

export URL=
export API_KEY=
python quickstart.py --model gpt-4o-2024-11-20

可重复性

性能

在复现过程中，您可能会发现训练过程中的验证分数与最终分数并不相同（约50% vs 80%）。这种现象是正常的，因为在训练时我们实际上使用了一个更为严格的验证器来防止奖励作弊，而在测试时则使用了一个较为宽松的验证器。具体来说：

• 在【训练验证器】（https://github.com/BytedTsinghua-SIA/MemAgent/blob/main/verl/utils/reward_score/hotpotqa.py）中，模型的答案必须放在 \boxed{} 内，且大小写完全匹配，不得包含任何额外字符。

• 在【测试验证器】（https://github.com/BytedTsinghua-SIA/MemAgent/blob/main/taskutils/memory_eval/utils/__init__.py）中，诸如“a/the”之类的冠词会被忽略，大小写差异和标点符号也不予考虑。

更为严格的训练验证器源自早期的数学相关强化学习工作，而较为宽松的测试验证器则符合Ruler和Qwen-Long等长上下文项目中的实践。

测试结果

pip install httpx==0.23.1 aiohttp -U ray[serve,default] vllm

1. 准备 QA 数据

cd taskutils/memory_data
bash download_qa_dataset.sh

2. 下载数据集

cd ../..
bash hfd.sh BytedTsinghua-SIA/hotpotqa --dataset --tool aria2c -x 10
export DATAROOT=$(pwd)/hotpotqa

3. 准备模型

测试中使用的模型将从HuggingFace下载。然而，Qwen2.5-Instruct系列模型需要手动下载，并正确配置其config.json以激活YaRN。请按照【Qwen2.5-Instruct仓库】中的说明操作（https://huggingface.co/Qwen/Qwen2.5-7B-Instruct）

bash hfd.sh Qwen/Qwen2.5-7B-Instruct --tool aria2c -x 10
bash hfd.sh Qwen/Qwen2.5-14B-Instruct --tool aria2c -x 10
bash hfd.sh Qwen/Qwen2.5-32B-Instruct --tool aria2c -x 10

# 然后手动修改 config.json

export MODELROOT=/your/path/to/models # 切换到你的模型根目录，这个环境变量在 run.py 脚本中会被使用
mv Qwen2.5-7B-Instruct $MODELROOT/Qwen2.5-7B-Instruct-128K
mv Qwen2.5-14B-Instruct $MODELROOT/Qwen2.5-14B-Instruct-128K
mv Qwen2.5-32B-Instruct $MODELROOT/Qwen2.5-32B-Instruct-128K

4. 运行

注意： 完成所有测试可能需要几天时间，你可以选择指定要运行的测试或模型。

cd taskutils/memory_eval
python run.py

注意： 该脚本会使用所有可用的 GPU 来服务模型。如果你有多个 GPU 节点，可以创建一个 Ray 集群，并在其中一个节点上运行该脚本。使用 SERVE_PORT 和 DASH_PORT 来指定 Ray 集群的端口。

cd taskutils/memory_eval
SERVE_PORT=8000 DASH_PORT=8265 python run.py # 这里的端口号是默认值，你可能需要根据你的 Ray 集群中的服务/仪表板端口进行调整

训练

首先，在 run_memory_7B.sh 和 run_memory_14B.sh 中指定 PROJ_ROOT（用于保存检查点）和 DATASET_ROOT（用于训练数据，应与测试时使用的数据相同）。

然后直接运行此脚本以启动单节点训练，或者正确配置 Ray 集群，并在集群中的某个节点上运行该脚本。

数据

请在 taskutils/memory_data 目录下执行本节中的以下命令。

cd taskutils/memory_data
pip install nltk pyyaml beautifulsoup4 html2text wonderwords tenacity fire

1. 训练集与验证集划分：hotpotqa_train.parquet 和 hotpotqa_dev.parquet

• 下载 QA 数据集和合成数据，如果你已经在上一步下载过，则可跳过此步骤：

bash download_qa_dataset.sh

python processing.py # 数据处理，生成长上下文多跳 QA 合成数据

• 在本地部署 Qwen-7B（端口 8000）和 Qwen-7B-Instruct（端口 8001）

• 数据过滤

python filter.py -i hotpotqa_dev_process.parquet -o hotpotqa_dev_result --noresume
python filter.py -i hotpotqa_train_process.parquet -o hotpotqa_train_result --noresume
python3 filter2.py # 过滤掉那些无需任何上下文即可被 LLM 正确回答的样本：

2. 主任务：eval_{50|100|200|...}.json

export DATAROOT="your_dir_to_hotpotqa_dev.parquet"
python convert_to_eval.py # 将 `hotpotqa_dev` 转换为 `eval_200.json`
python different_docs_eval.py.py # 创建包含不同数量文档的评估数据集

3. OOD 任务：eval_{rulersubset}_{8192|16384|...}.json

export DATAROOT="your_dir_to_hotpotqa_dev.parquet"
python download_paulgraham_essay.py
bash download_qa_dataset.sh
bash ruler_data_prepare.sh 

工程实现

同步模式：从工具调用到通用工作流

受 Search-R1 的启发，我们实现了一个支持独立上下文的通用多轮对话工作流框架。因此，上下文不再像原始的工具调用那样被限制为所有先前对话的拼接字符串。该框架使得我们可以以端到端的方式优化多步智能体。记忆智能体便是这一框架的一个示例，展示了如何利用强化学习来优化智能体在多步工作流中的表现。

具体实现细节请参见 recurrent/impls/memory.py，接口设计则可在 recurrent/interface.py 和 recurrent/generation_manager.py 中找到。

异步模式：将智能体作为函数

基于 服务器模式下的生成，我们进一步实现了一个全新的框架，允许用户以类似于 OpenAI API 的方式调用 LLM 来实现智能体功能，而无需担心分批张量操作，如分词、填充、状态追踪等，这些通常需要大量的样板代码，甚至状态机。

在这种视角下，每个智能体都是一条返回一个或多个 {"role":"", "content":""} 字典列表的函数：

• 原生模式：[{"role":"user","content":pmt},{"role":"assistant""content":rsp}]
• 多轮工具调用模式：[{"role":"user","content":pmt},{"role":"assistant","content":rsp1},{"role":"tool","content":obs},{"role":"assistant","content":rsp2}]
• 上下文独立多轮对话模式：[{"role":"user","content":pmt1},{"role":"assistant","content":rsp1}], [{"role":"user","content":pmt2},{"role":"assistant","content":rsp2}]

我们修改了 chat_template 以支持工具响应屏蔽，且无需任何张量操作。

更多详细信息请参见 recurrent/impls/async_*.py 中定义的智能体类的 rollout 方法实现，以及 recurrent/interface.py 和 recurrent/async_generation_manager.py 中的框架设计。

RayActor 进程池

计算密集型的奖励计算或工具调用可能会阻塞主节点向 LLM 发送生成请求。为了提高 CPU 密集型任务的效率，我们在每个节点上创建了一个 RayActor，运行一个进程池并接受来自主节点的任务。

因此，CPU 任务可以通过提交给 RayActor 来异步执行，GPU 任务（即 LLM 生成）也是如此。

更多详情请参见 verl/workers/reward_manager/thread.py。

致谢

我们感谢 verl 团队提供的灵活而强大的基础设施。

我们还感谢 服务器模式生成 的作者们所做的出色工作，他们的成果为我们构建异步智能体框架奠定了坚实的基础。

引用

如果你觉得这项工作对你有所帮助，请考虑引用我们的论文：

@article{yu2025memagent,
  title={MemAgent: Reshaping Long-Context LLM with Multi-Conv RL-based Memory Agent},
  author={Yu, Hongli and Chen, Tinghong and Feng, Jiangtao and Chen, Jiangjie and Dai, Weinan and Yu, Qiying and Zhang, Ya-Qin and Ma, Wei-Ying and Liu, Jingjing and Wang, Mingxuan and others},
  journal={arXiv preprint arXiv:2507.02259},
  year={2025}
}

MemAgent 快速上手指南

MemAgent 是一个基于多轮对话强化学习（Multi-Conv RL）的长上下文处理框架，能够在不改变模型架构的情况下，实现从 8K 训练上下文到 3.5M token 任务的高效外推。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• GPU: 支持 CUDA 的 NVIDIA GPU（本地部署 14B 模型建议显存总和 ≥ 48GB，需多卡并行）
• Python: 3.9 或更高版本

前置依赖

在开始之前，请确保已安装以下基础工具：

• git
• aria2c (用于加速数据集和模型下载)
• pip

安装 Python 依赖包：

pip install httpx==0.23.1 aiohttp -U ray[serve,default] vllm
pip install nltk pyyaml beautifulsoup4 html2text wonderwords tenacity fire

提示：国内用户建议使用国内镜像源加速安装，例如：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple httpx==0.23.1 aiohttp -U ray[serve,default] vllm

安装步骤

1. 克隆项目代码

   git clone https://github.com/BytedTsinghua-SIA/MemAgent.git
   cd MemAgent
   

2. 获取模型权重

   项目提供两种使用方式：本地部署或使用在线 API。

   方式 A：本地部署 (推荐) 从 Hugging Face 下载预训练模型（国内用户可使用镜像站或配置加速）：

   # 使用 hfd.sh 脚本下载 14B 模型
   bash hfd.sh BytedTsinghua-SIA/RL-MemoryAgent-14B --tool aria2c -x 10
   

   注：若脚本不可用，可直接使用 huggingface-cli 或浏览器下载。

   方式 B：在线服务 无需下载模型，但需要准备支持 OpenAI 格式的 API 端点和 Key。

基本使用

MemAgent 提供了 quickstart.py 脚本，支持一键启动测试。

场景一：本地 vLLM 部署

1. 启动 vLLM 服务 使用多卡并行加载模型（以 14B 模型为例，需 2 张卡）：

   vllm serve BytedTsinghua-SIA/RL-MemoryAgent-14B --tensor_parallel_size 2
   

2. 运行快速测试 在新终端中执行：

   python quickstart.py --model BytedTsinghua-SIA/RL-MemoryAgent-14B
   

场景二：调用在线 LLM 服务

如果您使用 Azure OpenAI 或其他兼容 OpenAI 接口的云服务，请配置环境变量后运行：

# 替换为您的实际端点和密钥
export URL=https://{your-endpoint}/openai/deployments/gpt-4o-2024-11-20
export API_KEY={your-api-key}

# 运行脚本，指定模型名称
python quickstart.py --model gpt-4o-2024-11-20

注意：

• 普通在线服务 URL 格式通常为 https://{endpoint}。
• Azure OpenAI 需在 URL 后追加 /openai/deployments/{deployment-name}。