SmartRAG

문서, 이미지, 오디오와 사적으로 대화하세요. SmartRAG는 사용자의 파일을 로컬에 인덱싱하며, Ollama를 통해 로컬 모델을 사용하여 정확한 출처로 연결되는 인라인 인용과 함께 질문에 답변합니다. 데이터가 기기를 벗어나지 않습니다.

기능 (Features)

• 멀티모달 수집 (Multimodal ingestion): PDF, DOCX, TXT 및 Markdown; Tesseract OCR 및 BLIP 캡셔닝을 통한 이미지; Whisper 전사(transcription)를 통한 오디오
• 근거 기반 답변 (Grounded answers): 번호가 매겨진 인용이 포함된 스트리밍 응답; 인용을 클릭하면 해당 페이지의 출처 열기
• 라이브러리 관리 (Library management): 드래그 앤 드롭 업로드, 미리보기, 삭제 및 선택한 문서에 대한 채팅 범위 지정
• 음성 입력 (Voice input): 질문 구술; Whisper를 사용하여 로컬로 전사됨
• 대화 기록 (Conversations): 후속 컨텍스트가 있는 여러 채팅을 브라우저에 저장

아키텍처 (Architecture)

로컬 설정 (Local setup)

1. 전제 조건 (Prerequisites)

Tesseract와 ffmpeg 설치:

# Windows
winget install UB-Mannheim.TesseractOCR Gyan.FFmpeg
# macOS
...

Windows에서는 Tesseract가 PATH에 없더라도 자동으로 C:\Program Files\Tesseract-OCR에서 인식됩니다. Tesseract 없이도 이미지는 캡션만 사용하여 인덱싱됩니다.

2. Ollama 모델 가져오기 (Pull the Ollama models)

Ollama가 실행 중인지 확인하세요 (데스크톱 앱이 자동으로 시작하며, 그렇지 않은 경우 ollama serve를 실행합니다). 그런 다음:

ollama pull llama3.1:8b        # 채팅 모델 (~4.9 GB)
ollama pull nomic-embed-text   # 임베딩 모델 (~270 MB)

3. 클론 및 설치 (Clone and install)

git clone https://github.com/itanishqshelar/SmartRAG.git
cd SmartRAG

...

실행 (Running)

한 명령어만으로

프로젝트 루트에서:

python start.py

이것은:

• FastAPI 백엔드를 http://localhost:8000에서 시작합니다 (자동 재로드 기능 포함)
• Next.js 개발 서버를 http://localhost:3000에서 시작합니다
• venv가 활성화되어 있지 않아도 자동으로 .venv 인터프리터를 사용합니다
• node_modules가 누락된 경우 frontend/ 디렉토리에서 npm install을 실행합니다
• Ollama에 http://localhost:11434로 연결할 수 없는 경우 경고 메시지를 표시합니다.

**http://localhost:3000**으로 이동하여 문서를 업로드하며 시작하세요. 두 서버를 중지하려면 Ctrl+C를 누르세요.

별도로 (Separately)

venv가 활성화된 상태에서 프로젝트 루트 디렉토리의 터미널 2개를 사용합니다:

# 터미널 1: 백엔드 (backend)
uvicorn api:app --reload --port 8000

...

확인 (Verify)

• http://localhost:8000/api/health는 Ollama와 모델의 사용 가능 여부를 보여줍니다.
• http://localhost:8000/docs에는 대화형 API 문서가 있습니다.

이미지 캡션 모델(~1 GB)과 Whisper 모델(~140 MB)은 이미지를 업로드하거나 오디오 파일을 처음 업로드할 때 Hugging Face에서 다운로드되므로, 각 유형의 첫 번째 업로드는 시간이 더 오래 걸립니다.

문제 해결 (Troubleshooting)

• "Ollama is not reachable": Ollama를 시작하고 (ollama serve 또는 데스크톱 앱) ollama list를 확인하여 두 모델이 모두 표시되는지 확인하세요.
• Model not found: config.yaml에 명시된 이름의 모델을 가져오거나 (models.llm_model / models.embedding_model), 사용 가능한 다른 모델로 변경하세요.
• Frontend can't reach the API: 백엔드가 8000 포트에 있는지 확인하세요. 만약 다른 곳에서 실행한다면, frontend/.env.local에 NEXT_PUBLIC_API_URL을 설정하고 config.yaml의 api.cors_origins에 프론트엔드 출처(origin)를 추가하세요.
• Image text isn't extracted: tesseract --version이 작동하는지 확인하세요 (Windows: C:\Program Files esseract-ocr에 설치되었는지 확인).
• Audio upload fails: 동일한 터미널에서 ffmpeg -version이 작동하는지 확인하세요.
• Port already in use: 3000/8000 포트를 사용하는 것을 중지하거나, 다른 포트에서 서버를 별도로 실행하세요 (위 참조).

Docker

Ollama, 백엔드, 프론트엔드를 컨테이너에서 실행합니다. Docker만 필요합니다.

cd docker
docker compose up -d --build

Open http://localhost:3000. 처음 시작할 때 ollama-pull 작업이 모델을 다운로드합니다(~5 GB), 따라서 이 작업이 완료될 때까지 채팅 기능을 사용할 수 없습니다. 진행 상황은 다음 명령어로 확인할 수 있습니다:

docker compose logs -f ollama-pull

업로드된 파일, 벡터 인덱스, 모델 및 Hugging Face 캐시는 재시작 시 Docker 볼륨에 유지됩니다.

docker compose down        # 중지 (데이터 보존)
docker compose down -v     # 중지 및 모든 데이터와 모델 삭제

호스트에서 이미 실행 중인 Ollama 인스턴스를 번들된 것 대신 사용하려면 다음을 수행합니다:

SMARTRAG_OLLAMA_HOST=http://host.docker.internal:11434 docker compose up -d --build backend frontend

NVIDIA GPU 가속화를 위해 docker/docker-compose.yml의 ollama 서비스 아래에 있는 deploy 블록의 주석을 해제하십시오.

설정 (Configuration)

설정은 config.yaml에 있습니다. 모든 값은 SMARTRAG_<SECTION>__<KEY>라는 환경 변수로 덮어쓸 수 있습니다:

SMARTRAG_MODELS__LLM_MODEL=llama3.2:3b
SMARTRAG_RETRIEVAL__TOP_K=8
SMARTRAG_GENERATION__TEMPERATURE=0.3

프론트엔드는 NEXT_PUBLIC_API_URL (기본값 http://localhost:8000)을 읽습니다.

API

대화형 문서: http://localhost:8000/docs