2026/08/28
OpenMAIC 深度教程：从多智能体课堂到可部署的学习系统
OpenMAIC 的架构、快速启动、模型接入、课堂导出与服务端持久化实践，重点说明本地部署时必须处理的安全边界。
OpenMAIC 的核心不是让模型回答一道题，而是把学习过程组织成一间可以运行的课堂：输入主题或材料，系统生成大纲，再生成幻灯片、测验、交互式 HTML 场景或项目制学习活动，AI 教师和 AI 同学在课堂中继续讲解、讨论和反馈。真正值得研究的是它如何把多智能体编排、可编辑内容、导出格式和存储层组合成一套可部署系统。
先理解两阶段生成流水线
课堂生成通常先做大纲，再把每个大纲条目变成具体场景。场景不是单一 Markdown 页面，而可能是 Slides、Quiz、Interactive 或 PBL。AI 教师可以配合白板、聚光灯和语音讲解，学习者则通过提问、测验和动手实验参与。这个设计把“内容生成”和“课堂运行”分开，便于在生成后修改大纲和幻灯片。
本地启动
仓库是 Next.js 16、React 19、TypeScript 5 和 pnpm workspace 项目，当前要求 Node.js 20.9 以上、pnpm 10 以上：
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
pnpm dev至少配置一个 LLM provider 才能生成课堂。项目支持 OpenAI、Azure OpenAI、Anthropic、Amazon Bedrock、Gemini、DeepSeek、Qwen、Kimi、MiniMax、Grok、OpenRouter、豆包、腾讯、小米 MiMo、GLM、Ollama，以及本地 Lemonade 和 FunASR 等路径。
模型路由应该按阶段设计
.env.example 记录了 DEFAULT_MODEL 和 MODEL_ROUTES。服务端配置的 provider 可以由管理员统一管理，客户端设置不应被当作安全边界。更稳的做法是为大纲、场景、语音、图像和搜索分别设定默认路径，先用一个成本可控的模型完成课堂结构，再把高难度场景交给能力更强的模型。出现失败时，记录阶段、provider、模型和输入规模，而不是笼统地说“AI 不稳定”。
本地 AI 与语音链路
Lemonade 可作为本地 OpenAI 兼容服务，为 LLM、图像、TTS 和 ASR 提供统一地址，不需要 API Key。FunASR 则通过本地兼容服务完成语音转写，仓库文档列出 SenseVoiceSmall、Paraformer 和 Fun-ASR-Nano。若课堂依赖大量语音，先测转写延迟、显存或内存、并发和失败重试，再决定是本地运行还是使用云服务。
导出不是附属功能
OpenMAIC 可以导出可编辑 PPTX、交互式 HTML 和课堂 ZIP；启用 video-export profile 后，额外的 render-service 才提供 MP4。渲染服务使用 Chromium 与 FFmpeg，官方 compose 配置把它放到隔离网络，并设计了 CPU/内存 profile。没有 render-service 时，系统会退回 ZIP 等路径，不能把“支持 MP4”理解成默认启动就拥有完整视频渲染能力。
服务端持久化的危险开关
server-persistence profile 运行 OpenMAIC 应用和 PostgreSQL，持久化 HTTP API 嵌入应用的 /api/persistence。但仓库明确警告：NEXT_PUBLIC_PERSISTENCE_TOKEN 会编译进浏览器包，不是秘密，也不提供用户隔离；这种开发 token 只适合 localhost 或可信网络的单用户部署。生产环境必须替换为服务端会话校验，并让 learner partition 来自服务端身份，不能让客户端自由选择。
OpenClaw 适合做入口，不适合替代治理
OpenMAIC 支持通过 OpenClaw 从飞书、Slack、Discord、Telegram 等聊天应用触发课堂生成。聊天入口降低了启动门槛，但 provider 凭证、课堂数据、导出资产和访问码仍需在 OpenMAIC 部署侧治理。共享部署可设置 ACCESS_CODE；公网部署还要关注 SSRF 防护、私有网络模型地址、CSP frame ancestors 和日志中的敏感数据。
何时值得部署
它适合希望把课程材料快速转成可互动课堂、又需要保留导出和二次编辑能力的教育团队、培训团队和技术社区。评估时不要只看一次生成效果，应固定一份教材，比较大纲修改、测验反馈、HTML 交互、PPTX 编辑、离线 ZIP 和服务端恢复是否符合真实流程。先从单用户、可信网络和一个 provider 开始，安全边界清楚后再扩展到多人。