Qdrant¶

Overview¶

Qdrant 是一款以 Rust 編寫的開源向量資料庫，專門用於儲存、檢索和管理由機器學習模型產生的向量嵌入（Embedding）。在近年大型語言模型（LLM）及檢索增強生成（RAG）應用蓬勃發展的背景下，Qdrant 成為一個重要的底層元件，負責高效率的相似度搜尋。其核心功能是允許使用者將圖文、音訊或任何可被向量化的數據轉換為高維向量，再透過 Qdrant 進行近即時檢索。

與傳統關聯式資料庫不同，Qdrant 不處理 SQL 查詢，而是提供向量相似度比對，例如餘弦距離、歐氏距離及點積。除了基本檢索能力，Qdrant 亦支援 Payload（中繼資料）過濾、向量索引、分片及複製等功能，讓開發者可以在搜尋時同時根據標籤、類別或其他結構化條件進行過濾。

在 wiki.benhoweb.com 的部署情境中，Qdrant 被建置為一項自我託管（Self-hosted）服務，執行於 Oracle Cloud 虛擬機器之上。這樣做的好處包括數據私隱保障、部署成本控制，以及與同一 Docker 網絡內的其他服務進行低延遲整合。

Architecture¶

Qdrant 的系統架構以「集合（Collection）」、「點（Point）」及「向量（Vector）」為核心抽象概念。一個 Collection 可以視為一組向量的資料庫，而每個 Point 則包含一個唯一 ID、向量本體以及可選的 Payload。Payload 是 JSON 格式的結構化資料，讓使用者可以附加豐富的後設資訊，例如文章分類、來源網址、時間戳記及權限標記。

Qdrant 使用基於 HNSW（Hierarchical Navigable Small World）演算法的近似最近鄰（ANN）搜尋索引，以在極高維度數據中保持高速搜尋。它亦支援 flat index 及 payload index，讓不同使用場景可以選擇合適的索引方式。除此之外，Qdrant 提供 RESTful API 及 gRPC API，方便不同程式語言和框架接入。

在部署架構上，Qdrant 容器透過 Docker 網絡與其他服務連接。以下是這個服務的 Docker Compose 定義：

networks:
  cf_network:
    external: true

services:

  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant

    restart: unless-stopped

    volumes:
      - ./data:/qdrant/storage

    networks:
      cf_network:
        ipv4_address: 172.21.0.35

    environment:
      TZ: Asia/Hong_Kong
      QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}

在此架構中，cf_network 被定義為外部網絡，這表示它已經預先存在於 Docker 引擎中，通常由反向代理或 Cloudflare Tunnel 等容器建立。Qdrant 被賦予固定 IP 172.21.0.35，使其他服務可以透過這個 IP 或服務名稱訪問 Qdrant，而毋需每次重新查詢動態位址。

Deployment¶

Qdrant 在 Oracle Cloud 上的部署需要一台具備 Docker 及 Docker Compose 的 Linux 虛擬機器。Oracle Cloud 的 Always Free 資源通常已足夠小型專案使用，但若需要較大記憶體來載入 HNSW 索引，則建議依照實際數據量選擇更大的運算資源。

部署步驟大致如下：

建立資料目錄，例如 qdrant/。
在目錄內建立 docker-compose.yml 檔案，內容如上所示。
建立 .env 檔案，定義 QDRANT_API_KEY 變數，例如：
```
QDRANT_API_KEY=your_secure_api_key_here
```
執行 docker compose up -d 啟動服務。
確認服務狀態：docker compose ps。
透過反向代理將網域或路徑指向 http://172.21.0.35:6333。

使用 latest 標籤可以讓部署保持最新版本，但在生產環境中，較為穩妥的做法是鎖定特定版本號碼，例如 qdrant/qdrant:v1.12.0，以避免無預警升級造成相容性問題。

Configuration¶

Qdrant 的設定可以透過環境變數、設定檔或 API 進行。在 Docker Compose 中，所有以 QDRANT__ 開首的環境變數均會對應至 Qdrant 的 YAML 設定結構。雙底線符號 __ 代表巢狀層級。

在此部署中，使用了兩個環境變數：

TZ=Asia/Hong_Kong：設定容器時區為香港時間，確保日誌時間戳與操作時間一致。
QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}：從 .env 檔案讀取 API 金鑰，並設定為 Qdrant 服務層級的 API 金鑰。這項設定啟用後，所有 API 請求都必須帶有該金鑰，否則會被拒絕。

另外，container_name: qdrant 固定了容器名稱，方便在 Docker 指令中直接識別。restart: unless-stopped 確保服務在系統重新啟動或意外停止時自動恢復。

外部網絡的設定方面，cf_network 需要事先建立。如果尚未建立，可以使用以下指令手動建立：

docker network create cf_network --subnet=172.21.0.0/24

但需要注意，若網絡已存在且子網路不同，則需要調整 ipv4_address 至對應範圍，否則會出現 IP 分配衝突。

Operations¶

日常營運 Qdrant 時，最常需要執行的操作包括檢查服務健康狀態、檢視日誌、備份數據及更新版本。

Qdrant 提供健康檢查端點，例如：

GET /readyz：確認服務是否已準備好接受請求。
GET /livez：確認服務進程是否仍然運行。

透過反向代理或 curl 指令即可快速得知服務狀態。若要檢視日誌，可以使用：

docker logs -f qdrant

備份方面，Qdrant 的數據預設儲存在容器內的 /qdrant/storage，而 Compose 設定將此路徑映射到主機上的 ./data 目錄。因此，只需備份該目錄即可保留所有集合、向量及索引。建議採用快照或定期複製到 Oracle Cloud Object Storage，以備災難復原。

更新 Qdrant 版本時，可以使用以下流程：

docker compose pull qdrant
docker compose up -d qdrant

更新前應先進行備份。若升級後出現異常，可以使用舊版本映像檔及備份數據進行回滾。

安全性方面，除了設定 API 金鑰，亦應避免將 Qdrant 的 6333 連接埠直接暴露於互聯網。最佳做法是讓 Qdrant 僅存在於 Docker 內網，並透過 Cloudflare Tunnel、Nginx 或其他反向代理提供對外存取。這樣可以同時獲得 TLS 加密、存取控制及 DDoS 防護。

FAQ¶

Qdrant 的主要用途是什麼？

Qdrant 主要用於向量相似度搜尋，常見應用包括 RAG 知識庫、圖像檢索、推薦系統、異常檢測及語義搜尋。它可以與 LangChain、LlamaIndex 或 litellm 等工具整合，讓 AI 模型能夠快速查找相關上下文。

為什麼要自我託管 Qdrant，而不是使用雲端版？

自我託管可以將所有數據保留在自己的基礎架構內，避免資料外洩。對於使用 Oracle Cloud 的使用者而言，自我託管亦可以節省長期訂閱費用，並可根據需求自由調整設定。

如何確認 API 金鑰已生效？

設定 API 金鑰後，若直接使用 curl 呼叫 API 而沒有帶上 api-key 標頭，會收到 401 Unauthorized 回應。正確的請求需要加入：

curl -H "api-key: your_secure_api_key_here" http://localhost:6333/collections

Qdrant 的儲存目錄可否直接複製至另一台伺服器？

可以。Qdrant 的 storage 目錄內包含完整的集合數據。將 ./data 目錄複製至另一台伺服器的相同位置，並啟動相同版本的 Qdrant，即可完成遷移。需要注意目錄權限必須正確，否則容器可能無法讀取。

Qdrant 與其他向量資料庫有何不同？

Qdrant 使用 Rust 開發，效能表現出色，而且內建豐富的 Payload 過濾功能，讓搜尋不再局限於向量距離計算。它的 API 設計直觀，社群活躍，且支援精簡的單節點部署。相較於 Milvus 等較重的解決方案，Qdrant 更適合中小型部署。

Qdrant 可否與 LiteLLM 一同使用？

可以。litellm 作為大型語言模型閘道，可以統一不同模型供應商的 API，而 Qdrant 則可作為知識庫的向量儲存層。透過 LiteLLM 取得嵌入向量後，可以存入 Qdrant；檢索時亦可將 Qdrant 的相關結果傳遞給 LLM 生成答案。

docker
docker-compose
oracle-cloud
litellm
向量資料庫
RAG
反向代理
API 金鑰

Source¶

Coverage auto (container scan)