Woodpecker

Woodpecker — это очередь сообщений по умолчанию (журнал предварительной записи, WAL) в Milvus 3.x. Это облачный WAL, разработанный специально для объектного хранилища, который обеспечивает высокую пропускную способность, низкие эксплуатационные затраты и плавную масштабируемость. Подробную информацию об архитектуре и результатах тестирования см. в разделе «Woodpecker».

Обзор

• В Milvus 3.x Woodpecker является WAL/очередью сообщений по умолчанию, обеспечивающей упорядоченную запись и восстановление в качестве службы ведения журнала. Внешняя служба очереди сообщений (такая как Pulsar или Kafka) не требуется.
• Woodpecker может работать встроенным в узел Milvus/streaming (по умолчанию) или в качестве отдельного сервиса со своими собственными под (только в распределённом режиме/кластере).
• Он поддерживает три режима хранения данных ( storage.type ): объектное хранилище (minio, по умолчанию), локальную файловую систему (local) и выделенное хранилище ( service). См. раздел «Режимы развертывания».

Быстрый старт

Чтобы включить 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 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.

Ключевые моменты:

• woodpecker.meta
  • type: В настоящее время поддерживается только etcd. Используйте тот же etcd, что и для Milvus, для хранения облегчённых метаданных.
  • prefix: Префикс ключей для метаданных. По умолчанию: woodpecker.
• woodpecker.client
  • Управляет поведением добавления/последовательного обновления/аудита сегментов на стороне клиента для обеспечения баланса между пропускной способностью и сквозной задержкой.
• woodpecker.logstore
  • Управляет политиками синхронизации, сброса, уплотнения и чтения для сегментов журнала. Это основные параметры для настройки пропускной способности и задержки.
• woodpecker.storage
  • type: minio для объектного хранилища, совместимого с MinIO/S3 (MinIO/S3/GCS/OSS и т. д.); local для локальных/общих файловых систем.
  • rootPath: корневой путь для бэкэнда хранилища (действует для local; при использовании minio пути определяются корзиной/префиксом).

Режимы развёртки

Woodpecker поддерживает три режима работы с storage.type:

storage.type	Как работает Woodpecker	Бэкенд WAL	Автономный Milvus	Распределенная версия Milvus (кластер)
minio (по умолчанию)	Встроенный в узел Milvus/потоковой передачи	Объектное хранилище (совместимое с MinIO/S3)	Поддерживается	Поддерживается
local	Встроен в узел Milvus/потоковой передачи	Локальная файловая система	Поддерживается	Ограничено (все узлы нуждаются в общей файловой системе, например NFS)
service	Выделенный сервис Woodpecker (собственные поды)	Объектное хранилище (совместимое с MinIO/S3)	Не поддерживается	Поддерживается

Примечания:

• При использовании режима « minio » Woodpecker использует то же объектное хранилище, что и Milvus (MinIO/S3/GCS/OSS и т. д.).
• При использовании режима « local » локальный диск одного узла подходит только для автономного режима. Если все поды имеют доступ к общей файловой системе (например, NFS), в кластерном режиме также можно использовать режим « local ».
• service Режим «minio » запускает Woodpecker как отдельный, независимо масштабируемый сервис и доступен только для распределенных/кластерных развертываний. Автономные развертывания используют встроенные режимы ( или local).

Совместимость с объектными хранилищами для storage.type=minio

В приведённой ниже таблице обобщена известная на данный момент совместимость бэкэндов объектного хранилища при настройке Woodpecker с использованием storage.type=minio. Эта информация основана на обсуждении № 150 на GitHub.

Поставщик / сервис	Статус	Примечания
Хранилище Blob в Azure	Поддерживается	Использует собственный SDK для Azure.
AWS S3	Поддерживается	Нативная поддержка S3 с полной поддержкой условной записи.
MinIO (>= 2024-12)	Поддерживается	Полная поддержка условной записи S3.
Aliyun OSS	Поддерживается	Поддерживается через интерфейс, совместимый с S3.
Tencent COS	Поддерживается	Поддерживается через интерфейс, совместимый с S3.
Google Cloud Storage (GCS)	Поддерживается	Поддерживается через режим взаимодействия с S3.
Huawei Cloud OBS	Не поддерживается	Отсутствует необходимая семантика условной записи.
VAST Data	Поддерживается	Проверено сообществом; работает только с бакетами без управления версиями.
Другие хранилища, совместимые с S3	Частично	Зависит от полной поддержки семантики условной записи S3.

Примечания:

• Совместимость зависит от поддержки нативного SDK или поддержки семантики условной записи S3.
• Если вы самостоятельно развертываете MinIO для Woodpecker, используйте версию RELEASE.2024-12-18T13-15-44Z или более позднюю.
• Данная матрица отражает текущее состояние обсуждения и может изменяться по мере дальнейшей проверки поддержки бэкэнда.

Руководства по развертыванию

Включение Woodpecker для кластера Milvus в Kubernetes (Milvus Operator, storage=minio)

После установки Milvus Operator запустите кластер Milvus с включенным Woodpecker, используя официальный пример:

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, следуйте инструкциям, описанным в разде ле «Настройка».

Включение Woodpecker для кластера Milvus в Kubernetes (Helm Chart, storage=minio)

Сначала добавьте и обновите диаграмму Helm для Milvus, как описано в разделе «Запуск Milvus в Kubernetes с помощью Helm».

Затем выполните развертывание, воспользовавшись одним из следующих примеров:

– Развертывание кластера (рекомендуемые настройки с включенными Woodpecker и Streaming Node):

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

– Автономное развертывание (с включенным Woodpecker):

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

После развертывания следуйте инструкциям в документации для перенаправления портов и подключения. Чтобы настроить параметры Woodpecker, следуйте инструкциям, описанным в разделе «Конфигурация».

Включение Woodpecker для автономной версии Milvus в Docker (storage=local)

В Milvus 3.x автономное развертывание в Docker по умолчанию использует Woodpecker с локальной файловой системой в качестве бэкэнда WAL — дополнительная настройка не требуется. Следуйте инструкциям из раздела «Запуск Milvus в 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

Для настройки Woodpecker отредактируйте сгенерированный файл ` user.yaml ` после первого запуска и выполните команду ` bash standalone_embed.sh restart `, чтобы применить изменения (при новом запуске ` start ` файл ` user.yaml` генерируется заново, поэтому примените изменения с помощью команды ` restart`):

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

Включение Woodpecker для автономной версии Milvus с Docker Compose (storage=minio)

Следуйте инструкциям по запуску Milvus с помощью Docker Compose. Пример:

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

Включение режима службы Woodpecker для кластера Milvus (Helm)

Режим службы Woodpecker является функцией Milvus 3.0. Для распределенных/кластерных развертываний вы можете запускать Woodpecker в качестве выделенной службы (отдельные поды) вместо встраивания в узел потоковой обработки, установив параметр ` 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

При этом Woodpecker развертывается в виде выделенного StatefulSet (my-release-milvus-woodpecker, по умолчанию 4 реплики), управляемого безголовым сервисом, с кластеризацией по алгоритму «gossip» на портах 18080 (сервис), 17946 (gossip) и 9091 (метрики), с MinIO в качестве бэкэнда хранилища. Сервису требуется кворум из 3 узлов; значение по умолчанию в 4 реплики обеспечивает кворум, допуская отказ одного узла, поэтому не устанавливайте значение параметра ` woodpecker.replicaCount ` ниже 3. В этом случае кластер включает отдельный набор под-контейнеров woodpecker:

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

Советы по настройке пропускной способности

Характеристики пропускной способности и задержки Woodpecker различаются в встроенном режиме и режиме службы (функция Milvus 3.0). Приведенные ниже рекомендации сгруппированы по режимам.

Встроенный режим

Основываясь на результатах тестов и ограничениях бэкэнда в Woodpecker, оптимизируйте сквозную пропускную способность записи, учитывая следующие аспекты:

• Со стороны хранилища
  • Объектное хранилище (совместимое с MinIO/S3): увеличьте количество одновременных операций и размер объектов (избегайте очень маленьких объектов). Следите за ограничениями пропускной способности сети и корзины. Один узел MinIO на SSD часто ограничивается скоростью около 100 МБ/с локально; один EC2, подключенный к S3, может достигать скорости в гигабайтах в секунду.
  • Локальные/общие файловые системы (локальные): отдавайте предпочтение NVMe или быстрым дискам. Убедитесь, что файловая система хорошо обрабатывает мелкие записи и имеет низкую задержку fsync.
• Параметры Woodpecker
  • Увеличьте значения параметров ` logstore.segmentSyncPolicy.maxFlushSize ` и ` maxFlushThreads ` для более крупных операций сброса и более высокой степень параллелизма.
  • Настройте параметр maxInterval в соответствии с характеристиками носителя (пожертвуйте задержкой ради пропускной способности за счет более длительной агрегации).
  • Для объектного хранилища рассмотрите возможность увеличения значения segmentRollingPolicy.maxSize, чтобы сократить количество переключений сегментов.
• Со стороны клиента/приложения
  • Используйте пакеты большего размера и большее количество одновременно записывающих клиентов.
  • Контролируйте время обновления/построения индекса (соберите пакеты перед запуском), чтобы избежать частых мелких записей.

Режим службы (Milvus 3.0+)

Режим службы сохраняет высокую пропускную способность записи WAL, опирающегося на объектное хранилище, одновременно обеспечивая низкую задержку (см. раздел «Задержка»). Вышеуказанная настройка со стороны хранилища и со стороны клиента по-прежнему применима; кроме того, поскольку Woodpecker работает как отдельный сервис, вы можете горизонтально масштабировать пропускную способность записи, добавляя реплики (woodpecker.replicaCount, по умолчанию 4), а записи получают преимущества от кворумной репликации с одним RTT и чтений с учетом топологии, которые позволяют избежать пересылки через брокер.

Демонстрация пакетной вставки — используйте следующее для измерения пропускной способности записи:

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

Задержка

Встроенный режим

Woodpecker — это облачный WAL, разработанный для объектного хранилища с компромиссами между пропускной способностью, стоимостью и задержкой. Легкий встроенный режим уделяет приоритетное внимание оптимизации стоимости и пропускной способности, поскольку в большинстве сценариев требуется лишь запись данных в течение определённого времени, а не низкая задержка для отдельных запросов на запись. Поэтому Woodpecker использует пакетную запись с интервалами по умолчанию 10 мс для бэкэндов хранения на основе локальной файловой системы и 200 мс для бэкэндов хранения типа MinIO. Во время медленных операций записи максимальная задержка равна времени интервала плюс время сброса.

Обратите внимание, что пакетная запись запускается не только по временным интервалам, но и по размеру пакета, который по умолчанию составляет 2 МБ.

Режим «Service» (Milvus 3.0+)

Режим службы обеспечивает задержку записи на уровне миллисекунд — того же порядка, что и у традиционного WAL с тремя репликами на локальном диске — при низких затратах. В типичном развертывании с тремя репликами, распределенном между зонами доступности (AZ), задержка записи остается в диапазоне миллисекунд. Это достигается за счет:

• Записи с кворумом за один RTT — репликация, управляемая клиентом, завершает запись с кворумом за один цикл обмена данными, при этом трафик между зонами ограничивается объемом данных двух реплик (по сравнению с дополнительным трафиком между зонами, составляющим примерно 1/3, характерным для репликации на основе брокера или лидера).
• Чтение с одним прыжком с учётом топологии — каждое чтение направляется непосредственно на ближайшую реплику, а не пересылается через брокер, что позволяет избежать случайных чтений между зонами (≈2/3 трафика чтения между зонами) в системах на основе брокера.
• Немедленная загрузка в объектное хранилище после смены сегмента — каждый сегмент отслеживает весь свой жизненный цикл и загружается в объектное хранилище сразу после смены, что позволяет снизить занимаемое место на локальном диске и затраты на хранение без ухудшения задержки.
• Отсутствие непрерывной репликации между узлами — журналы сохраняются в объектном хранилище, выступающем в качестве общего хранилища, поэтому при отработке отказа повторно загружаются только уцелевшие реплики (без копирования всего узла), масштабирование не ограничивается пропускной способностью межузловой репликации, а замена узлов в больших масштабах не вызывает «репликационных штормов».

В развертываниях с пересечением зон доступности (AZ) режим службы также позволяет сэкономить примерно 1/3 сетевого трафика записи и 2/3 трафика чтения между зонами доступности по сравнению с системами журналов на основе брокера. Полный анализ архитектуры и затрат см. в разделе «Архитектура Woodpecker».

Подробности об архитектуре, режимах развертывания (MemoryBuffer / QuorumBuffer) и производительности см. в разделе «Архитектура Woodpecker».

Более подробную информацию о параметрах см. в репозитории Woodpecker на GitHub.