본문으로 건너뛰기

Quick Start

가장 빠른 설치 경로 — 약 30분(§2 Ollama 준비 포함) 안에 Core 모드(인증없음) 단일 호스트 docker-compose로 배포해 기능을 빠르게 확인할 수 있다.

이 문서는 설치와 서비스 시작까지만 다룬다. 설치가 끝난 뒤 KB를 만들고 문서를 올려 인덱싱한 뒤 실제로 검색해보는 흐름은 첫 KB와 검색에서 이어서 진행한다. 인증(SSO)·접근 제어는 sso-and-auth-setup.md, Kubernetes 설치는 kubernetes.md를 참고한다[ENT].

1. 사전 요구사항​

항목요구
OSLinux 또는 macOS (Docker Desktop)
소프트웨어Docker 24+, Docker Compose v2, git
리소스4 vCPU / 16 GB RAM / 50 GB 디스크 권장
임베딩 서버Ollama (아래 §2에서 준비 — GPU 권장, CPU도 평가 가능)
Python소스 빌드 기준 3.12 (3.13 이상 미지원 — 알려진 제약 참조)

2. 임베딩 서버(Ollama) 준비​

임베딩 모델 서버는 compose에 포함되지 않는다. 설치 호스트 또는 접근 가능한 GPU 서버에 Ollama를 설치하고 기본 임베딩 모델을 내려받는다.

ollama pull bge-m3
OLLAMA_HOST=0.0.0.0 ollama serve  # 데몬으로 이미 실행 중이면 생략

# 확인 (bge-m3가 목록에 있어야 함)
curl http://localhost:11434/api/tags

GPU 서버가 없으면 Ollama 대신 OpenAI API를 사용할 수 있다 — §4 참고. 이 경우 이 단계는 생략된다.

3. 소스 준비​

Core 모드 평가는 rag-api 저장소 하나로 충분하다.

git clone https://github.com/cnapcloud/rag-api.git
cd rag-api/docker

4. 설정​

docker/settings.yaml에서 임베딩 서버 주소만 환경에 맞게 수정한다.

provider:
  name: "ollama"
  url: "http://<ollama-host-ip>:11434"   # 컨테이너에서 접근 가능한 주소

embedding:
  model: "bge-m3"

GPU 서버 없이 OpenAI API로 대체하는 경우 다음과 같이 설정한다.

provider:
  name: "openai"
  api_key: "<발급받은 API 키>"

embedding:
  model: "text-embedding-3-small"
  vector_size: 1536

문서 내용이 외부 API로 전송되는 점 유의.

  • 리랭킹(retrieval.rerank)은 provider: "jina"(외부 API) 또는 provider: "internal"(자체 호스팅 Cohere-호환 rerank 서버, base_url로 지정)을 지원한다. 둘 다 쓰지 않으려면 enabled: false로 두어도 검색은 정상 동작한다 (RRF 점수 사용).

5. 서비스 시작​

docker compose up -d --build

빌드 포함 최초 서비스 시작은 수 분 소요된다. 상태 확인:

docker compose ps                        # 전 서비스 Up/healthy 확인
curl http://localhost:8000/ready         # {"status":"ready", ...} 이면 준비 완료

/ready가 503이면 아직 의존 서비스 초기화 중일 수 있다. 1~2분 후 재시도하고, 계속 실패하면 checks에서 false인 항목의 컨테이너 로그를 확인한다.

접속 주소​

서비스주소용도
RAG APIhttp://localhost:8000REST API (Swagger UI: /docs)
관리 콘솔http://localhost:8080KB·문서·커넥터 관리, 검색 콘솔
Dagster UIhttp://localhost:3000인덱싱 파이프라인 실행 현황
MinIO 콘솔http://localhost:9001원본 문서 스토리지 확인 (admin/password)
Mailpithttp://localhost:8025평가용 메일 수신함 (ENT 초대 메일 확인용)

6. 정리 및 다음 단계​

docker compose down            # 중지 (데이터 볼륨 유지)
docker compose down -v         # 중지 + 데이터 삭제

/ready가 정상이면 설치는 끝났다. 이제 첫 KB와 검색에서 KB를 만들고 문서를 올려 실제로 검색해본다.

다음 단계문서
KB 생성 → 문서 업로드 → 검색 (튜토리얼)first-kb-and-query.md
SSO·KB 접근제어 포함 Enterprise 평가guides/rag-ent/sso-and-auth-setup.md
운영 환경(k8s) 설치kubernetes.md
커넥터(Confluence·GitHub·웹) 설정guides/rag-api/connectors.md