Qdrant 연결

Qdrant는 별도 서버로 운영하는 벡터 DB입니다. 문서가 많아 검색 데이터가 수만 건을 넘거나, AI 검색 데이터를 SpaceBuilder 서버와 분리해서 운영하고 싶을 때 사용합니다.

Qdrant를 쓰더라도 원본 파일과 문서 텍스트는 SpaceBuilder에 그대로 남습니다. Qdrant에는 검색에 필요한 벡터와 최소한의 정보만 저장됩니다.

Qdrant 설치

SpaceBuilder 서버에서 접속할 수 있는 Qdrant 서버가 필요합니다. 이미 운영 중인 Qdrant가 있다면 이 절은 건너뛰고 연결 설정으로 가세요.

Qdrant는 Docker로 설치하는 것이 가장 간단합니다. 아래 절차는 Linux 서버에 Docker가 설치되어 있다는 전제입니다.

준비

실행

데이터가 컨테이너를 지워도 남도록 저장 폴더를 반드시 연결하세요. 아래는 /data/qdrant에 저장하고, 서버가 재부팅되어도 자동으로 다시 시작되도록 설정한 예시입니다.

이미지 버전은 QDRANT_VERSION 변수로 고정합니다. 버전을 지정하지 않으면 latest가 설치되어, 컨테이너를 다시 만들 때 의도하지 않게 버전이 올라갈 수 있습니다. 예시의 v1.13.0은 이 문서의 파일별 벡터 수 확인이 동작하는 1.12 이상의 버전입니다. 실제로 설치할 때는 Qdrant 릴리스 페이지에서 검증한 안정 버전으로 바꾸세요.

QDRANT_VERSION=v1.13.0
sudo mkdir -p /data/qdrant

docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v /data/qdrant:/qdrant/storage \
  qdrant/qdrant:${QDRANT_VERSION}

SpaceBuilder와 다른 서버에서 운영하거나 여러 사람이 접근할 수 있는 네트워크라면 API 키를 함께 켜세요. 키는 길고 추측하기 어려운 값으로 정합니다.

QDRANT_VERSION=v1.13.0
docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v /data/qdrant:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='<API 키>' \
  qdrant/qdrant:${QDRANT_VERSION}

설치 확인

curl http://localhost:6333/collections

"status":"ok"가 포함된 응답이 오면 정상입니다. API 키를 켰다면 curl -H 'api-key: <API 키>' http://localhost:6333/collections처럼 api-key 헤더를 붙여야 응답이 옵니다.

브라우저에서 http://<Qdrant 서버 주소>:6333/dashboard를 열면 컬렉션과 저장된 데이터를 볼 수 있는 대시보드가 나옵니다.

운영 팁

• 업데이트: Qdrant 공식 업그레이드 안내에 따라 마이너 버전을 한 단계씩(예: 1.12 → 1.13) 올리세요. QDRANT_VERSION을 다음 버전으로 바꾸고 docker pull qdrant/qdrant:${QDRANT_VERSION}으로 이미지를 받은 뒤, 컨테이너를 지우고 같은 명령으로 다시 실행합니다. 데이터는 /data/qdrant에 남습니다.
• 백업: 컨테이너를 멈춘 뒤 /data/qdrant 폴더를 통째로 복사하거나, Qdrant의 스냅샷 API를 사용합니다. 다만 벡터는 원본에서 다시 만들 수 있는 파생 데이터라, 백업이 없어도 SpaceBuilder에서 전체 데이터 다시 인덱싱으로 복구할 수 있습니다.
• 방화벽: SpaceBuilder 서버만 6333 포트에 접속할 수 있게 제한하세요. HTTPS로 접속해야 한다면 Qdrant 앞에 리버스 프록시를 두는 방식을 권장합니다.

연결 설정

AI DB 설정 화면의 로컬 AI DB 구성에서 아래와 같이 입력하고 저장합니다.

Qdrant는 서비스형 저장소라 데이터 경로 입력란이 표시되지 않습니다. 데이터는 모두 Qdrant 서버에 저장됩니다.

저장하면 인덱싱 스케줄러가 바로 새 설정을 확인하고, 필요한 경우 원본 전체 재인덱싱을 자동으로 시작합니다. 따로 전체 데이터 다시 인덱싱을 누르지 않아도 됩니다.

컬렉션은 자동으로 만들어집니다

Qdrant 대시보드에서 컬렉션을 미리 만들 필요가 없습니다. SpaceBuilder가 첫 번째 검색 데이터를 저장할 때 설정한 이름으로 컬렉션을 만들고, 검색 필터에 필요한 인덱스도 함께 만듭니다.

첫 인덱싱 전에는 로컬 AI DB 운영 현황의 컬렉션 구성에 아직 생성되지 않음 · 첫 인덱싱 때 자동으로 만들어집니다가 표시됩니다. 오류가 아니므로 인덱싱이 시작될 때까지 기다리면 됩니다.

컬렉션을 직접 만들 때 주의할 점

Qdrant 대시보드의 Create New Collection 화면에서 Simple Hybrid Search나 이름이 있는 벡터(named vector)로 만든 컬렉션은 SpaceBuilder와 호환되지 않습니다. 이런 컬렉션을 지정하면 컬렉션 구성에 컬렉션 설정 확인 필요가 표시되고 인덱싱이 저장 단계에서 실패합니다.

컬렉션을 직접 만들어야 한다면 대시보드의 Console에서 아래 요청을 실행하세요. size는 설정한 벡터 차원과 같아야 합니다.

PUT /collections/setfn_knowledge_example
{
  "vectors": { "size": 1024, "distance": "Cosine" }
}

저장된 데이터 확인

로컬 AI DB 운영 현황에서 Qdrant 상태를 확인합니다.

벡터 1개는 문서 조각(청크) 1개입니다. 문서는 형식에 따라 섹션, 페이지, 행 단위로 먼저 나누고, 다시 한국어 기준 약 700~1,000자 크기로 나눠 저장합니다. 그래서 문서 수보다 벡터 수가 훨씬 많은 것이 정상입니다.

Qdrant 대시보드의 Console에서 실제 저장 내용을 볼 수 있습니다.

파일별 벡터 수 확인:

POST /collections/setfn_knowledge_example/facet
{ "key": "source_path", "limit": 50 }

저장된 문서 조각 일부 확인:

POST /collections/setfn_knowledge_example/points/scroll
{ "limit": 10, "with_payload": ["source_path", "text"], "with_vector": false }

여러 인스턴스가 Qdrant 하나를 함께 쓸 때

인스턴스마다 다른 컬렉션 이름을 쓰면 데이터가 완전히 분리됩니다. 기본 컬렉션 이름(knowledge_vectors)을 그대로 쓰면 화면에 경고와 함께 이 인스턴스의 권장 이름이 표시됩니다.

같은 컬렉션을 함께 쓰더라도 새로 저장하는 벡터에는 인스턴스 격리 키가 붙어, 검색과 삭제는 각 인스턴스의 데이터 안에서만 이루어집니다. 다만 백업, 용량 관리, 삭제를 인스턴스별로 하려면 컬렉션을 나누는 것이 안전합니다.

같은 서버에서 실행 중인 다른 SpaceBuilder 프로젝트가 같은 컬렉션을 쓰고 있으면 설정 화면에 경고가 표시됩니다.

관련 문서

• AI DB 설정
• 벡터 DB 운영 가이드
• Milvus 연결
• 지식 인덱싱