Tự host OpenMAIC: biến tài liệu thành lớp học AI có giáo viên và bạn học AI

Một team lead phòng CNTT nhờ mình xem lại bộ tài liệu onboarding cho nhân viên mới: gần 40 slide, ba file PDF, một runbook dài chục trang. Tài liệu viết kỹ, nhưng sau hai tuần, nhân viên mới vẫn hỏi lại những thứ đã có sẵn trong slide — vì không ai học hết tài liệu tĩnh.

Tự học một stack mới một mình cũng vậy: chatbot trả lời ngay, nhưng không ai đặt câu hỏi ngược lại, không ai cùng thảo luận, không có bài tập nào bắt mình làm thật.

OpenMAIC sinh ra cho đúng khoảng trống đó: một lớp học AI đa agent mã nguồn mở, tự host được, biến một chủ đề hoặc một tài liệu thành buổi học tương tác — giáo viên AI, bạn học AI, bảng trắng, quiz, mô phỏng, học theo dự án. Bài này hướng dẫn tự host OpenMAIC.

OpenMAIC là gì? Lớp học AI đa agent từ Tsinghua MAIC

OpenMAIC là viết tắt của Open Multi-Agent Interactive Classroom, dự án mã nguồn mở giấy phép MIT từ phòng thí nghiệm MAIC của Đại học Thanh Hoa. Kho mã nguồn tại github.com/THU-MAIC/OpenMAIC, demo tại open.maic.chat. Dự án có khoảng 42.768 star và 6.579 fork; bản mới nhất v1.4.1 ra ngày 6 tháng 11 năm 2026.

Bạn đưa vào một chủ đề hoặc một tài liệu, hệ thống dàn xếp nhiều agent AI thành một lớp học. Giáo viên AI giảng bằng slide, bảng trắng, đặt câu hỏi kiểm tra. Bạn học AI đặt câu hỏi, nêu ý kiến khác, thảo luận theo thời gian thực. Người học thảo luận, làm quiz, chạy mô phỏng. PBL v3 để AI tutor dẫn người học qua yêu cầu, thiết kế, triển khai.

Đối tượng phù hợp: team lead và trainer cần đào tạo nội bộ, sysadmin và DevOps muốn biến runbook thành buổi học cho cả team, developer tự học stack mới, và người chơi homelab. Cần phân biệt OpenMAIC với DeepTutor, gia sư AI 1-1 trên tài liệu của bạn. DeepTutor là một gia sư riêng: bạn hỏi, nó trả lời dựa trên tài liệu, có quiz và truy vết bằng chứng. OpenMAIC là một lớp học đa agent: có thảo luận, có giáo viên và bạn học. Nếu chỉ cần hỏi-đáp nhanh, gia sư 1-1 là đủ và nhẹ hơn nhiều.

Kiến trúc: Next.js, PostgreSQL và mô hình provider/slot

OpenMAIC chạy trên Next.js 16, React 19, TypeScript 5, Tailwind CSS 4, với PostgreSQL 16 làm kho dữ liệu. Hai đường chạy: Docker Compose, hoặc dev từ source với pnpm. Cả hai đều cần key LLM — mặc định chỉ cần OPENAI_API_KEY.

Điểm kiến trúc đáng chú ý nhất nằm ở file openmaic.yml: nó tách việc dàn xếp lớp học khỏi việc chọn model, khai báo các provider và các slot — mỗi slot là một khâu, ví dụ llm hay course.outline — và gán cho mỗi slot một model cụ thể. Key giữ trong .env.local, tham chiếu bằng ${VAR}. Nhờ vậy, khâu quan trọng dùng model frontier, khâu phụ dùng model rẻ hơn hoặc local.

Lớp học ở đây là một tiến trình dài có trạng thái, không phải chatbot bọc slide. Phiên học, tiến độ người học và các chỉnh sửa được giữ bền vững trong PostgreSQL, với đồng bộ nền giữ edits và learner progress (v1.4.1). Knowledge base cho phép upload tài liệu và nhắc đến bằng @, parse một lần rồi tái dùng. PBL v3 là opt-in, cần sandbox provider và checkpoint storage. Theo mình, chất lượng lớp học phụ thuộc vào ba thứ: model gán cho từng slot, session bền vững trong Postgres, và timeout của reverse proxy.

flowchart TB
    A["Người dùng / Người học<br/>localhost:3000"] --> B["OpenMAIC App — Next.js 16<br/>Agent Workbench, Pro Mode, 24 skill<br/>Classroom UI: slide/whiteboard/quiz/simulation"]
    B --> C["Multi-agent Orchestrator<br/>Giáo viên AI + bạn học AI"]
    C --> D["openmaic.yml — Provider/Slot Router<br/>Slots: llm, course.outline...<br/>Model theo từng khâu"]
    D --> E["LLM Providers<br/>OpenAI, Anthropic, Gemini, DeepSeek<br/>Ollama / Lemonade local, OpenAI-compatible"]
    E --> C
    C --> F["PostgreSQL 16<br/>Durable sessions, learner progress"]
    F --> B
    B --> G["Knowledge Base<br/>@ mention, parse một lần"]
    G --> C
    C --> H["PBL v3 — opt-in<br/>Sandbox Provider + Checkpoint Storage"]
    H --> F
    B --> I["Export — ngoài luồng học chính<br/>PPTX / offline HTML<br/>MP4 qua render service (video-export)"]

Theo chiều dữ liệu: người dùng gửi chủ đề hoặc tài liệu, orchestrator gọi skill, router chọn model theo từng slot, provider trả nội dung về, session và tiến độ được ghi vào Postgres, giao diện render slide, bảng trắng, quiz.

Tự host OpenMAIC bằng Docker Compose

Điều kiện tiên quyết. Docker và Docker Compose đã cài. Key LLM: mặc định là OpenAI, hoặc key của provider khác được hỗ trợ (Anthropic, Gemini, DeepSeek, OpenRouter, Ollama local…). Chạy dev từ source thì cần Node.js từ 22.19, pnpm từ 10, PostgreSQL 16 (pnpm db:up lo Postgres).

Cách 1 — Docker Compose (khuyên dùng). Đây là đường ít biến số nhất:

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
docker compose up --build

Sau đó mở http://localhost:3000. Hai container: app và PostgreSQL. Dữ liệu nằm trong hai named volume openmaic-postgres và openmaic-data, sống sót sau docker compose down — chỉ mất khi chạy docker compose down -v. Muốn mở từ máy khác, đặt OPENMAIC_PUBLISH_ADDRESS=0.0.0.0.

Cách 2 — Chạy dev từ source. Nếu muốn sửa code hoặc theo dõi log chi tiết:

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
cp openmaic.example.yml openmaic.yml
pnpm db:up
pnpm dev

pnpm dev chạy dev; production từ source thì dùng pnpm build && pnpm start.

Cấu hình .env.local và openmaic.yml. Trong .env.local, với ví dụ mặc định bạn chỉ cần điền OPENAI_API_KEY. Nếu dùng provider khác, đổi provider tương ứng trong openmaic.yml. Key luôn nằm trong .env.local, tham chiếu dạng ${VAR} — tuyệt đối không commit file này lên Git. Xem từng slot đang gán model nào trước khi tạo lớp học đầu tiên. Theo mình, gán model frontier cho course.outline và khâu giảng chính.

Kiểm tra và lỗi thường gặp. Kiểm tra bằng docker compose ps: cả hai container app và Postgres đều phải running. Mở http://localhost:3000 và thấy giao diện tạo lớp học.

• Sai key provider: lớp học báo lỗi gọi model. Kiểm tra .env.local và provider trong openmaic.yml, rồi khởi động lại container.
• Postgres chưa lên: app không kết nối được database. Chờ Postgres healthy, hoặc xem docker compose logs postgres.
• Port 3000 bận: đổi port mapping trong file compose hoặc dừng ứng dụng chiếm port.
• Build Docker lần đầu lâu hoặc lỗi: lần build đầu cần tải nhiều dependency; kiểm tra mạng và ổ đĩa, rồi chạy lại.
• Mở từ máy khác không được: kiểm tra OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 và firewall có cho qua port 3000 không.

Tạo lớp học AI đầu tiên

Từ một chủ đề. Bạn nhập chủ đề “Docker cơ bản cho nhân viên vận hành mới”, chọn phong cách lecture, workshop hay vocational — rồi để hệ thống tạo dàn ý, slide và quiz. Giáo viên AI giảng từng phần, bạn học AI đặt câu hỏi: “container khác gì máy ảo?”, “khi nào nên dùng volume?”. Người học trả lời, thảo luận, rồi làm quiz.

Từ tài liệu. Nếu đã có tài liệu sẵn — runbook, PDF quy trình, slide cũ — bạn upload vào knowledge base và nhắc đến bằng @ khi tạo lớp học. Tài liệu được parse một lần rồi tái dùng.

Trong lớp học. Giáo viên AI giảng, bạn học AI hỏi và thảo luận, bảng trắng ghi lại ý chính, quiz kiểm tra ngay sau từng phần, mô phỏng tương tác cho người học thao tác trực tiếp. Agent Workbench và Pro Mode có 24 skill built-in. Thử một lớp học nhỏ với chủ đề thật trước, đọc kỹ nội dung AI sinh ra.

PBL v3 và xuất bài học

PBL v3 là chế độ học theo dự án, có trong v1.4.0. AI tutor dẫn người học qua các bước xác định yêu cầu, thiết kế, triển khai.

PBL v3 là tính năng opt-in, không bật mặc định. Để dùng, cần sandbox provider và checkpoint storage, rồi mở /pbl-v3. Thiếu hai thứ này, tính năng sẽ thất bại hoặc mất tiến độ học viên.

Xuất bài học: xuất PPTX giữ nguyên từng scene, hoặc một file HTML offline duy nhất để chia sẻ. Xuất MP4 một click thì cần render service riêng (profile video-export), không kèm sẵn trong bản deploy mặc định.

docker compose --profile video-export up

Chạy AI local và kiểm soát chi phí

OpenMAIC hỗ trợ chạy model local qua Ollama và Lemonade, nhận giọng nói local qua FunASR, và TTS VoxCPM2. Đường thử nghiệm rẻ: chạy thử lớp học bằng model local trước, thấy ổn mới dùng API trả phí.

Chiến lược slot là cách kiểm soát chi phí: model frontier cho outline và giảng, model rẻ/local cho khâu phụ. Nhưng dùng model local hoặc model rẻ cho mọi slot thì chất lượng giảng và dàn ý có thể sụt — mình chưa test chất lượng TTS hay chất lượng lớp học với model local. Key LLM nằm trong .env.local, tham chiếu ${VAR} trong openmaic.yml; không commit .env.local, deploy cho team thì đặt sau reverse proxy có xác thực.

Đánh giá kỹ thuật: ưu điểm, nhược điểm, bảo mật, vận hành

Ưu điểm. Mô hình đa agent tương tác thật, không phải chatbot gắn thêm slide. Export linh hoạt: PPTX giữ nguyên scene, HTML offline, MP4 khi cần video. Provider mở: OpenAI, Anthropic, Gemini, DeepSeek, Ollama local và API tương thích OpenAI. Giấy phép MIT, nhịp phát hành tích cực — v1.4.1 ra ngày 6 tháng 11 năm 2026.

Nhược điểm. Chất lượng lớp học phụ thuộc hoàn toàn vào model, prompt và tài liệu đầu vào — không đảm bảo nội dung AI sinh ra đúng chuyên môn hay đúng sư phạm. Chưa có số liệu hiệu năng hay RAM/CPU đã kiểm chứng, chất lượng TTS chưa được test. Nhịp release nhanh, đối chiếu đúng v1.4.1.

Bảo mật. Key trong .env.local, không commit. Khi publish với OPENMAIC_PUBLISH_ADDRESS=0.0.0.0, đặt sau reverse proxy và xác thực, không phơi trực tiếp ra internet.

Vận hành và nâng cấp. Nâng cấp từ v1.3.x và v1.4.0 là một chiều: dừng mọi instance cũ trước khi nâng cấp, bản mới sẽ migrate database và instance cũ tự thoát. Rollback chỉ thực hiện được bằng cách restore database. Vì vậy, pin version khi chạy production, backup Postgres trước mọi lần nâng cấp. Sao lưu bằng backup volume openmaic-postgres hoặc pg_dump.

So sánh với các lựa chọn cùng phạm vi

Theo mình, OpenMAIC không thay thế LMS hay gia sư 1-1 — nó lấp khoảng giữa: buổi học tương tác thay vì soạn tay toàn bộ nội dung như LMS, và nhiều hơn hỏi-đáp 1-1 của chatbot.

Use case thực tế

Doanh nghiệp và đào tạo nội bộ. Onboarding nhân viên mới, chuẩn hóa kiến thức vận hành. Team lead tạo lớp học từ runbook sẵn có, nhân viên học qua thảo luận và quiz.

Homelab. Chạy lớp học AI tại nhà, thử model local qua Ollama hoặc Lemonade trước khi dùng API trả phí — cách rẻ nhất để đánh giá OpenMAIC.

DevOps và IT admin. Biến runbook, tài liệu hệ thống, quy trình xử lý sự cố thành lớp học tương tác. Người mới học bằng cách thảo luận về chính tài liệu vận hành của team mình.

Giáo viên, trainer và developer. Dạy stack mới, dùng PBL v3 để học viên làm dự án thật thay vì chỉ đọc slide.

Kết luận: ai nên tự host, ai chưa nên

Nên thử nếu bạn là team lead, trainer, sysadmin hay DevOps cần đào tạo tương tác từ tài liệu sẵn có và đã có key LLM cùng một máy chủ Docker. Thử theo thứ tự: mở demo tại open.maic.chat, deploy bằng Docker Compose, tạo một lớp học nhỏ, rồi mới mở rộng cho team.

Chưa nên nếu bạn chỉ cần hỏi-đáp nhanh trên tài liệu — lúc đó gia sư 1-1 là đủ. Chưa nên nếu bạn không có key LLM tốt, vì chất lượng lớp học phụ thuộc trực tiếp vào model. Chưa nên dùng cho đào tạo chính thức khi nội dung chưa được rà soát.

Bài học rút ra

1. Chọn Docker Compose trước, dev-from-source sau — ít biến số nhất, volume giữ dữ liệu sau docker compose down.
2. Gán model theo slot trong openmaic.yml — chất lượng và chi phí đều nằm ở chỗ này.
3. Coi việc tạo lớp học là tiến trình dài có state trong Postgres.
4. Pin version và backup database trước mọi nâng cấp — upgrade một chiều, rollback chỉ bằng restore database.
5. Đừng mở 0.0.0.0 và đừng commit .env.local — key và dữ liệu lớp học cần reverse proxy và xác thực.
6. Kiểm chứng chất lượng lớp học bằng một chủ đề thật trước khi dùng cho đào tạo chính thức.

Phạm vi kiểm chứng

Kiểm chứng ngày 6 tháng 11 năm 2026 với README và GitHub API của THU-MAIC/OpenMAIC: giấy phép MIT, khoảng 42.768 star và 6.579 fork, bản v1.4.1 ra ngày 6 tháng 11 năm 2026, stack Next.js 16 / PostgreSQL 16, lệnh clone, pnpm, Docker Compose, danh sách provider. Các tính năng như PBL v3, bảng trắng, xuất PPTX/HTML/MP4, 24 skill built-in, Lemonade và FunASR đã được tài liệu mô tả, chưa được cài chạy độc lập. Chưa kiểm chứng: chất lượng lớp học, chất lượng TTS, mức RAM/CPU khi tự host, Docker build lần đầu — mình chưa chạy thử.

Tham khảo

• OpenMAIC — GitHub: https://github.com/THU-MAIC/OpenMAIC
• OpenMAIC — bản demo trực tuyến: https://open.maic.chat/
• OpenMAIC — bản phát hành v1.4.1: https://github.com/THU-MAIC/OpenMAIC/releases/tag/v1.4.1
• DeepTutor tự host: gia sư AI trên tài liệu của bạn — phamnam.me: https://phamnam.me/posts/deeptutor-gia-su-ai-ca-nhan-hoa/