Openrag¶

Overview¶

OpenRAG 是一個以容器化方式分發的檢索增強生成（RAG）服務，由 LangflowAI 提供 OpenSearch 基礎映像檔，適合需要將文件檢索、向量搜尋與大語言模型整合的自架環境。本頁所述部署方式，以 Oracle Cloud 上的自助架設為主，利用 Docker Compose 將 OpenRAG OpenSearch 與 OpenSearch Dashboards 組成一套可運作的 RAG 基礎架構。

OpenRAG 的設計哲學是「把 RAG 的複雜底層收納喺容器入面」，讓開發者可以使用標準 OpenSearch API 做向量資料索引，再配合 litellm 或其他模型閘道，統一控制 Embedding、Rerank 與 LLM 請求。部署時使用 TZ: Asia/Hong_Kong，方便香港時區嘅日誌同排程操作。

Architecture¶

OpenRAG 由兩個核心容器組成：

OpenRAG OpenSearch：負責文件儲存、向量索引、全文檢索及 k-NN 搜尋。採用 single-node 模式，適合 Oracle Cloud 免費層的小型部署。
OpenSearch Dashboards：提供網頁管理介面，方便檢查索引狀態、執行查詢及觀察效能。

容器會固定 IP 於 cf_network 網絡內：

openrag-opensearch：172.21.0.78
openrag-dashboards：172.21.0.79

將兩個容器放入同一個 Docker 自訂網絡，好處係唔需要對外開放 OpenSearch 9200 埠，減少攻擊面。若配合 Cloudflare Tunnel，甚至可以唔開任何公開埠，只由 Dashboards 做內部管理。

基本流程如下：

文件內容傳入 OpenRAG OpenSearch；
使用者查詢經 Embedding 模型轉成向量；
OpenSearch 執行向量相似度搜尋；
檢索結果經 litellm 轉發至 LLM 生成答案。

Deployment¶

部署前需要準備：

Oracle Cloud Linux 實例，建議至少 2 OCPU 及 4GB RAM；
已安裝 Docker 及 Docker Compose；
預先建立 Docker 網絡 cf_network：

docker network create --subnet=172.21.0.0/24 cf_network

建立專案目錄並準備環境變數檔 .env：

mkdir -p /home/opc/openrag
cd /home/opc/openrag
cat > .env <<EOF
OPENSEARCH_PASSWORD=YourStrongPassword123!
EOF

以下為 docker-compose.yml 嘅精簡範例：

services:
  openrag-opensearch:
    image: langflowai/openrag-opensearch:latest
    container_name: openrag-opensearch
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.78
    environment:
      TZ: Asia/Hong_Kong
      discovery.type: single-node
      OPENSEARCH_INITIAL_ADMIN_PASSWORD: ${OPENSEARCH_PASSWORD}
      OPENSEARCH_JAVA_OPTS: -Xms1g -Xmx1g
      OPENSEARCH_HOST: 0.0.0.0
    volumes:
      - /home/opc/openrag/opensearch-data:/usr/share/opensearch/data
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65535
        hard: 65535
    healthcheck:
      test: ["CMD-SHELL", "curl -ks -u admin:$$OPENSEARCH_INITIAL_ADMIN_PASSWORD https://localhost:9200/_cluster/health | grep -qE '\"(status)\":\"(green|yellow)\"'"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 90s
    stop_grace_period: 120s

  openrag-dashboards:
    image: opensearchproject/opensearch-dashboards:3.6.0
    container_name: openrag-dashboards
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.79
    depends_on:
      openrag-opensearch:
        condition: service_healthy
    environment:
      TZ: Asia/Hong_Kong
      OPENSEARCH_HOSTS: https://openrag-opensearch:9200
    ports:
      - "5601:5601"

networks:
  cf_network:
    external: true

啟動服務：

docker compose up -d

Configuration¶

OpenRAG 的主要設定集中在環境變數及 Docker volume。

OPENSEARCH_PASSWORD 是 OpenSearch 管理員 admin 嘅初始密碼。密碼必須夠強，建議包含大小階英文、數字及特殊符號，否則 OpenSearch 安全組件可能拒絕啟動。

OPENSEARCH_JAVA_OPTS 控制 JVM heap 大小。喺 Oracle Cloud 免費層常見嘅 6GB RAM 實例上，-Xms1g -Xmx1g 係安全設定；如果文件量好大，可以增加到 2g，但要留意系統記憶體。

discovery.type=single-node 表示 OpenSearch 唔會嘗試尋找其他 cluster 節點，簡化部署。若未來需要擴展至多節點，就必須改用標準 discovery 設定，並考慮用 OpenSearch 專屬安全設定。

Volume /home/opc/openrag/opensearch-data 負責持久化所有索引資料。請確認路徑有足夠磁碟空間，並設定定期備份。Dashboard 方面，OPENSEARCH_HOSTS 唔好寫成 localhost，因為容器內嘅 localhost 唔會指向 OpenSearch 容器；應該使用 container name openrag-opensearch。

Operations¶

日常操作包括：

docker compose ps
docker compose logs -f openrag-opensearch

健康檢查會每 30 秒執行一次，用 curl 檢查 OpenSearch cluster 狀態。若未有回應，可以睇：

docker logs openrag-opensearch

資料備份最簡單係直接打包 volume：

tar -czf openrag-backup.tgz /home/opc/openrag/opensearch-data

升級 OpenRAG 時，先拉新映像檔，再重新建立容器：

docker compose pull
docker compose up -d --force-recreate

正式上線前，建議喺 Oracle Cloud VCN 嘅 Security List 只開放 5601 埠俾管理員 IP，或者使用 Cloudflare Tunnel，避免將管理介面公開到互聯網。

FAQ¶

OpenRAG 同一般 OpenAI API 有咩分別？

OpenRAG 提供檢索層，令 LLM 可以查閱你自己嘅私有文件；OpenAI API 只係模型生成結果，本身唔會知道你內部知識庫嘅內容。

點解要固定 IP 喺 cf_network？

固定 IP 可確保 OpenSearch 同 Dashboards 之間嘅連線唔會因為 Docker 重建而改變，亦方便 Firewall 同代理伺服器設定。

OpenSearch 需要對外開放嗎？

唔需要。OpenRAG OpenSearch 只應該俾內部容器訪問；如果 litellm 或應用程式需要連接，建議都係經 Docker 網絡或者加密 Tunnel。

點解我嘅 OpenSearch 容器啟動失敗？

最常見原因係 OPENSEARCH_PASSWORD 太弱，或者 /home/opc/openrag/opensearch-data 嘅權限唔正確。可以查看容器日誌確認。

可以用 HK 時區嗎？

可以。範例中已經設定 TZ: Asia/Hong_Kong，系統日誌同 OpenSearch 索引時間都會使用香港時間。

docker
OpenSearch
litellm
oracle-cloud
RAG

Source¶

Coverage auto (container scan)