DeepTutor tự host: gia sư AI trên tài liệu của bạn

Vì sao chatbot chung chung không đủ để học sâu tài liệu kỹ thuật?

Học công nghệ mới bằng chatbot chung chung thường đi theo cùng một kịch bản: bạn đọc câu trả lời, thấy hiểu, rồi một tuần sau quên gần hết. Vấn đề không phải bạn đọc ít, mà là kiến thức không được kiểm chứng lại — không có câu hỏi ôn tập, lộ trình từ dễ đến khó, hay cách xác minh câu trả lời về đoạn tài liệu gốc.

Một khung chat RAG chỉ giải quyết bài toán “hỏi và nhận câu trả lời từ tài liệu” — đủ cho tra cứu nhanh. Nhưng học sâu cần nhiều hơn: đọc có cấu trúc, tự kiểm tra bằng quiz, luyện tập theo lộ trình, và quay lại bằng chứng gốc mỗi khi nghi ngờ câu trả lời. Đó là khoảng trống mà DeepTutor nhắm tới.

DeepTutor là gì? Gia sư AI mã nguồn mở tự host

DeepTutor là một workspace học tập “agent-native” mã nguồn mở, giấy phép Apache-2.0, phát triển bởi nhóm HKUDS thuộc Data Intelligence Lab của Đại học Hong Kong, với bản preprint thiết kế trên arXiv (2604.26962). Phiên bản 1.7.0 mới ra ngày 28/10/2026. Nói ngắn gọn: DeepTutor không phải một chatbot hỏi đáp, mà là một phòng học chạy trên tài liệu của chính bạn.

Bài toán nó giải quyết rất thực tế: tài liệu của bạn nằm rải rác — PDF, sách, repo GitHub, video — và kiến thức trong đó không tự biến thành hiểu biết. DeepTutor nạp các nguồn đó vào một workspace duy nhất, lập chỉ mục để truy hồi, rồi dùng model do chính bạn cấu hình để dạy, ra quiz và dẫn bạn đi theo lộ trình.

Các chế độ học trong một runtime

DeepTutor gom nhiều chế độ học vào cùng một runtime: Chat và Ask Questions để hỏi đáp có truy vết; Quiz tạo câu hỏi kiểm tra từ chính tài liệu; Research đào sâu một chủ đề; Visualize trực quan hoá khái niệm; Solve giải bài tập từng bước; Mastery Path là lộ trình luyện tập; Immersive Reading để đọc sâu kèm ghi chú; Audio Overview là tóm tắt dạng audio.

Kiến trúc DeepTutor: nhiều engine tri thức, một bộ nhớ kiểm chứng được

Tổng quan kiến trúc

DeepTutor gồm frontend Next.js 16 và backend Python. Ở đường cài pip, backend mặc định chạy cổng 8001, frontend cổng 3782. Khi đưa lên VPS, bạn cần reverse proxy và xác thực phía trước: xác thực tắt theo mặc định nên bản chạy thử là chế độ single-user; khi bật xác thực (cấu hình tại data/user/settings/auth.json, người dùng đăng ký đầu tiên trở thành admin), DeepTutor hỗ trợ workspace riêng biệt theo từng người dùng, kèm cơ chế cấp quyền.

Tầng tri thức đa engine

DeepTutor không dùng một RAG duy nhất mà cắm được nhiều engine tri thức — LlamaIndex, PageIndex, GraphRAG, LightRAG (native lẫn remote server), WeKnora tự host, kho Kiwix ZIM cho tài liệu offline, và Obsidian vault liên kết trực tiếp.

Vì mỗi loại tài liệu cần một cách lập chỉ mục khác nhau: tài liệu nhiều thực thể và quan hệ chằng chịt — kiến trúc hệ thống, RFC, tài liệu API — hợp với GraphRAG; truy vấn nhanh trên kho lớn hợp với LightRAG; kho offline hợp với Kiwix. Hệ quả thực tế: cùng một tài liệu, đổi engine có thể thay đổi trải nghiệm học nhiều hơn đổi model. Nếu câu trả lời kém, hãy xem lại engine trước khi kết luận model yếu.

Bộ nhớ L1/L2/L3 và Memory Graph

DeepTutor tổ chức bộ nhớ thành ba tầng có thể kiểm tra được: L1 là traces — dấu vết thô của quá trình làm việc; L2 là surface summaries — các tóm tắt bề mặt; L3 là synthesis — tổng hợp ở tầng cao hơn. Memory Graph liên kết các fact ở L2 về bằng chứng L1 gốc. Theo mình, đây là điểm khác biệt thực sự so với chatbot RAG thông thường: khi AI trả lời sai, bạn truy vết được nó sai từ đâu.

Nhưng L1 traces cũng là bề mặt lưu trữ nhạy cảm: tài liệu nội bộ nạp vào tồn tại dưới dạng trace và bằng chứng, không chỉ file gốc. Xóa file gốc mà không xóa trace thì dữ liệu vẫn còn đó.

Học với video và cầu nối agent harness

DeepTutor hỗ trợ học từ video YouTube và Bilibili: phát video trong workspace, tìm kiếm transcript, lưu ghi chú, và tutoring gắn timestamp — câu hỏi neo vào đúng đoạn video. Từ Chat, nó còn tham vấn agent harness đang chạy (Claude Code, Codex, Grok CLI và một số agent khác): học trong DeepTutor trước, viết code với agent sau.

Hướng dẫn cài đặt DeepTutor tự host: Docker và pip install

Điều kiện tiên quyết

Yêu cầu phụ thuộc vào đường cài bạn chọn, đừng gộp chung:

• Đường pip/source: Python 3.11–3.14 và Node.js 20+ trên PATH (cài từ source yêu cầu Node.js 22 LTS để khớp CI và Docker). Cổng 8001 (backend) và 3782 (frontend) còn trống.
• Đường Docker trial: chỉ cần Docker, không cần Python hay Node.js trên máy host.
• Cả hai đường: cần một LLM provider với base URL, API key và tên model.

Cách 1 — DeepTutor Docker

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

Lệnh này chỉ publish cổng frontend 3782 trên localhost; backend 8001 vẫn nằm trong container, được frontend gọi qua Next.js middleware — chỉ publish thêm khi cần truy cập trực tiếp API. Volume deeptutor-data giữ cấu hình và dữ liệu local; cờ --rm xóa container khi dừng nhưng giữ lại volume.

Cách 2 — DeepTutor pip install

Phiên bản 1.7.0 tách cài đặt thành modular: deeptutor thuần là core, deeptutor[full] là web app đầy đủ kèm CLI — với đa số người dùng, bản full là lựa chọn đúng:

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U "deeptutor[full]"
deeptutor init
deeptutor start

deeptutor init hỏi cổng backend (8001) và frontend (3782), LLM provider, base URL, API key, model, rồi embedding và search provider tùy chọn. deeptutor start khởi động cả backend và frontend; giữ terminal mở, nhấn Ctrl+C để dừng cả hai.

Kiểm chứng cài đặt

Sau khi khởi động, mở http://127.0.0.1:3782. Dấu hiệu cài đặt đúng: giao diện tải được và Settings → Providers hiển thị provider bạn đã cấu hình. Nếu giao diện lên nhưng mọi câu hỏi đều trống model, đó là provider chưa được cấu hình, không phải lỗi app.

Lỗi thường gặp và cách xử lý

• Cổng bị chiếm: nếu 8001 (đường pip) hoặc 3782 đã có dịch vụ khác dùng, đổi cổng trong bước init hoặc kiểm tra tiến trình đang giữ cổng trước khi kết luận cài đặt lỗi.
• Bỏ qua init: app vẫn boot với cổng mặc định và model trống — vào Settings → Providers cấu hình lại, không cần cài lại.
• Thiếu provider hoặc API key sai: mọi tính năng cần model đều không hoạt động. Kiểm tra lại base URL, key và tên model trong Settings → Providers.
• Thiếu ffmpeg: các adapter STT native yêu cầu ffmpeg có trên PATH — cài ffmpeg rồi khởi động lại nếu bạn dùng tính năng này.
• Nạp tài liệu lớn dở dang: theo release notes v1.7.0, chỉ các lần rebuild LlamaIndex bị gián đoạn tương thích mới tiếp tục được từ những embedding checkpoint đã hoàn thành — không phải mọi quá trình ingestion. Khi tiến trình bị ngắt, hãy kiểm tra trạng thái ingestion trước khi xóa dữ liệu và nạp lại từ đầu.

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

Ưu điểm. Giấy phép Apache-2.0, tài liệu nằm trên hạ tầng của bạn thay vì qua một SaaS trung gian, engine linh hoạt theo loại tài liệu, bộ nhớ phân tầng cho phép truy vết câu trả lời về bằng chứng gốc, và các chế độ học — quiz, mastery path, video gắn timestamp — bao phủ cả quá trình học chứ không chỉ khâu hỏi đáp.

Nhược điểm. Phụ thuộc hoàn toàn vào model bên ngoài: không có provider thì không có gia sư. Đường pip yêu cầu cả Python và Node.js, tăng bề mặt vận hành so với một container duy nhất. Chưa có bằng chứng độc lập về chất lượng dạy hay chất lượng quiz — mọi tuyên bố về hiệu quả học tập hiện tại đều là tuyên bố từ phía dự án. Phần này mình chưa chạy thử, chỉ đối chiếu tài liệu.

Bảo mật và kiểm soát dữ liệu. Tự host giải quyết được một nửa bài toán: tài liệu không nằm trên server của bên thứ ba. Nửa còn lại vẫn nằm ở provider — nội dung tài liệu và prompt vẫn được gửi lên LLM, embedding và search provider mà bạn chọn, nên hãy cân nhắc cách provider đó xử lý dữ liệu trước khi nạp tài liệu nhạy cảm. API key trong cấu hình cũng cần quản trị: lộ file cấu hình hoặc volume deeptutor-data đồng nghĩa với lộ quyền truy cập provider và phát sinh chi phí.

Đặc biệt, đừng phơi cổng 3782 trực tiếp ra Internet mà không có reverse proxy và xác thực. Với đường Docker, backend 8001 vốn không được publish ra ngoài — chỉ publish thêm khi bạn thực sự cần truy cập trực tiếp API — nhưng cổng 3782 đã đủ để lộ workspace nếu không có lớp bảo vệ phía trước. Xác thực tắt theo mặc định nên bản chạy thử mặc định là single-user; nếu mở cho nhiều người, hãy bật xác thực để mỗi người có workspace riêng biệt kèm cơ chế cấp quyền.

Vận hành và bảo trì. Trước mỗi lần nâng cấp, hãy sao lưu volume deeptutor-data (đường Docker) hoặc thư mục runtime (đường pip install). Với Docker trial dùng cờ --rm, chỉ cần docker stop deeptutor — lệnh này dừng và xóa luôn container nhưng giữ lại volume; chạy thêm docker rm deeptutor sau đó sẽ thừa và báo lỗi vì container đã không còn. Lệnh docker rm chỉ cần cho trường hợp chạy detached mà không dùng --rm. Với pip install, dừng bằng Ctrl+C và gỡ package; dữ liệu runtime không tự biến mất khi gỡ package, nên cần xóa tay nếu muốn dọn sạch.

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

Tiêu chí so sánh: tự host được, học trên nguồn tài liệu riêng, có quiz hoặc mastery, truy vết được bằng chứng, và kiểm soát model cùng chi phí.

So với công cụ kiểu NotebookLM. Các công cụ kiểu NotebookLM mã nguồn mở — ví dụ open-notebook — thiên về ghi chú học tập: nạp tài liệu, hỏi đáp, tóm tắt. DeepTutor đi xa hơn với quiz, mastery path, bộ nhớ truy vết phân tầng và đa engine. Chỉ cần đọc và hỏi tài liệu thì app ghi chú nhẹ hơn có thể đủ; cần luyện tập có cấu trúc thì DeepTutor đầy đủ hơn.

So với công cụ RAG cho AI agent. Đây là điểm dễ nhầm nhất. Các công cụ như Graphify hay Xerj phục vụ coding agent: lập chỉ mục và tìm kiếm để agent viết code tốt hơn. DeepTutor phục vụ người học cuối: gia sư, quiz, lộ trình. Bạn có thể dùng cả hai mà không trùng vai trò.

So với chatbot RAG tự build. Tự build cho toàn quyền kiểm soát, nhưng bạn phải tự bảo trì ingestion, truy hồi, giao diện và đánh giá chất lượng. DeepTutor đổi sự linh hoạt đó lấy một hệ thống sẵn dùng với đa engine và bộ nhớ truy vết. Theo mình, tự build chỉ đáng khi yêu cầu của bạn khác biệt rõ rệt so với những gì DeepTutor có sẵn.

Use case thực tế: dùng DeepTutor ở đâu cho đáng?

Team IT và onboarding. Biến runbook, RFC và tài liệu nội bộ thành lộ trình onboarding kèm quiz: người mới đọc tài liệu thật, làm quiz từ chính tài liệu đó, và mentor kiểm tra lại qua truy vết thay vì hỏi miệng.

Dev tự học công nghệ mới. Thay vì đọc lướt tài liệu rồi quên, bạn nạp tài liệu chính thức vào, đi theo mastery path và tự kiểm tra bằng quiz trước khi áp dụng vào dự án.

Workflow với AI coding-agent. Dùng DeepTutor biến tài liệu kỹ thuật thành câu hỏi, quiz và bài tập trước khi để agent hỗ trợ triển khai.

Kết luận: DeepTutor phù hợp với ai, không phù hợp với ai?

Nên dùng DeepTutor nếu bạn cần học sâu trên tài liệu riêng, muốn tự host để kiểm soát dữ liệu, và sẵn sàng cấu hình provider cùng chịu trách nhiệm vận hành. Giá trị của nó nằm ở khớp nối giữa tầng lập chỉ mục đa engine và workspace gia sư có bộ nhớ truy vết được — không nằm ở model, vì model là thứ bạn tự mang tới.

Không nên dùng nếu bạn chỉ cần hỏi đáp nhanh vài câu mỗi ngày, không muốn cấu hình provider, hoặc cần một LMS đầy đủ với báo cáo đào tạo và quản lý khóa học. Phân biệt rõ: đa người dùng tự nó không phải lý do loại DeepTutor — khi bật xác thực, mỗi người dùng có workspace riêng biệt kèm cơ chế cấp quyền.

Bước tiếp theo thiết thực nhất: chạy Docker trial, nạp một tài liệu thật, thử tạo quiz và kiểm tra truy vết về bằng chứng gốc. Nếu hai việc đó thuyết phục được bạn, hãy tính tới cài đặt pip lâu dài và sao lưu volume đàng hoàng.

Tài liệu tham khảo

• DeepTutor trên GitHub: https://github.com/HKUDS/DeepTutor
• Trang chính thức của dự án: https://deeptutor.info
• Release v1.7.0: https://github.com/HKUDS/DeepTutor/releases/tag/v1.7.0
• Preprint thiết kế trên arXiv: https://arxiv.org/abs/2604.26962