Woodpecker

Woodpecker は、Milvus 3.xのデフォルトのメッセージキュー（書き込み先行ログ、WAL）です。オブジェクトストレージ向けに設計されたクラウドネイティブな WAL であり、高いスループット、低い運用オーバーヘッド、シームレスなスケーラビリティを提供します。アーキテクチャおよびベンチマークの詳細については、「Woodpecker」を参照してください。

概要

• Milvus 3.x では、WoodpeckerがデフォルトのWAL/メッセージキューとして機能し、ロギングサービスとして順序付き書き込みとリカバリを提供します。Pulsar や Kafka などの外部メッセージキューサービスは不要です。
• Woodpeckerは、Milvus/ストリーミングノードに組み込んで実行することも（デフォルト）、独自のポッドを持つ専用サービスとして実行することも可能です（分散/クラスターのみ）。
• storage.type モードとして、オブジェクトストレージ（minio 、デフォルト）、ローカルファイルシステム（local ）、および専用のservice の3つをサポートしています。「デプロイメントモード」を参照してください。

クイックスタート

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
  • type: MinIO/S3互換のオブジェクトストレージ（MinIO/S3/GCS/OSSなど）の場合はminio 、ローカル/共有ファイルシステムの場合はlocal 。
  • rootPath: ストレージバックエンドのルートパス（local で有効。minio では、パスはバケット/プレフィックスによって決定されます）。

デプロイモード

Woodpeckerは、storage.type の3つのモードをサポートしています：

storage.type	Woodpeckerの動作	WAL バックエンド	Milvus スタンドアロン	Milvus 分散型（クラスタ）
minio (デフォルト)	Milvus/ストリーミングノードに組み込み	オブジェクトストレージ（MinIO／S3互換）	対応	サポート済み
local	Milvus/ストリーミングノードに組み込み	ローカルファイルシステム	対応	制限あり（すべてのノードに共有ファイルシステム（例：NFS）が必要）
service	専用のWoodpeckerサービス（独自のポッド）	オブジェクトストレージ（MinIO／S3互換）	未対応	対応

注：

• minio では、WoodpeckerはMilvus（MinIO/S3/GCS/OSSなど）と同一のオブジェクトストレージを共有します。
• local では、シングルノードのローカルディスクはスタンドアロンモードでのみ利用可能です。すべてのポッドが共有ファイルシステム（例：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の条件付き書き込みを完全にサポートしています。
Aliyun OSS	対応	S3互換インターフェースを通じてサポートされています。
Tencent COS	対応	S3互換インターフェースを通じてサポートされています。
Google Cloud Storage (GCS)	対応	S3相互運用モードを通じてサポートされています。
Huawei Cloud OBS	未対応	必要な条件付き書き込みのセマンティクスが欠けています。
VAST Data	サポートされています	コミュニティにより検証済み。バージョン管理されていないバケットでのみ動作します。
その他のS3互換ストレージ	部分的に	S3の条件付き書き込み（Conditional Write）のセマンティクスが完全にサポートされているかどうかに依存します。

注：

• 互換性は、ネイティブ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 をメッセージキューとして設定し、ストリーミングノードを有効にします。初回起動時はイメージの取得に時間がかかる場合があります。すべてのポッドの準備が整うまでお待ちください:

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

準備が整うと、次のようなポッドが表示されます:

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 および Streaming Node を有効にした推奨設定）：

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 クラスタ（Helm）で Woodpecker サービスモードを有効にする

Woodpeckerサービスモードは Milvus 3.0の機能です。分散/クラスタ展開の場合、streaming.woodpecker.embedded=false を設定することで、Woodpecker をストリーミングノードに組み込むのではなく、専用のサービス（個別のポッド）として実行できます：

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は、1ノードの障害を許容しつつクォーラムを維持するため、woodpecker.replicaCount を3未満に設定しないでください。このクラスタには、別途woodpecker ポッドセットが含まれます：

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）を追加することで書き込み容量を水平方向にスケールでき、書き込みは1-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はバッチ書き込みを採用しており、デフォルトの間隔はローカルファイルシステムストレージバックエンドで10ms、MinIOのようなストレージバックエンドで200msに設定されています。書き込み処理が遅い場合、最大レイテンシは間隔時間とフラッシュ時間の合計となります。

なお、バッチ挿入は時間間隔だけでなく、デフォルトで2MBに設定されているバッチサイズによってもトリガーされる点に注意してください。

サービスモード (Milvus 3.0 以降)

サービスモードでは、コストを低く抑えつつ、ミリ秒レベルの書き込みレイテンシ（従来の3レプリカ構成のローカルディスクWALと同等）を実現します。一般的な3レプリカのAZ横断展開において、書き込みレイテンシはミリ秒単位の範囲に収まります。これは以下の仕組みによって実現されます：

• 1 RTT クォーラム書き込み— クライアント主導型レプリケーションでは、1回のラウンドトリップ（RTT）以内にクォーラム書き込みを完了します。これにより、AZをまたぐトラフィックは2つのレプリカ分のデータ量に固定されます（これに対し、ブローカー／リーダーベースのレプリケーションでは、通常、約1/3分の追加のAZ間トラフィックが発生します）。
• トポロジーを意識したシングルホップ読み取り— 各読み取りはブローカーを経由せずに最寄りのレプリカに直接行われるため、ブローカーベースのシステムに見られるランダムなAZ間読み取り（AZ間読み取りトラフィックの約2/3）を回避します。
• セグメントのローリング後の即時オブジェクトストレージへのアップロード— 各セグメントはそのライフサイクル全体を追跡し、ローリングされるとすぐにオブジェクトストレージにアップロードされるため、レイテンシを犠牲にすることなく、ローカルディスクの占有容量とストレージコストを低く抑えることができる。
• ノード間での継続的なレプリケーションなし— ログは共有ストレージとして機能するオブジェクトストレージに永続化されるため、フェイルオーバー時には生存しているレプリカのみを再アップロードすればよく（ノード全体のコピーは不要）、スケーリングはノード間レプリケーションの帯域幅に制限されず、大規模なノード交換でもレプリケーションストームが発生しません。

AZをまたぐ展開において、サービスモードでは、ブローカーベースのログシステムと比較して、AZ間ネットワークトラフィックの書き込みを約1/3、読み取りを約2/3削減できます。詳細な設計およびコスト分析については、「Woodpeckerアーキテクチャ」を参照してください。

アーキテクチャ、デプロイメントモード（MemoryBuffer / QuorumBuffer）、およびパフォーマンスの詳細については、「Woodpecker Architecture」を参照してください。

パラメータの詳細については、WoodpeckerのGitHubリポジトリを参照してください。