> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant

**벡터 데이터베이스**입니다. 텍스트, 이미지 등을 숫자 배열(벡터)로 변환한 **임베딩**(Embedding)을 저장하고, 의미적으로 유사한 데이터를 검색합니다.

## 어디에 쓰이나요?

* **RAG (Retrieval-Augmented Generation)**: 문서를 임베딩으로 변환하여 저장하고, 사용자 질문과 유사한 문서를 검색하여 LLM에 전달
* **시맨틱 검색**: 키워드 일치가 아닌, 의미가 비슷한 문서를 검색 (예: "강아지"로 검색하면 "반려견", "puppy" 관련 문서도 검색)
* **추천 시스템**: 사용자가 본 상품과 유사한 상품 추천
* **이미지 검색**: 이미지를 벡터로 변환하여 비슷한 이미지 검색

일반적인 데이터베이스는 정확한 값의 일치 여부를 비교하지만, 벡터 데이터베이스는 벡터 간의 **거리**(유사도)를 계산하여 가장 가까운 결과를 반환합니다.

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  qdrant_data:
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

REST API로 상태를 확인합니다.

```bash theme={null}
curl http://localhost:6333/healthz
```

정상이면 다음과 같이 응답합니다.

```
OK
```

웹 대시보드는 `http://localhost:6333/dashboard`에서 접근할 수 있습니다.

## 기본 정보

| 항목          | 값                                                                  |
| ----------- | ------------------------------------------------------------------ |
| REST API 포트 | 6333                                                               |
| gRPC 포트     | 6334                                                               |
| 대시보드        | [http://localhost:6333/dashboard](http://localhost:6333/dashboard) |
| 데이터 저장 경로   | qdrant\_data 볼륨                                                    |

## API 키 설정

운영 환경에서는 API 키를 설정하여 접근을 제한합니다.

```yaml docker-compose.yml theme={null}
services:
  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    environment:
      - QDRANT__SERVICE__API_KEY=your-api-key-here
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  qdrant_data:
```

API 키가 설정된 경우 요청에 헤더를 포함해야 합니다.

```bash theme={null}
curl -H "api-key: your-api-key-here" http://localhost:6333/healthz
```

## 환경 변수

| 변수                                   | 설명                 |
| ------------------------------------ | ------------------ |
| `QDRANT__SERVICE__API_KEY`           | REST/gRPC API 키    |
| `QDRANT__SERVICE__READ_ONLY_API_KEY` | 읽기 전용 API 키        |
| `QDRANT__STORAGE__STORAGE_PATH`      | 저장 경로              |
| `QDRANT__SERVICE__GRPC_PORT`         | gRPC 포트 (기본: 6334) |

## 라이선스

| 구분     | 내용                       |
| ------ | ------------------------ |
| 라이선스   | Apache License 2.0       |
| 개인 사용  | 자유롭게 사용 가능               |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음 |

## 참고

* [Qdrant Docker 설치 가이드](https://qdrant.tech/documentation/guides/installation/#docker)
* [Qdrant 공식 문서](https://qdrant.tech/documentation/)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Neo4j" icon="arrow-right" href="/stacks/neo4j">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>