Woodpeckerを使うCompatible with Milvus 2.6.x

このガイドでは、WoodpeckerをMilvus 2.6.xの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を再利用して軽量メタデータを保存します。
  • prefix：メタデータのキープレフィックス。デフォルト:woodpecker 。
• woodpecker.client
  • スループットとエンド・ツー・エンドのレイテンシのバランスを取るために、クライアント側でセグメントの追加／ローリング／監査動作を制御する。
• woodpecker.logstore
  • ログセグメントの同期/フラッシュ/コンパクション/読み取りポリシーを制御する。これらはスループット/レイテンシを調整するための主要なノブです。
• woodpecker.storage
  • type: MinIO/S3互換オブジェクトストレージ（MinIO/S3/GCS/OSSなど）の場合はminio 、ローカル/共有ファイルシステムの場合はlocal 。
  • rootPath：ストレージバックエンドのルートパス（local に対して有効。minio の場合、パスはバケット/プレフィックスによって決定される）。

デプロイモード

Milvusはスタンドアロンとクラスタの両方のモードをサポートしています。Woodpeckerストレージバックエンドサポートマトリックス

	storage.type=local	storage.type=minio
Milvus スタンドアロン	サポート	スタンドアロン
Milvusクラスタ	制限付き（共有FSが必要）	対応

注意事項

• minio では、WoodpeckerはMilvus（MinIO/S3/GCS/OSSなど）と同じオブジェクトストレージを共有します。
• local では、シングルノードのローカルディスクはスタンドアロンにのみ適しています。すべてのポッドが共有ファイルシステム（NFSなど）にアクセスできる場合、クラスタモードでもlocal を使用できます。

デプロイメントガイド

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をメッセージキューとして設定し、Streaming Nodeを有効にしています。最初の起動はイメージのプルに時間がかかるかもしれません：

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のパラメータを調整する必要がある場合は、message storage configに記載されている設定に従ってください。

Kubernetes上のMilvusクラスタでWoodpeckerを有効にする（Helmチャート、storage=minio）

まず、Run Milvus in Kubernetes with Helmで説明されているように、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のパラメータを調整するには、message storage configに記載されている設定に従ってください。

DockerでMilvusスタンドアロン用のWoodpeckerを有効にする(storage=local)

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を有効にする (storage=minio)

Run Milvus with Docker Composeに従ってください。例

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ノードでは、ローカルで100MB/s程度が上限となることが多い。
  • ローカル/共有ファイルシステム（ローカル）：NVMe/高速ディスクを推奨。FSが小さな書き込みとfsyncレイテンシをうまく処理できるようにする。
• Woodpeckerノブ
  • より大きなフラッシュとより高い並列性のために、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はバッチ書き込みを採用しており、ローカルファイルシステムストレージバックエンドではデフォルトで10ms、MinIOライクストレージバックエンドでは200msの間隔で書き込みを行います。低速の書き込み操作では、最大レイテンシはインターバル時間＋フラッシュ時間に等しくなります。

バッチ挿入は、時間間隔だけでなく、バッチサイズ（デフォルトは2MB）によってもトリガーされることに注意。

アーキテクチャ、展開モード（MemoryBuffer / QuorumBuffer）、パフォーマンスの詳細については、Woodpeckerアーキテクチャを参照してください。

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