MemSlides 快速开始教程:一条命令生成你的第一套 PPT,附新手常见坑点清单
MemSlides 快速开始教程:一条命令生成你的第一套 PPT,附新手常见坑点清单
MemSlides 是一个带分层记忆的 AI PPT 生成框架(hierarchical memory framework for personalized presentation agents)。本教程带你 5 分钟完成安装,用一条命令生成第一套 PPT,并提前避开新手最常踩的 API Key、中文字体、Playwright 依赖等坑点,让你快速跑通"生成—修改—导出"的完整流程。
一、MemSlides 是什么:会记住你的 PPT 智能体
和"一次性转换"不同,MemSlides 把做 PPT 当作一个有状态、可多轮修改的过程,核心由三层记忆驱动:
- 用户画像记忆(Long-term Memory):跨任务记住你的主题、版式、模板偏好,按演示意图(intent)自动注入新任务;
- 工作记忆(Working Memory):在当前套件的多次修改轮次中,保持临时偏好和会话约束不丢失;
- 工具记忆(Tool Memory):沉淀可复用的工具链执行经验,避免同类编辑反复失败;
- 局部化修订(Slide-local Revision):收到反馈后只改受影响的幻灯片区域,而不是整副 deck 重写。
项目入口与说明可参考 README.md,完整安装文档见 docs/INSTALL.md。
二、安装前准备:环境要求一览
| 依赖 | 版本/说明 |
|---|---|
| Python | 3.11(见 environment.yml) |
| Node.js | 20,PPTX 导出运行时使用 |
| 系统工具 | LibreOffice、Poppler、CJK 中文字体(Linux 用 apt 安装) |
| 浏览器内核 | Playwright Chromium + ffmpeg |
⚠️ Windows 用户请单独安装 LibreOffice 和 Poppler,并保证命令行工具在
PATH中,详见 docs/INSTALL.md。
克隆仓库
git clone https://gitcode.com/gh_mirrors/me/Memslides
cd Memslides
三、5 步安装:从克隆到可用
第 1 步:安装系统依赖(Linux)
sudo apt-get update
sudo apt-get install -y libreoffice fontconfig fonts-noto-cjk poppler-utils
第 2 步:创建 conda 环境
conda env create -f environment.yml
conda activate memslides
第 3 步:以可编辑模式安装 Python 包
pip install -e ".[research]"
第 4 步:安装 Playwright 浏览器内核
python -m playwright install chromium ffmpeg
第 5 步:验证安装
python -m memslides.experiment --help
能打印出 run / resume / report / personas 等子命令,即安装成功。
四、一条命令生成你的第一套 PPT
4.1 最小验证:跑内置 smoke 套件
python -m memslides.experiment run smoke_minimal \
--output-base .memslides/experiments \
--parallel 1
内置套件 smoke_minimal.yml 会生成一页纯标题幻灯片,并禁用联网检索与生图,是验证"生成 → 渲染 → PPTX 导出"全链路最快的方式。套件用法详见 use.md。
4.2 自由生成:一条命令出 PPT
python -m memslides generate \
--instruction "Create a one-slide project summary" \
--num-pages 1 --language zh
核心命令解析位于 src/memslides/main.py,还支持通过 --input 传入 JSON 请求体、--workspace 指定工作区。
4.3 多轮局部修改:只改你说的那一页
python -m memslides revise --workspace .memslides/session --feedback "Tighten the title"
revise 会把反馈投影到最小的受影响区域,只做局部补丁修订,实现逻辑在 src/memslides/main.py。
4.4 把自己的 PPTX 变成可复用模板
python -m memslides template induct --template-file template.pptx
生成结果统一落在 .memslides/ 目录下,运行结束后可用汇总命令查看:
python -m memslides.experiment report .memslides/experiments/smoke_minimal
五、配置要点:API Key 怎么放才安全
真实生成需要模型与服务的凭据。MemSlides 的公开配置是 memslides.yaml,其中的占位符会在加载时从环境变量展开,支持三种配置方式(按推荐顺序):
- 环境变量:如
MEMSLIDES_DESIGN_BASE_URL、MEMSLIDES_DESIGN_MODEL、MEMSLIDES_DESIGN_API_KEY; - 本地
.env文件:放在仓库根目录,不要提交; - 私有 YAML:通过
--config参数或MEMSLIDES_CONFIG_FILE环境变量指定。
🔒 安全提醒:不要提交
.env、.memslides/、生成的工作区和私有配置文件,官方安全说明见 README.md。
六、新手常见坑点清单 ✅
| # | 现象 | 原因与解决 |
|---|---|---|
| 1 | 报 missing-api-key 相关错误 |
未配置模型凭据。检查 memslides.yaml 中各 Agent 的 api_key,用环境变量或 .env 注入 |
| 2 | 导出的 PPT 中文乱码/豆腐块 | 缺少 CJK 字体,执行 sudo apt-get install -y fonts-noto-cjk |
| 3 | PDF/PPTX 导出失败 | 未安装 LibreOffice 或 Poppler,参考 docs/INSTALL.md 补齐系统依赖 |
| 4 | 启动时报浏览器相关错误 | 漏了 python -m playwright install chromium ffmpeg |
| 5 | Python/Node 版本不符 | 环境要求 Python 3.11 + Node 20,用 environment.yml 锁定的 conda 环境最稳 |
| 6 | smoke 套件没体现"记忆"效果 | smoke_minimal 默认 memory_enabled: false,属最小验证套件;测记忆需自定义 suite YAML 打开开关 |
| 7 | 第一次导出 PPTX 很慢 | 首次会自动安装 Node 依赖到缓存;离线环境可预装 presentation_export 的依赖并设置 MEMSLIDES_PPTX_EXPORT_NODE_MODULES |
| 8 | Docker 跑完状态"消失" | 容器内状态在 /app/.cache/memslides,需挂卷持久化,见 docker/README.md |
| 9 | 并行跑挂掉 | 新手先用 --parallel 1 串行跑通再调大 |
七、可选:用 Docker 最快跑通(免本机装依赖)
如果不想在本机装 LibreOffice 等一整套依赖,Docker 镜像已包含 Python、Node、Playwright、LibreOffice 与导出运行时:
docker compose build
docker compose run --rm memslides python -m memslides.experiment run smoke_minimal \
--output-base /app/.cache/memslides/experiments \
--parallel 1
需要私有 YAML 配置时,叠加 private override 文件运行:
docker compose -f docker-compose.yml -f docker-compose.private.yml run --rm memslides \
python -m memslides.experiment run smoke_minimal \
--output-base /app/.cache/memslides/experiments --parallel 1
Compose 会把实验状态和产物保存在 ./.memslides,完整说明见 docker/README.md。
写在最后
按照"装依赖 → conda 环境 → 安装 Playwright → 跑 smoke 套件 → generate 出 PPT"这条路径,MemSlides 从克隆到生成第一套 PPT 只需要几条命令。遇到报错时,对照第六节的坑点清单逐一排查,绝大多数新手问题(API Key、中文字体、浏览器内核)都能快速定位。跑通之后,再试试 revise 多轮局部修改,感受"只改你说的那一页"的差异化体验。

