Woodpecker

Woodpecker est la file d’attente de messages (journal d’écriture anticipée, WAL) par défaut dans Milvus 3.x. Il s’agit d’un WAL natif du cloud conçu pour le stockage d’objets, offrant un débit élevé, une faible charge opérationnelle et une évolutivité transparente. Pour plus de détails sur l’architecture et les tests de performance, consultez la page Woodpecker.

Présentation

• Dans Milvus 3.x, Woodpecker est le WAL/la file d’attente de messages par défaut, assurant les écritures ordonnées et la récupération en tant que service de journalisation. Aucun service externe de file d’attente de messages (tel que Pulsar ou Kafka) n’est requis.
• Woodpecker peut s’exécuter de manière intégrée au nœud Milvus/streaming (par défaut), ou en tant que service dédié avec ses propres pods (distribution/cluster uniquement).
• Il prend en charge trois modes d’ storage.type: le stockage d’objets (minio, par défaut), le système de fichiers local (local) et le service dédié service. Voir Modes de déploiement.

Démarrage rapide

Pour activer Woodpecker, définissez le type de MQ sur Woodpecker :

mq:
  type: woodpecker

Remarque : le changement d’ mq.type e pour un cluster en cours d’exécution est une opération de mise à niveau. Suivez attentivement la procédure de mise à niveau et effectuez des tests sur un nouveau cluster avant de basculer vers l’environnement de production.

Configuration

Vous trouverez ci-dessous le bloc de configuration complet de Woodpecker (modifiez le fichier milvus.yaml ou remplacez-le dans 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.

Remarques importantes :

• woodpecker.meta
  • type: Actuellement, seul etcd est pris en charge. Réutilisez le même etcd que Milvus pour stocker les métadonnées légères.
  • prefix: le préfixe des clés pour les métadonnées. Par défaut : woodpecker.
• woodpecker.client
  • Contrôle le comportement d’ajout, de rotation et d’audit des segments côté client afin d’équilibrer le débit et la latence de bout en bout.
• woodpecker.logstore
  • Contrôle les politiques de synchronisation, de vidage, de compactage et de lecture des segments de journal. Il s'agit des principaux paramètres permettant d'ajuster le débit et la latence.
• woodpecker.storage
  • type: minio pour le stockage d’objets compatible MinIO/S3 (MinIO/S3/GCS/OSS, etc.) ; local pour les systèmes de fichiers locaux/partagés.
  • rootPath: chemin racine du backend de stockage (applicable pour local; avec minio, les chemins sont déterminés par le bucket/préfixe).

Modes de déploiement

Woodpecker prend en charge trois modes d’ storage.type:

storage.type	Fonctionnement de Woodpecker	Backend WAL	Milvus autonome	Milvus distribué (cluster)
minio (par défaut)	Intégré au nœud Milvus/streaming	Stockage objet (compatible MinIO/S3)	Prise en charge	Prise en charge
local	Intégré au nœud Milvus/streaming	Système de fichiers local	Pris en charge	Limité (tous les nœuds ont besoin d’un système de fichiers partagé, par exemple NFS)
service	Service Woodpecker dédié (ses propres pods)	Stockage objet (compatible MinIO/S3)	Non pris en charge	Prise en charge

Remarques :

• Avec minio, Woodpecker partage le même stockage d’objets que Milvus (MinIO/S3/GCS/OSS, etc.).
• Avec le mode « local », un disque local à nœud unique ne convient qu’au mode « Standalone ». Si tous les pods peuvent accéder à un système de fichiers partagé (par exemple, NFS), le mode « Cluster » peut également utiliser le mode « local ».
• service Ce mode exécute Woodpecker en tant que service distinct et évolutif de manière indépendante ; il n’est disponible que pour les déploiements distribués/en cluster. Les déploiements autonomes utilisent les modes intégrés (minio ou local).

Compatibilité avec le stockage objet pour storage.type=minio

Le tableau suivant résume la compatibilité actuellement connue des backends de stockage objet lorsque Woodpecker est configuré avec storage.type=minio. Ces informations sont basées sur la discussion GitHub n° 150.

Fournisseur / service	Statut	Remarques
Azure Blob Storage	Pris en charge	Utilise le SDK natif d'Azure.
AWS S3	Pris en charge	S3 natif avec prise en charge complète de l'écriture conditionnelle.
MinIO (>= 2024-12)	Pris en charge	Prise en charge complète de l'écriture conditionnelle S3.
Aliyun OSS	Prise en charge	Prise en charge via son interface compatible S3.
Tencent COS	Prise en charge	Prise en charge via son interface compatible S3.
Google Cloud Storage (GCS)	Prise en charge	Pris en charge via le mode d'interopérabilité S3.
Huawei Cloud OBS	Non pris en charge	Ne dispose pas de la sémantique d'écriture conditionnelle requise.
VAST Data	Pris en charge	Vérifié par la communauté ; fonctionne uniquement avec des compartiments non versionnés.
Autres solutions de stockage compatibles S3	Partiel	Dépend de la prise en charge complète de la sémantique d'écriture conditionnelle S3.

Remarques :

• La compatibilité dépend de la prise en charge native par le SDK ou de la prise en charge de la sémantique d'écriture conditionnelle S3.
• Si vous hébergez vous-même MinIO pour Woodpecker, utilisez la version RELEASE.2024-12-18T13-15-44Z ou une version ultérieure.
• Ce tableau reflète l'état actuel des discussions et est susceptible d'évoluer à mesure que la prise en charge du backend sera validée.

Guides de déploiement

Activer Woodpecker pour un cluster Milvus sur Kubernetes (Milvus Operator, storage=minio)

Après avoir installé Milvus Operator, démarrez un cluster Milvus avec Woodpecker activé à l’aide de l’exemple officiel :

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

Cet exemple configure Woodpecker comme file d’attente de messages et active le nœud de streaming. Le premier démarrage peut prendre un certain temps pour récupérer les images ; attendez que tous les pods soient prêts :

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

Une fois prêt, vous devriez voir des pods similaires à ceux-ci :

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

Exécutez la commande suivante pour désinstaller le cluster Milvus.

kubectl delete milvus my-release

Si vous devez ajuster les paramètres de Woodpecker, suivez les instructions décrites dans la section Configuration.

Activer Woodpecker pour un cluster Milvus sur Kubernetes (Helm Chart, storage=minio)

Commencez par ajouter et mettre à jour le Helm Chart Milvus comme décrit dans la section « Exécuter Milvus sur Kubernetes avec Helm ».

Déployez ensuite à l’aide de l’un des exemples suivants :

– Déploiement en cluster (paramètres recommandés avec Woodpecker et Streaming Node activés) :

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

– Déploiement autonome (Woodpecker activé) :

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

Après le déploiement, suivez la documentation pour configurer la redirection de port et vous connecter. Pour ajuster les paramètres de Woodpecker, suivez les instructions décrites dans la section « Configuration ».

Activer Woodpecker pour Milvus autonome dans Docker (storage=local)

Dans Milvus 3.x, le déploiement autonome sous Docker utilise par défaut Woodpecker avec le système de fichiers local comme backend WAL — aucune configuration supplémentaire n’est requise. Suivez les instructions de la section « Exécuter Milvus dans 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

Pour optimiser Woodpecker, modifiez le fichier généré ` user.yaml ` après le premier démarrage, puis exécutez ` bash standalone_embed.sh restart ` pour appliquer les modifications (une nouvelle commande ` start ` régénère le fichier ` user.yaml` ; appliquez donc les modifications avec ` restart` ) :

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

Activer Woodpecker pour Milvus Standalone avec Docker Compose (storage=minio)

Suivez les instructions de la section « Exécuter Milvus avec Docker Compose ». Exemple :

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

Activer le mode service de Woodpecker pour un cluster Milvus (Helm)

Le mode service de Woodpecker est une fonctionnalité de Milvus 3.0. Pour les déploiements distribués/en cluster, vous pouvez exécuter Woodpecker en tant que service dédié (pods séparés) plutôt que de l’intégrer au nœud de streaming en configurant ` 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

Cela déploie Woodpecker sous la forme d’un StatefulSet dédié (my-release-milvus-woodpecker, 4 répliques par défaut) mis en avant par un service sans interface utilisateur, formant un cluster de type « gossip » sur les ports 18080 (service), 17946 (gossip) et 9091 (métriques), avec MinIO comme backend de stockage. Le service nécessite un quorum de 3 nœuds ; la valeur par défaut de 4 répliques permet de maintenir le quorum tout en tolérant la défaillance d’un seul nœud. Ne définissez donc pas woodpecker.replicaCount sur une valeur inférieure à 3. Le cluster comprend ensuite un ensemble distinct de pods woodpecker:

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

Conseils d’optimisation du débit

Les performances en termes de débit et de latence de Woodpecker diffèrent selon qu’il est utilisé en mode intégré ou en mode service (une fonctionnalité de Milvus 3.0). Les recommandations ci-dessous sont classées par mode.

Mode intégré

En vous basant sur les tests de performance et les limites du backend de Woodpecker, optimisez le débit d’écriture de bout en bout en tenant compte des aspects suivants :

• Côté stockage
  • Stockage objet (compatible MinIO/S3): augmentez le nombre de requêtes simultanées et la taille des objets (évitez les objets de très petite taille). Surveillez les limites de bande passante du réseau et des compartiments. Un seul nœud MinIO sur SSD atteint souvent un plafond d’environ 100 Mo/s en local ; une seule connexion EC2 vers S3 peut atteindre plusieurs Go/s.
  • Systèmes de fichiers locaux/partagés (locaux): privilégiez les disques NVMe ou rapides. Assurez-vous que le système de fichiers gère correctement les petites écritures et la latence de fsync.
• Paramètres de Woodpecker
  • Augmentez les paramètres « logstore.segmentSyncPolicy.maxFlushSize » et « maxFlushThreads » pour obtenir des vidages plus volumineux et un parallélisme plus élevé.
  • Réglez maxInterval en fonction des caractéristiques du support (compromis entre latence et débit avec une agrégation plus longue).
  • Pour le stockage objet, envisagez d’augmenter la valeur de segmentRollingPolicy.maxSize afin de réduire les changements de segment.
• Côté client/application
  • Utilisez des tailles de lots plus importantes et un plus grand nombre d’écriteurs/clients simultanés.
  • Contrôlez le moment de l’actualisation/de la construction de l’index (regroupez les lots avant de déclencher l’opération) pour éviter les petites écritures fréquentes.

Mode Service (Milvus 3.0+)

Le mode service conserve le débit d’écriture élevé d’un WAL s’appuyant sur un stockage objet tout en offrant une faible latence (voir Latence). Les réglages côté stockage et côté client mentionnés ci-dessus restent d'application ; de plus, comme Woodpecker s'exécute en tant que service autonome, vous pouvez faire évoluer horizontalement la capacité d'écriture en ajoutant des répliques (woodpecker.replicaCount, 4 par défaut), et les écritures bénéficient d'une réplication à quorum en un seul RTT ainsi que de lectures tenant compte de la topologie qui évitent le transfert par le courtier.

Démonstration d’insertion par lots — utilisez ce qui suit pour mesurer le débit d’écriture :

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

Latence

Mode intégré

Woodpecker est un WAL natif du cloud conçu pour le stockage objet, qui établit un compromis entre débit, coût et latence. Le mode intégré, léger, privilégie l’optimisation des coûts et du débit, car la plupart des scénarios exigent uniquement que les données soient écrites dans un délai donné, plutôt qu’une faible latence pour chaque requête d’écriture. Par conséquent, Woodpecker utilise des écritures par lots, avec des intervalles par défaut de 10 ms pour les backends de stockage sur système de fichiers local et de 200 ms pour les backends de stockage de type MinIO. Lors d’opérations d’écriture lentes, la latence maximale est égale à la durée de l’intervalle plus le temps de vidage.

Notez que l’insertion par lots est déclenchée non seulement par des intervalles de temps, mais aussi par la taille des lots, qui est de 2 Mo par défaut.

Mode « Service » (Milvus 3.0+)

Le mode Service offre une latence d’écriture de l’ordre de la milliseconde — comparable à celle d’un WAL traditionnel à trois répliques sur disque local — tout en maintenant des coûts faibles. Dans un déploiement typique à trois répliques inter-zones de disponibilité (AZ), la latence d’écriture reste de l’ordre de la milliseconde. Ce résultat est obtenu grâce à :

• Des écritures à quorum en un seul RTT — la réplication pilotée par le client effectue une écriture à quorum en un seul aller-retour, le trafic inter-zones étant limité à l’équivalent des données de deux répliques (contre environ un tiers de trafic inter-zones supplémentaire, typique de la réplication basée sur un courtier ou un leader).
• Lectures en un seul saut tenant compte de la topologie — chaque lecture est dirigée directement vers la réplique la plus proche au lieu d’être acheminée via un courtier, ce qui évite les lectures aléatoires inter-zones de disponibilité (environ les deux tiers du trafic de lecture inter-zones) propres aux systèmes basés sur un courtier.
• Téléchargement immédiat vers le stockage objet après le roulement d’un segment — chaque segment suit l’intégralité de son cycle de vie et est téléchargé vers le stockage objet dès son roulement, ce qui permet de maintenir un encombrement minimal sur le disque local et de faibles coûts de stockage sans compromettre la latence.
• Pas de réplication continue de nœud à nœud — les journaux sont conservés dans le stockage objet qui fait office de stockage partagé ; ainsi, en cas de basculement, seules les répliques survivantes sont réimportées (pas de copie intégrale du nœud), la scalabilité n’est pas limitée par la bande passante de réplication inter-nœuds, et le remplacement de nœuds à grande échelle ne provoque pas de « tempêtes de réplication ».

Dans les déploiements inter-zones de disponibilité (AZ), le mode service permet également d’économiser environ un tiers du trafic réseau inter-AZ en écriture et deux tiers en lecture par rapport aux systèmes de journaux basés sur un courtier. Pour une analyse complète de la conception et des coûts, consultez l’architecture Woodpecker.

Pour plus de détails sur l’architecture, les modes de déploiement (MemoryBuffer / QuorumBuffer) et les performances, consultez l’architecture Woodpecker.

Pour plus de détails sur les paramètres, consultez le dépôt GitHub de Woodpecker.