OpenMAIC: tạo lớp học AI có giáo viên và bạn học ảo từ một chủ đề — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về THU-MAIC/OpenMAIC — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: OpenMAIC: biến chủ đề hoặc tài liệu thành lớp học AI tương tác — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
OpenMAIC (Open Multi-Agent Interactive Classroom) là nền tảng mã nguồn mở, giấy phép MIT, biến một chủ đề hoặc tài liệu thành lớp học tương tác với giáo viên AI và bạn học AI. Bạn tự chạy trên máy mình bằng Node.js, pnpm và PostgreSQL, hoặc bằng Docker. Cài không quá khó nhưng cần có API key của một nhà cung cấp mô hình AI.
OpenMAIC (Open Multi-Agent Interactive Classroom) là một nền tảng mã nguồn mở, biến một chủ đề hoặc một bộ tài liệu thành lớp học tương tác. Bạn nhập chủ đề, AI dựng bài giảng gồm slide, câu hỏi kiểm tra, mô phỏng tương tác. Giáo viên AI sẽ giảng, vẽ lên bảng trắng và nói thành tiếng. Bên cạnh còn có các bạn học AI để thảo luận cùng bạn.
Repo này hợp với ba nhóm người. Thứ nhất là giáo viên, người làm đào tạo nội bộ trong doanh nghiệp, cần dựng bài giảng nhanh. Thứ hai là người tự học, muốn có một lớp học chạy riêng theo đúng chủ đề mình quan tâm. Thứ ba là lập trình viên muốn tự host một hệ thống học tập có AI. Repo viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 43.435 sao và 6.698 fork, và vẫn được cập nhật trong 3 tháng gần đây.
Điểm đáng giá nhất là bạn không chỉ nhận một bộ slide. Bạn nhận cả một buổi học có người giảng, có người hỏi lại, có bài tập dự án. Kết quả còn xuất ra được file .pptx, file .html chạy offline, hoặc gói ZIP để chuyển sang máy khác.
THU-MAIC/OpenMAIC
OpenMAIC biến một chủ đề hoặc tài liệu thành lớp học tương tác: slide, quiz, mô phỏng, có giáo viên AI giảng và vẽ bảng trắng.
I.OpenMAIC làm được gì
Dưới đây là các tính năng chính theo mô tả của tác giả, kèm lợi ích thực tế.
- Tạo bài giảng chỉ với một lần mô tả. Bạn nêu chủ đề hoặc đính kèm tài liệu, AI dựng cả bài học trong vài phút. Người làm văn phòng đỡ phải ngồi chỉnh từng slide.
- Lớp học nhiều tác tử. Giáo viên AI và bạn học AI cùng giảng, thảo luận và tương tác với bạn theo thời gian thực. Học có đối thoại dễ nhớ hơn đọc một chiều.
- Nhiều loại cảnh học. Gồm slide, quiz, mô phỏng HTML tương tác và học theo dự án (PBL). Bản PBL mới nhất cho bạn làm ra một sản phẩm chạy được cùng gia sư AI, theo từng mốc.
- Bảng trắng và giọng nói. Tác tử vẽ sơ đồ, viết công thức và giải thích thành tiếng.
- Xuất ra nhiều dạng. Có file
.pptxgiữ đủ các cảnh, một file.htmloffline phát được cả bài, hoặc ZIP lớp học để chuyển sang nơi khác. - Kết nối với trợ lý khác. Skill OpenMAIC có sẵn chạy được với OpenClaw và một số agent workbench như Codex, DeepSeek, WorkBuddy. Nhờ đó bạn tạo lớp học từ ứng dụng nhắn tin như Feishu, Slack, Telegram, hoặc ngay trong IDE.
- Chọn mô hình AI linh hoạt. Hỗ trợ OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok, OpenRouter, Ollama và nhiều bên khác, kể cả mọi API tương thích OpenAI.
II.Cần chuẩn bị gì
Theo README và package.json, bạn cần:
- Node.js từ 22.19 trở lên.
- pnpm từ 10 trở lên.
- PostgreSQL 16, vì khoá học được lưu trên máy chủ. Khi chạy thử trên máy cá nhân, lệnh
pnpm db:upsẽ dựng giúp một PostgreSQL trong Docker. Vậy bạn cần cài thêm Docker nếu dùng cách này. - API key của ít nhất một nhà cung cấp mô hình. Bản cấu hình mẫu chỉ cần
OPENAI_API_KEY, hoặc bạn đổi sang nhà cung cấp khác mà bạn có key. - Git để tải mã nguồn về.
README phần đã cung cấp không nói rõ hệ điều hành nào được hỗ trợ và không nêu yêu cầu card đồ hoạ. Mô hình AI được gọi qua API của các nhà cung cấp, trừ khi bạn tự chọn chạy cục bộ bằng Ollama hoặc Lemonade. Phần phần cứng cho trường hợp đó README chưa nói trong đoạn mình có.
API key là thứ tính tiền. Chỉ điền vào file .env.local trên máy bạn, không dán vào chat, không đưa lên GitHub. Mỗi lần tạo bài giảng sẽ gọi mô hình nhiều lần nên có thể tốn phí tuỳ nhà cung cấp.
III.Cài đặt từng bước
- Tải mã nguồnClone repo và cài thư viện bằng pnpm
- Tạo file cấu hìnhSao chép .env.example và openmaic.example.yml
- Điền API keyGhi key vào .env.local, chọn mô hình trong openmaic.yml
- Bật cơ sở dữ liệuChạy pnpm db:up rồi bỏ comment dòng DATABASE_URL
- Chạy ứng dụngChạy pnpm dev và mở localhost:3000
A.Tải mã nguồn và cài thư viện
Mở terminal (PowerShell trên Windows, Terminal trên macOS hay Linux) ở thư mục bạn muốn lưu dự án, rồi chạy:
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm installLệnh đầu tải mã nguồn về. Lệnh thứ hai đi vào thư mục dự án. Lệnh thứ ba cài các thư viện cần thiết. Nếu máy báo không có pnpm, bạn cần cài pnpm trước. README phần đã cung cấp không ghi cách cài pnpm, bạn xem hướng dẫn trên trang chính thức của pnpm.
B.Tạo file cấu hình
Hai lệnh sau sao chép file mẫu thành file thật:
cp .env.example .env.local # API keys and server options
cp openmaic.example.yml openmaic.yml # which models the server usesFile .env.local chứa key và tuỳ chọn máy chủ. File openmaic.yml nói máy chủ dùng mô hình nào. Phần sau # chỉ là chú thích, bạn không cần gõ. Trên PowerShell, cp là bí danh của lệnh sao chép nên dùng được. Nếu bị lỗi, bạn có thể copy file bằng tay trong File Explorer và đổi tên.
C.Điền API key và chọn mô hình
Mở .env.local và điền OPENAI_API_KEY (hoặc key của nhà cung cấp khác). Mọi dòng còn lại trong file mẫu đang được comment, chưa cần động tới.
File openmaic.yml khai báo hai thứ. Providers là các tài khoản mà máy chủ được gọi. Slots là từng việc dùng AI (dựng dàn ý, nội dung slide, đọc thành tiếng, tìm web...), mỗi việc gắn một mô hình. Key luôn nằm trong .env.local và được gọi lại bằng ${TÊN_BIẾN}. Ví dụ từ README:
providers:
openai:
preset: openai
apiKey: ${OPENAI_API_KEY} # OPENAI_API_KEY=sk-... in .env.local
anthropic:
preset: anthropic
apiKey: ${ANTHROPIC_API_KEY}
slots:
llm: openai:gpt-5.5 # the default chat model
course.outline: anthropic:claude-sonnet-4-6
video: null # turn a capability offDòng llm là mô hình chat mặc định. Dòng video: null là tắt hẳn một khả năng. Nếu bạn chỉ có key OpenAI, hãy đổi các slot đang trỏ sang Anthropic cho khớp với nhà cung cấp bạn có, hoặc bỏ phần Anthropic. Sai chỗ nào, máy chủ sẽ báo đúng tên trường lỗi (hoặc số dòng nếu YAML hỏng) khi khởi động.
Tác giả gợi ý bật đủ các khả năng (ảnh minh hoạ, giọng đọc, video, tìm web) và chọn mô hình nhanh, ngữ cảnh dài làm mặc định. Một số nhà cung cấp có gói token dùng một key cho nhiều khả năng. Ví dụ với MiniMax:
providers:
minimax:
preset: minimax
apiKey: ${MINIMAX_API_KEY}
slots:
llm: minimax:MiniMax-M3
image: minimax # a provider id alone: the plan's default model
video: minimax
tts: minimax
webSearch: minimaxBạn có thể bỏ qua bước này lúc mới thử. Chỉ cần một key chạy được là đủ.
D.Bật cơ sở dữ liệu
Khoá học được lưu ở máy chủ, nên cần PostgreSQL. Có Docker thì chạy:
pnpm db:upLệnh này dựng một PostgreSQL phát triển tại 127.0.0.1:5432. Nếu cổng 5432 đã bị chiếm, README cho biết đặt biến OPENMAIC_DB_PORT để dùng cổng khác. Dừng DB mà giữ dữ liệu thì dùng pnpm db:down. Sau đó mở .env.local, bỏ dấu comment ở dòng DATABASE_URL:
DATABASE_URL=postgres://openmaic:openmaic-dev@127.0.0.1:5432/openmaicBạn dùng PostgreSQL khác cũng được, miễn điền đúng địa chỉ vào DATABASE_URL.
E.Chạy ứng dụng
pnpm devĐể cửa sổ terminal này mở trong lúc dùng. Tắt terminal là ứng dụng tắt theo.
F.Cách khác: chạy bằng Docker
Nếu không muốn cài Node và pnpm, README có sẵn cách chạy bằng Docker Compose gồm hai container: ứng dụng và PostgreSQL.
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --buildDữ liệu nằm trong hai volume openmaic-postgres và openmaic-data, vẫn còn sau docker compose down. Lệnh docker compose down -v thì xoá sạch chúng, nên đừng chạy nếu chưa muốn mất bài học. Bản Compose này là cài đặt cá nhân: chỉ lắng nghe ở 127.0.0.1:3000, mọi trình duyệt trên máy thấy chung một thư viện.
Muốn cho máy khác truy cập, README yêu cầu đặt trước ACCESS_CODE dài và ngẫu nhiên trong .env.local, cùng PERSISTENCE_POSTGRES_PASSWORD. Không có ACCESS_CODE thì ai tới được cổng cũng sửa và xoá được toàn bộ thư viện.
IV.Kiểm tra đã chạy được chưa
Sau khi pnpm dev (hoặc docker compose up --build) chạy xong, mở trình duyệt vào http://localhost:3000. Nếu thấy giao diện OpenMAIC hiện ra là cài thành công. README viết đúng câu "Open http://localhost:3000 and start learning".
Nếu quên khai báo DATABASE_URL, máy chủ sẽ từ chối khởi động và in hướng dẫn cách cung cấp. Đây không phải lỗi lạ. Đó là cách repo nhắc bạn làm nốt bước cơ sở dữ liệu.
Bước thử đầu tiên nên là một chủ đề nhỏ, ví dụ "nguyên tắc cơ bản của bảng cân đối kế toán". Nếu bài giảng được dựng ra thì key và mô hình đã nối đúng.
V.Dùng vào việc thật
A.Dựng bài đào tạo nhân viên mới
Chị Lan làm hành chính nhân sự ở một công ty nhỏ, tuần nào cũng giới thiệu quy trình cho nhân viên mới. Chị đính kèm tài liệu quy trình nội bộ vào OpenMAIC và nhập yêu cầu: "Dựng bài giới thiệu quy trình xin nghỉ phép và hoàn ứng, kèm vài câu hỏi kiểm tra". Kết quả là một lớp học có slide, có quiz, có giáo viên AI giảng. Chị xuất file .pptx để chỉnh thêm hoặc file .html offline để gửi cho nhân viên xem lại.
Một lớp học có người giảng, có người hỏi lại, chứ không chỉ là xấp slide.
Ông T
B.Tự học một chủ đề mới
Anh Minh làm kinh doanh, muốn hiểu cơ bản về dòng tiền. Anh nhập chủ đề, bật thêm tìm web nếu đã cấu hình slot webSearch, rồi vào học. Giữa chừng anh hỏi bạn học AI những chỗ chưa hiểu, xem giáo viên vẽ sơ đồ trên bảng trắng. Bản mới có chat trong lớp, cho phép hỏi về từng phần tử của slide. Kết quả là buổi học theo tốc độ của anh, không phải xem video dài.
C.Học lập trình qua một dự án nhỏ
Bạn là lập trình viên mới và muốn có sản phẩm thật. Chọn chế độ học theo dự án (PBL), mô tả thứ bạn muốn làm. Gia sư AI dẫn bạn đi qua từng mốc để ra một dự án chạy được. README ghi rõ PBL v3 là nâng cấp một chiều, nên nếu bạn nâng từ bản cũ thì nên sao lưu dữ liệu trước.
D.Tạo lớp học ngay từ ứng dụng nhắn tin hoặc IDE
Dev trong nhóm muốn gõ yêu cầu ngay trong Slack, Telegram hoặc IDE. README nói skill OpenMAIC dùng được với OpenClaw, Codex, DeepSeek, WorkBuddy. Cách cài skill không nằm trong phần README mình có, nên bạn hãy xem thư mục skills/ và mục OpenClaw trong README của repo.
VI.Lỗi hay gặp và cách xử lý
Server không khởi động, báo thiếu DATABASE_URL. Bạn chưa bật PostgreSQL hoặc chưa bỏ comment dòng DATABASE_URL trong .env.local. Chạy pnpm db:up, mở .env.local và bỏ dấu comment như hướng dẫn ở trên.
pnpm install hoặc chạy lỗi vì phiên bản Node. Repo yêu cầu Node từ 22.19 trở lên. Kiểm tra bằng node -v. Nếu thấp hơn, hãy nâng cấp Node rồi cài lại.
Cổng 5432 đang bị chiếm. Máy bạn có thể đang chạy một PostgreSQL khác. Dùng biến OPENMAIC_DB_PORT để đổi cổng, rồi sửa số cổng tương ứng trong DATABASE_URL. Hoặc dùng luôn PostgreSQL đó.
Máy chủ báo lỗi cấu hình openmaic.yml. README cho biết máy chủ kiểm tra file lúc khởi động và nêu tên trường sai, hoặc số dòng nếu YAML hỏng. Thường là thụt lề sai, hoặc slot trỏ tới nhà cung cấp bạn chưa khai báo key. Sửa đúng chỗ báo rồi chạy lại.
Tạo bài giảng không được dù đã mở được trang. Thường là key sai, hết hạn mức, hoặc mô hình ghi trong slot không có trong tài khoản của bạn. Kiểm tra lại key trong .env.local và tên mô hình trong openmaic.yml.
Định đưa lên Vercel. Hosting serverless chỉ hỗ trợ đến bản 1.1.x. Từ 1.2.0, việc tạo bài giảng chạy trong một tiến trình sống lâu trên máy chủ, nên cần Node.js chạy liên tục cùng PostgreSQL (Docker hoặc pnpm start).
VII.Có nên dùng không
Điểm mạnh. Giấy phép MIT, tự chạy trên máy mình. Hỗ trợ rất nhiều nhà cung cấp mô hình, kể cả mô hình chạy cục bộ. Xuất được .pptx, .html offline và ZIP nên không bị khoá vào một nơi. Dự án cập nhật đều, có nhiều bản vá bảo mật được ghi trong lịch sử phát hành.
Giới hạn. Bạn phải tự lo Node, pnpm, PostgreSQL (hoặc Docker) và API key, nên không phải ứng dụng bấm cài là xong. Chất lượng bài giảng phụ thuộc mô hình bạn chọn, và chi phí gọi API do bạn chịu. Bản Docker mặc định là cho một người dùng, muốn mở cho nhiều người phải tự thiết lập ACCESS_CODE và mật khẩu. Một số cập nhật là nâng cấp một chiều, nên cần đọc ghi chú phát hành trước khi nâng.
Khi nào chọn cách khác. Nếu bạn chỉ cần vài slide nhanh một lần, một công cụ tạo slide có sẵn sẽ gọn hơn. Nếu bạn không có người hỗ trợ kỹ thuật và không quen terminal, hãy thử bản chạy Docker trước, hoặc nhờ một bạn kỹ thuật cài giúp. Nếu cần hệ thống nhiều người dùng với phân quyền, hãy đọc kỹ phần Hosting and identity trong tài liệu của repo trước khi quyết định.
Câu hỏi thường gặp
OpenMAIC có miễn phí không?
Mã nguồn dùng giấy phép MIT nên bạn tải và chạy miễn phí. Tuy nhiên bạn cần API key của nhà cung cấp mô hình AI, và chi phí gọi API do bạn trả tuỳ nhà cung cấp. Bảng giá cụ thể repo không nêu.
Cần GPU không?
Tư liệu không yêu cầu GPU. Mô hình AI được gọi qua API của nhà cung cấp mà bạn cấu hình. README có nhắc Ollama, Lemonade và FunASR cho trường hợp chạy cục bộ, nhưng phần yêu cầu phần cứng của các mục đó chưa có trong thông tin mình có.
Chạy được trên Windows không?
README phần đã cung cấp không nêu rõ hệ điều hành hỗ trợ. Yêu cầu chỉ ghi Node.js từ 22.19, pnpm từ 10 và PostgreSQL 16. Có cả cách chạy bằng Docker Compose, thường tiện hơn nếu bạn không muốn cài từng thứ.
Dữ liệu và API key có an toàn không?
Key nằm trong file .env.local trên máy chủ của bạn, và khoá học lưu trong PostgreSQL do bạn quản lý. Bản Docker mặc định chỉ lắng nghe ở 127.0.0.1. Nếu mở cho máy khác, README yêu cầu đặt ACCESS_CODE dài ngẫu nhiên, nếu không ai tới được cổng cũng sửa và xoá được thư viện. Nội dung bạn gửi cho nhà cung cấp mô hình thì theo chính sách của họ.
Có cần cài PostgreSQL riêng không?
Có, cần PostgreSQL 16 vì khoá học lưu trên máy chủ. Khi phát triển trên máy cá nhân, lệnh pnpm db:up dựng giúp một bản trong Docker. Không có DATABASE_URL thì máy chủ từ chối khởi động.
Xuất bài giảng ra được những định dạng nào?
Theo README, bạn xuất được file .pptx giữ đủ các cảnh, một file .html offline phát cả bài học, hoặc ZIP lớp học để chuyển sang nơi triển khai khác.
Có chạy được trên Vercel không?
Chỉ bản đến 1.1.x. Từ 1.2.0, việc tạo bài giảng chạy trong tiến trình sống lâu, nên cần Node.js chạy liên tục cùng PostgreSQL, bằng Docker hoặc pnpm start. Vercel và các host serverless khác không được hỗ trợ.


