# DeepTutor: gia sư AI cá nhân hoá, học từ tài liệu của bạn — hướng dẫn cài đặt và dùng

> DeepTutor (HKUDS) là ứng dụng gia sư AI mã nguồn mở viết bằng Python, giúp bạn học từ chính tài liệu của mình và theo dõi tiến độ lâu dài. Repo có giao diện web, dòng lệnh và bản chạy bằng Docker. Mức độ cài đặt vừa phải: cần Python 3.11 đến 3.14 hoặc Docker, và một nhà cung cấp mô hình AI do bạn tự cấu hình.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-09 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/deeptutor-gia-su-ai-ca-nhan-hoa-huong-dan-cai-dat-2

DeepTutor là một ứng dụng gia sư AI mã nguồn mở, do nhóm HKUDS phát triển, viết chủ yếu bằng Python. Mô tả của tác giả là "Lifelong Personalized Tutoring", tức gia sư cá nhân hoá theo bạn suốt quá trình học. Repo hiện có khoảng 58.722 sao và 7.135 fork, giấy phép Apache-2.0.

Nếu bạn từng nhét tài liệu vào một khung chat AI rồi hỏi qua hỏi lại, bạn sẽ thấy nó thiếu hai thứ: nhớ bạn đã học đến đâu, và biến tài liệu thành bài tập, sách, lộ trình. DeepTutor đi theo hướng đó. Nó gom tài liệu thành kho kiến thức, trò chuyện với bạn dựa trên kho đó, ra bài kiểm tra, và ghi nhớ tiến độ của bạn.

Điểm đáng giá nhất là repo này rất đầy đủ và được cập nhật dày. README ghi hàng chục bản phát hành liên tiếp, và repo vẫn có hoạt động trong vài tháng gần đây. Mặt trái là nó lớn, nên cài lần đầu cần kiên nhẫn hơn một công cụ nhỏ. Bạn có thể xem video ngắn bên dưới để thấy giao diện trước khi cài.

```repo
- repo | HKUDS/DeepTutor
- kind | Ứng dụng
- desc | DeepTutor là gia sư AI mã nguồn mở: nạp tài liệu của bạn, hỏi đáp, làm bài tập, nghiên cứu sâu và theo dõi tiến độ học lâu dài.
- stars | 59k
- lang | Python
- license | Apache-2.0
```

```video
- youtube | https://youtube.com/shorts/MVGQe6HqqMM
- facebook | https://www.facebook.com/reel/1618302949216785
- title | Video giới thiệu DeepTutor
```

## DeepTutor làm được gì

Phần README mình đọc được chủ yếu là nhật ký phát hành. Qua đó, đây là những nhóm tính năng nổi bật nhất. Mình chỉ nêu những gì tư liệu có nhắc.

### Học từ tài liệu của bạn

Bạn tạo "knowledge base" (kho kiến thức) từ tài liệu riêng. Nhật ký phát hành nhắc đến nhiều cách truy xuất như LightRAG, GraphRAG, PageIndex, cùng nhiều công cụ đọc tài liệu (PDF, DOCX, XLSX, EPUB). Lợi ích thực tế: câu trả lời bám theo giáo trình, báo cáo hay tài liệu nội bộ của bạn, thay vì chỉ trả lời chung chung.

### Đọc tài liệu cạnh khung chat

Chế độ "Immersive Reading" mở tài liệu bên cạnh cuộc trò chuyện, và trích dẫn theo từng trang. Bạn hỏi, rồi kiểm tra ngay câu trả lời nằm ở đâu trong tài liệu.

### Nghiên cứu sâu, giải bài, ra câu hỏi

Bản phát hành v1.4.0 nhắc đến các khả năng Deep Research, Solve và Question chạy theo kiểu agent. Hiểu đơn giản: một yêu cầu lớn được chia nhỏ, tìm thông tin, rồi tổng hợp thành báo cáo hoặc bộ câu hỏi.

### Học có theo dõi

Có Guided Learning với ngưỡng thành thạo cho từng loại câu hỏi, bảng theo dõi học tập, ngân hàng câu hỏi, luyện tập hằng ngày và nhật ký học. Đây là phần "cá nhân hoá lâu dài": hệ thống biết bạn đã làm được gì.

### Bộ nhớ nhiều tầng

Tư liệu nhắc đến bộ nhớ ba lớp (L1/L2/L3). Nhờ đó gia sư nhớ ngữ cảnh học của bạn qua nhiều buổi.

### Partners và kênh chat

"Partners" (trước đây là TutorBot) là trợ lý có tính cách và kho riêng, nối được với các kênh nhắn tin. README nhắc tới 15 kênh, ví dụ Mattermost, Zulip, WeChat. Bạn cũng có thể kết nối Claude Code hoặc Codex trên máy để gia sư hỏi ý kiến giữa chừng.

### Nhiều nhà cung cấp mô hình

Nhật ký nhắc nhiều nhà cung cấp: OpenAI, Anthropic, Gemini, NVIDIA NIM, Novita AI, Eden AI và các cổng tương thích OpenAI. Có cả đăng nhập bằng gói ChatGPT qua Codex OAuth. Bạn chọn mô hình theo ngân sách của mình.

### Dùng nhiều người, nhiều ngôn ngữ

Có chế độ nhiều tài khoản với không gian riêng cho từng người, gồm cả tài khoản học viên và người giám hộ. Giao diện đã được dịch sang nhiều ngôn ngữ như Pháp, Đức, Ukraina, Ba Lan, Hàn (bản xem trước).

## Cần chuẩn bị gì

Tư liệu mình có chỉ cho biết những điều sau:

- **Python**: file pyproject.toml yêu cầu Python từ 3.11 đến dưới 3.15, tức dùng được 3.11, 3.12, 3.13 và 3.14.
- **Docker** (nếu chọn cách chạy bằng container): repo có sẵn Dockerfile, compose.yaml, docker-compose.yml, docker-compose.ghcr.yml và compose.codex-oauth.yaml.
- **Một nhà cung cấp mô hình AI**: DeepTutor không tự mang theo "bộ não". Bạn cần cấu hình mô hình (và mô hình nhúng/embedding nếu lập chỉ mục tài liệu) trong phần Settings. Cần tài khoản hoặc API key của nhà cung cấp bạn chọn.
- **Cổng mạng**: file .env.example có ba biến HOST_PORT_BACKEND, HOST_PORT_FRONTEND, HOST_PORT_POCKETBASE để đổi cổng khi chạy bằng Docker.

Tư liệu chưa nói rõ yêu cầu RAM, GPU hay hệ điều hành cụ thể. Mình không đoán. Nhưng repo có bản tải về cho máy tính (desktop) theo nhật ký phát hành, và có cả Docker, nên chạy trên Windows là khả thi.

```note
API key là chìa khoá tính tiền của tài khoản bạn. Không dán key vào ảnh chụp màn hình, tin nhắn nhóm hay file đẩy lên GitHub. Mỗi lần AI đọc tài liệu và trả lời đều có thể tốn chi phí theo nhà cung cấp bạn chọn, nên hãy đặt hạn mức chi tiêu ở trang quản lý của họ.
```

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

Lưu ý quan trọng: phần README mình được cung cấp bị cắt trước mục hướng dẫn cài ("Get Started"). Vì vậy mình không chép lệnh cài chi tiết ở đây để tránh sai. Mình chỉ đưa các lệnh phổ thông chắc chắn đúng, và chỉ rõ chỗ bạn cần mở README để lấy lệnh chính thức.

```steps
- Kiểm tra Python hoặc Docker | Python 3.11 đến 3.14, hoặc Docker nếu muốn chạy bằng container
- Tải mã nguồn | Dùng git clone để lấy repo về máy
- Đọc mục Get Started | Mở README.md trong repo để lấy lệnh cài chính thức
- Cài và khởi chạy | Làm đúng lệnh trong README (bản Python hoặc Docker)
- Cấu hình mô hình AI | Điền nhà cung cấp và API key trong phần Settings của giao diện web
```

### Kiểm tra phiên bản Python

Mở terminal. Trên Windows bạn có thể mở PowerShell từ menu Start. Gõ lệnh sau và xem số phiên bản.

```bash
python --version
```

Nếu ra 3.11 đến 3.14 là ổn. Nếu thấp hơn 3.11 thì cần cài Python mới, hoặc chọn cách chạy bằng Docker. Chỗ người mới hay vấp: trên một số máy lệnh là `python3` hoặc `py` chứ không phải `python`.

### Tải mã nguồn về máy

Lệnh dưới tải repo về một thư mục tên DeepTutor, rồi đi vào thư mục đó. Bạn cần cài sẵn Git.

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
```

Từ giờ mọi lệnh bên dưới đều chạy trong thư mục DeepTutor này. Đây là chỗ người mới hay quên: mở terminal mới thì phải `cd` lại.

### Lấy lệnh cài chính thức trong README

Tên gói Python của dự án là `deeptutor`. Repo có đủ các file khai báo: pyproject.toml, setup.py, requirements.txt và thư mục requirements/. Nhật ký phát hành v1.7.0 còn nhắc đến "modular installation" (cài theo từng module). Nghĩa là có thể có nhiều lựa chọn cài, tuỳ phần bạn cần.

Vì lý do đó, hãy mở README.md ở mục Get Started và làm đúng lệnh ở đó. Nếu muốn xem thêm, hãy đọc file SKILL.md và thư mục docs-for-dev/ trong repo. README phần mình có chưa ghi lệnh cụ thể nên mình không chép lại.

### Hoặc chạy bằng Docker

Repo có sẵn file compose (compose.yaml, docker-compose.yml). Lệnh Docker Compose phổ thông để chạy là:

```bash
docker compose up -d
```

Lệnh này đọc file compose trong thư mục hiện tại và chạy các dịch vụ nền. Trước khi chạy, hãy xem README xem có cần tạo file .env từ .env.example hay không, và biến nào bắt buộc. Nếu cổng bị trùng với chương trình khác trên máy, bạn đổi bằng HOST_PORT_BACKEND, HOST_PORT_FRONTEND hoặc HOST_PORT_POCKETBASE trong file .env. Tư liệu mình có chưa nói giá trị mặc định của các cổng.

### Cấu hình mô hình AI

Sau khi giao diện web chạy, vào phần Settings để chọn nhà cung cấp và nhập API key. Nhật ký phát hành v1.7.2 nhắc "easier model setup" (thiết lập mô hình dễ hơn), và Settings có mục chấm mức sẵn sàng để bạn biết còn thiếu gì. Cài xong mà chưa cấu hình mô hình thì chat sẽ chưa trả lời được.

## Kiểm tra đã chạy được chưa

Có hai cách, từ dễ đến chi tiết.

Cách thứ nhất là mở giao diện web ở địa chỉ README chỉ định (thường là localhost kèm số cổng frontend), rồi thử gửi một câu hỏi đơn giản. Có câu trả lời nghĩa là chuỗi "giao diện, máy chủ, mô hình AI" đã thông.

Cách thứ hai là dùng công cụ chẩn đoán. Nhật ký phát hành v1.5.17 nhắc có lệnh `deeptutor doctor`. Nhật ký v1.3.9 nhắc có `deeptutor start`. Bạn thử trong môi trường đã cài:

```bash
deeptutor doctor
```

Lệnh này dùng để kiểm tra môi trường. Mình chưa thấy README mô tả chi tiết đầu ra, nên hãy đọc thông báo nó in ra: mục nào báo lỗi thì xử lý mục đó. Nếu máy báo không nhận lệnh `deeptutor`, nghĩa là bạn chưa cài xong gói hoặc chưa bật đúng môi trường ảo.

## Dùng vào việc thật

Các tình huống dưới đây bám theo khả năng mà nhật ký phát hành mô tả. Giao diện cụ thể có thể khác tuỳ bản bạn cài.

### Sinh viên ôn thi từ giáo trình PDF

Bối cảnh: bạn có giáo trình và slide môn Kinh tế vi mô, thi sau hai tuần. Bạn tạo một kho kiến thức, tải PDF lên và chờ hệ thống lập chỉ mục. Sau đó mở chế độ đọc cạnh khung chat và hỏi:

```text
Giải thích khái niệm co giãn của cầu theo giá trong chương 3, cho ví dụ đơn giản.
```

Kết quả: câu trả lời kèm trích dẫn theo trang, bạn bấm vào là thấy đúng đoạn gốc. Xong bạn yêu cầu tạo bộ câu hỏi luyện tập và làm theo chế độ học có theo dõi để xem mình đã vững phần nào.

> Học với AI hiệu quả nhất khi nó trả lời từ tài liệu của chính bạn và nhớ bạn đã làm sai ở đâu.
>
> — Ông T

### Nhân viên văn phòng học quy trình nội bộ

Bối cảnh: công ty có bộ tài liệu quy trình dạng Word và Excel, nhân viên mới đọc rất lâu. Bạn nạp các file này vào một kho kiến thức, rồi nhờ gia sư tạo câu hỏi kiểm tra. Nhật ký phát hành nhắc xem trước DOCX/XLSX ngay trong trình duyệt. Kết quả: nhân viên mới hỏi tình huống cụ thể, ví dụ "hoàn ứng chi phí cần giấy tờ gì", và nhận câu trả lời dựa trên đúng tài liệu công ty. Nếu dùng chung nhiều người, hãy xem chế độ nhiều tài khoản có không gian riêng cho từng người.

### Chủ shop tìm hiểu một mảng mới

Bối cảnh: bạn bán hàng online và muốn hiểu về quảng cáo trả phí hay thuế thương mại điện tử. Bạn dùng khả năng Deep Research, yêu cầu nghiên cứu một chủ đề và nhận báo cáo tổng hợp. README ghi rõ Deep Research sẽ cảnh báo khi báo cáo chỉ hoàn thành một phần. Hãy coi báo cáo là bản nháp để đọc nhanh, rồi tự kiểm tra các con số quan trọng ở nguồn gốc trước khi áp dụng vào việc kinh doanh.

### Lập trình viên mới học một mã nguồn

Bối cảnh: bạn vừa vào dự án và phải đọc một repo lạ. Nhật ký phát hành v1.5.17 nhắc GitHub repo có thể làm nguồn kiến thức. Bạn thêm repo vào kho, rồi hỏi gia sư về cấu trúc thư mục, luồng chạy chính. Kết quả: bạn có một người hướng dẫn trả lời theo đúng mã nguồn đang đọc. Hãy so lại với mã thật khi cần, vì AI vẫn có thể hiểu sai.

## Lỗi hay gặp và cách xử lý

### Gõ lệnh deeptutor báo không nhận ra

Thường là do chưa cài xong, hoặc cài trong một môi trường ảo mà terminal hiện tại chưa bật. Bật lại đúng môi trường, hoặc cài lại theo README. Nếu muốn tránh rắc rối môi trường Python, hãy thử cách chạy bằng Docker.

### Python sai phiên bản

Pyproject.toml yêu cầu Python 3.11 đến 3.14. Python 3.10 hoặc 3.15 trở lên có thể không cài được. Kiểm tra bằng `python --version`, cài đúng bản, hoặc chuyển sang Docker.

### Chat không trả lời hoặc báo lỗi mô hình

Hay do chưa nhập API key, key sai, hết hạn mức, hoặc chọn mô hình mà tài khoản không có quyền. Vào Settings, kiểm tra lại nhà cung cấp, key và tên mô hình. Có thể thử `deeptutor doctor` để xem thông báo chẩn đoán.

### Tài liệu tải lên nhưng hỏi không ra nội dung

Việc lập chỉ mục có thể chưa xong, hoặc tài liệu là bản scan (ảnh) khó đọc. Chờ trạng thái lập chỉ mục hoàn tất. Nếu một tài liệu bị lỗi, nhật ký v1.5.1 cho biết bạn có thể xoá riêng tài liệu đó thay vì dựng lại cả kho. Với PDF scan, thử đổi công cụ đọc tài liệu trong Settings (README nhắc nhiều engine như MinerU, PyMuPDF4LLM, LiteParse).

### Cổng đã bị chương trình khác dùng khi chạy Docker

Đổi cổng bằng các biến HOST_PORT_BACKEND, HOST_PORT_FRONTEND, HOST_PORT_POCKETBASE trong file .env rồi chạy lại. Đây là cách làm an toàn hơn so với tắt chương trình lạ đang chiếm cổng mà bạn chưa biết nó là gì.

## Có nên dùng không

**Điểm mạnh.** Đây là bộ công cụ học tập tương đối trọn gói: kho kiến thức riêng, đọc có trích dẫn, bài tập, theo dõi tiến độ, nhớ lâu dài, nhiều nhà cung cấp mô hình, và nhiều tài khoản. Giấy phép Apache-2.0 cho phép dùng linh hoạt. Dự án đang được cập nhật đều.

**Giới hạn.** Repo lớn và thay đổi nhanh, nên giao diện và bước cài có thể đổi giữa các bản. Bạn vẫn phải tự lo API key và chi phí mô hình. Chất lượng đầu ra phụ thuộc mô hình bạn chọn và chất lượng tài liệu. Phần README mình được xem chưa có hướng dẫn cài chi tiết, nên hãy dành thời gian đọc mục Get Started.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi nhanh một tài liệu, một khung chat AI thông thường đã đủ và đỡ phải cài. Nếu bạn cần dữ liệu tuyệt đối không rời máy, hãy tự kiểm tra kỹ nhà cung cấp mô hình bạn dùng, vì tư liệu chưa nói rõ về việc này. DeepTutor hợp nhất với người muốn học nghiêm túc, lâu dài, và sẵn sàng bỏ chút công cài đặt.

## Câu hỏi thường gặp

### DeepTutor có miễn phí không?

Mã nguồn dùng giấy phép Apache-2.0 nên tải và dùng được. Tuy nhiên bạn cần tự cấu hình một nhà cung cấp mô hình AI, và nhà cung cấp đó có thể tính phí theo mức dùng. Tư liệu chưa nêu bảng giá cụ thể.

### DeepTutor cần Python phiên bản nào?

File pyproject.toml yêu cầu Python từ 3.11 đến dưới 3.15. Nếu không muốn lo phiên bản Python, repo có sẵn Dockerfile và các file compose để chạy bằng container.

### Có cần GPU không?

Tư liệu mình có chưa nói về yêu cầu GPU hay RAM. Ứng dụng hỗ trợ nhiều nhà cung cấp mô hình trên đám mây, nên về nguyên tắc phần nặng có thể do nhà cung cấp xử lý. Bạn nên xem README để biết chắc.

### Chạy được trên Windows không?

Tư liệu không nêu cụ thể hệ điều hành. Tuy nhiên repo hỗ trợ chạy bằng Docker, và nhật ký phát hành nhắc tới bản tải cho máy tính (desktop), nên Windows có khả năng dùng được. Hãy xác nhận ở README.

### Dữ liệu và tài liệu của tôi có an toàn không?

Bạn tự chạy ứng dụng trên máy hoặc máy chủ của mình, nhưng nội dung khi hỏi đáp sẽ được gửi tới nhà cung cấp mô hình bạn chọn. Tư liệu chưa có thông tin chi tiết về chính sách dữ liệu. Nếu tài liệu nhạy cảm, hãy kiểm tra điều khoản của nhà cung cấp trước.

### DeepTutor khác gì việc hỏi ChatGPT với file đính kèm?

Theo nhật ký phát hành, DeepTutor có kho kiến thức lâu dài, trích dẫn theo trang, bài tập có theo dõi mức thành thạo, bộ nhớ nhiều tầng và nhiều tài khoản. Khung chat thông thường tiện hơn để hỏi nhanh, còn DeepTutor hợp với việc học dài hơi.

### Có dùng được với nhiều ngôn ngữ, trong đó có tiếng Việt không?

Nhật ký phát hành nhắc nhiều giao diện ngôn ngữ như Pháp, Đức, Ukraina, Ba Lan, Hàn, và có thiết lập ngôn ngữ đầu ra của mô hình riêng. Phần tư liệu mình có chưa nói rõ về giao diện tiếng Việt, nên bạn nên mở phần Settings để kiểm tra.
