Woodpecker

Woodpecker adalah antrian pesan (write-ahead log, WAL) bawaan di Milvus 3.x. Ini adalah WAL berbasis cloud yang dirancang untuk penyimpanan objek, menawarkan throughput tinggi, beban operasional rendah, dan skalabilitas yang mulus. Untuk detail arsitektur dan benchmark, lihat Woodpecker.

Gambaran Umum

• Di Milvus 3.x, Woodpecker adalah WAL/antrian pesan bawaan, yang menyediakan penulisan terurut dan pemulihan sebagai layanan pencatatan. Layanan antrian pesan eksternal (seperti Pulsar atau Kafka) tidak diperlukan.
• Woodpecker dapat dijalankan secara tertanam di dalam node Milvus/streaming (default), atau sebagai layanan khusus dengan pod-nya sendiri (hanya untuk distribusi/kluster).
• Woodpecker mendukung tiga mode penyimpanan ( storage.type ): penyimpanan objek (minio, default), sistem file lokal (local), dan penyimpanan khusus ( service). Lihat Mode Deployment.

Panduan Cepat

Untuk mengaktifkan Woodpecker, atur jenis MQ menjadi Woodpecker:

mq:
  type: woodpecker

Catatan: Mengganti " mq.type " pada kluster yang sedang berjalan merupakan operasi peningkatan versi. Ikuti prosedur peningkatan versi dengan cermat dan lakukan validasi pada kluster baru sebelum beralih ke lingkungan produksi.

Konfigurasi

Di bawah ini adalah blok konfigurasi Woodpecker lengkap (edit milvus.yaml atau ganti di 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.

Catatan penting:

• woodpecker.meta
  • type: Saat ini hanya etcd yang didukung. Gunakan etcd yang sama dengan Milvus untuk menyimpan metadata ringan.
  • prefix: Awalan kunci untuk metadata. Default: woodpecker.
• woodpecker.client
  • Mengontrol perilaku penambahan/pergantian/audit segmen di sisi klien untuk menyeimbangkan throughput dan latensi ujung ke ujung.
• woodpecker.logstore
  • Mengontrol kebijakan sinkronisasi/pembersihan/pemadatan/pembacaan untuk segmen log. Ini adalah pengaturan utama untuk penyesuaian throughput dan latensi.
• woodpecker.storage
  • type: minio untuk penyimpanan objek yang kompatibel dengan MinIO/S3 (MinIO/S3/GCS/OSS, dll.); local untuk sistem berkas lokal/bersama.
  • rootPath: Jalur akar untuk backend penyimpanan (berlaku untuk local; dengan minio, jalur ditentukan oleh bucket/prefiks).

Mode penerapan

Woodpecker mendukung tiga mode storage.type:

storage.type	Cara kerja Woodpecker	Backend WAL	Milvus Mandiri	Milvus Distributed (kluster)
minio (default)	Terintegrasi dalam node Milvus/streaming	Penyimpanan objek (kompatibel dengan MinIO/S3)	Didukung	Didukung
local	Terintegrasi dalam node Milvus/streaming	Sistem berkas lokal	Didukung	Terbatas (semua node memerlukan sistem berkas bersama, misalnya NFS)
service	Layanan Woodpecker khusus (pod-podnya sendiri)	Penyimpanan objek (kompatibel dengan MinIO/S3)	Tidak didukung	Didukung

Catatan:

• Dengan mode " minio", Woodpecker berbagi penyimpanan objek yang sama dengan Milvus (MinIO/S3/GCS/OSS, dll.).
• Dengan mode " local", disk lokal pada satu node hanya cocok untuk mode Standalone. Jika semua pod dapat mengakses sistem file bersama (misalnya, NFS), mode Cluster juga dapat menggunakan " local".
• service Mode ini menjalankan Woodpecker sebagai layanan terpisah yang dapat diskalakan secara independen dan hanya tersedia untuk penyebaran terdistribusi/kluster. Penyebaran Standalone menggunakan mode tertanam (minio atau local).

Kompatibilitas penyimpanan objek untuk storage.type=minio

Matriks berikut merangkum kompatibilitas backend penyimpanan objek yang saat ini diketahui ketika Woodpecker dikonfigurasi dengan storage.type=minio. Informasi ini didasarkan pada Diskusi GitHub #150.

Penyedia / layanan	Status	Catatan
Penyimpanan Blob Azure	Didukung	Menggunakan SDK Azure bawaan.
AWS S3	Didukung	S3 asli dengan dukungan Penulisan Bersyarat penuh.
MinIO (>= 2024-12)	Didukung	Dukungan Penulisan Bersyarat S3 yang lengkap.
Aliyun OSS	Didukung	Didukung melalui antarmuka yang kompatibel dengan S3.
Tencent COS	Didukung	Didukung melalui antarmuka yang kompatibel dengan S3.
Google Cloud Storage (GCS)	Didukung	Didukung melalui mode interoperabilitas S3.
Huawei Cloud OBS	Tidak didukung	Tidak memiliki semantik Conditional Write yang diperlukan.
VAST Data	Didukung	Telah diverifikasi oleh komunitas; hanya berfungsi dengan bucket non-versi.
Penyimpanan lain yang kompatibel dengan S3	Sebagian	Bergantung pada dukungan penuh untuk semantik Penulisan Bersyarat S3.

Catatan:

• Kompatibilitas bergantung pada dukungan SDK asli atau dukungan untuk semantik Penulisan Bersyarat S3.
• Jika Anda menghosting MinIO sendiri untuk Woodpecker, gunakan versi RELEASE.2024-12-18T13-15-44Z atau yang lebih baru.
• Matriks ini mencerminkan diskusi saat ini dan dapat berubah seiring dengan validasi dukungan backend lebih lanjut.

Panduan penerapan

Aktifkan Woodpecker untuk Kluster Milvus di Kubernetes (Milvus Operator, storage=minio)

Setelah menginstal Milvus Operator, jalankan kluster Milvus dengan Woodpecker diaktifkan menggunakan contoh resmi:

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

Contoh ini mengonfigurasi Woodpecker sebagai antrian pesan dan mengaktifkan Streaming Node. Pengaktifan pertama mungkin memerlukan waktu untuk mengunduh gambar; tunggu hingga semua pod siap:

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

Jika sudah siap, Anda akan melihat pod yang mirip dengan:

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

Jalankan perintah berikut untuk menghapus instalasi kluster Milvus.

kubectl delete milvus my-release

Jika Anda perlu menyesuaikan parameter Woodpecker, ikuti pengaturan yang dijelaskan di bagian Konfigurasi.

Mengaktifkan Woodpecker untuk Kluster Milvus di Kubernetes (Helm Chart, storage=minio)

Pertama, tambahkan dan perbarui Helm Chart Milvus seperti yang dijelaskan dalam bagian " Menjalankan Milvus di Kubernetes dengan Helm".

Kemudian lakukan deployment dengan salah satu contoh berikut:

– Deploy kluster (pengaturan yang direkomendasikan dengan Woodpecker dan Streaming Node diaktifkan):

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

– Deploy mandiri (Woodpecker diaktifkan):

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

Setelah penerapan, ikuti panduan untuk melakukan port-forward dan terhubung. Untuk menyesuaikan parameter Woodpecker, ikuti pengaturan yang dijelaskan dalam Konfigurasi.

Aktifkan Woodpecker untuk Milvus Standalone di Docker (storage=local)

Di Milvus 3.x, penerapan mandiri Docker menggunakan Woodpecker dengan sistem file lokal sebagai backend WAL-nya secara default — tidak diperlukan konfigurasi tambahan. Ikuti Jalankan Milvus di Docker:

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

Untuk menyesuaikan Woodpecker, edit berkas ` user.yaml ` yang dihasilkan setelah startup pertama, lalu jalankan perintah ` bash standalone_embed.sh restart ` untuk menerapkan perubahan (perintah ` start ` akan menghasilkan ulang berkas ` user.yaml`, jadi terapkan perubahan dengan ` restart`):

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

Aktifkan Woodpecker untuk Milvus Standalone dengan Docker Compose (storage=minio)

Ikuti panduan " Jalankan Milvus dengan Docker Compose". Contoh:

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

Aktifkan mode layanan Woodpecker untuk Kluster Milvus (Helm)

Mode layanan Woodpecker adalah fitur Milvus 3.0. Untuk penyebaran terdistribusi/kluster, Anda dapat menjalankan Woodpecker sebagai layanan khusus (pod terpisah) alih-alih tertanam di node streaming dengan mengatur ` streaming.woodpecker.embedded=false`:

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

Pengaturan ini akan menyebarkan Woodpecker sebagai StatefulSet khusus (my-release-milvus-woodpecker, 4 replika secara default) yang didukung oleh layanan tanpa antarmuka pengguna (headless), terkluster melalui mekanisme gossip pada port 18080 (layanan), 17946 (gossip), dan 9091 (metrik), dengan MinIO sebagai backend penyimpanannya. Layanan ini memerlukan kuorum sebanyak 3 node; pengaturan default 4 replika memastikan kuorum tetap terpenuhi sekaligus menoleransi kegagalan satu node, jadi jangan atur ` woodpecker.replicaCount ` di bawah 3. Kluster tersebut kemudian mencakup sekumpulan pod ` woodpecker ` terpisah:

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

Tips penyesuaian throughput

Profil throughput dan latensi Woodpecker berbeda antara mode tertanam dan mode layanan (fitur Milvus 3.0). Panduan di bawah ini disusun berdasarkan mode.

Mode tertanam

Berdasarkan tolok ukur dan batasan backend di Woodpecker, optimalkan throughput penulisan ujung ke ujung dari aspek-aspek berikut:

• Sisi penyimpanan
  • Penyimpanan objek (kompatibel dengan MinIO/S3): Tingkatkan konkurensi dan ukuran objek (hindari objek berukuran sangat kecil). Perhatikan batasan bandwidth jaringan dan bucket. Satu node MinIO pada SSD sering kali memiliki batas sekitar 100 MB/detik secara lokal; satu EC2 ke S3 dapat mencapai GB/detik.
  • Sistem file lokal/bersama (lokal): Pilih NVMe/disk cepat. Pastikan sistem file dapat menangani penulisan kecil dan latensi fsync dengan baik.
• Pengaturan Woodpecker
  • Tingkatkan nilai ` logstore.segmentSyncPolicy.maxFlushSize ` dan ` maxFlushThreads ` untuk flush yang lebih besar dan paralelisme yang lebih tinggi.
  • Sesuaikan nilai maxInterval sesuai dengan karakteristik media (tukar latensi dengan throughput dengan agregasi yang lebih panjang).
  • Untuk penyimpanan objek, pertimbangkan untuk meningkatkan nilai ` segmentRollingPolicy.maxSize ` guna mengurangi pergantian segmen.
• Sisi klien/aplikasi
  • Gunakan ukuran batch yang lebih besar dan lebih banyak penulis/klien yang berjalan secara bersamaan.
  • Kontrol waktu penyegaran/pembuatan indeks (lakukan pengelompokan sebelum memicu proses) untuk menghindari penulisan kecil yang sering.

Mode layanan (Milvus 3.0+)

Mode layanan mempertahankan throughput penulisan yang tinggi dari WAL yang didukung penyimpanan objek sekaligus menambahkan latensi rendah (lihat Latensi). Penyesuaian di sisi penyimpanan dan sisi klien di atas tetap berlaku; selain itu, karena Woodpecker berjalan sebagai layanannya sendiri, Anda dapat menskalakan kapasitas penulisan secara horizontal dengan menambahkan replika (woodpecker.replicaCount, default 4), dan penulisan mendapat manfaat dari replikasi kuorum satu-RTT serta pembacaan yang sadar topologi yang menghindari penerusan broker.

Demo penyisipan batch — gunakan perintah berikut untuk mengukur throughput penulisan:

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}")

Latensi

Mode tertanam

Woodpecker adalah WAL cloud-native yang dirancang untuk penyimpanan objek dengan kompromi antara throughput, biaya, dan latensi. Mode tertanam yang ringan memprioritaskan optimasi biaya dan throughput, karena sebagian besar skenario hanya memerlukan data ditulis dalam waktu tertentu daripada menuntut latensi rendah untuk setiap permintaan penulisan. Oleh karena itu, Woodpecker menerapkan penulisan berbatch, dengan interval default 10 ms untuk backend penyimpanan sistem berkas lokal dan 200 ms untuk backend penyimpanan sejenis MinIO. Selama operasi penulisan yang lambat, latensi maksimum sama dengan waktu interval ditambah waktu flush.

Perlu dicatat bahwa penyisipan batch dipicu tidak hanya oleh interval waktu tetapi juga oleh ukuran batch, yang secara default sebesar 2MB.

Mode Layanan (Milvus 3.0+)

Mode layanan menghadirkan latensi penulisan tingkat milidetik — setara dengan WAL disk lokal tiga replika tradisional — sambil menjaga biaya tetap rendah. Dalam penerapan tiga replika lintas AZ yang umum, latensi penulisan tetap berada dalam kisaran milidetik. Hal ini dicapai melalui:

• Penulisan kuorum satu RTT — replikasi yang digerakkan klien menyelesaikan penulisan kuorum dalam satu putaran perjalanan (round trip), dengan lalu lintas lintas-AZ dibatasi pada data setara dua replika (dibandingkan dengan lalu lintas lintas-AZ tambahan sekitar 1/3 yang umum pada replikasi berbasis broker/leader).
• Pembacaan satu lompatan yang sadar topologi — setiap pembacaan langsung menuju replika terdekat alih-alih diteruskan melalui broker, sehingga menghindari pembacaan lintas AZ acak (≈2/3 lalu lintas pembacaan lintas AZ) yang umum terjadi pada sistem berbasis broker.
• Unggahan langsung ke penyimpanan objek setelah penggantian segmen — setiap segmen melacak siklus hidupnya secara penuh dan diunggah ke penyimpanan objek segera setelah diganti, sehingga menjaga penggunaan ruang disk lokal dan biaya penyimpanan tetap rendah tanpa mengorbankan latensi.
• Tidak ada replikasi node-ke-node yang berkelanjutan — log disimpan ke penyimpanan objek yang berfungsi sebagai penyimpanan bersama, sehingga failover hanya mengunggah ulang replika yang masih berfungsi (tanpa menyalin seluruh node), penskalaan tidak dibatasi oleh bandwidth replikasi antar-node, dan penggantian node skala besar tidak menyebabkan badai replikasi.

Dalam penerapan lintas-AZ, mode layanan juga menghemat sekitar 1/3 lalu lintas jaringan tulis dan 2/3 lalu lintas jaringan baca lintas-AZ dibandingkan dengan sistem log berbasis broker. Untuk analisis desain dan biaya selengkapnya, lihat Arsitektur Woodpecker.

Untuk detail mengenai arsitektur, mode penerapan (MemoryBuffer / QuorumBuffer), dan kinerja, lihat Arsitektur Woodpecker.

Untuk detail parameter lebih lanjut, lihat repositori GitHub Woodpecker.