Woodpecker

Woodpecker 是 Milvus 3.x 中的預設訊息佇列（預寫日誌，WAL）。它是一款專為物件儲存設計的雲原生 WAL，具備高吞吐量、低運作開銷及無縫擴展性。有關架構與效能測試的詳細資訊，請參閱Woodpecker。

概述

• 在 Milvus 3.x 中，Woodpecker 是預設的WAL／訊息佇列，作為記錄服務提供有序寫入與復原功能。無需外部訊息佇列服務（例如 Pulsar 或 Kafka）。
• Woodpecker 可以內嵌於Milvus/streaming 節點中運行（預設），或作為擁有獨立 Pod的專用服務運行（僅限分散式／叢集環境）。
• 它支援三種storage.type 模式：物件儲存（minio ，預設）、本地檔案系統（local ）以及專用service 。請參閱「部署模式」。

快速入門

若要啟用 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 number of flush retries.
      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
  • type：目前僅支援etcd 。請沿用與 Milvus 相同的 etcd 來儲存輕量級元資料。
  • prefix：元資料的鍵前綴。預設值：woodpecker 。
• woodpecker.client
  • 控制客戶端端的區段追加／滾動／稽核行為，以平衡吞吐量與端到端延遲。
• woodpecker.logstore
  • 控制日誌區段的同步／沖洗／壓縮／讀取政策。這些是調整吞吐量與延遲的主要控制項。
• woodpecker.storage
  • 類型：minio 適用於 MinIO/S3 相容的物件儲存（MinIO/S3/GCS/OSS 等）；local 適用於本機/共用檔案系統。
  • rootPath：儲存後端的根路徑（僅適用於local ；若使用minio ，路徑則由儲存桶／前綴決定）。

部署模式

Woodpecker 支援三種storage.type 模式：

storage.type	Woodpecker 的運作方式	WAL 後端	Milvus 獨立模式	Milvus 分散式（叢集）
minio （預設）	嵌入於 Milvus/串流節點中	物件儲存（MinIO／S3 相容）	受支援	支援
local	內建於 Milvus/串流節點中	本機檔案系統	支援	有限（所有節點都需要共用檔案系統，例如 NFS）
service	專用的 Woodpecker 服務（擁有專屬的 Pod）	物件儲存（MinIO／S3 相容）	不支援	受支援

備註：

• 在minio 模式下，Woodpecker與Milvus共用相同的物件儲存（MinIO/S3/GCS/OSS等）。
• 在「local 」模式下，單節點本機磁碟僅適用於「獨立模式」。若所有 Pod 皆可存取共用檔案系統（例如 NFS），則「叢集模式」亦可使用「local 」。
• service 此模式將 Woodpecker 作為獨立且可自主擴展的服務運行，僅適用於分散式／叢集部署。獨立部署則使用內嵌模式（minio 或local ）。

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

下表彙整了當 Woodpecker 配置為storage.type=minio 時，目前已知的物件儲存後端相容性。此資訊基於GitHub 討論串 #150。

供應商／服務	狀態	備註
Azure Blob Storage	受支援	使用原生 Azure SDK。
AWS S3	已支援	原生 S3，並完全支援條件寫入。
MinIO (>= 2024-12)	已支援	完整支援 S3 條件寫入功能。
阿里雲 OSS	已支援	透過其 S3 相容介面提供支援。
騰訊 COS	支援	透過其 S3 相容介面提供支援。
Google Cloud Storage (GCS)	受支援	透過 S3 互通模式支援。
華為雲 OBS	不支援	缺乏所需的「條件寫入」語義。
VAST Data	受支援	經社群驗證；僅適用於非版本化儲存桶。
其他 S3 相容儲存服務	部分	取決於是否完全支援 S3 條件寫入語義。

備註：

• 相容性取決於原生 SDK 的支援，或對 S3 條件寫入語義的支援。
• 若您為 Woodpecker 自行架設 MinIO，請使用RELEASE.2024-12-18T13-15-44Z 或更新版本。
• 此對照表反映當前的討論內容，並可能隨著後端支援的進一步驗證而有所變動。

部署指南

在 Kubernetes 上的 Milvus 叢集中啟用 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 設定為訊息佇列，並啟用串流節點。首次啟動時，拉取映像檔可能需要一些時間；請等待直到所有 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 參數，請參照「設定」章節中的說明進行設定。

在 Kubernetes 上為 Milvus 叢集啟用 Woodpecker（Helm 圖表，storage=minio）

首先，請依照《使用 Helm 在 Kubernetes 上執行 Milvus》中的說明，新增並更新 Milvus Helm 圖表。

接著，請參照以下範例之一進行部署：

– 叢集部署（建議設定：啟用 Woodpecker 與串流節點）：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v3.0.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=v3.0.0 \
  --set cluster.enabled=false \
  --set pulsarv3.enabled=false \
  --set standalone.messageQueue=woodpecker \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true

部署完成後，請依照文件說明進行端口轉發並建立連線。若要調整 Woodpecker 參數，請參照「設定」章節中的說明進行設定。

在 Docker 中的 Milvus 獨立模式（storage=local）啟用 Woodpecker

在 Milvus 3.x 中，Docker 獨立部署預設會使用Woodpecker，並以本地檔案系統作為其 WAL 後端 — 無需額外配置。請參照《在 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
bash standalone_embed.sh start

若要調整 Woodpecker，請在首次啟動後編輯生成的 `user.yaml ` 檔案，並執行 `bash standalone_embed.sh restart ` 以套用變更（執行 `start ` 會重新生成 `user.yaml`，因此請使用 `restart` 來套用編輯內容）：

# user.yaml
woodpecker:
  logstore:
    segmentSyncPolicy:
      maxFlushThreads: 16

透過 Docker Compose 為 Milvus 獨立執行環境啟用 Woodpecker（storage=minio）

請參照《使用 Docker Compose 執行 Milvus》。範例：

mkdir milvus-wp-compose && cd milvus-wp-compose
wget https://github.com/milvus-io/milvus/releases/download/v3.0.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

為 Milvus 叢集啟用 Woodpecker 服務模式（Helm）

Woodpecker服務模式是 Milvus 3.0的一項功能。對於分散式／叢集部署，您可以透過設定 `streaming.woodpecker.embedded=false`，將 Woodpecker作為專用服務（獨立 Pod）運行，而非嵌入至串流節點中：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v3.0.0 \
  --set woodpecker.enabled=true \
  --set woodpecker.image.tag=v0.1.37 \
  --set streaming.enabled=true \
  --set streaming.woodpecker.embedded=false

此設定將 Woodpecker 部署為專用的 StatefulSet（my-release-milvus-woodpecker ，預設 4 個複本），由無頭服務作為前端，透過18080 （服務）、17946 （閒聊）及9091 （指標）這三個埠進行閒聊式叢集，並以 MinIO 作為其儲存後端。 該服務需要3個節點的法定人數；預設的4個複本既能維持法定人數，又能容忍單一節點故障，因此請勿將 `woodpecker.replicaCount ` 設定為低於 3。該叢集還包含一個獨立的woodpecker Pod 集合：

my-release-milvus-woodpecker-0
my-release-milvus-woodpecker-1
my-release-milvus-woodpecker-2
my-release-milvus-woodpecker-3

吞吐量調校要訣

Woodpecker在嵌入式模式與服務模式（Milvus 3.0 的新功能）下的吞吐量與延遲表現各不相同。以下指引將依模式分類說明。

嵌入式模式

根據Woodpecker 中的基準測試結果與後端限制，請從以下方面優化端到端的寫入吞吐量：

• 儲存端
  • 物件儲存（MinIO／S3 相容）：提高並發數並增大物件大小（避免使用微小物件）。注意網路與儲存桶的頻寬限制。單一搭載 SSD 的 MinIO 節點，本地頻寬通常上限約為 100 MB/s；單一從 EC2 傳輸至 S3 的頻寬則可達 GB/s。
  • 本機／共用檔案系統（本機）：優先選用 NVMe／高速硬碟。確保檔案系統能妥善處理小量寫入及 fsync 延遲。
• Woodpecker 調整參數
  • 增加 `logstore.segmentSyncPolicy.maxFlushSize ` 和 `maxFlushThreads ` 參數值，以實現更大的寫入批次及更高的並行度。
  • 根據儲存媒體特性調整maxInterval （透過延長聚合時間，在延遲與吞吐量之間取得平衡）。
  • 對於物件儲存，可考慮增加segmentRollingPolicy.maxSize 以減少區段切換。
• 客戶端／應用程式端
  • 使用較大的批次大小，並增加並行寫入者／客戶端數量。
  • 控制刷新／索引建置的時機（在觸發前先進行批次彙總），以避免頻繁的小量寫入。

服務模式（Milvus 3.0+）

服務模式在維持以物件儲存為後端的 WAL 高寫入吞吐量的同時，還增加了低延遲（請參閱「延遲」）。 上述儲存端與客戶端側的調校方法依然適用；此外，由於 Woodpecker 以獨立服務形式運行，您可以透過增加複本（woodpecker.replicaCount ，預設為 4）來水平擴展寫入容量，且寫入操作可受益於單次 RTT 法定人數複製，以及能避免經由中介伺服器轉發的拓撲感知讀取。

批次插入示範— 請使用以下指令測量寫入吞吐量：

from pymilvus import MilvusClient
import random
import time

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

# 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。

服務模式（Milvus 3.0+）

服務模式在維持低成本的同時，可實現毫秒級的寫入延遲——與傳統的三副本本地磁碟 WAL 處於同一量級。在典型的三副本跨可用區域（AZ）部署中，寫入延遲維持在毫秒範圍內。其實現方式如下：

• 單 RTT 法定數寫入— 由客戶端驅動的複製可在單次往返內完成法定數寫入，且跨可用區域的流量固定為兩個副本的資料量（相較於基於中介/領導節點的複製通常會產生額外約 1/3 的跨可用區域流量）。
• 拓撲感知單跳讀取— 每次讀取皆直接連線至最近的副本，而非透過中介節點轉發，從而避免了基於中介節點系統中隨機的跨可用區域讀取（約佔跨可用區域讀取流量的 2/3）。
• 區段滾動後立即上傳至物件儲存— 每個區段皆追蹤其完整生命週期，並在滾動後立即上傳至物件儲存，在維持低延遲的同時，將本地磁碟佔用空間與儲存成本控制在低水平。
• 無需持續的節點間複製— 日誌持久化至充當共享儲存的物件儲存中，因此故障轉移時僅需重新上傳存活的副本（無需複製整個節點），擴展能力不受節點間複製頻寬限制，且大規模節點更換也不會引發複製風暴。

在跨可用區域（AZ）部署中，相較於基於中介服務器的日誌系統，此服務模式還能節省約1/3 的跨可用區域寫入流量及2/3 的跨可用區域讀取流量。完整的設計與成本分析，請參閱《Woodpecker 架構》。

有關架構、部署模式（MemoryBuffer / QuorumBuffer）及效能的詳細資訊，請參閱《Woodpecker 架構》。

如需更多參數詳情，請參閱 WoodpeckerGitHub 儲存庫。