Usar o WoodpeckerCompatible with Milvus 2.6.x

Este guia explica como habilitar e usar o Woodpecker como Write-Ahead Log (WAL) no Milvus 2.6.x. O Woodpecker é um WAL nativo da nuvem projetado para armazenamento de objetos, oferecendo alta taxa de transferência, baixa sobrecarga operacional e escalabilidade contínua. Para obter detalhes de arquitetura e benchmark, consulte Woodpecker.

Visão geral

• A partir do Milvus 2.6, o Woodpecker é um WAL opcional que fornece gravações ordenadas e recuperação como o serviço de registro.
• Como uma opção de fila de mensagens, ele se comporta de forma semelhante ao Pulsar/Kafka e pode ser ativado via configuração.
• Dois backends de armazenamento são suportados: sistema de arquivos local (local) e armazenamento de objetos (minio/S3-compatível).

Início rápido

Para ativar o Woodpecker, defina o tipo de MQ como Woodpecker:

mq:
  type: woodpecker

Nota: Mudar mq.type para um cluster em execução é uma operação de atualização. Siga o procedimento de atualização cuidadosamente e valide-o num novo cluster antes de mudar para produção.

Configuração

Abaixo está o bloco de configuração completo do Woodpecker (edite milvus.yaml ou substitua em 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.

Key notes:

• woodpecker.meta
  • tipo: Atualmente, apenas etcd é suportado. Reutilize o mesmo etcd do Milvus para armazenar metadados leves.
  • prefixo: O prefixo da chave para os metadados. Predefinição: woodpecker.
• woodpecker.client
  • Controla o comportamento de anexação/rolagem/audição de segmentos no lado do cliente para equilibrar a taxa de transferência e a latência de ponta a ponta.
• woodpecker.logstore
  • Controla as políticas de sincronização/flush/compactação/leitura para segmentos de log. Esses são os principais botões para ajuste de taxa de transferência/latência.
• woodpecker.storage
  • type: minio para armazenamento de objectos compatível com MinIO/S3 (MinIO/S3/GCS/OSS, etc.); local para sistemas de ficheiros locais/partilhados.
  • rootPath: Caminho da raiz para o backend de armazenamento (efetivo para local; com minio, os caminhos são ditados por bucket/prefixo).

Modos de implantação

Milvus suporta os modos Standalone e Cluster. Matriz de suporte do backend de armazenamento Woodpecker:

	storage.type=local	storage.type=minio
Milvus Standalone	Suportado	Suportado
Milvus Cluster	Limitado (precisa de FS partilhado)	Suportado

Notas:

• Com minio, o Woodpecker partilha o mesmo armazenamento de objectos com o Milvus (MinIO/S3/GCS/OSS, etc.).
• Com local, um disco local de nó único só é adequado para Standalone. Se todos os pods puderem acessar um sistema de arquivos compartilhado (por exemplo, NFS), o modo Cluster também poderá usar local.

Compatibilidade de armazenamento de objectos para storage.type=minio

A seguinte matriz resume a compatibilidade atualmente conhecida dos backends de armazenamento de objetos quando o Woodpecker está configurado com storage.type=minio. Essas informações são baseadas na Discussão #150 do GitHub.

Provedor / serviço	Status	Observações
Armazenamento de Blobs do Azure	Suportado	Usa o SDK nativo do Azure.
AWS S3	Suportado	S3 nativo com suporte completo de escrita condicional.
MinIO (>= 2024-12)	Suportado	Suporte completo para escrita condicional no S3.
Aliyun OSS	Suportado	Suportado através da sua interface compatível com S3.
Tencent COS	Suportado	Suportado através da sua interface compatível com S3.
Armazenamento em nuvem do Google (GCS)	Suportado	Suportado através do modo de interoperabilidade S3.
OBS da Huawei Cloud	Não suportado	Não possui a semântica de escrita condicional necessária.
Dados VAST	Suportado	Verificado pela comunidade; funciona apenas com buckets não versionados.
Outro armazenamento compatível com S3	Parcial	Depende do suporte total à semântica de gravação condicional do S3.

Observações:

• A compatibilidade depende do suporte nativo ao SDK ou do suporte à semântica de gravação condicional do S3.
• Se você auto-hospedar o MinIO para o Woodpecker, use RELEASE.2024-12-18T13-15-44Z ou posterior.
• Esta matriz reflecte a discussão atual e pode evoluir à medida que o suporte de backend é validado.

Guias de implantação

Habilitar o Woodpecker para um Cluster Milvus no Kubernetes (Operador Milvus, storage=minio)

Depois de instalar o Milvus Operator, inicie um cluster Milvus com o Woodpecker habilitado usando a amostra oficial:

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

Este exemplo configura o Woodpecker como a fila de mensagens e habilita o nó de streaming. A primeira inicialização pode levar algum tempo para puxar imagens; espere até que todos os pods estejam prontos:

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

Quando estiver pronto, você deverá ver pods semelhantes a:

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

Execute o seguinte comando para desinstalar o cluster Milvus.

kubectl delete milvus my-release

Se você precisar ajustar os parâmetros do Woodpecker, siga as configurações descritas em message storage config.

Habilitar o Woodpecker para um cluster do Milvus no Kubernetes (Helm Chart, storage=minio)

Primeiro, adicione e atualize o gráfico do Milvus Helm conforme descrito em Executar o Milvus no Kubernetes com o Helm.

Em seguida, implante com um dos exemplos a seguir:

- Implantação de cluster (configurações recomendadas com Woodpecker e Streaming Node ativados):

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

- Implantação autônoma (Woodpecker ativado):

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

Após a implantação, siga os documentos para fazer o encaminhamento de porta e conectar-se. Para ajustar os parâmetros do Woodpecker, siga as configurações descritas na configuração do armazenamento de mensagens.

Habilitar o Woodpecker para o Milvus Standalone no Docker (storage=local)

Siga Executar o Milvus no Docker. Exemplo:

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

Para alterar ainda mais as configurações do Woodpecker, atualize user.yaml e execute bash standalone_embed.sh restart.

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

Siga Executar o Milvus com o Docker Compose. Exemplo:

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

Dicas de ajuste de taxa de transferência

Com base nos benchmarks e nos limites de back-end no Woodpecker, otimize a taxa de transferência de gravação de ponta a ponta nos seguintes aspectos:

• Lado do armazenamento
  • Armazenamento de objetos (compatível com minio/S3): Aumente a concorrência e o tamanho do objeto (evite objetos minúsculos). Observe os limites de largura de banda da rede e do bucket. Um único nó MinIO em SSD geralmente limita cerca de 100 MB/s localmente; um único EC2 para S3 pode atingir GB/s.
  • Sistemas de arquivos locais/compartilhados (local): Prefira NVMe/discos rápidos. Certifique-se de que o FS lida bem com pequenas gravações e latência de fsync.
• Botões do Woodpecker
  • Aumente logstore.segmentSyncPolicy.maxFlushSize e maxFlushThreads para obter maiores descargas e maior paralelismo.
  • Ajuste maxInterval de acordo com as caraterísticas do meio (troque a latência pela taxa de transferência com agregação mais longa).
  • Para o armazenamento de objectos, considere aumentar segmentRollingPolicy.maxSize para reduzir as trocas de segmentos.
• Lado do cliente/aplicação
  • Utilizar tamanhos de lote maiores e mais escritores/clientes simultâneos.
  • Controlar o tempo de atualização/criação de índices (aumentar o lote antes de o ativar) para evitar pequenas escritas frequentes.

Demonstração de inserção de lote

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

Latência

O Woodpecker é um WAL nativo da nuvem projetado para armazenamento de objetos com compensações entre taxa de transferência, custo e latência. O modo embutido leve suportado atualmente prioriza a otimização de custo e taxa de transferência, já que a maioria dos cenários exige apenas que os dados sejam gravados dentro de um determinado tempo, em vez de exigir baixa latência para solicitações de gravação individuais. Portanto, o Woodpecker emprega gravações em lote, com intervalos padrão de 10ms para backends de armazenamento de sistemas de arquivos locais e 200ms para backends de armazenamento do tipo MinIO. Durante operações de escrita lentas, a latência máxima é igual ao tempo de intervalo mais o tempo de descarga.

Observe que a inserção de lotes é acionada não apenas por intervalos de tempo, mas também pelo tamanho do lote, cujo padrão é 2 MB.

Para obter detalhes sobre a arquitetura, modos de implantação (MemoryBuffer / QuorumBuffer) e desempenho, consulte Arquitetura do Woodpecker.

Para obter mais detalhes sobre os parâmetros, consulte o repositório do Woodpecker no GitHub.