Woodpecker

Woodpecker es la cola de mensajes predeterminada (registro de escritura anticipada, WAL) en Milvus 3.x. Se trata de un WAL nativo de la nube diseñado para el almacenamiento de objetos, que ofrece un alto rendimiento, una baja sobrecarga operativa y una escalabilidad fluida. Para obtener más detalles sobre la arquitectura y las pruebas de rendimiento, consulta Woodpecker.

Descripción general

• En Milvus 3.x, Woodpecker es el WAL/cola de mensajes predeterminado, que proporciona escrituras ordenadas y recuperación como servicio de registro. No se requiere ningún servicio externo de colas de mensajes (como Pulsar o Kafka).
• Woodpecker puede ejecutarse integrado en el nodo Milvus/streaming (por defecto) o como un servicio dedicado con sus propios pods (solo en modo distribuido/clúster).
• Admite tres modos de « storage.type »: almacenamiento de objetos (minio, el predeterminado), sistema de archivos local (local) y el modo dedicado service. Consulte Modos de implementación.

Inicio rápido

Para habilitar Woodpecker, configura el tipo de MQ como Woodpecker:

mq:
  type: woodpecker

Nota: Cambiar « mq.type » en un clúster en ejecución es una operación de actualización. Sigue el procedimiento de actualización cuidadosamente y comprueba que todo funciona correctamente en un clúster nuevo antes de realizar el cambio en el entorno de producción.

Configuración

A continuación se muestra el bloque de configuración completo de Woodpecker (edita milvus.yaml o sobrescríbelo en 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.

Notas importantes:

• woodpecker.meta
  • type: Actualmente solo se admite etcd. Reutiliza el mismo etcd que Milvus para almacenar metadatos ligeros.
  • prefijo: El prefijo de clave para los metadatos. Por defecto: woodpecker.
• woodpecker.client
  • Controla el comportamiento de adición, rotación y auditoría de segmentos en el lado del cliente para equilibrar el rendimiento y la latencia de extremo a extremo.
• woodpecker.logstore
  • Controla las políticas de sincronización, vaciado, compactación y lectura de los segmentos de registro. Estos son los principales parámetros para ajustar el rendimiento y la latencia.
• woodpecker.storage
  • type: minio para almacenamiento de objetos compatible con MinIO/S3 (MinIO/S3/GCS/OSS, etc.); local para sistemas de archivos locales o compartidos.
  • rootPath: Ruta raíz del backend de almacenamiento (aplicable a local; con minio, las rutas vienen determinadas por el bucket o el prefijo).

Modos de implementación

Woodpecker admite tres modos de storage.type:

storage.type	Cómo funciona Woodpecker	Backend WAL	Milvus autónomo	Milvus distribuido (clúster)
minio (por defecto)	Integrado en el nodo Milvus/streaming	Almacenamiento de objetos (compatible con MinIO/S3)	Compatible	Compatible
local	Integrado en el nodo Milvus/streaming	Sistema de archivos local	Compatible	Limitado (todos los nodos necesitan un sistema de archivos compartido, p. ej., NFS)
service	Servicio Woodpecker dedicado (con sus propios pods)	Almacenamiento de objetos (compatible con MinIO/S3)	No compatible	Compatible

Notas:

• Con « minio », Woodpecker comparte el mismo almacenamiento de objetos que Milvus (MinIO/S3/GCS/OSS, etc.).
• Con « local », un disco local de un solo nodo solo es adecuado para el modo autónomo. Si todos los pods pueden acceder a un sistema de archivos compartido (por ejemplo, NFS), el modo de clúster también puede utilizar « local ».
• service Este modo ejecuta Woodpecker como un servicio independiente y escalable por sí mismo, y solo está disponible para implementaciones distribuidas o en clúster. Las implementaciones autónomas utilizan los modos integrados (minio o local).

Compatibilidad con el almacenamiento de objetos para storage.type=minio

La siguiente matriz resume la compatibilidad actualmente conocida de los backends de almacenamiento de objetos cuando Woodpecker se configura con storage.type=minio. Esta información se basa en la discusión n.º 150 de GitHub.

Proveedor / servicio	Estado	Notas
Almacenamiento de blobs de Azure	Compatible	Utiliza el SDK nativo de Azure.
AWS S3	Compatible	S3 nativo con compatibilidad total con la escritura condicional.
MinIO (>= 2024-12)	Compatible	Compatibilidad total con la escritura condicional de S3.
Aliyun OSS	Compatible	Compatible a través de su interfaz compatible con S3.
Tencent COS	Compatible	Compatible a través de su interfaz compatible con S3.
Google Cloud Storage (GCS)	Compatible	Compatible a través del modo de interoperabilidad con S3.
Huawei Cloud OBS	No compatible	Carece de la semántica de escritura condicional necesaria.
VAST Data	Compatible	Verificado por la comunidad; solo funciona con buckets sin versiones.
Otros almacenes compatibles con S3	Parcial	Depende de la compatibilidad total con la semántica de escritura condicional de S3.

Notas:

• La compatibilidad depende de la compatibilidad nativa con el SDK o de la compatibilidad con la semántica de escritura condicional de S3.
• Si alojas tú mismo MinIO para Woodpecker, utiliza la versión RELEASE.2024-12-18T13-15-44Z o posterior.
• Esta matriz refleja el estado actual de las conversaciones y puede evolucionar a medida que se valide más a fondo la compatibilidad del backend.

Guías de implementación

Habilitar Woodpecker para un clúster de Milvus en Kubernetes (Milvus Operator, storage=minio)

Tras instalar el Milvus Operator, inicia un clúster de Milvus con Woodpecker habilitado utilizando el ejemplo oficial:

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

Este ejemplo configura Woodpecker como cola de mensajes y habilita el nodo de streaming. El primer arranque puede tardar un tiempo en descargar las imágenes; espera hasta que todos los pods estén listos:

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

Cuando esté listo, deberías ver pods similares a estos:

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

Ejecuta el siguiente comando para desinstalar el clúster de Milvus.

kubectl delete milvus my-release

Si necesitas ajustar los parámetros de Woodpecker, sigue la configuración descrita en «Configuración».

Habilitar Woodpecker para un clúster de Milvus en Kubernetes (Helm Chart, storage=minio)

En primer lugar, añade y actualiza el gráfico Helm de Milvus tal y como se describe en «Ejecutar Milvus en Kubernetes con Helm».

A continuación, realiza la implementación siguiendo uno de los ejemplos siguientes:

– Implementación en clúster (configuración recomendada con Woodpecker y Streaming Node habilitados):

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

– Despliegue independiente (Woodpecker habilitado):

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

Tras el despliegue, sigue la documentación para realizar el reenvío de puertos y conectarte. Para ajustar los parámetros de Woodpecker, sigue la configuración descrita en «Configuración».

Habilitar Woodpecker para Milvus autónomo en Docker (storage=local)

En Milvus 3.x, la implementación autónoma en Docker utiliza Woodpecker con el sistema de archivos local como backend de WAL de forma predeterminada; no se requiere ninguna configuración adicional. Sigue las instrucciones de «Ejecutar Milvus en 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

Para ajustar Woodpecker, edita el archivo generado « user.yaml » tras el primer inicio y ejecuta « bash standalone_embed.sh restart » para aplicar los cambios (un nuevo « start » regenera « user.yaml », por lo que debes aplicar los cambios con « restart »):

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

Habilitar Woodpecker para Milvus Standalone con Docker Compose (storage=minio)

Sigue las instrucciones de «Ejecutar Milvus con Docker Compose». Ejemplo:

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

Habilitar el modo de servicio de Woodpecker para un clúster de Milvus (Helm)

El modo de servicio de Woodpecker es una característica de Milvus 3.0. Para implementaciones distribuidas o en clúster, puede ejecutar Woodpecker como un servicio dedicado (pods independientes) en lugar de integrado en el nodo de streaming configurando ` 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

Esto implementa Woodpecker como un StatefulSet dedicado (my-release-milvus-woodpecker, 4 réplicas por defecto) respaldado por un servicio sin interfaz gráfica, agrupado mediante el protocolo «gossip» en los puertos 18080 (servicio), 17946 (gossip) y 9091 (métricas), con MinIO como backend de almacenamiento. El servicio necesita un quórum de 3 nodos; el valor predeterminado de 4 réplicas mantiene el quórum al tiempo que tolera el fallo de un único nodo, por lo que no se debe establecer woodpecker.replicaCount por debajo de 3. El clúster incluye entonces un conjunto independiente de pods woodpecker:

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

Consejos para optimizar el rendimiento

El perfil de rendimiento y latencia de Woodpecker difiere entre el modo integrado y el modo de servicio (una característica de Milvus 3.0). Las siguientes recomendaciones se organizan por modo.

Modo integrado

Basándote en las pruebas de rendimiento y los límites del backend de Woodpecker, optimiza el rendimiento de escritura de extremo a extremo teniendo en cuenta los siguientes aspectos:

• Lado del almacenamiento
  • Almacenamiento de objetos (compatible con MinIO/S3): Aumenta la concurrencia y el tamaño de los objetos (evita los objetos muy pequeños). Presta atención a los límites de ancho de banda de la red y del bucket. Un único nodo MinIO en SSD suele tener un límite de unos 100 MB/s a nivel local; un único EC2 conectado a S3 puede alcanzar GB/s.
  • Sistemas de archivos locales/compartidos (locales): da preferencia a NVMe o discos rápidos. Asegúrate de que el sistema de archivos gestione bien las escrituras pequeñas y la latencia de fsync.
• Parámetros de Woodpecker
  • Aumenta los valores de « logstore.segmentSyncPolicy.maxFlushSize » y « maxFlushThreads » para obtener vaciados más grandes y un mayor paralelismo.
  • Ajuste maxInterval según las características del soporte (sacrifique latencia a cambio de rendimiento con una agregación más larga).
  • En el caso del almacenamiento de objetos, plantéate aumentar segmentRollingPolicy.maxSize para reducir los cambios de segmento.
• Lado del cliente/de la aplicación
  • Utilice lotes de mayor tamaño y más escritores/clientes simultáneos.
  • Controle el momento de la actualización o la creación del índice (agrupe los datos antes de activarlo) para evitar pequeñas escrituras frecuentes.

Modo de servicio (Milvus 3.0+)

El modo de servicio mantiene el alto rendimiento de escritura de un WAL respaldado por almacenamiento de objetos, al tiempo que añade baja latencia (véase «Latencia»). El ajuste tanto en el lado del almacenamiento como en el del cliente descrito anteriormente sigue siendo válido; además, dado que Woodpecker se ejecuta como un servicio independiente, la capacidad de escritura se escala horizontalmente añadiendo réplicas (woodpecker.replicaCount, 4 por defecto), y las escrituras se benefician de la replicación por quórum de un RTT y de lecturas que tienen en cuenta la topología, lo que evita el reenvío por parte del broker.

Demostración de inserción por lotes: utiliza lo siguiente para medir el rendimiento de escritura:

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

Latencia

Modo integrado

Woodpecker es un WAL nativo de la nube diseñado para el almacenamiento de objetos, que ofrece un equilibrio entre rendimiento, coste y latencia. El modo integrado, de bajo peso, da prioridad a la optimización del coste y el rendimiento, ya que la mayoría de los escenarios solo requieren que los datos se escriban en un plazo determinado, en lugar de exigir una baja latencia para las solicitudes de escritura individuales. Por lo tanto, Woodpecker emplea escrituras por lotes, con intervalos predeterminados de 10 ms para backends de almacenamiento en sistemas de archivos locales y de 200 ms para backends de almacenamiento tipo MinIO. Durante las operaciones de escritura lentas, la latencia máxima es igual al tiempo del intervalo más el tiempo de vaciado.

Cabe señalar que la inserción por lotes se activa no solo por intervalos de tiempo, sino también por el tamaño del lote, cuyo valor por defecto es de 2 MB.

Modo de servicio (Milvus 3.0+)

El modo de servicio ofrece una latencia de escritura del orden de los milisegundos —del mismo orden que un WAL tradicional en disco local con tres réplicas— al tiempo que mantiene bajos los costes. En una implementación típica con tres réplicas entre zonas de disponibilidad (AZ), la latencia de escritura se mantiene en el rango de los milisegundos. Esto se consigue mediante:

• Escrituras de quórum en un solo RTT: la replicación impulsada por el cliente completa una escritura de quórum en un solo viaje de ida y vuelta, con el tráfico entre zonas fijado en el volumen de datos equivalente a dos réplicas (frente al tráfico adicional entre zonas de aproximadamente un tercio, típico de la replicación basada en brokers o líderes).
• Lecturas de un solo salto que tienen en cuenta la topología: cada lectura se dirige directamente a la réplica más cercana en lugar de reenviarse a través de un broker, lo que evita las lecturas aleatorias entre zonas (aproximadamente dos tercios del tráfico de lectura entre zonas) propias de los sistemas basados en brokers.
• Carga inmediata al almacenamiento de objetos tras el desplazamiento de segmentos: cada segmento realiza un seguimiento de todo su ciclo de vida y se carga al almacenamiento de objetos tan pronto como se desplaza, lo que mantiene bajo el espacio ocupado en el disco local y el coste de almacenamiento sin sacrificar la latencia.
• No hay replicación continua de nodo a nodo: los registros persisten en el almacenamiento de objetos, que actúa como almacenamiento compartido, por lo que la conmutación por error solo vuelve a cargar las réplicas supervivientes (sin copia completa del nodo); el escalado no está limitado por el ancho de banda de replicación entre nodos, y la sustitución de nodos a gran escala no provoca «tormentas de replicación».

En implementaciones entre zonas de disponibilidad (AZ), el modo de servicio también ahorra aproximadamente un tercio del tráfico de red de escritura y dos tercios del de lectura entre zonas de disponibilidad, en comparación con los sistemas de registros basados en brokers. Para consultar el análisis completo del diseño y los costes, véase Arquitectura de Woodpecker.

Para obtener más detalles sobre la arquitectura, los modos de implementación (MemoryBuffer / QuorumBuffer) y el rendimiento, consulta la arquitectura de Woodpecker.

Para obtener más detalles sobre los parámetros, consulte el repositorio de GitHub de Woodpecker.