SLiM-MAS - 结构化潜变量记忆增强多智能体系统

SLiM-MAS 是面向复杂推理与代码生成任务的多智能体协作系统。系统以潜变量协作为基础，将 B-MAP 结构化通信、A-MEM 式 Agentic Memory 与 CodeAct 执行反馈闭环 融合到统一运行框架中，在减少多智能体文本通信开销的同时，提供可检索记忆、代码执行验证、自动修复、实验统计和可视化能力。

本仓库代码目录在提交包中统一命名为 SLiM-MAS/。部分 Python 方法名和历史脚本仍保留 latent_mas，这是为了兼容已有实验参数与结果文件。

🎯 主要功能

• 结构化多智能体协作：Planner、Critic、Refiner、Judger 按顺序完成规划、审查、改进和裁决。
• 潜变量状态传递：通过模型 KV Cache 传递中间状态，减少完整自然语言思维链的重复生成。
• B-MAP 结构化通信：用紧凑控制消息记录智能体角色、阶段、动作和工具请求。
• A-MEM 式长期记忆：支持正负经验写入、检索、选择、演化、弱连接和连续任务复用。
• CodeAct 执行闭环：对生成代码进行语法检查、受限执行、公开测试验证和失败后自动修复。
• 多方法统一评测：支持单智能体、文本多智能体、结构化潜变量多智能体和记忆增强方法。
• 代码数据集支持：支持 HumanEval+、MBPP+，并可导出 EvalPlus 官方评测输入。
• 推理服务与可视化：提供 FastAPI 后端和浏览器前端，可查看任务进度、Token、耗时、通信与记忆状态。
• 离线模型运行：模型与数据缓存完成后，可设置 Hugging Face 离线模式在无外网环境运行。

🧩 系统架构

用户任务 / HumanEval+ / MBPP+
                │
                ▼
        Planner 任务规划
                │
        B-MAP 控制消息 + Latent KV
                ▼
        Critic 方案审查
                │
                ▼
        Refiner 方案改进
                │
                ▼
        Judger 生成最终答案
                │
                ▼
   CodeAct 语法检查、执行与公开测试
                │
        ┌───────┴────────┐
        │                │
      成功          失败 → 自动修复
        │                │
        └───────┬────────┘
                ▼
    指标汇总 / A-MEM 经验写回 / 前端展示

📁 项目结构

SLiM-MAS/
├── run.py                         # 统一实验与推理入口
├── models.py                      # Hugging Face 模型与潜变量处理
├── methods/
│   ├── baseline.py                # 单智能体基线
│   ├── text_mas.py                # 文本通信多智能体
│   └── latent_mas.py              # 潜变量、B-MAP 与记忆增强方法
├── bmap_protocol.py               # B-MAP 结构化消息协议
├── agentic_memory_controller.py   # A-MEM 式 Agentic Memory 控制器
├── shared_memory.py               # 加权检索记忆兼容实现
├── code_task_evaluator.py         # CodeAct 公共评测与修复入口
├── codeact_bridge.py              # 主流程与 CodeAct 工具适配层
├── codeact_tools/
│   ├── codeact_executor.py        # CodeAct 执行器
│   ├── sandbox_runner.py          # 受限 Python 子进程执行
│   ├── code_generator.py          # 代码生成辅助
│   └── llm_code_generator.py      # LLM 代码生成与修复
├── api_server.py                  # FastAPI 推理服务
├── frontend/                      # Web 可视化界面
├── dashboard_exporter.py          # 实验结果聚合与前端数据导出
├── evalplus_exporter.py           # EvalPlus 样本导出
├── prepare_evalplus_samples.py    # 官方评测输入准备工具
├── data/                          # 本地数据文件
├── tests/                         # 单元测试与接口测试
├── outputs/                       # 推理、评测、日志与记忆输出
├── requirements.txt               # Python 依赖
└── README.md

🔧 系统要求

项目	推荐配置
操作系统	openEuler 24.03-LTS-SP3（x86_64 / aarch64）
Python	3.10.x
GPU	NVIDIA GPU，建议显存不低于 24 GB
GPU 驱动	与所安装 PyTorch CUDA Wheel 兼容
内存	建议 32 GB 及以上
磁盘	建议预留 40 GB 及以上模型、数据和结果空间
模型	Qwen3-4B / Qwen3-8B / Qwen3-14B

CPU 环境可以完成编译检查和大部分单元测试，但大模型推理建议使用 NVIDIA GPU。

🐧 openEuler 24.03-LTS-SP3 环境准备

以下命令适用于全新 openEuler 24.03-LTS-SP3 环境。命令默认使用 Bash；普通用户执行系统软件安装时需要 sudo。

步骤 1：确认操作系统

cat /etc/os-release
uname -m

预期 VERSION 或 PRETTY_NAME 中包含 openEuler 24.03 (LTS-SP3)。

步骤 2：安装系统编译工具

sudo dnf install -y \
  git curl wget tar bzip2 \
  gcc gcc-c++ make cmake \
  openssl-devel libffi-devel zlib-devel \
  xz-devel sqlite-devel readline-devel ncurses-devel

这些软件包用于安装 Python 扩展、构建依赖和执行项目辅助工具。

步骤 3：准备 Python 3.10 环境

推荐使用 Conda/Miniforge 隔离依赖：

conda create -n slim-mas python=3.10 -y
conda activate slim-mas

python --version
python -m pip install --upgrade pip setuptools wheel

如果服务器尚未安装 Conda，可先安装与机器架构对应的 Miniforge，再执行上述命令。

步骤 4：安装 PyTorch 与项目依赖

NVIDIA GPU 环境：

cd /path/to/SLiM-MAS

# CUDA 13.0 Wheel；如果驱动或集群 CUDA 版本不同，请改用匹配的官方索引。
python -m pip install torch --index-url https://download.pytorch.org/whl/cu130
python -m pip install -r requirements.txt

仅用于编译、接口或 CPU 测试的环境：

cd /path/to/SLiM-MAS

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install -r requirements.txt

步骤 5：验证 GPU 与核心依赖

nvidia-smi

python -c "import torch; print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('available:', torch.cuda.is_available())"
python -c "import transformers, fastapi, pytest; print('dependencies: OK')"

GPU 推理环境中，torch.cuda.is_available() 应输出 True。

⚙️ 模型与缓存配置

建议把 Hugging Face 缓存放在容量较大的数据盘：

export HF_HOME=/data/huggingface
export HF_DATASETS_CACHE="$HF_HOME/datasets"
export TOKENIZERS_PARALLELISM=false

mkdir -p "$HF_HOME" "$HF_DATASETS_CACHE"

模型下载完成后，可切换到离线运行：

export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1

如需预先下载 Qwen3-8B：

huggingface-cli download Qwen/Qwen3-8B

首次下载模型和数据集时不要设置离线变量。集群环境无法访问 Hugging Face 时，可在可联网机器下载后将缓存目录完整复制到服务器。

🔨 编译检查

本项目以 Python 为主，不需要生成独立二进制文件。提交前使用 py_compile 检查核心源码是否可被 Python 正常编译：

cd /path/to/SLiM-MAS

python -m py_compile \
  run.py api_server.py \
  agentic_memory_controller.py bmap_protocol.py \
  code_task_evaluator.py codeact_bridge.py \
  shared_memory.py dashboard_exporter.py \
  methods/*.py codeact_tools/*.py

命令无输出且退出码为 0 即表示编译检查通过。

✅ 运行测试

运行完整测试套件：

cd /path/to/SLiM-MAS
python -m pytest -q tests

当前提交版本的参考结果：

...................................                                      [100%]
35 passed

也可以分别测试关键模块：

python -m pytest -q tests/test_agentic_memory.py
python -m pytest -q tests/test_code_task_evaluator.py
python -m pytest -q tests/test_evalplus_exporter.py
python -m pytest -q tests/test_api_server.py

🚀 快速开始

1️⃣ 查看命令参数

python run.py --help

2️⃣ 单样本冒烟测试

以下命令使用 Qwen3-8B 对一个 HumanEval+ 样本运行结构化潜变量多智能体方法，并启用 CodeAct：

python run.py \
  --method structured_latent_mas \
  --model_name Qwen/Qwen3-8B \
  --task humanevalplus \
  --max_samples 1 \
  --max_new_tokens 2048 \
  --generate_bs 1 \
  --latent_steps 10 \
  --latent_space_realign \
  --structured_comm_in_prompt \
  --enable_codeact \
  --codeact_timeout_s 10 \
  --codeact_repair_rounds 1 \
  --codeact_fresh_finalize \
  --output_dir outputs/smoke/structured_latent_mas

3️⃣ 记忆增强连续任务

python run.py \
  --method memory_structured_latent_mas \
  --model_name Qwen/Qwen3-8B \
  --task humanevalplus \
  --max_samples 2 \
  --continuous_rounds 2 \
  --task_sequence repeat_pairs \
  --max_new_tokens 2048 \
  --generate_bs 1 \
  --latent_steps 10 \
  --latent_space_realign \
  --memory_agentic \
  --memory_online_update \
  --memory_in_prompt \
  --memory_injection_target planner \
  --memory_backend chroma \
  --memory_retrieval_mode hybrid \
  --memory_dir outputs/smoke/memory_store \
  --enable_codeact \
  --codeact_timeout_s 10 \
  --codeact_repair_rounds 1 \
  --codeact_fresh_finalize \
  --output_dir outputs/smoke/memory_structured_latent_mas

🧪 支持的方法与任务

推理方法

方法	--method	文本通信	B-MAP	Latent KV	A-MEM
单智能体基线	baseline	否	否	否	否
文本多智能体	text_mas	是	否	否	否
原始潜变量多智能体	latent_mas	辅助	否	是	否
结构化潜变量多智能体	structured_latent_mas	辅助	是	是	否
记忆增强结构化潜变量多智能体	memory_structured_latent_mas	辅助	是	是	是

CodeAct 是各方法共用的可选执行评测层，通过 --enable_codeact 开启。

数据集

gsm8k、aime2024、aime2025、gpqa、arc_easy、arc_challenge、mbppplus、humanevalplus、medqa。

🌐 启动推理服务与前端

步骤 1：启动 FastAPI

cd /path/to/SLiM-MAS
chmod +x start_api_server.sh

HOST=127.0.0.1 PORT=8000 ./start_api_server.sh

健康检查：

curl http://127.0.0.1:8000/api/health

接口文档：

http://127.0.0.1:8000/docs

步骤 2：打开前端

另开一个终端：

cd /path/to/SLiM-MAS/frontend
python -m http.server 8080

浏览器访问：

http://127.0.0.1:8080

在远程服务器部署时，建议通过 SSH 端口转发访问，不要把推理接口直接暴露到公网：

ssh -L 8000:127.0.0.1:8000 -L 8080:127.0.0.1:8080 user@server

📊 输出文件

每次实验由 --output_dir 指定独立目录，常见文件如下：

文件	说明
summary.json	样本数、准确率、Token、耗时、CodeAct 和记忆汇总
results.jsonl	每个样本的完整推理与评测记录
evalplus_samples.jsonl	EvalPlus 官方评测输入
structured_messages.jsonl	B-MAP 结构化消息日志
protocol_initialize.json	B-MAP 协议初始化信息
agentic_memory.jsonl	A-MEM 式长期记忆
run.log	队列脚本运行日志

查看汇总：

python -m json.tool outputs/smoke/structured_latent_mas/summary.json

🔒 安全注意事项

• CodeAct 会执行模型生成的 Python 代码。当前实现提供超时、语法和受限子进程保护，但不应被视为强隔离沙箱。
• 在生产或多用户环境中，建议把 CodeAct 放入无特权容器、独立账号或专用计算节点。
• 不要在仓库中提交 API Key、SSH 密钥、访问令牌或包含个人信息的数据。
• 推理 API 默认应监听 127.0.0.1，需要远程访问时优先使用 SSH 隧道或受控反向代理。
• outputs/ 可能包含题目、模型回答、执行日志和记忆内容，提交前应检查并清理敏感数据。

📝 常见问题

Q：openEuler 上安装依赖时提示编译器或头文件缺失？

重新执行“安装系统编译工具”中的 dnf install 命令，并确认当前 Conda 环境已经激活：

conda activate slim-mas
which python
python -m pip --version

Q：torch.cuda.is_available() 返回 False？

依次检查：

nvidia-smi
python -c "import torch; print(torch.__version__, torch.version.cuda)"

确认 NVIDIA 驱动正常，并且安装的是 CUDA Wheel 而不是 CPU Wheel。容器环境还需要正确映射 GPU 设备。

Q：模型或数据集无法下载？

检查是否误设了离线变量：

unset HF_HUB_OFFLINE
unset TRANSFORMERS_OFFLINE

如果计算节点无外网，请提前下载 Hugging Face 缓存并复制到 HF_HOME。

Q：显存不足（CUDA out of memory）？

• 优先使用 Qwen/Qwen3-4B 或 Qwen/Qwen3-8B。
• 将 --generate_bs 调整为 1。
• 减小 --max_new_tokens 和 --latent_steps。
• 运行前设置 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True。
• 确认没有其他进程占用 GPU。

Q：CodeAct 通过是否等于 EvalPlus 官方评测通过？

不是。CodeAct 通过表示候选代码完成语法检查并通过当前可见的执行或公开测试；最终 HumanEval+、MBPP+ 指标应以 EvalPlus 官方隐藏测试结果为准。

Q：只想验证提交包，不下载大模型怎么办？

只运行编译和单元测试即可：

python -m py_compile run.py api_server.py agentic_memory_controller.py \
  bmap_protocol.py code_task_evaluator.py codeact_bridge.py
python -m pytest -q tests

📄 许可证与致谢

本项目沿用仓库中的 LICENSE。SLiM-MAS 基于 LatentMAS 研究代码进行扩展，并融合 B-MAP 结构化通信、A-MEM 式 Agentic Memory 与 CodeAct 执行反馈机制。使用和再发布时请保留原始项目及相关研究工作的版权和引用信息。

---

让多智能体协作更紧凑、更可复用，也更容易被执行结果验证。