로컬 논문 검토·수정 도우미 튜토리얼: Linux에 개인정보 보호 중심 CLI Agent 배포

프로젝트 소개

로컬 논문 검토·수정 도우미는 Linux용 경량 논문 지원 CLI Agent입니다. 사용자가 질문을 입력하면 모델이 로컬 도구와 논문 검색 기능을 호출하여 로컬 논문 내용의 읽기, 요약 및 분석을 지원합니다.

프로젝트는 기본적으로 Qwen3-14B-AWQ를 사용하며, 모델 가중치 용량은 약 9.4 GB입니다. NVIDIA GPU를 보유하고 로컬에서 모델을 실행하면서 논문과 질문의 개인정보를 보호하려는 사용자에게 적합합니다. 기본적으로 온라인 검색은 활성화되지 않으며, 답변은 주로 모델 자체의 기능과 사용자가 구축한 로컬 지식 베이스를 기반으로 합니다.

프로젝트는 MCP 프로토콜을 지원하며 도구 등록 메커니즘을 통해 MCP 서비스에 연결할 수 있습니다. 입력 예산, 시스템 프롬프트 및 도구 출력 길이를 설정할 수 있으므로 논문 지원 외의 용도로도 활용할 수 있습니다.

주요 기능

• Linux 환경에서 로컬 논문 지원 Agent를 실행합니다.
• 기본적으로 Qwen3-14B-AWQ 로컬 모델을 사용합니다.
• 텍스트 기반 PDF, Markdown 및 TXT 파일을 로컬 검색 지식 베이스로 구축할 수 있습니다.
• 대화형 질문과 명령줄을 통한 단일 질문 실행을 지원합니다.
• 질문과 답변 기록을 Markdown 형식으로 저장할 수 있습니다.
• MCP 프로토콜과 도구 등록 메커니즘을 지원합니다.
• 선택 사항인 LangGraph 세션 체크포인트를 사용하여 창을 넘어 세션을 이어갈 수 있습니다.
• 환경, GPU 및 모델 설정을 확인하는 스크립트를 제공합니다.

설치 전 준비

프로젝트는 Linux를 대상으로 하며 NVIDIA GPU가 장착된 컴퓨터 사용을 권장합니다. 모델 가중치 용량은 약 9.4 GB이며, 실제 실행 시 모델 추론을 위해 충분한 VRAM도 확보해야 합니다. 모델, 입력 예산 또는 출력 길이를 조정할 때는 VRAM 용량을 함께 고려해야 합니다.

현재 스캔된 PDF는 OCR을 지원하지 않습니다. 스캔 논문을 검색하려면 먼저 내용을 텍스트로 변환하거나 프로젝트에서 지원하는 텍스트 기반 PDF, Markdown 또는 TXT 파일을 사용해야 합니다.

프로젝트 다운로드 및 설치

먼저 GitHub 저장소를 복제하고 프로젝트 디렉터리 이름을 local-agent로 지정합니다.

git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agent

Git을 사용하지 않는 경우 GitHub 페이지에서 Code → Download ZIP을 선택하고 압축을 푼 뒤 프로젝트 디렉터리에서 터미널을 엽니다.

프로젝트 디렉터리로 이동한 후 설치 스크립트를 실행합니다.

bash scripts/install.sh

설치가 완료되면 시작 스크립트를 실행합니다.

bash scripts/start.sh

처음 시작할 때는 모델이 로드될 때까지 기다려야 합니다. 터미널에 >>> 프롬프트가 표시되면 질문을 입력할 수 있습니다. 예:

>>> 잔차 연결은 어떤 문제를 해결하는지 설명해 주세요

이후 프로젝트 디렉터리에 들어가 bash scripts/start.sh만 실행하면 시작할 수 있습니다.

첫 실행 및 모델 설정

모델 디렉터리가 완전하지 않거나 모델을 다시 선택해야 하는 경우 다음 명령을 실행합니다.

bash scripts/setup.sh

모델 다운로드에 실패하면 먼저 네트워크를 확인해야 합니다. 네트워크가 연결된 컴퓨터에서 전체 모델 디렉터리를 다운로드한 뒤 대상 컴퓨터로 복사하고, 설정 과정에서 기존 모델을 선택할 수도 있습니다.

모델 시작에 실패하면 터미널에 표시된 로그 파일을 확인합니다. 로그는 일반적으로 다음 위치에 있습니다.

logs/cli-vllm-*.log

GPU VRAM을 다른 프로그램이 점유하고 있지 않은지도 확인합니다.

논문 가져오기 및 색인 구축

Agent가 사용자의 논문을 기반으로 질문에 답하도록 하려면 텍스트 기반 PDF, Markdown 또는 TXT 파일을 data/knowledge/ 디렉터리에 넣습니다. 예를 들어 디렉터리에 여러 논문과 관련 메모를 포함할 수 있습니다.

파일을 준비한 후 지식 베이스 색인 명령을 실행합니다.

bash scripts/start.sh rag-index

처음 색인을 구축할 때는 별도의 검색 모델을 다운로드하므로 네트워크 연결이 필요합니다. 색인 구축이 완료되면 대화형 Agent를 다시 시작합니다.

bash scripts/start.sh

이제 로컬 논문에 기반한 질문을 할 수 있습니다. 예:

로컬 논문을 바탕으로 YOLOv1의 핵심 혁신을 요약하고 출처를 나열해 주세요.

논문을 넣지 않았거나 색인을 구축하지 않았다면 답변은 로컬 논문 내용이 아니라 주로 모델 자체의 지식을 기반으로 합니다. 프로젝트는 기본적으로 온라인 검색을 활성화하지 않습니다.

대화형 사용

시작한 후 >>> 프롬프트에 질문을 입력하고 Enter 키를 누르면 됩니다. 연속 질문, 논문 관점 비교 또는 동일한 주제의 단계별 분석에 적합합니다.

다음 내장 명령으로 대화 과정을 관리할 수 있습니다.

• /help: 대화 명령을 확인합니다.
• /new: 새 세션을 시작합니다.
• /exit, /quit 또는 Ctrl+D: 프로그램을 종료합니다.

각 질문과 답변은 기본적으로 Markdown 파일로 저장되며 경로 형식은 다음과 같습니다.

output/월/일/시간_마이크로초.md

명령줄에서 단일 작업 실행

대화형 인터페이스에 들어갈 필요가 없다면 질문을 시작 스크립트의 인수로 직접 전달할 수 있습니다.

bash scripts/start.sh "어텐션 메커니즘 요약"

--quiet를 사용하면 답변만 출력할 수 있습니다.

bash scripts/start.sh "어텐션 메커니즘 요약" --quiet

답변 파일을 저장하지 않으려면 --no-save를 추가합니다.

bash scripts/start.sh "질문" --no-save

입력 예산, 출력 길이 및 프롬프트 설정

Agent의 입력 예산과 시스템 프롬프트는 config/agent.yaml에서 수정할 수 있으므로, 프로젝트를 다른 로컬 Agent 용도로도 사용할 수 있습니다.

다음 두 매개변수는 반드시 구분해야 합니다. 설정 파일의 tool_output_max_chars: 4000은 도구 결과의 문자 잘라내기 상한이며 모델 답변의 token 상한이 아닙니다. 모델의 최대 출력 길이는 환경 파일의 LOCAL_AGENT_MAX_TOKENS로 제어되며, .env.example의 기본값은 2048 token입니다.

Agent의 기본 입력 예산은 4096 token입니다. 입력 예산, 시스템 프롬프트, 도구 출력 길이 또는 최대 출력 token을 조정할 때는 컨텍스트 길이와 사용 가능한 VRAM을 종합적으로 고려하여 설정이 너무 높아 모델이 정상적으로 실행되지 않는 상황을 피해야 합니다.

창을 넘어 세션 저장 및 복원

기본적으로 세션 컨텍스트는 현재 프로세스에만 저장됩니다. CLI를 종료하면 프로그램은 컨텍스트를 자동으로 복원하지 않으며, 이미 생성된 Markdown 답변 파일도 자동으로 다시 읽지 않습니다.

창을 넘어 동일한 세션을 이어가려면 config/agent.yaml에서 run.checkpoint_enabled를 true로 변경하고 항상 동일한 세션 ID를 사용합니다.

bash scripts/start.sh -i --thread-id my-paper

세션 상태는 다음 위치에 저장됩니다.

data/checkpoints/langgraph.sqlite

/new를 입력하거나 새 대화형 창을 시작할 때 세션 ID를 지정하지 않으면 새 세션이 생성됩니다. 모델 호출마다 기본적으로 최근 4회의 대화를 사용하며, 4096 token 입력 예산 제한도 계속 적용됩니다.

환경 확인 및 문제 해결

문제가 발생하면 먼저 환경 확인 스크립트를 실행하는 것이 좋습니다.

bash scripts/doctor.sh

이 스크립트는 환경, GPU 및 모델 설정을 확인하지만 대규모 모델을 로드하거나 추론을 시작하지 않습니다. 따라서 실제 시작 전이나 문제 해결 시 사용하기에 적합합니다.

• GPU가 없음: NVIDIA GPU가 장착된 Linux 컴퓨터를 사용하는 것이 좋습니다.
• 모델 디렉터리가 불완전함: bash scripts/setup.sh를 실행하여 모델을 다시 선택하거나 다운로드를 계속합니다.
• 모델 다운로드 실패: 네트워크를 확인하거나 네트워크가 연결된 컴퓨터에서 전체 모델 디렉터리를 다운로드한 뒤 대상 환경으로 복사합니다.
• 모델 시작 실패: logs/cli-vllm-*.log를 확인하고 VRAM을 다른 프로그램이 점유하고 있지 않은지 확인합니다.
• 로컬 논문이 사용되지 않음: 파일이 data/knowledge/에 있고 bash scripts/start.sh rag-index를 실행했는지 확인합니다.

실용적인 사용 팁

• 처음 사용하기 전에 bash scripts/doctor.sh를 실행하여 GPU, 모델 디렉터리 또는 설정 문제를 조기에 확인합니다.
• 인용과 분석이 필요한 논문을 data/knowledge/에 모은 뒤 색인을 구축하고 질문합니다.
• 질문할 때 요약 범위, 출력 형식 또는 출처 목록을 명확히 지정하면 로컬 논문 내용을 더 쉽게 검증할 수 있습니다.
• VRAM이 부족하다면 입력 예산, 도구 출력 상한 또는 최대 출력 token을 무작정 늘리지 않습니다.
• 동일한 연구 주제를 계속 처리해야 한다면 체크포인트를 활성화하고 --thread-id를 고정합니다.
• 스캔 PDF는 현재 프로젝트의 OCR에 직접 의존할 수 없으므로 먼저 검색 가능한 텍스트를 준비해야 합니다.

요약

paperchecker는 로컬 모델 시작, 논문 색인부터 CLI 질의응답까지의 전체 흐름을 제공합니다. 프로젝트를 설치한 후 기본 모델로 일반적인 질문을 분석할 수 있으며, 텍스트 기반 논문을 지식 베이스에 넣고 색인을 구축하여 Agent가 로컬 자료를 기반으로 답변하도록 할 수도 있습니다. agent.yaml, 환경 변수 및 세션 체크포인트를 통해 컨텍스트, 출력 및 세션 관리 방식을 추가로 조정할 수 있습니다.

프로젝트 코드는 MIT 라이선스를 따릅니다. 사용 중 시작 또는 모델 문제가 발생하면 먼저 진단 스크립트를 실행하고 로그를 확인하세요.