使用啄木鳥Compatible with Milvus 2.6.x

本指南說明如何在 Milvus 2.6.x 中啟用和使用 Woodpecker 作為 Write-Ahead Log (WAL)。Woodpecker 是專為物件儲存而設計的雲原生 WAL，提供高吞吐量、低操作開銷和無縫擴充能力。有關架構和基準的詳細資訊，請參閱Woodpecker。

概述

• 從 Milvus 2.6 開始，Woodpecker 是一個可選的 WAL，提供有序寫入和恢復的日誌服務。
• 作為訊息佇列的選擇，它的行為與 Pulsar/Kafka 相似，並可透過設定啟用。
• 支援兩種儲存後端：本機檔案系統 (local) 和物件儲存 (minio/S3 相容)。

快速啟動

要啟用 Woodpecker，請將 MQ 類型設定為 Woodpecker：

mq:
  type: woodpecker

注意：為運行中的群集切換mq.type 是一項升級作業。在切換生產之前，請仔細遵循升級步驟，並在新的群集上進行驗證。

配置

以下是完整的 Woodpecker 配置區塊 (編輯milvus.yaml 或在user.yaml 中覆寫 )：

# Related configuration of woodpecker, used to manage Milvus logs of recent mutation operations, output streaming log, and provide embedded log sequential read and write.
woodpecker:
  meta:
    type: etcd # The Type of the metadata provider. currently only support etcd.
    prefix: woodpecker # The Prefix of the metadata provider. default is woodpecker.
  client:
    segmentAppend:
      queueSize: 10000 # The size of the queue for pending messages to be sent of each log.
      maxRetries: 3 # Maximum number of retries for segment append operations.
    segmentRollingPolicy:
      maxSize: 256M # Maximum size of a segment.
      maxInterval: 10m # Maximum interval between two segments, default is 10 minutes.
      maxBlocks: 1000 # Maximum number of blocks in a segment
    auditor:
      maxInterval: 10s # Maximum interval between two auditing operations, default is 10 seconds.
  logstore:
    segmentSyncPolicy:
      maxInterval: 200ms # Maximum interval between two sync operations, default is 200 milliseconds.
      maxIntervalForLocalStorage: 10ms # Maximum interval between two sync operations local storage backend, default is 10 milliseconds.
      maxBytes: 256M # Maximum size of write buffer in bytes.
      maxEntries: 10000 # Maximum entries number of write buffer.
      maxFlushRetries: 5 # Maximum size of write buffer in bytes.
      retryInterval: 1000ms # Maximum interval between two retries. default is 1000 milliseconds.
      maxFlushSize: 2M # Maximum size of a fragment in bytes to flush.
      maxFlushThreads: 32 # Maximum number of threads to flush data
    segmentCompactionPolicy:
      maxSize: 2M # The maximum size of the merged files.
      maxParallelUploads: 4 # The maximum number of parallel upload threads for compaction.
      maxParallelReads: 8 # The maximum number of parallel read threads for compaction.
    segmentReadPolicy:
      maxBatchSize: 16M # Maximum size of a batch in bytes.
      maxFetchThreads: 32 # Maximum number of threads to fetch data.
  storage:
    type: minio # The Type of the storage provider. Valid values: [minio, local]
    rootPath: /var/lib/milvus/woodpecker # The root path of the storage provider.

主要注意事項：

• woodpecker.meta
  • 類型：目前僅支援etcd 。重複使用與 Milvus 相同的 etcd 來儲存輕量級的 metadata。
  • prefix：元資料的關鍵前綴。預設：woodpecker 。
• woodpecker.client
  • 控制用戶端的段附加/滾動/稽核行為，以平衡吞吐量和端對端延遲。
• woodpecker.logstore
  • 控制日誌段的同步/刷新/壓縮/讀取政策。這些是吞吐量/延遲調整的主要旋鈕。
• woodpecker.storage
  • type:minio 適用於 MinIO/S3 相容的物件儲存 (MinIO/S3/GCS/OSS 等)；local 適用於本機/共用檔案系統。
  • rootPath：儲存後端的根路徑 (對local 有效；使用minio 時，路徑由 bucket/prefix 決定)。

部署模式

Milvus 支援 Standalone 和 Cluster 兩種模式。Woodpecker 儲存後端支援矩陣：

	storage.type=local	storage.type=minio
Milvus 單機版	支援	支援
Milvus 集群	有限 (需要共享 FS)	支援

備註：

• 使用minio ，Woodpecker 與 Milvus 共用相同的物件儲存空間 (MinIO/S3/GCS/OSS 等)。
• 使用local ，單結點本機磁碟僅適用於 Standalone。如果所有 Pod 都可以存取共用檔案系統 (例如 NFS)，Cluster 模式也可以使用local 。

的物件儲存相容性。storage.type=minio

以下矩陣總結了目前已知的物件儲存後端在 Woodpecker 配置為storage.type=minio 時的相容性。此資訊基於GitHub 討論 #150。

提供者/服務	狀態	備註
Azure Blob 儲存	支援	使用本機 Azure SDK。
AWS S3	支援	完全支援條件寫入的原生 S3。
MinIO (>= 2024-12)	支援	完整的 S3 Conditional Write 支援。
阿里雲 OSS	支援	透過其 S3 相容介面支援。
騰訊 COS	支援	透過其 S3 相容介面支援。
Google Cloud Storage (GCS)	支援	透過 S3 互操作模式支援。
華為雲 OBS	不支援	缺乏所需的條件寫入語意。
VAST 資料	支援	已通過社群驗證；僅適用於非版本控制的資料桶。
其他 S3 相容的儲存空間	部分支援	取決於對 S3 Conditional Write 語意的完整支援。

備註：

• 相容性取決於原始 SDK 支援或 S3 Conditional Write 語意的支援。
• 如果您為 Woodpecker 自行託管 MinIO，請使用RELEASE.2024-12-18T13-15-44Z 或更新版本。
• 此矩陣反映目前的討論，並可能隨著後端支援的進一步驗證而演變。

部署指南

為 Kubernetes 上的 Milvus Cluster 啟用 Woodpecker (Milvus Operator, storage=minio)

安裝Milvus Operator 之後，使用官方範例啟用 Woodpecker 來啟動 Milvus 叢集：

kubectl apply -f https://raw.githubusercontent.com/zilliztech/milvus-operator/main/config/samples/milvus_cluster_woodpecker.yaml

此範例會設定 Woodpecker 為訊息佇列，並啟用 Streaming Node。第一次啟動可能需要一些時間來拉取影像；請等待直到所有 Pod 都準備就緒：

kubectl get pods
kubectl get milvus my-release -o yaml | grep -A2 status

準備就緒後，您應該會看到類似以下的 Pod：

NAME                                               READY   STATUS    RESTARTS   AGE
my-release-etcd-0                                  1/1     Running   0          17m
my-release-etcd-1                                  1/1     Running   0          17m
my-release-etcd-2                                  1/1     Running   0          17m
my-release-milvus-datanode-7f8f88499d-kc66r        1/1     Running   0          16m
my-release-milvus-mixcoord-7cd7998d-x59kg          1/1     Running   0          16m
my-release-milvus-proxy-5b56cf8446-pbnjm           1/1     Running   0          16m
my-release-milvus-querynode-0-558d9cdd57-sgbfx     1/1     Running   0          16m
my-release-milvus-streamingnode-58fbfdfdd8-vtxfd   1/1     Running   0          16m
my-release-minio-0                                 1/1     Running   0          17m
my-release-minio-1                                 1/1     Running   0          17m
my-release-minio-2                                 1/1     Running   0          17m
my-release-minio-3                                 1/1     Running   0          17m

執行下列指令卸載 Milvus 叢集。

kubectl delete milvus my-release

如果您需要調整 Woodpecker 參數，請遵循message storage config 中所述的設定。

為 Kubernetes 上的 Milvus 叢集啟用 Woodpecker (Helm Chart, storage=minio)

首先按照在Kubernetes 中使用 Helm 執行 Milvus 中所述，新增並更新Milvus Helm 圖表。

然後使用下列其中一個範例進行部署：

- 群集部署（建議設定啟用 Woodpecker 和 Streaming Node）：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v2.6.0 \
  --set pulsarv3.enabled=false \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true \
  --set indexNode.enabled=false

- 獨立部署 (啟用 Woodpecker)：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v2.6.0 \
  --set cluster.enabled=false \
  --set pulsarv3.enabled=false \
  --set standalone.messageQueue=woodpecker \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true

部署完成後，按照說明文件進行連接埠轉接和連接。若要調整 Woodpecker 參數，請遵循訊息儲存配置中所述的設定。

在 Docker 中為 Milvus 單機啟用 Woodpecker (儲存=本地)

遵循在 Docker 中執行 Milvus。範例：

mkdir milvus-wp && cd milvus-wp
curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh

# Create user.yaml to enable Woodpecker with local filesystem
cat > user.yaml <<'EOF'
mq:
  type: woodpecker
woodpecker:
  storage:
    type: local
    rootPath: /var/lib/milvus/woodpecker
EOF

bash standalone_embed.sh start

若要進一步變更 Woodpecker 設定，請更新user.yaml 並執行bash standalone_embed.sh restart 。

使用 Docker Compose 為 Milvus Standalone 啟用 Woodpecker (儲存空間=minio)

遵循使用 Docker Compose 執行 Milvus。範例：

mkdir milvus-wp-compose && cd milvus-wp-compose
wget https://github.com/milvus-io/milvus/releases/download/v2.6.0/milvus-standalone-docker-compose.yml -O docker-compose.yml
# By default, the Docker Compose standalone uses Woodpecker
sudo docker compose up -d
# If you need to change Woodpecker parameters further, write an override:
docker exec -it milvus-standalone bash -lc 'cat > /milvus/configs/user.yaml <<EOF
mq:
  type: woodpecker
woodpecker:
  logstore:
    segmentSyncPolicy: 
      maxFlushThreads: 16
  storage:
    type: minio
EOF'

# Restart the container to apply the changes
docker restart milvus-standalone

吞吐量調整技巧

根據Woodpecker 中的基準和後端限制，從以下幾方面優化端到端的寫入吞吐量：

• 儲存端
  • 物件儲存 (minio/S3 相容)：增加並發量和物件大小 (避免極小的物件)。注意網路和儲存桶的頻寬限制。SSD 上的單一 MinIO 節點在本機的上限通常約為 100 MB/s；單一 EC2 至 S3 的上限可達 GB/s。
  • 本機/共用檔案系統 (本機)：偏好 NVMe/快速磁碟。確保 FS 能妥善處理小型寫入和 fsync 延遲。
• 啄木鳥旋鈕
  • 增加logstore.segmentSyncPolicy.maxFlushSize 和maxFlushThreads ，以獲得更大的刷新和更高的並行性。
  • 根據媒體特性調整maxInterval (以延遲換取較長聚合的吞吐量)。
  • 對於物件儲存，可考慮增加segmentRollingPolicy.maxSize 以減少區段切換。
• 用戶端/應用程式端
  • 使用更大的批次大小和更多的並發寫入程式/用戶端。
  • 控制刷新/索引建立時間 (在觸發之前批次建立)，以避免頻繁的小寫入。

批次插入示範

from pymilvus import MilvusClient
import random

# 1. Set up a Milvus client
client = MilvusClient(
    uri="http://<Proxy Pod IP>:27017",
)

# 2. Create a collection
res = client.create_collection(
    collection_name="test_milvus_wp",
    dimension=512,
    metric_type="IP",
    shards_num=2,
)
print(res)

# 3. Insert randomly generated vectors
colors = ["green", "blue", "yellow", "red", "black", "white", "purple", "pink", "orange", "brown", "grey"]
data = []

batch_size = 1000
batch_count = 2000
for j in range(batch_count):
    start_time = time.time()
    print(f"Inserting {j}th vectors {j * batch_size} startTime{start_time}")
    for i in range(batch_size):
        current_color = random.choice(colors)
        data.append({
            "id": (j*batch_size + i),
            "vector": [ random.uniform(-1, 1) for _ in range(512) ],
            "color": current_color,
            "color_tag": f"{current_color}_{str(random.randint(1000, 9999))}"
        })
    res = client.insert(
        collection_name="test_milvus_wp",
        data=data
    )
    data = []
    print(f"Inserted {j}th vectors endTime:{time.time()} costTime:{time.time() - start_time}")

延遲

Woodpecker 是專為物件儲存而設計的雲原生 WAL，可在吞吐量、成本和延遲之間進行權衡。目前支援的輕量級嵌入式模式優先優化成本和吞吐量，因為大多數情況只要求在一定時間內寫入資料，而不是要求個別寫入請求的低延遲。因此，Woodpecker 採用分批寫入，本機檔案系統儲存後端預設間隔為 10 毫秒，類似 MinIO 的儲存後端預設間隔為 200 毫秒。在慢速寫入作業期間，最大延遲等於間隔時間加上刷新時間。

請注意，批次插入不僅會由時間間隔觸發，也會由預設為 2MB 的批次大小觸發。

有關架構、部署模式 (MemoryBuffer / QuorumBuffer) 和效能的詳細資訊，請參閱Woodpecker Architecture。

更多參數詳情，請參閱 WoodpeckerGitHub 套件庫。