Qdrant는 고성능 벡터 데이터베이스(Vector Database) 로, 벡터 유사성 검색과 필터링을 효율적으로 수행할 수 있도록 설계되었습니다. Rust로 개발되어 빠른 성능을 제공하며, 오픈 소스로 제공되어 다양한 환경에서 자유롭게 사용할 수 있습니다. 예를 들어 텍스트, 이미지, 오디오 등 다양한 데이터를 벡터 형태로 저장해 두고 가장 유사한 항목들을 빠르게 찾아주는 역할을 합니다. 이러한 벡터 검색 기능은 검색 엔진의 의미 기반 검색, 추천 시스템, 챗봇의 지식 베이스 구축(RAG), 이상탐지 등 AI 개발 분야에서 폭넓게 활용됩니다.
이 글에서는 윈도우 환경에서 Docker를 사용하여 Qdrant를 로컬에 설치하고 간단히 테스트하는 방법을 단계별로 알아보겠습니다.
Streamlit RAG 챗봇과 n8n 활용은 Streamlit RAG 챗봇과 자동화 툴로 완성한 인공지능 학습 파이프라인 #1을 참고해 주세요.
1. WSL2 및 Docker Desktop 설치
WSL2 활성화
- 윈도우 검색 (Win + S)에서 ‘기능’ 검색
- ‘Windows 기능 켜기/끄기’ 실행
- Hyper-V와 Linux용 Windows 하위 시스템을 체크하고 확인
Docker Desktop 설치
- https://docs.docker.com/desktop/setup/install/windows-install 접속
- Docker Desktop for Windows – x86_64 다운로드
- 설치파일을 실행하고 기본 설정으로 설치
- 기존 계정이 있다면 사용하고 없다면
Create an account진행
- 설치가 완료되면 다음과 같은 화면을 볼 수 있습니다
- 이메일 인증을 하지 않으면 정상적으로 사용할 수 없으니 꼭 이메일 인증까지 완료하세요
2. Qdrant 도커 컨테이너 설치 및 실행
Qdrant를 Docker 컨테이너로 설치해보겠습니다. 이번에는 보안 설정과 함께 설치하는 방법으로 진행하겠습니다. 기본적인 로컬 설치 방법은 Local Quickstart – Qdrant에서 확인 가능합니다.
Qdrant에서 사용할 암호화 키를 생성
- 먼저 Google Code Archive에서 Windows용 openssl 실행파일을 다운로드합니다.
- 다운로드 받은 openssl-for-windows 파일의 압축을 해제한 후
- 해당 폴더 안의 bin 폴더에서 다음 명령어 실행. 32바이트의 랜덤 키값을 생성합니다.
openssl rand -hex 32
- 생성된 암호화키는 잊어버리지 않게 메모해 두세요.
- Windows PowerShell을 실행
- Dockerhub에서 최신 Qdrant 이미지를 다운로드
docker pull qdrant/qdrant
- 이미지 다운로드가 완료되면 다음 명령어를 사용해 Docker에서 Qdrant 컨테이너를 실행합니다. 백그라운드로 실행되도록
-d옵션을 추가했습니다. - 다음 항목들은 내 설정에 맞게 변경하세요.
- db가 저장될 경로: 내 윈도우PC에서 Qdrant DB가 저장될 경로를 지정
- 생성한 암호화 키: 앞서 생성한 암호화키 입력
docker run -d -p 6333:6333 -p 6334:6334 -v "[db가 저장될 경로]/qdrant_storage:/qdrant/storage:z" -e QDRANT__SERVICE__API_KEY=[생성한 암호화 키] qdrant/qdrant
- 실행이 성공하면 Docker Desktop에서 다음과 같은 화면을 보실 수 있습니다.
3. 간단한 테스트 및 데이터 삽입
Dashboard 확인
컨테이너가 정상 기동되었다면, 현재 PC의 localhost에서 Qdrant 서비스를 이용할 준비가 된 것입니다. Qdrant는 기본 설정으로 RESTful API 서버를 제공하며, 웹 브라우저에서 http://localhost:6333으로 접속하면 Qdrant의 상태를 확인할 수 있습니다. 특별한 웹 페이지가 나타나지 않고 JSON 형태의 응답이 나오거나 빈 페이지라면 일단 정상입니다. Qdrant 1.3.0 이상 버전부터는 내장된 대시보드(Web UI)가 함께 제공되는데, http://localhost:6333/dashboard로 접속하면 웹 UI 인터페이스를 확인할 수 있습니다.
- http://localhost:6333/dashboard 접속
- API Key 입력하는 창이 나오면 앞서 생성한 암호화키를 입력
- 처음 시작하면 Dashboard 화면은 다음과 같습니다.
벡터 데이터 저장 테스트
Dashboard에 있는 Console 탭에서 명령어를 입력하고 결과를 확인할 수 있습니다.
- 사이드바에서 Console 선택
- 코드 입력 후 위에 Run 클릭
- 결과 확인
- test_collection이라는 cosine 유사도를 사용하는 4개의 차원으로 구성된 컬렉션을 만들어 보겠습니다.
PUT collections/test_collection
{
"vectors": {
"size": 4,
"distance": "Cosine"
}
}
- 결과가 다음과 같이 나오면 성공한 것입니다.
{
"result": true,
"status": "ok",
"time": 0.736352708
}
- 생성된 컬렉션은 Collections 탭에서 확인 가능합니다.
- 데이터를 추가해 보겠습니다.
PUT collections/test_collection/points
{
"points": [
{
"id": 1,
"vector": [0.1, 0.2, 0.3, 0.4],
"payload": {
"context": "내용입니다.",
"metadata": {
"category": "기사"
}
}
}
]
}
- Dashboard > Collections 탭 > test_collection을 클릭하면 추가된 데이터를 확인할 수 있습니다.
4. 마무리 및 추가 참고자료
이 글에서는 Windows 11 사용자 기준으로 Docker를 활용하여 로컬에 Qdrant 서버를 구축하고, 간단한 예제를 통해 벡터 DB의 핵심 동작을 살펴보았습니다. 요약하면, Docker Desktop을 설치하고 Docker로 Qdrant 컨테이너를 손쉽게 실행하여 벡터 임베딩 데이터를 추가할 수 있었습니다.
앞으로 Qdrant를 활용한 다양한 AI 개발 방법과 RAG 구현에 대한 포스팅을 계획하고 있으니 많은 관심 부탁드립니다.
이상으로 Qdrant 로컬 설치 튜토리얼을 마칩니다. 이제 벡터 DB를 활용한 흥미로운 프로젝트를 직접 시도해 보세요!