跳轉至

Embedding Server

概述

Embedding Server 係一個本地容器服務，將文字轉換成稠密向量（dense vector），Hindsight 需要呢啲向量做語意理解，Qdrant 亦會利用呢啲向量做相似度檢索。實際部署使用 intfloat/multilingual-e5-large 模型，支援多語言文本，特別係中英文混合場景。呢個服務只喺 cf_network 內部運行，唔開 host port，其他容器可以經 hostname embedding-server:8000 連線。

架構

  • 容器名：embedding-server
  • 鏡像：embedding-server:1.0.0（本地 build）
  • 模型：intfloat/multilingual-e5-large
  • 模型快取：volume embedding_models:/models
  • 資源上限：mem_limit: 4g、cpus: 2.0
  • 網絡：外部 network cf_network，固定 IPv4 172.21.0.80
  • 客戶端：Hindsight、LiteLLM 經 http://embedding-server:8000 攞 embeddings；Qdrant 儲存及查詢向量

因為沒有 publish port，主機唔會多咗一個 listening port。容器之間靠 Docker DNS 解析 embedding-server，唔需要記住 IP；固定 IP 主要用嚟配合 firewall 或 network policy。

部署

Compose 使用 external: true 嘅 cf_network，所以部署前要確保 network 存在：

docker network create cf_network

然後起服務：

docker compose up -d embedding-server

第一次啟動會下載 multilingual-e5-large 模型，之後會 cache 喺 embedding_models volume。檢查狀態：

docker compose ps
docker compose logs -f embedding-server

如果想喺另一個容器入面測試：

curl http://embedding-server:8000/health

返回 healthy 即代表服務正常。

配置

主要環境變數：

  • TZ=Asia/Hong_Kong：令 log 時間跟香港時區。
  • MODEL_CACHE_DIR=/models：指定模型存放位置，配合 volume 持久化。
  • EMBEDDING_MODEL=intfloat/multilingual-e5-large：指定 Hugging Face 模型識別碼。

健康檢查每 30 秒打一次 127.0.0.1:8000/health，timeout 10 秒，連續 5 次失敗會標記 unhealthy。start_period: 180s 係用嚟容許模型下載同載入，避免啟動初期誤報。

維運與監控

  • docker logs -f embedding-server：睇模型載入日誌同 API 錯誤。
  • docker stats embedding-server：即時睇 CPU 同記憶體使用量。
  • 如果容器被 OOM killer 殺死，日誌會出現 Killed，需要考慮加大 mem_limit 或者改用更細嘅 embedding model。
  • 呢個服務只可以喺 cf_network 內部用；如果想對外提供，要經 Cloudflare Tunnel 或者 LiteLLM 等 reverse proxy 暴露。

常見問題

  1. Healthcheck 長期 failed：通常係模型仲未下載完，或者模型喺 HDD 載入得好慢。睇 log 有冇顯示下載進度。
  2. Hindsight 連唔到 embedding-server：確認兩個 container 都喺同一個 cf_network，而且要連 embedding-server:8000，唔好用 127.0.0.1:8000。
  3. network cf_network not found：執行 docker network create cf_network，再檢查 compose file 嘅 network 名稱。
  4. 想換模型：改 EMBEDDING_MODEL 之後重啟；舊模型仍然會留喺 volume，如唔需要可以清空 embedding_models。
  5. Host port 唔夠用：呢個 service 冇 publish port，所以唔會同主機上其他服務爭 port。

相關鏈接

docker docker-compose litellm qdrant hindsight cloudflare-tunnel

來源

自動生成（2026-08-19 容器覆蓋率補完第二批）