# 第十三章：安裝 Qdrant（向量資料庫）到 Docker

Qdrant 是專為 AI、搜尋與相似度查詢所設計的向量資料庫，支援高效的向量檢索。以下將介紹如何在本機環境利用 Docker 快速安裝 Qdrant，適合想嘗試 AI 向量搜尋、建置 RAG 系統、或資料科學相關應用的開發者。

## 前言

Qdrant 是一款開源的向量資料庫，支援高維向量的儲存、查詢與篩選，常見應用於語意搜尋、推薦系統、聊天機器人等。利用 Docker 安裝能快速建置可移植的測試或開發環境。

## 步驟一：準備環境

### 1. 安裝 Docker

請先確認你的電腦已安裝好 Docker。 若尚未安裝，請參考官方教學：Docker 官方安裝教學

### 2. 下載 Qdrant 映像檔

Qdrant 官方提供 Docker 映像，可以直接從 Docker Hub 取得。

```
docker pull qdrant/qdrant
```

## 步驟二：啟動 Qdrant 容器（含 Windows / Mac 環境指令）

### 1. 於 Linux / macOS 終端機

可直接於專案目錄下輸入：

```
docker run -d \
  -p 6333:6333 \
  -v $(pwd)/qdrant_data:/qdrant/storage \
  --name qdrant \
  qdrant/qdrant
```

* `$(pwd)` 會自動取得目前目錄路徑。

### 2. 於 Windows CMD / PowerShell

需改用絕對路徑，例如：

```
docker run -d -p 6333:6333 -v C:/qdrant_data:/qdrant/storage --name qdrant qdrant/qdrant
```

* `C:/qdrant_data` 請自行建立對應資料夾，或改成你想存放的資料路徑。
* 若使用 PowerShell，可用 `${PWD}` 取得目前目錄：

```
docker run -d -p 6333:6333 -v ${PWD}/qdrant_data:/qdrant/storage --name qdrant qdrant/qdrant
```

> 建議路徑以英文資料夾命名避免權限或特殊字元問題。

### 3. 開發環境直接啟動（資料不需持久化）

#### Linux / macOS

```
docker run -d -p 6333:6333 --name qdrant-dev qdrant/qdrant
```

#### Windows CMD / PowerShell

```
docker run -d -p 6333:6333 --name qdrant-dev qdrant/qdrant
```

```
bash docker run -d 
-p 6333:6333 
-v $(pwd)/qdrant_data:/qdrant/storage 
--name qdrant 
qdrant/qdrant
```

* `-p 6333:6333`：將本機 6333 埠口對應到容器內的 6333 埠口（REST API 入口）。
* `-v $(pwd)/qdrant_data:/qdrant/storage`：將本機的 `qdrant_data` 資料夾對應到容器內的資料存放路徑，方便資料持久化。
* `--name qdrant`：命名此容器為 qdrant。

> 若你在 Windows，`$(pwd)` 請改為對應本機資料夾路徑（例如 `C:/qdrant_data:/qdrant/storage`）。

***

## 步驟三：開發用法 - 直接啟動快速測試

開發階段若只需快速啟動（不需資料持久化），可以簡化為下列指令：

```bash
docker run -d -p 6333:6333 --name qdrant-dev qdrant/qdrant
```

* **說明**：這樣啟動的 Qdrant 資料將只存在於容器中，關閉或刪除容器即會消失。適合用於開發、測試、CI/CD pipeline。

如需重新啟動開發容器：

```
docker stop qdrant-dev
# 再啟動
docker start qdrant-dev
```

如需清除：

```
docker rm -f qdrant-dev
```

## 步驟四：測試 Qdrant 是否安裝成功

啟動後，可用瀏覽器或 `curl` 測試 Qdrant API 是否正常運作：

```
curl http://localhost:6333/collections
```

如果看到空集合（或 JSON 回應），表示 Qdrant 已成功啟動。

## 常用指令

*   **查看容器狀態**

    ```
    docker ps
    ```
*   **停止容器**

    ```
    docker stop qdrant
    ```
*   **重啟容器**

    ```
    docker start qdrant
    ```
*   **移除容器**

    ```
    docker rm -f qdrant
    ```

## 常見問題

### 1. 埠號衝突怎麼辦？

如本機 6333 埠已被佔用，可將 `-p 6333:6333` 改為其他未被佔用的埠口，例如 `-p 7000:6333`，使用時記得改用 `http://localhost:7000/collections`。

### 2. 如何更改資料保存路徑？

預設會將資料儲存在 `$(pwd)/qdrant_data`，可自行更換路徑，但要確保對應資料夾已建立且有權限。

### 3. 如何升級 Qdrant 版本？

執行 `docker pull qdrant/qdrant:latest` 取得最新版本，再重啟容器即可。

## 參考資源

* Qdrant 官方文件
* Docker Hub - qdrant/qdrant
* 向量資料庫應用介紹
