目录
master
分支1
标签0
+ 疑修
Web IDE
Xiyu_Zhu
决赛终版修改
1个月前7次提交
README.md

LightMAS

LightMAS 是一个面向连续任务链的多智能体协作原型。项目通过 Planner、 Retriever、Executor 和 Summarizer 四个角色完成任务，并比较自然语言通信 （Text）与结构化通信（Protocol）在答案质量、模型调用、通信量、耗时、状态外置 和记忆复用方面的差异。

当前版本为 v0.1.0，要求 Python 3.9 或更高版本。项目可在 Windows 上开发和 运行，也提供基于 openEuler 24.03-LTS-SP3 与 Podman 的容器验证流程。

本项目是实验与验证原型，不是生产级通用 Agent 平台，也不在本地部署 DeepSeek 模型。运行时会调用配置中的 OpenAI-compatible 模型接口。

核心流程

一次任务按轮次执行以下流程：

Task -> Planner -> Retriever -> Executor -> Summarizer -> Acceptance
                    |             |             |
                    +------ shared memory ------+
                                  |
                         state exchange / StateRef
  • Planner：拆解任务并生成计划；
  • Retriever：检索输入文档和已保存的共享记忆；
  • Executor：在代码任务需要时执行受限 Python 子进程；
  • Summarizer：合并结果并生成结构化最终答案；
  • Orchestrator：负责轮次调度、完成度检查、记忆提交和指标采集。

当前调度是同步顺序执行。Protocol 模式使用结构化字段传递控制信息；较大的状态 可通过 StateRef 外置到 state exchange。它不代表四个 Agent 已经作为独立服务并行 部署。

内置任务

任务组 任务 ID 数量 内容
document doc_A1 - doc_A6 6 openEuler 部署文档、变更、FAQ、验收与恢复
code code_B1 - code_B5 5 benchmark 数据、分析脚本、增量更新和诊断
operations ops_C1 - ops_C10 10 openEuler 环境、通信、StateRef、记忆、安全与验收

同一组内的后续任务可以复用前序任务的记忆和产物。普通命令只运行一题； --benchmark 才会运行所选任务组的完整连续任务链，并分别执行 Text 和 Protocol。

目录说明

src/                       代码根目录；以下安装、运行命令均在此执行
  lightmas/                Agent、调度、模型适配、记忆与评测代码
  configs/                 默认、openEuler 和实验配置
  deploy/openeuler/        openEuler 运行脚本与验收说明
  tests/                   单元与集成测试
  benchmarks/              固定 benchmark 数据
  campares/                多模型、框架对比和消融实验脚本
  dashboard/               静态结果页面
  logs/                    实验日志和导出结果，随提交附带；不含凭据目录
  data/                    已保存的 SQLite 持久化数据
  Containerfile            openEuler 容器镜像定义
  README.md                代码根目录快速使用说明
docs/                      比赛提交说明、项目说明和声明材料
presentation/              决赛 PPT、演示视频和标识素材
demo/                      演示材料
tests/                     随提交附带的补充测试文件

campares 是仓库当前保留的目录名，执行命令时不要改成 compares。

本地安装

从提交目录根目录进入 src（包含 pyproject.toml）后执行。除明确说明外， 本文后续命令的工作目录均为 src。实验日志随本提交附带， src/logs/provider_credentials/ 中的本机加密凭据不会提交。

Windows PowerShell：

cd src
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Linux：

cd src
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

模型配置与密钥

默认配置为 configs/default.yaml，openEuler 容器使用 configs/openeuler.yaml。两者目前都配置为 DeepSeek 的 OpenAI-compatible 接口，并关闭 thinking 输出，以提高 Agent 结构化结果的稳定性。

API Key 不应写入 YAML、镜像、日志或命令历史文件。程序依次读取：

  1. 配置中非空的 api_key；
  2. LIGHTMAS_API_KEY；
  3. OPENAI_API_KEY；
  4. DEEPSEEK_API_KEY。

推荐始终使用 LIGHTMAS_API_KEY：

# Windows PowerShell
$env:LIGHTMAS_API_KEY="your-api-key"
# Linux / openEuler
export LIGHTMAS_API_KEY='your-api-key'

不要用 echo $LIGHTMAS_API_KEY 输出密钥。可用下面的命令只确认变量是否存在：

test -n "${LIGHTMAS_API_KEY:-}" && echo 'LIGHTMAS_API_KEY is set'

最小验证

先检查配置与模型连通性：

python -m lightmas --config configs/default.yaml --dry-run

这里的 --dry-run 只表示不启动 Agent，仍会连接模型接口并执行健康检查。

运行与 openEuler 脚本一致的最小任务：

python -m lightmas \
  --config configs/openeuler.yaml \
  --mode text \
  --task-group document \
  --task-id doc_A1

验证通过时，输出应同时包含：

  • 模型状态为 connected；
  • Mode: text | Group: document；
  • Task: doc_A1；
  • Status: completed；
  • 非空的 Final Answer。

仅看到镜像构建成功或 Successfully tagged，不能说明 Agent 任务已经验证通过。

openEuler 容器验证

openEuler 24.03-LTS-SP3 上的最短流程如下：

sudo dnf install -y podman
podman --version

cd src  # 从提交目录根目录进入代码根目录；如已位于 src 则省略
export LIGHTMAS_API_KEY='your-api-key'
bash deploy/openeuler/run.sh

run.sh 会构建 localhost/lightmas:openeuler-24.03-lts-sp3，以只读根文件系统、 CPU/内存/进程限制和最小权限启动容器，然后运行 doc_A1 + text。这是部署连通性和 基本 Agent 流程的验收，不是完整 benchmark。

建议由普通用户运行 Podman。使用 root 用户可以完成容器功能验证，但不能把该结果 作为“rootless Podman 已验证”的证据。

完整的安装、重建、成功判据、证据收集和故障排查见 openEuler 验证指南。

常用运行方式

运行单题：

python -m lightmas --mode text --task-group document --task-id doc_A1
python -m lightmas --mode protocol --task-group code --task-id code_B1

使用 SQLite 保存记忆和事件，并导出 JSONL：

python -m lightmas \
  --mode protocol \
  --task-group document \
  --task-id doc_A1 \
  --persist \
  --export results.jsonl

运行一个完整任务组的 Text/Protocol 对比：

python -m lightmas \
  --config configs/default.yaml \
  --benchmark \
  --task-group document \
  --benchmark-export logs/document_benchmark.csv

运行 A、B 两组比赛 benchmark：

python -m lightmas \
  --config configs/default.yaml \
  --competition-benchmark \
  --competition-export logs/competition_benchmark.json

完整 benchmark 会产生较多模型调用。建议先通过 --dry-run 和单题验证，再执行 连续任务链。中途产生的 *.partial.json 是检查点，不代表最终实验成功。

测试

python -m pytest -q

测试不需要真实 API Key。openEuler 的环境清单脚本见 deploy/openeuler/collect_manifest.sh。

结果与 Dashboard

常见输出包括：

  • 单题终端结果：状态、轮次、最终答案和调用统计；
  • *.csv / *.json：benchmark 汇总；
  • *.manifest.json：不含密钥的复现配置；
  • results.jsonl：事件级运行记录；
  • data/lightmas_memory.db、data/lightmas_events.db：启用 --persist 后的数据库。

生成静态 Dashboard：

python -m lightmas --dashboard

默认输出到 dashboard/index.html。静态页面不会自动读取刚产生的新结果；需要通过 --dashboard-* 参数指定对应实验文件后重新生成。

A1–A3 连续任务现场演示

在提交目录的 src 下启动本地服务。先在同一个 PowerShell 窗口设置密钥，再启动 服务；设置或修改环境变量后，已经运行的服务需要重启。

cd src  # 从提交目录根目录执行；如已位于 src 则省略
$env:LIGHTMAS_API_KEY = "your-deepseek-api-key"
.\.venv\Scripts\python.exe -m lightmas --dashboard
.\.venv\Scripts\python.exe -m lightmas.demo_server --config configs/default.yaml --port 8765

浏览器打开 http://127.0.0.1:8765/，先运行环境预检，再分别点击“运行 Text”和 “运行 Protocol”。预检和两个按钮使用同一配置文件、同一 Python 和同一模型名， 不会强制替换为其他模型。配置中的模型名须与接口返回的 /models 列表一致； 第三方服务的 Key 必须配合该服务的 API 地址。

每次从空记忆执行 doc_A1 → doc_A2 → doc_A3，各题最多一轮。两个模式分别新建 运行时，仅将本次已验收成果写入记忆。页面分别保留每题与整条链的耗时、LLM 调用、 API Token、控制面字节及返回文本，并展示实际命中的前序成果 ID 与摘要。记忆命中 说明成果已提供给后续角色；Text 同样启用记忆，不应将记忆复用视为 Protocol 独有。 整链执行耗时不含初始化；总耗时还包含子进程启动、接口预检和嵌入模型初始化。 失败题也计入调用等开销。Token 缺少完整 API usage 时显示 N/A；控制面和状态读写 为本地逻辑字节计量，不能直接等同于网络流量。旧的 A6 独立测试注入固定 A1–A5 摘要，无法证明复用了本次执行前五题的成果，故现场入口改为真实连续任务。

逐次结果保存于 src/logs/demo_jobs/<job_id>.json。服务另存 latest_a1_a3_text.json 与 latest_a1_a3_protocol.json，重启后会标明“上次已保存实测” 及保存时间；本次会话的新结果优先展示。也可直接运行单种模式，并通过 --max-rounds 调整最大轮数：

.\.venv\Scripts\python.exe -m lightmas.demo_task --config configs/default.yaml --mode text --scenario a1_a3 --result logs/a1_a3_text.json
.\.venv\Scripts\python.exe -m lightmas.demo_task --config configs/default.yaml --mode protocol --scenario a1_a3 --result logs/a1_a3_protocol.json

常见问题

podman: command not found

Podman 尚未安装或不在 PATH。在 openEuler 上执行：

sudo dnf install -y podman

Podman 报 short-name 无法解析

当前 Containerfile 已使用完整镜像名：

FROM docker.io/openeuler/openeuler:24.03-lts-sp3

如果仍出现 short-name ... did not resolve，说明 openEuler 上的代码不是当前版本， 应重新同步 Containerfile 并构建镜像。

模型健康检查失败

确认变量名严格为 LIGHTMAS_API_KEY，不是 LIGHTMAS_API_KET 或 LIGHTMAS_KEY_API；再检查容器网络、base_url 和 model_name。Windows 可用并不 自动代表 openEuler 容器能访问同一接口，代理、DNS、防火墙和 CA 证书都可能不同。

任务运行三轮后没有最终答案

这通常表示模型返回内容未通过 Agent 的结构化解析或完成度检查，不是 Podman 构建 失败。先确认 openEuler 端已经同步以下当前文件并重新构建：

  • lightmas/__main__.py；
  • configs/openeuler.yaml；
  • deploy/openeuler/run.sh；
  • Containerfile。

当前配置会把 thinking: disabled 传给模型，并为回答保留 3072 个输出 Token。详细 排查命令见 openEuler 验证指南。

补充文档

这些报告记录不同阶段的实验，不等同于当前环境的现场验收结果。复现实验时应以本次 运行生成的日志、manifest 和环境清单为准。

关于
README.md
379.0 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号