Qdrant¶

概述¶

Qdrant 係 benhoweb 基建入面負責向量檢索嘅核心服務，主要承載 agent_memory collection，向量維度係 2048，用嚟做語義檢索、Embedding 比對同 RAG（Retrieval-Augmented Generation）。Hindsight 同 QwenPaw Memory Sync 會每日將對話記憶轉換成 embedding 並同步落 Qdrant，令 Agent 可以透過語義相似度搵返相關歷史。

Qdrant 以 Docker container 部署，使用 static IP 172.21.0.35，歸入 cf_network external network，同 Cloudflare Tunnel 及其他內部服務互通。REST API 預設 port 係 6333，gRPC port 係 6334。

架構¶

運行環境：Docker + Docker Compose，工作目錄 /opt/qdrant，storage volume 對應 ./data:/qdrant/storage。
網絡：接入 cf_network external network，固定 IP 為 172.21.0.35。不對外直接 publish port，避免跳過 Tunnel 直接暴露 API。
流量路徑：外部請求經 Cloudflare Tunnel 轉發至 172.21.0.35:6333；內網服務例如 Hindsight、QwenPaw 可以直接使用 http://172.21.0.35:6333。
資料模型：主要 collection 為 agent_memory，vector size 2048，儲存 Agent 嘅 memory chunk、metadata、timestamp 同來源 session。
認證：API Key 由 Qdrant 內建 service.api-key 機制保護，所有對 collection 嘅操作都要帶 api-key header。

部署（Docker Compose 片段）¶

實際部署使用以下 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 network inspect cf_network

啟動命令：

cd /opt/qdrant
docker compose pull
docker compose up -d

配置與環境變數¶

TZ: Asia/Hong_Kong：設定容器時區，確保 log timestamp 同香港時間對齊。
QDRANT__SERVICE__API_KEY：對應 Qdrant config 嘅 service.api-key。實際值由 Infisical 管理，Compose 只引用 ${QDRANT_API_KEY}，唔會直接寫死喺 repository。
./data:/qdrant/storage：所有 collection、segment、snapshot 都寫喺 host 目錄。Backup 時直接備份呢個 volume。
image: qdrant/qdrant:latest：現有部署跟隨 latest。若要提高穩定性，建議喺正式環境改用指定版本 tag，例如 qdrant/qdrant:v1.13.x。

維運與監控¶

健康檢查：

curl -s http://172.21.0.35:6333/healthz

確認 agent_memory collection 狀態：

curl -s \
  -H "api-key: ${QDRANT_API_KEY}" \
  http://172.21.0.35:6333/collections/agent_memory | jq

查看容器日誌：

cd /opt/qdrant
docker compose logs -f --tail=200 qdrant

Snapshot 備份：

curl -X POST \
  -H "api-key: ${QDRANT_API_KEY}" \
  http://172.21.0.35:6333/collections/agent_memory/snapshots

Snapshot 產生後會寫入 /qdrant/storage/snapshots，對應 host 路徑為 ./data/snapshots。定期將 snapshot 複製去 NAS 或者 object storage，避免本地磁碟故障時無法還原。

監控重點：

磁碟空間：Qdrant 對 I/O 敏感，容量不足會令 collection 進入 degraded 狀態。
記憶體同 CPU：用 docker stats qdrant --no-stream 定期檢查。
Collection size：用 REST API 檢查 points_count 同 status。
Prometheus：Qdrant /metrics endpoint 可以接入 Prometheus + Grafana，用嚟監察向量搜尋延遲同 snapshot 失敗次數。

常見問題¶

401 Unauthorized：通常係 QDRANT_API_KEY 同 .env / Infisical 內嘅值唔一致。檢查 docker compose exec qdrant env | grep QDRANT。
Connection refused：容器可能未啟動或者 IP 已變。先 docker compose ps，再 docker inspect qdrant 確認 IP 係 172.21.0.35。
Vector dimension mismatch：如果 upsert 返回 dimension error，表示 Embedding model 輸出唔係 2048 維。要檢查 LiteLLM / Embedding service 配置。
Collection not found：可能 agent_memory 未建立，或者 snapshot 還原時用錯 collection name。可以重新建立 collection，再執行一次 Hindsight / Qwen

Qdrant¶

概述¶

架構¶

部署（Docker Compose 片段）¶

配置與環境變數¶

維運與監控¶

常見問題¶

相關鏈接¶