Post
Repo Deep Dive: HKUDS/DeepTutor — 자료와 학습 활동을 잇는 개인화 튜터
2026년 10월 30일 07:10 KST에 확인한 GitHub Trending 일간 전체 언어 목록에서 HKUDS/DeepTutor가 1위였다. 이 순위는 저장소 선정 시점의 스냅샷이며, 글이 발행되거나 읽히는 시점의 실시간 순위를 뜻하지 않는다.
1. 프로젝트 소개
DeepTutor는 HKUDS 그룹에서 Bingxi Zhao가 이끌고 커뮤니티와 함께 공개 개발하는 학습용 AI 작업 공간이다. 단발성 질문 응답뿐 아니라 사용자가 모은 자료를 바탕으로 대화하고, 문제를 풀고, 연습 문제를 만들고, 읽기와 복습을 이어가는 흐름을 한 웹 앱과 CLI에 묶는다. README가 제시하는 출발점은 과목이나 프로젝트별 workspace다. 그 안에서 대화, 학습 활동, 자료를 관리하고, 계정 차원의 개인화 설정은 별도로 유지한다. 따라서 특정 강의의 문서를 읽으며 질문하다가 같은 자료로 문제를 만들거나 책 형태의 학습 콘텐츠를 구성하려는 사람에게 맞는 구조다.
이 프로젝트를 ‘모든 질문에 정답을 보장하는 교사’로 이해해서는 안 된다. 모델 공급자와 검색·임베딩 설정, 제공한 자료의 품질에 따라 결과가 달라진다. 저장소도 답변이 선택 자료와 충돌하거나 인용 근거가 약할 때 진단 자료를 모으는 별도 점검 문서를 안내한다. 여기서는 확인 가능한 기능과 조작 경로를 설명하며 학습 효과나 답변 정확도를 측정한 결과로 확대 해석하지 않는다.
2. 해결하려는 문제
일반적인 챗봇으로 공부하면 질문마다 문서의 어느 부분을 읽고 있었는지, 앞서 만든 문제와 노트가 무엇인지 다시 알려줘야 한다. 문서 검색 도구, 필기 앱, 문제 은행, 복습 도구를 따로 쓰면 같은 자료를 옮겨 적거나 파일을 중복 등록하는 일도 생긴다. DeepTutor의 접근은 학습 자료와 대화를 workspace에 묶고, 지원되는 학습 기능이 지식 베이스·책·노트·문제 은행·메모리를 다시 참조하도록 하는 것이다. 한 대화에서 자료를 인용해 질문한 다음, 별도의 학습 활동으로 넘어갈 때도 선택된 workspace와 사용할 수 있는 자료가 흐름의 기준이 된다.
자료를 단순히 모델 입력창에 붙여 넣는 것과 지식 베이스를 만드는 것도 다르다. DeepTutor의 Knowledge Center는 문서를 색인해 검색하는 LlamaIndex 기본 엔진 외에 페이지 단위 인용을 위한 PageIndex, 그래프 기반 GraphRAG·LightRAG 등 여러 검색 엔진의 연결 경로를 문서화한다. 다만 엔진을 나열한다고 한 지식 베이스가 모든 엔진을 동시에 사용한다는 뜻은 아니다. README에 따르면 지식 베이스 하나는 한 엔진에 연결되고, 일부 엔진은 별도 설치나 외부 서비스가 필요하다. 사용자는 자료의 형태와 운영 환경에 맞는 경로를 선택해야 한다.
3. 주요 기능
자료를 근거로 이어지는 대화. Chat은 기본 진입점이며 사용자의 질문, 선택한 지식 베이스, 첨부 자료와 현재 세션 문맥을 받아 답변을 만든다. 도구를 켜면 웹 검색이나 자료 검색 등을 호출할 수 있다. workspace·모델·지식 베이스 같은 세션 문맥은 다음 턴에 남지만, + 메뉴에서 넣는 파일이나 특정 노트 같은 참조는 한 번의 턴에만 적용된다. 이 구분을 모르면 일회성 자료가 다음 질문에도 자동 적용된다고 오해하기 쉽다. 답변의 인용은 실제로 사용한 자료와 맞는지 사용자가 확인해야 한다.
지식 베이스 구성과 비교. 새 지식 베이스는 문서를 올려 색인하거나 기존 색인에 연결할 수 있고, GitHub 저장소나 문서 사이트를 자료 원천으로 등록해 변경분을 동기화할 수도 있다. README에는 색인 재생성 시 기존 버전을 남기는 방식과 실패한 문서 하나를 제거하는 경로가 설명돼 있다. 검색 품질을 비교하려면 deeptutor kb eval에 질문과 기대 근거 구절을 담은 JSONL을 주고 상위 검색 결과의 Recall@k, Precision@k, nDCG@k 등을 볼 수 있다. 이는 검색 순위와 지정한 정답 구절의 일치도를 계산하는 기능이지, 최종 튜터 답변의 의미적 정확도를 자동 인증하는 기능은 아니다. PageIndex는 순위가 있는 청크를 돌려주지 않아 이 평가 대상에서 빠진다.
읽기·쓰기·연습의 연결. Reading은 문서와 지원되는 동영상·오디오를 읽는 활동으로, 영상의 경우 자막 검색과 시각 정보에 연결된 질문, 메모와 진행 상태를 다룬다. 자막이 없으면 재생은 가능해도 튜터가 해당 영상 내용에 근거를 대는 범위는 제한된다. Learning notebook에서는 페이지·하위 페이지·블록으로 사용자의 글을 조직하고, 특정 구절에 대해 Dito에게 설명·예시·재작성을 요청한 뒤 제안된 변경을 수락할지 검토한다. Book은 지식 베이스, 즐겨찾기, 문제 은행, 대화 이력 등의 선택 자료에서 장 구성안을 제안하고, 사용자의 검토 후 본문을 생성한다. 생성된 책의 퀴즈·플래시카드·메모 등은 정적 PDF 한 장과 달리 읽는 도중 상호작용하는 블록이다.
웹과 CLI의 두 진입점. 브라우저에서는 Home의 Chat에서 시작해 Learning과 Resources로 이동한다. 터미널에서는 deeptutor chat으로 대화형 세션을 열거나 deeptutor run <capability> <message>로 한 턴을 실행한다. --format json은 콘텐츠, 도구 호출과 결과, 종료 이벤트를 줄마다 출력하므로 다른 프로그램이 session_id를 받아 다음 요청을 같은 세션에 연결할 수 있다. 2026년 10월 28일의 v1.7.0 릴리스는 기본 deeptutor 패키지를 코어 채팅·CLI·SDK로 나누고, 전체 웹 앱을 원할 때 deeptutor[full]을 설치하도록 바꿨다. 예전 설치 지침과 혼용하면 웹 앱이 빠질 수 있는 중요한 차이다.
4. 사용 방법과 동작 흐름
로컬 전체 웹 앱을 새로 설치할 때 README는 Python 3.11–3.14와 PATH에 있는 Node.js 20 이상을 요구한다. 아래 명령은 기존 설치를 업그레이드하는 절차가 아니라 새 실행 디렉터리에서 시작하는 최소 흐름이다. deeptutor init에서 사용할 LLM 제공자·모델과 필요하면 임베딩·검색 제공자를 설정한다. 지식 베이스/RAG를 쓰려면 채팅 모델 외에 임베딩 설정도 필요하다.
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U "deeptutor[full]"
deeptutor init
deeptutor start
시작 후 터미널에 표시되는 프런트엔드 주소를 열면 된다. 기본 주소는 http://127.0.0.1:3782이며, 설정한 포트가 다르면 출력된 주소를 따른다. 먼저 Chat에서 질문해 모델 연결을 확인하고, 자체 자료가 필요하면 Knowledge Center에서 지식 베이스를 만든 뒤 문서를 추가한다. 그다음 대화에서 해당 지식 베이스를 선택해 질문한다. 답변은 인용된 자료를 원문과 대조해 읽고, 검색이 빗나가면 문서 파싱·색인 상태와 선택한 검색 엔진부터 점검하는 것이 문서화된 흐름에 부합한다.
웹 앱을 설치하지 않고 터미널에서 바로 한 턴을 실행하는 예시는 다음과 같다. 이 명령의 textbook은 사용자가 먼저 만들고 등록한 지식 베이스 이름이라는 전제가 있다. --kb를 붙이면 해당 지식 베이스가 검색 문맥으로 공급되며, 없는 이름을 적는다고 자료가 자동 생성되지는 않는다.
deeptutor run chat "이 교재에서 푸리에 변환을 어떻게 설명하나요?" --kb textbook
Docker 체험 경로도 공식 README에 있다. ghcr.io/hkuds/deeptutor:latest를 127.0.0.1:3782에 연결하고 /app/data에 이름 있는 볼륨을 붙이면 재실행 후에도 설정과 로컬 자료가 남는다. 브라우저의 Settings → Providers에서 모델을 설정한다. 반대로 볼륨 없이 임시 컨테이너만 실행하면 저장한 학습 자료가 계속 남으리라 기대해서는 안 된다. v1.7.0으로 기존 설치를 올리는 경우에는 실행을 중지하고 런타임 홈을 백업하며, 예전 deeptutor-cli 패키지를 사용했다면 공식 업그레이드 순서를 먼저 따라야 한다.
5. 활용 사례
논문·강의 문서로 질문하고 검색을 점검하는 경우. 강의 자료를 지식 베이스에 넣은 뒤 Chat에서 해당 지식 베이스를 선택하면 질문과 검색된 문서 구절을 연결할 수 있다. 같은 자료를 Reading에서 직접 살피거나 Book의 원천으로 선택할 수 있다는 점이 단발성 파일 첨부와 다르다. 어느 검색 엔진이 이 자료에 적합한지 비교하고 싶다면 공식 kb eval 예시처럼 질문과 기대 구절을 JSONL로 만들어 측정한다. 이때 보고서의 수치는 검색 결과의 순위 평가로 해석해야 한다.
동영상 학습 내용을 메모와 질문으로 이어가는 경우. README는 YouTube 또는 Bilibili 링크를 Reading에 추가해 재생, 자막 검색, 시각 정보에 연결된 튜터 질문, 메모와 재개 가능한 진행 상태를 사용하는 흐름을 소개한다. 수업 영상의 특정 구간에서 막혔을 때 해당 위치를 기반으로 묻고 기록을 남기는 식이다. 영상 자체는 재생되더라도 자막을 구할 수 없으면 영상 내용에 대한 근거 기반 답변이 제한된다는 조건까지 함께 보아야 한다.
초안을 쓰면서 출처와 수정 제안을 검토하는 경우. Learning notebook에 자신의 글을 페이지와 블록으로 정리하고 Favorites의 원본 기록을 넣는다. Dito에 특정 문단의 설명이나 재작성을 요청하면 제안을 바로 원문으로 덮어쓰는 대신 검토한 뒤 수락하거나 아래에 답변을 삽입할 수 있다. 공식 v1.7.0 릴리스 노트도 이 편집 흐름과 Markdown·Word 내보내기를 명시한다. 이는 튜터가 글을 자동으로 완성해 준다는 주장보다, 자료·사용자 글·제안 변경을 구분해 작업하는 사용 사례에 가깝다.
댓글