Ubuntu 24.04에서 AI 애플리케이션을 위한 오픈 소스 벡터 데이터베이스 Qdrant 배포하기

Qdrant는 고차원 임베딩 (high-dimensional embeddings)에 대한 유사도 검색 (similarity search)에 최적화된 AI 애플리케이션용 오픈 소스 벡터 데이터베이스 (vector database)로, REST/gRPC API, 페이로드 필터링 (payload filtering), 그리고 내장된 대시보드 (dashboard)를 제공합니다. 이 가이드는 Traefik을 사용하여 자동 HTTPS를 처리하고, API 키 인증 (API-key authentication)을 적용하며, 유사도 검색을 실행하는 샘플 컬렉션 (collection)을 포함하여 Docker Compose를 통해 Qdrant를 배포합니다. 이 과정을 마치면 여러분의 도메인에서 보안이 적용된 벡터 검색을 제공하는 Qdrant를 갖게 될 것입니다.

디렉토리 구조 설정

1. 프로젝트 디렉토리 생성:

$ mkdir -p ~/qdrant/data
$ cd ~/qdrant

2. 강력한 API 키 생성:

$ openssl rand -hex 32

생성된 값을 .env 파일에 저장하세요.

3. 환경 파일 생성:

$ nano .env

DOMAIN=qdrant.example.com
LETSENCRYPT_EMAIL=admin@example.com
QDRANT_API_KEY=PASTE_GENERATED_KEY_HERE

Docker Compose로 배포

1. Compose 매니페스트 (manifest) 생성:

$ nano docker-compose.yaml

services:
  traefik:
    image: traefik:v3.6
...

2. 서비스 시작 및 로그 확인:

$ docker compose up -d
$ docker compose ps
$ docker compose logs --tail=50

대시보드 및 상태 엔드포인트 (Health Endpoint) 접속

1. https://qdrant.example.com/dashboard를 열고 요청 시 API 키를 붙여넣으세요.

2. 서비스 준비 상태 확인:

$ curl https://qdrant.example.com/readyz

all shards are ready라는 응답이 오면 Qdrant가 정상(healthy)임을 확인한 것입니다.

컬렉션 생성 및 유사도 검색 실행

1. API 키 내보내기 (Export):

$ export QDRANT_API_KEY=YOUR_API_KEY

2. 코사인 거리 (cosine distance)를 사용하는 4차원 컬렉션 생성:

$ curl -X PUT "https://qdrant.example.com/collections/star_charts" \
    -H "Content-Type: application/json" \
    -H "api-key: ${QDRANT_API_KEY}" \
...

3. 샘플 포인트 (points) 삽입:

$ curl -X PUT "https://qdrant.example.com/collections/star_charts/points" \
    -H "Content-Type: application/json" \
    -H "api-key: ${QDRANT_API_KEY}" \
...

4. 유사도 검색 (Similarity search) 실행:

$ curl -X POST "https://qdrant.example.com/collections/star_charts/points/search" \
    -H "Content-Type: application/json" \
    -H "api-key: ${QDRANT_API_KEY}" \
...

최상위 결과는 Moon 포인트(코사인 유사도 ~0.99)입니다. 대시보드의 Collections 탭에는 star_charts가 녹색 상태와 함께 5개의 포인트가 있는 것으로 표시됩니다.

다음 단계

Qdrant가 실행 중이며 HTTPS를 통해 벡터 검색 (Vector search) 서비스를 제공하고 있습니다. 이제 다음과 같은 작업을 수행할 수 있습니다:

• OpenAI, Cohere 또는 Sentence-Transformers를 사용하여 임베딩 (Embeddings)을 생성하고 이를 업서트 (Upsert) 하기
• 페이로드 필터 (Payload filters)를 추가하여 벡터 유사도와 구조화된 기준을 결합하기
• 복구가 가능한 백업을 위해 data/ 볼륨을 정기적으로 스냅샷 (Snapshot) 찍기

추가적인 팁이 포함된 전체 가이드를 확인하려면 **Vultr Docs**의 원문 기사를 방문하세요.