OpenMAIC

1. OpenMAIC là gì?

OpenMAIC là phần mềm mã nguồn mở của Đại học Thanh Hoa (Trung Quốc) giúp biến một chủ đề hoặc một tài liệu thành cả một lớp học tương tác. Bạn gõ "dạy tôi Excel" hoặc tải tài liệu lên, AI dựng các trang bài giảng, câu hỏi kiểm tra, mô phỏng tương tác, và có "thầy giáo" cùng "bạn học" AI trò chuyện, giảng bài bằng giọng nói, vẽ lên bảng trắng. Bài có thể xuất ra file .pptx hoặc trang .html.

Phần mềm miễn phí (giấy phép MIT), nhưng nó không tự có bộ não AI: bạn phải nối nó với một dịch vụ mô hình AI (ví dụ OpenAI, Anthropic, Google Gemini, DeepSeek…) bằng khóa API của bạn, và các dịch vụ này thường tính tiền theo lượng dùng. Cũng có thể nối với mô hình chạy trên máy bạn (ví dụ Ollama), khi đó không tốn tiền dịch vụ nhưng cần máy mạnh.

OpenMAIC làm cho người quen dùng Docker và dòng lệnh. Với người mới, cài xong lần đầu mất khoảng 30–60 phút.

Hợp với bạn nếu:

• Bạn là giáo viên, sinh viên hoặc người tự học muốn thử dựng bài giảng bằng AI.
• Bạn đã có (hoặc sẵn sàng tạo) khóa API của một dịch vụ AI và chấp nhận trả phí theo lượng dùng.
• Bạn có thể cài Docker và gõ vài lệnh.

Chưa hợp nếu:

• Bạn muốn dùng ngay không cần cài đặt hay khóa API. README có ghi một bản demo trực tuyến tại https://open.maic.chat/ và chế độ "hosted" cần mã truy cập lấy ở trang đó; hãy xem trang đó trước khi quyết định cài.
• Bạn không muốn trả tiền cho dịch vụ AI và máy bạn không đủ mạnh để chạy mô hình cục bộ.

2. Cần chuẩn bị gì?

Mục	Yêu cầu
Máy	Máy tính chạy được Docker (Windows, macOS hoặc Linux)
Docker	Docker Desktop (Windows/macOS) tại https://docs.docker.com/desktop/ , hoặc Docker Engine trên Linux tại https://docs.docker.com/engine/install/
Git (tùy chọn)	Để tải mã nguồn bằng lệnh. Không có Git thì dùng nút Code > Download ZIP trên trang https://github.com/THU-MAIC/OpenMAIC rồi giải nén
Khóa API	Ít nhất một dịch vụ mô hình AI (OpenAI, Anthropic, Gemini, DeepSeek… hoặc mô hình chạy trên máy). Phần lớn tính phí theo lượng dùng

Ngoài ra, bản chạy thẳng từ mã nguồn (không dùng Docker) cần Node.js từ 22.19, pnpm từ 10 và PostgreSQL 16. Hướng dẫn này đi đường Docker vì đơn giản hơn: Docker lo luôn cơ sở dữ liệu.

3. Cài đặt từng bước

Các lệnh dưới đây lấy từ mục "Docker Deployment" của README chính thức. Chưa từng dùng dòng lệnh thì xem khung "Chưa từng dùng dòng lệnh?" ở trên trang.

Bước 1: Tải mã nguồn

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

Nếu không dùng Git, giải nén file ZIP rồi mở Terminal/PowerShell ngay trong thư mục vừa giải nén.

Bước 2: Tạo file cấu hình

cp .env.example .env.local

Trên Windows PowerShell dùng copy .env.example .env.local. Mở .env.local bằng trình soạn văn bản và điền khóa API của dịch vụ bạn dùng vào dòng tương ứng, ví dụ OPENAI_API_KEY= cho OpenAI. README ghi bản mẫu chỉ cần OPENAI_API_KEY; nếu bạn dùng nhà cung cấp khác, xem danh sách trong README. Cũng có thể bỏ trống và kết nối dịch vụ mô hình trong phần cài đặt mô hình của ứng dụng sau khi chạy.

Lưu ý: khóa API là bí mật như mật khẩu. Đừng đăng lên mạng hay gửi cho người khác.

Bước 3: Chạy

docker compose up --build

Lần đầu Docker dựng ứng dụng và cơ sở dữ liệu nên mất một lúc (có thể vài phút đến hơn chục phút). Bộ này gồm hai container: ứng dụng và PostgreSQL; ứng dụng chỉ khởi động khi cơ sở dữ liệu báo sẵn sàng.

Thấy gì thì là đúng: màn hình in nhiều dòng nhật ký và dừng ở trạng thái ứng dụng đang chạy (cửa sổ này phải để mở). Mở trình duyệt vào http://localhost:3000 sẽ thấy giao diện OpenMAIC.

Mặc định ứng dụng chỉ mở trên chính máy bạn (127.0.0.1:3000), người khác trong mạng không vào được. Muốn mở cho máy khác, README yêu cầu đặt ACCESS_CODE dài và ngẫu nhiên trong .env.local trước.

4. Dùng lần đầu

1. Mở http://localhost:3000.
2. Nếu chưa điền khóa API ở Bước 2, vào phần cài đặt mô hình trong ứng dụng và kết nối dịch vụ AI của bạn.
3. Gõ một chủ đề (ví dụ "Giới thiệu về Excel cho người mới") hoặc đính kèm tài liệu của bạn, rồi bắt đầu tạo bài.
4. Chờ AI dựng bài. Kết quả là một lớp học gồm các trang, câu hỏi và nội dung do AI tạo. Hãy thử trước với chủ đề ngắn để biết tốn bao nhiêu lượt dùng trước khi tạo bài lớn.

Dự án có thể tạo nội dung bằng ngôn ngữ bạn dùng (README ghi tự nhận diện ngôn ngữ từ bản 0.1.1), nhưng chất lượng tiếng Việt phụ thuộc vào mô hình bạn nối. Hãy kiểm tra thử trước khi dùng thật.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
docker: command not found hoặc docker compose không nhận	Chưa cài Docker, hoặc Docker Desktop chưa được mở	Cài Docker theo mục 2 và mở Docker Desktop trước khi gõ lệnh
git: command not found	Chưa cài Git	Cài Git từ https://git-scm.com/downloads hoặc dùng cách tải file ZIP
Vào http://localhost:3000 không thấy gì	Container còn đang dựng, hoặc cổng 3000 đang bị chương trình khác dùng	Chờ nhật ký báo ứng dụng đã chạy; tắt chương trình đang chiếm cổng 3000 (README cho phép đổi cổng bằng biến OPENMAIC_PORT)
Bấm tạo bài nhưng báo lỗi mô hình hoặc khóa	Chưa điền khóa API, khóa sai, hoặc hết hạn mức	Kiểm tra khóa trong .env.local hoặc trong cài đặt mô hình; kiểm tra số dư ở nhà cung cấp
Sửa .env.local nhưng không có tác dụng	Ứng dụng chỉ đọc cấu hình khi khởi động	Dừng (Ctrl+C) rồi chạy lại docker compose up --build
Muốn truy cập từ máy khác không được	Mặc định chỉ mở trên máy chủ	Làm theo mục "Docker Deployment" của README: đặt ACCESS_CODE và OPENMAIC_PUBLISH_ADDRESS

6. Gỡ cài đặt / cập nhật

Dừng. Nhấn Ctrl+C ở cửa sổ đang chạy, hoặc trong thư mục OpenMAIC chạy docker compose down. Theo README, các bài đã tạo nằm trong các ổ đĩa Docker nên vẫn còn sau docker compose down.

Xóa sạch dữ liệu. docker compose down -v xóa luôn các bài đã tạo. Chỉ dùng khi bạn chắc chắn không cần chúng nữa.

Cập nhật. Dự án phát hành khá thường xuyên và nhiều bản gần đây là bản sửa lỗi bảo mật (xem https://github.com/THU-MAIC/OpenMAIC/releases). Tải mã nguồn mới (trong thư mục đã clone: git pull), rồi chạy lại docker compose up --build. Hãy đọc ghi chú phát hành trước, vì README nhắc có thay đổi cách chạy giữa các bản.

7. Câu hỏi hay gặp

Có mất tiền không? Phần mềm miễn phí, nhưng dịch vụ AI nối vào thường tính tiền theo lượng dùng. Dùng mô hình chạy trên máy bạn thì không tốn phí dịch vụ nhưng cần máy mạnh.

Có cần mạng không? Cần mạng để tải lúc cài, và để gọi dịch vụ AI nếu bạn dùng dịch vụ đám mây.

Dữ liệu có bị gửi đi đâu không? Bài giảng lưu trên máy bạn dựng. Nội dung bạn nhập hoặc tải lên sẽ được gửi tới nhà cung cấp mô hình AI mà bạn chọn, vì vậy đừng đưa tài liệu nhạy cảm nếu chưa đọc chính sách của họ.

Máy yếu có chạy được không? Với dịch vụ AI đám mây thì máy chỉ cần chạy được Docker. README không nêu mức RAM tối thiểu, nên hãy xem trang chính thức nếu bạn dùng máy cũ.