HKUDS DeepTutor

1. DeepTutor là gì?

DeepTutor là một "gia sư AI" chạy trên máy của bạn, mở bằng trình duyệt. Bạn đưa tài liệu học vào (sách, bài giảng, ghi chú), rồi hỏi đáp, nhờ giải bài từng bước, tạo đề trắc nghiệm, nghiên cứu một chủ đề, vẽ sơ đồ minh họa hoặc học theo lộ trình. Bạn cũng có thể dán link YouTube để vừa xem vừa hỏi theo đúng mốc thời gian trong video. Dự án do nhóm HKUDS phát triển, mã nguồn mở, giấy phép Apache-2.0.

Phần mềm miễn phí. Nhưng DeepTutor không kèm sẵn "bộ não" AI: bạn phải nối nó với một mô hình ngôn ngữ, qua khóa API của một nhà cung cấp (thường tính tiền theo lượng dùng) hoặc qua một mô hình chạy ngay trên máy như Ollama, LM Studio.

Nói thẳng: DeepTutor chưa có file cài .exe hay .dmg. Bạn cài bằng vài dòng lệnh. Các bước không khó, nhưng bạn cần chịu khó gõ lệnh.

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

• Bạn là học sinh, sinh viên hoặc người tự học, muốn một chỗ gom tài liệu để hỏi đáp và luyện tập.
• Bạn sẵn sàng gõ 3–4 dòng lệnh và tự lấy một khóa API.
• Bạn muốn dữ liệu học tập nằm trên máy mình.

Chưa hợp nếu:

• Bạn chỉ có điện thoại. DeepTutor cài trên máy tính.
• Bạn muốn tải về, bấm đúp là dùng, không cấu hình gì.
• Bạn không muốn tạo khóa API và cũng không chạy được mô hình AI trên máy.

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

Thứ cần có	Chi tiết
Máy tính	Windows, macOS hoặc Linux.
Python 3.11 đến 3.14	Ngôn ngữ lập trình mà phần lõi DeepTutor chạy trên đó. Tải tại https://www.python.org/downloads/ . Trên Windows, khi cài nhớ tích ô "Add python.exe to PATH".
Node.js từ bản 20	Môi trường chạy phần giao diện web. Tải tại https://nodejs.org/
Một mô hình ngôn ngữ	Khóa API của một nhà cung cấp (thường mất tiền theo lượng dùng, giá xem ở trang của nhà cung cấp), hoặc mô hình chạy trên máy qua Ollama, LM Studio, llama.cpp, vLLM, Lemonade.
Mô hình embedding	Không bắt buộc. Chỉ cần khi bạn dùng tính năng Kho kiến thức (hỏi đáp trên tài liệu của riêng bạn).
Docker Desktop	Không bắt buộc. Chỉ cần nếu bạn chọn Cách B. Docker là phần mềm chạy ứng dụng trong một "hộp" đóng gói sẵn. Tải tại https://www.docker.com/products/docker-desktop/
Mạng	Cần để cài đặt và để gọi mô hình AI qua API.

Tài liệu dự án không nêu yêu cầu tối thiểu về RAM hay dung lượng ổ cứng. Xem thêm tài liệu chính thức tại https://deeptutor.info/

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

Dự án có bốn cách cài. Bài này hướng dẫn hai cách hợp với người mới: Cách A cài từ PyPI (kho gói Python), Cách B chạy bằng Docker. Hai cách còn lại (cài từ mã nguồn, bản chỉ có dòng lệnh) dành cho lập trình viên, xem README của dự án.

Bước 1 (Cách A): Kiểm tra Python và Node.js

Sau khi cài Python và Node.js, gõ lần lượt:

python --version
node --version

Thấy gì là đúng: dòng đầu in số bản Python từ 3.11 đến 3.14, dòng sau in số bản Node từ v20 trở lên. Trên macOS và Linux, nếu python báo lỗi thì thử python3.

Bước 2 (Cách A): Tạo thư mục riêng và cài DeepTutor

DeepTutor lưu cấu hình và dữ liệu ngay trong thư mục bạn đứng khi khởi động. Vì vậy hãy tạo một thư mục riêng và luôn chạy từ đó.

Windows (PowerShell):

mkdir my-deeptutor
cd my-deeptutor
pip install -U deeptutor

macOS / Linux:

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor

Thấy gì là đúng: máy tải nhiều gói trong vài phút, kết thúc bằng dòng có chữ "Successfully installed".

Bước 3 (Cách A): Thiết lập ban đầu

deeptutor init

Lệnh này hỏi bạn lần lượt: cổng cho phần lõi (mặc định 8001), cổng cho giao diện (mặc định 3782), nhà cung cấp mô hình, địa chỉ Base URL, khóa API và tên mô hình. Sau đó nó hỏi thêm nhà cung cấp embedding và tìm kiếm web, cả hai đều bỏ qua được.

Thấy gì là đúng: lệnh kết thúc không báo lỗi, trong thư mục xuất hiện thư mục con data.

Lưu ý: Bạn có thể bỏ qua bước này để xem thử cho nhanh. Ứng dụng vẫn mở với cổng mặc định, nhưng chưa có mô hình nào. Bạn cấu hình sau trong trang Settings.

Bước 4 (Cách A): Khởi động

deeptutor start

Thấy gì là đúng: cửa sổ dòng lệnh in ra địa chỉ của giao diện, mặc định là http://127.0.0.1:3782. Hãy để nguyên cửa sổ này mở. Muốn tắt ứng dụng, bấm Ctrl+C trong cửa sổ đó.

Cách B: Chạy bằng Docker

Nếu bạn đã cài Docker Desktop và nó đang chạy, chỉ cần một lệnh:

docker run --rm --name deeptutor -p 127.0.0.1:3782:3782 -v deeptutor-data:/app/data ghcr.io/hkuds/deeptutor:latest

Thấy gì là đúng: Docker tải ảnh (image) về rồi in nhật ký khởi động. Mở http://127.0.0.1:3782 trong trình duyệt. Cấu hình, khóa API, nhật ký và kho kiến thức được giữ trong ổ dữ liệu tên deeptutor-data, nên tắt đi bật lại không mất.

Với Cách B, bạn không chạy deeptutor init. Bạn cấu hình mô hình ngay trong trang Settings của giao diện web.

4. Dùng lần đầu

1. Mở trình duyệt, vào http://127.0.0.1:3782.
2. Nếu chưa khai báo mô hình: vào Settings → Providers, điền Base URL và khóa API rồi lưu. Sang mục Language models, thêm một mô hình và chọn nó.
3. Quay lại phần Chat, gõ một câu hỏi, ví dụ: "Giải thích phép biến đổi Fourier cho học sinh lớp 12".

Kết quả trông thế nào: câu trả lời hiện dần từng dòng trong khung chat. Nếu được vậy, phần mô hình đã nối đúng.

Việc nên thử tiếp:

• Task Board: bảng theo dõi việc học với ba cột To do, In progress, Done. Tính năng này không cần cấu hình mô hình.
• Kho kiến thức: tải tài liệu của bạn lên để hỏi đáp trên chính tài liệu đó. Cần thêm một mô hình embedding trong Settings.
• Quiz: nhờ tạo đề trắc nghiệm từ chủ đề hoặc tài liệu.
• Học qua video: dán một link YouTube để xem kèm phụ đề và hỏi theo mốc thời gian.

Giao diện có nhiều ngôn ngữ, đổi trong Settings. Danh sách ngôn ngữ xem trong ứng dụng.

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

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ pip hoặc deeptutor thì báo "command not found" hoặc "is not recognized"	Python chưa được thêm vào PATH (danh sách nơi máy tìm lệnh), hoặc bạn chưa mở lại cửa sổ dòng lệnh sau khi cài.	Đóng rồi mở lại cửa sổ dòng lệnh. Trên Windows, cài lại Python và tích ô "Add python.exe to PATH". Có thể thử python -m pip install -U deeptutor.
deeptutor start chạy phần lõi nhưng giao diện không lên	Thiếu Node.js hoặc bản cũ hơn 20. Giao diện web do Node.js chạy.	Cài Node.js bản 20 trở lên, mở lại cửa sổ dòng lệnh, chạy lại deeptutor start.
Báo cổng đã bị chiếm, hoặc trang 127.0.0.1:3782 không mở được	Một chương trình khác đang dùng cổng 3782 hoặc 8001.	Chạy lại deeptutor init và chọn cổng khác. Với Docker, đổi số bên trái trong -p, ví dụ -p 127.0.0.1:8088:3782, rồi mở http://127.0.0.1:8088.
Ứng dụng mở được nhưng chat không trả lời	Chưa khai báo mô hình, hoặc khóa API sai.	Vào Settings → Providers kiểm tra Base URL và khóa API, rồi chọn mô hình trong Language models.
Đã điền khóa vào file .env mà không có tác dụng	DeepTutor không đọc file .env ở thư mục gốc làm cấu hình.	Nhập khóa trong trang Settings. Cấu hình thật nằm trong data/user/settings/.
Chạy bằng Docker, nối Ollama qua localhost không được	Bên trong Docker, localhost là chính cái hộp, không phải máy bạn.	Trong Settings → Providers, dùng http://host.docker.internal:11434/v1 cho Ollama. Trên Linux, thêm --add-host=host.docker.internal:host-gateway vào lệnh docker run.
Mở lại thì mất hết cấu hình	Bạn chạy deeptutor start từ một thư mục khác lần trước.	Luôn cd vào đúng thư mục đã tạo ở Bước 2 trước khi khởi động.

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

Cập nhật (Cách A). Tắt ứng dụng bằng Ctrl+C, rồi chạy lại lệnh cài có tham số -U:

pip install -U deeptutor

Cập nhật (Cách B). Dừng hộp đang chạy, tải ảnh mới rồi chạy lại lệnh ở Cách B:

docker pull ghcr.io/hkuds/deeptutor:latest

Bản mới nhất lúc viết bài là v1.6.12 (phát hành 27/9/2026). Dự án ra bản mới rất dày, vài ngày một lần.

Gỡ cài đặt. Dự án hướng dẫn gỡ theo ba phần tách rời:

1. Tắt ứng dụng: bấm Ctrl+C trong cửa sổ đang chạy deeptutor start.
2. Xóa dữ liệu, chỉ khi bạn muốn xóa hết: cấu hình, khóa API, lịch sử chat, bộ nhớ, sổ ghi chú, kho kiến thức. Tất cả nằm trong thư mục data bên trong thư mục bạn tạo ở Bước 2. Khi khởi động, dòng bắt đầu bằng Workspace: cho biết chính xác đường dẫn. Hãy sao lưu nếu còn cần, rồi kéo thư mục đó vào Thùng rác.
3. Gỡ gói phần mềm:

python -m pip uninstall deeptutor

Với Docker, gỡ hộp và ổ dữ liệu. Lệnh thứ hai xóa vĩnh viễn toàn bộ dữ liệu:

docker rm -f deeptutor
docker volume rm deeptutor-data

Lưu ý: Nếu bạn đã đặt "Content Workspace" (thư mục nội dung) ở một nơi khác trong Settings, thư mục đó không bị xóa khi gỡ. Bạn tự sao lưu hoặc xóa riêng.

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

Có mất tiền không? DeepTutor miễn phí. Tiền, nếu có, là tiền bạn trả cho nhà cung cấp mô hình AI theo lượng dùng. Nếu chạy mô hình ngay trên máy (ví dụ qua Ollama) thì không mất phí API.

Có cần mạng không? Cần mạng để cài đặt và để gọi mô hình qua API. Riêng tính năng học qua video và tìm kiếm web luôn cần mạng.

Dữ liệu của tôi nằm ở đâu? Cấu hình, khóa API, lịch sử chat và kho kiến thức lưu trên máy bạn, trong thư mục data. Tuy nhiên câu hỏi và đoạn tài liệu liên quan sẽ được gửi tới nhà cung cấp mô hình mà bạn chọn để lấy câu trả lời.

Máy yếu có chạy được không? Tài liệu dự án không nêu cấu hình tối thiểu. Khi dùng mô hình qua API, phần tính toán nặng nằm ở máy chủ của nhà cung cấp. Khi chạy mô hình ngay trên máy thì máy cần đủ mạnh cho mô hình đó.

Có dùng được tiếng Việt không? Bạn hỏi đáp bằng tiếng Việt được nếu mô hình bạn chọn hiểu tiếng Việt. Về ngôn ngữ giao diện, hãy xem danh sách trong Settings của bản bạn cài.