교재 PDF를 채팅창에 올려 설명을 듣고 나면, 다음 날에는 어느 페이지를 물었는지부터 다시 찾게 된다. 틀린 문제와 정리한 노트까지 같은 과목 아래 남기고 싶을 때 쓰는 도구가 DeepTutor다. HKUDS가 공개한 오픈소스 학습 작업공간으로, 문서를 옆에 펴 놓고 질문하거나 교재를 바탕으로 복습 문제를 만들 수 있다. 11월 1일 나온 1.7.1에는 노트의 플래시카드를 Anki로 내보내는 기능도 추가됐다.
웹서비스에 가입해 바로 쓰는 방식과는 다르다. 내 컴퓨터에 앱을 띄우고 답변을 생성할 모델을 연결해야 한다. 여기서는 개인 컴퓨터에서 시작하는 설치 방법과, 교재 한 단원을 읽고 복습 자료로 남기는 흐름을 다룬다.
DeepTutor 설치 방법: Docker로 웹앱 띄우기
Docker는 앱과 실행에 필요한 환경을 묶어 돌리는 도구다. Docker가 설치돼 실행 중인 컴퓨터라면 Python이나 Node.js를 따로 준비하지 않고 전체 웹앱을 시험할 수 있다. Windows는 시작 메뉴에서 PowerShell을 검색해 열고, Mac은 Command+스페이스로 검색창을 연 뒤 ‘터미널’을 찾아 실행한다. Linux에서는 사용 중인 배포판의 터미널 앱을 연다. 명령을 입력할 창이 나타나면 docker --version으로 Docker 명령이 인식되는지 확인한다.
아래 명령은 공식 설치 예시의 로컬 접속 범위를 유지하면서 이미지를 1.7.1로 지정한 것이다. 처음에는 이미지 다운로드에 시간이 걸린다. 한 줄 전체를 복사해 실행한다.
docker run --rm --name deeptutor -p 127.0.0.1:3782:3782 -v deeptutor-data:/app/data ghcr.io/hkuds/deeptutor:1.7.1브라우저에서 http://127.0.0.1:3782를 연다. 127.0.0.1은 지금 쓰는 컴퓨터를 가리킨다. 이 명령은 접속 포트를 외부 네트워크에 열지 않는다. 실행 창에서 Ctrl+C로 종료해도 deeptutor-data라는 저장 공간에 설정과 학습 데이터가 남는다. 다시 시작할 때 같은 명령과 저장 공간 이름을 쓴다. 기본 설정은 인증이 꺼진 1인용이므로 공유 서버에 그대로 노출하지 않는다.
화면이 열리면 Settings의 Providers에서 사용할 모델 제공자를 연결하고, Language models에서 답변용 모델을 고른다. 프로그램이 뜨는 것과 답변을 받을 준비가 되는 것은 별개다. 연결 시험을 통과한 모델로 짧은 질문을 보내 응답까지 확인한다. 문서를 검색 가능한 자료 모음으로 만들 때는 검색용 임베딩 모델 설정도 필요하다. 임베딩은 문장을 검색에 쓸 숫자로 바꾸는 과정이다.
이미 Python 환경을 관리하고 있다면 패키지 설치도 가능하다. 공식 요구 조건은 Python 3.11~3.14와 Node.js 20.9 이상이다. 새 가상환경을 만든 뒤, 그 환경의 pip로 다음을 실행한다. pip는 Python 패키지 설치 도구다. 전체 웹앱에는 [full]이 필요하며, 이를 빼면 기본 채팅과 개발용 구성만 설치된다.
pip install --upgrade "deeptutor[full]==1.7.1"
deeptutor init
deeptutor doctor --online
deeptutor startinit에서 모델과 포트를 설정하고, doctor --online으로 실행 환경과 모델 연결을 점검한다. start가 출력한 주소를 열면 된다. Docker 방식과 패키지 방식 중 하나만 고르면 된다. 데스크톱 앱은 개발 브랜치의 미리보기 빌드여서, 이 글의 기본 설치 경로로 삼지 않았다.
교재를 읽다가 막힌 문장을 바로 묻기
먼저 공부할 과목의 workspace를 만든다. workspace는 그 과목의 대화와 자료, 학습 활동을 모으는 폴더에 가깝다. 여러 교재를 계속 검색할 계획이면 Resources의 Knowledge Center에 자료 모음을 만들고 파일을 넣는다. 문서 처리가 끝난 뒤 해당 자료 모음을 대화나 학습 활동에 연결한다. 파일을 올렸다는 사실만으로 검색 준비가 끝나지는 않는다.
한 문서를 차근차근 읽는 일에는 Learning의 새 학습 활동에서 Immersive Reading을 고르는 편이 맞다. 자료를 열면 가운데 읽기 영역과 오른쪽 질문 영역을 함께 쓸 수 있다. 아래 공식 예시는 푸리에 변환 입문 문서를 펼친 상태다. 오른쪽은 아직 질문을 보내기 전이므로, 답변 품질이나 문제 생성 결과를 보여 주는 화면은 아니다.
예를 들어 확률 교재를 읽는다면 ‘이 절에서 조건부확률의 분모가 왜 달라지는지, 교재의 기호를 유지해 설명해 줘’처럼 범위를 좁힌다. 문장을 선택해 설명을 요청하거나, 답변의 출처 표시로 원문 위치를 다시 확인한다. 설명이 자연스러워도 원문에 없는 가정이 끼었는지는 그 자리에서 대조한다. 스캔 PDF의 수식이나 표가 잘못 읽혔다면 질문을 다듬기 전에 추출된 내용부터 확인해야 한다.
설명을 이해한 뒤에는 문제를 풀고 기록을 남긴다
자료를 연결한 채팅에서 Quiz를 골라 ‘이 단원에서 객관식 3문항과 풀이를 만들어 줘’처럼 요청할 수 있다. 만들어진 문제의 정답과 해설을 교재와 맞춰 보고, 다시 풀 문제는 Question Bank에 모은다. 자료 밖 지식을 섞지 않게 요청하더라도 출처 확인을 생략하지 않는다.
Question Bank는 문제와 정답, 풀이, 오답을 보관하는 곳이고 Learning의 Practice는 모은 문제를 다시 푸는 곳이다. 먼저 답한 다음 해설을 열고, 얼마나 기억했는지 피드백하면 다음 복습 일정에 반영된다. 객관식처럼 답이 명확한 유형은 서버가 대조하지만, 단답·서술형은 자기평가가 쓰인다. 모든 풀이가 모델에게 자동 채점되는 구조로 생각하면 안 된다.
위 예시에서는 오늘 복습할 문제가 없어 시작 버튼이 비활성 상태다. 날짜가 아직 오지 않은 문제와 오늘 풀 문제를 구분하는 화면이지, 공부를 마쳤다는 통계는 아니다. 기존 문제집이 있다면 Excel·CSV·TSV·JSON 파일로 가져올 수도 있다. 업로드 후 미리보기를 확인해야 실제 문제로 등록된다.
내 말로 정리한 노트와 암기 카드를 밖으로 꺼내기
답변을 그대로 쌓는 대신 Home의 Learning notebook에 이해한 내용을 다시 적는다. 페이지와 하위 페이지, 블록으로 정리할 수 있고, Dito에 특정 구절의 설명이나 수정안을 요청할 수 있다. 제안을 검토한 뒤 받아들이는 방식이어서 원래 적어 둔 문장과 새 제안을 구분하며 작업한다. 아래 화면에는 핵심 개념과 복습할 항목을 정리한 푸리에 변환 학습 노트가 보인다.
노트는 Markdown이나 Word로 내보낼 수 있다. 노트 페이지에 Flash Cards 블록을 넣었다면 페이지 메뉴의 Export flashcards (Anki)를 고른다. 내려받은 .txt 파일을 Anki의 File → Import에서 불러오면 앞·뒷면과 태그, 수식을 옮길 수 있다. DeepTutor 안에서 정해 둔 복습 일정까지 함께 옮겨지는 것은 아니다. 앱 안에 기록을 남기는 일과, 다른 앱에서도 계속 쓸 수 있게 꺼내 두는 일을 나눠 생각할 수 있다.
한 번의 질문보다 과목을 이어 공부할 때 맞는다
설치 파일이 공개돼 있다는 것과 사용 비용이 없다는 것은 다르다. 클라우드 모델을 연결하면 설명과 문제 생성에 모델 사용료가 들고, 문서 검색을 준비하는 임베딩에도 제공자별 비용이 생길 수 있다. 로컬에 앱을 설치했어도 선택한 외부 모델·문서 처리 서비스로 자료 내용이 전송될 수 있다. 유료 교재의 이용 조건과 회사 내부 자료의 외부 전송 허용 범위를 먼저 따져야 한다.
짧은 PDF 하나를 한 번 요약하는 정도라면 이 설치와 설정을 감수할 이유는 적다. 같은 교재의 원문 위치로 돌아오고, 틀린 문제를 다시 풀며, 노트를 다음 주에도 이어 쓸 때 별도 작업공간의 이점이 생긴다. 첫 시험은 공개 가능한 교재 한 단원으로 제한하는 편이 좋다. 문서가 제대로 읽혔는지, 답변의 출처를 따라갈 수 있는지, 저장한 문제와 노트가 다음 실행에도 남는지를 확인한 뒤 과목 전체로 넓힌다.
출처: DeepTutor 공식 저장소 · 1.7.1 릴리스 · 복습·문제은행 문서