DeepTutor 사용법 2026: AI 개인 튜터 설치와 RAG 학습 환경 구성

DeepTutor 사용법의 핵심은 범용 챗봇에 질문하는 수준을 넘어 개인 자료와 학습 기록을 하나의 워크스페이스에 묶는 것입니다. Chat, Quiz, Research, Solve, Book, RAG 지식베이스와 메모리가 같은 에이전트 루프에서 돌아갑니다.

DeepTutor 사용법 핵심 요약

• Python 3.11 이상 3.14 미만과 Node.js 20 이상이 필요합니다.
• 설치 방식은 PyPI, 소스 코드, Docker, CLI 전용 구성으로 나뉩니다.
• LlamaIndex, PageIndex, GraphRAG, LightRAG, Obsidian 등 여러 지식베이스 엔진을 지원합니다.
• 학습 기록은 L1 원본 추적, L2 표면별 요약, L3 통합 프로필의 3단계 파일로 저장됩니다.
• 기본 상태에서는 인증이 꺼져 있으므로 외부 공개 서버에 바로 노출하면 안 됩니다.
• RAG를 쓰려면 LLM뿐 아니라 embedding provider도 설정해야 합니다.

DeepTutor는 어떤 문제를 해결하나

일반적인 AI 학습 환경에서는 문서 검색, 대화, 퀴즈, 노트, 장문 작성 도구가 따로 흩어집니다. DeepTutor는 이 기능을 한 런타임에 모았습니다. 대화에서 고른 지식베이스와 persona, 모델은 다음 턴에도 유지되며, 책이나 노트, 질문 은행, 이전 대화도 필요한 순간에 불러옵니다.

DeepTutor 사용법은 단순한 PDF 질의응답 도구보다 범위가 넓습니다. Knowledge Center에서 자료를 색인하면 Chat과 Co-Writer, Book, Partner가 같은 지식베이스를 씁니다. Claude Code, Codex, Gemini 같은 로컬 CLI 에이전트도 하위 에이전트로 연결할 수 있습니다.

작동 원리

DeepTutor의 학습 모드는 하나의 agent loop를 공유합니다. 모델은 라운드마다 필요한 도구를 호출하고 결과를 확인한 뒤 최종 답변을 만듭니다. Chat에서 시작한 맥락을 Quiz나 Research로 옮겨도 엔진은 그대로이고 목표만 달라집니다.

지식베이스 하나에는 검색 엔진 하나가 연결됩니다. 기본 LlamaIndex 구성은 로컬 vector 검색과 BM25를 함께 쓰고, PageIndex는 페이지 단위 인용이 필요한 문서에 맞습니다. GraphRAG와 LightRAG는 지식 그래프 검색을 제공하며, 이미 만든 외부 index를 연결하는 방식도 지원합니다.

메모리는 숨겨진 vector store에만 넣지 않고 파일로 남깁니다. L1에는 작업 영역과 append-only event trace가 쌓이고, L2에는 Chat, Quiz, Book 같은 표면별 사실이 정리됩니다. L3는 L2를 근거로 프로필과 최근 맥락을 합성합니다. Memory Graph에서는 합성된 내용이 어느 기록에서 왔는지 역추적할 수 있습니다.

DeepTutor 설치 방법

PyPI로 설치

DeepTutor 사용법을 처음 확인한다면 PyPI 설치가 가장 짧습니다. 공식 문서는 Python 3.11~3.13과 PATH에 등록된 Node.js 20 이상을 요구합니다.

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

deeptutor init에서 backend port 기본값 8001, frontend port 기본값 3782, LLM provider, model, API key를 지정합니다. 지식베이스를 쓸 계획이라면 embedding provider도 함께 설정합니다. 실행이 끝나면 터미널에 표시된 주소를 엽니다. 기본 URL은 http://127.0.0.1:3782입니다.

Docker로 실행

호스트에 dependency를 직접 설치하고 싶지 않다면 공식 GHCR 이미지를 사용합니다.

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

단일 container 구성이라면 3782 포트만 공개하면 됩니다. Next.js middleware가 container 내부의 FastAPI backend로 /api/*와 /ws/* 요청을 전달합니다. 설정, API key, log, memory, knowledge base는 deeptutor-data volume에 남습니다.

CLI에서 확인

초기 설정을 마치면 대화와 RAG 검색도 터미널에서 실행할 수 있습니다.

deeptutor chat
deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook
deeptutor kb create textbook --doc textbook.pdf
deeptutor memory show
deeptutor config show

CLI 전용 package는 2026년 8월 24일 기준으로 PyPI에 별도 배포되지 않았습니다. 저장소를 clone한 뒤 python -m pip install -e ./packaging/deeptutor-cli로 설치해야 합니다.

직접 확인한 설치 범위

2026년 8월 24일 테스트 환경은 Python 3.13.12와 Node.js 26.5.0이었습니다. PyPI에서 최신 version 1.5.16을 확인했고, 배포 wheel을 설치해 package metadata의 Python 조건이 >=3.11,<3.14인지와 deeptutor CLI entry point가 생성되는지 확인했습니다.

이번에는 전체 dependency 설치와 실제 LLM 응답, RAG index 생성까지 진행하지 않았습니다. 사용하는 provider의 API key, 로컬 model server, embedding 설정에 따라 결과와 비용이 달라지는 구간입니다.

공개 논문의 수치 읽기

프로젝트 논문은 TutorBench와 기존 benchmark를 사용한 평가 결과를 공개했습니다. 아래 수치는 저자 보고값이며 이번 글에서 독립적으로 재현한 결과는 아닙니다.

모든 학습 환경에서 같은 효과가 나온다고 해석하면 곤란합니다. 사용하는 model, 개인 자료의 품질, embedding과 retrieval engine 설정에 따라 답변의 근거성과 비용이 달라집니다.

도입 전 체크리스트

• Python과 Node.js version 조건을 먼저 확인합니다.
• DeepTutor 사용법에 맞춰 API key를 쓸지 Ollama, LM Studio 같은 local model server를 연결할지 정합니다.
• RAG가 필요하면 embedding provider와 문서 parsing engine을 함께 선택합니다.
• data/ volume이나 DEEPTUTOR_HOME 경로를 backup 대상에 넣습니다.
• 원격 공개 전 authentication과 cors_origins를 설정합니다.
• OpenAI Codex OAuth는 experimental 기능이며 원격 server에서는 SSH tunnel이 필요합니다.
• GraphRAG, LightRAG, Manim 같은 선택 기능은 추가 dependency와 system library 요구사항을 확인합니다.

현재 확인한 공개 정보

아래 값은 2026년 8월 24일 12:50 UTC에 GitHub API, PyPI, 공식 저장소에서 확인했습니다.

v1.5.16에서는 MarginNote 4 library 연결, streaming tool-call ID 처리, model별 temperature 제한, embedding gateway 호환성, image description 병렬화가 보강됐습니다. release가 자주 나오므로 설치 직전에 공식 release note와 upgrade note를 다시 확인해야 합니다.

DeepTutor 사용법 정리

DeepTutor는 문서 한두 개를 묻는 가벼운 RAG 화면보다 학습 자료와 대화 기록을 오래 쌓는 workspace에 가깝습니다. 웹 UI, CLI, 여러 retrieval engine, 파일 기반 memory를 한곳에서 다루고 싶을 때 검토할 만합니다. DeepTutor 사용법은 학습 맥락을 오래 유지하는 데 초점이 맞춰져 있습니다.

대신 초기 설정 항목이 많고 LLM과 embedding 비용은 별도입니다. 인증이 기본으로 꺼져 있다는 점도 원격 배포 전에 반드시 확인해야 합니다. 처음에는 PyPI 또는 Docker로 local에서 실행하고, LLM 하나와 작은 지식베이스 하나만 연결해 동작 범위를 확인하는 편이 낫습니다.

함께 보면 좋은 글

• LoopX 사용법 2026: 장기 실행 AI 에이전트 상태 관리 가이드
• Orca 사용법 2026: 병렬 AI 코딩 에이전트 ADE 설치 가이드
• Compound Engineering 사용법: AI 코딩 에이전트 워크플로 가이드

FAQ

DeepTutor는 무료인가요?

소스 코드는 Apache-2.0 license로 공개되어 있습니다. 다만 OpenAI, Anthropic 같은 유료 API를 연결하면 model과 embedding 사용료가 별도로 발생합니다. Local model을 연결하면 API 비용을 줄일 수 있지만 그만큼 hardware resource가 필요합니다.

GPU가 꼭 필요한가요?

DeepTutor 자체 웹 앱을 실행하는 데 GPU가 필수라고 명시되어 있지는 않습니다. 외부 API를 사용하면 local GPU 없이도 동작합니다. Ollama나 vLLM으로 local model을 구동하려면 선택한 model에 맞는 CPU, RAM, GPU 조건을 따로 확인해야 합니다.

기존 PDF와 노트를 지식베이스로 쓸 수 있나요?

가능합니다. 기본 LlamaIndex 외에 PageIndex, GraphRAG, LightRAG를 선택할 수 있고 Obsidian vault와 MarginNote 4 library도 연결할 수 있습니다. engine마다 index 방식과 dependency가 다릅니다. 작은 자료부터 넣어 확인하는 편이 낫습니다.

서버에 공개해도 되나요?

가능하지만 authentication은 기본적으로 꺼져 있습니다. 외부 공개 전 auth 설정, CORS, reverse proxy, TLS, data volume 권한을 점검해야 합니다. 여러 사용자가 쓰는 경우 첫 registered user가 admin이 되는 초기화 절차도 확인해야 합니다.

출처

• HKUDS/DeepTutor GitHub 저장소
• DeepTutor v1.5.16 release note
• DeepTutor PyPI
• DeepTutor: Towards Agentic Personalized Tutoring
• DeepTutor container 배포 문서

AI/IT도구에서 이어서 보면 좋은 글

• LoopX 사용법 2026: 장기 실행 agent의 상태, event, approval을 한 화면에서 관리하는 control plane을 다룹니다.
• Orca 사용법 2026: 여러 coding agent를 git worktree와 함께 병렬로 운용하는 방법을 정리했습니다.
• Compound Engineering 사용법: 계획, 구현, review 과정을 재사용 가능한 agent workflow로 구성하는 방법을 설명합니다.

AI/IT도구 전체 보기 · 블로그 최신 글