Woodpecker

Woodpecker는 Milvus 3.x의 기본 메시지 큐(사전 기록 로그, WAL) 입니다. 오브젝트 스토리지를 위해 설계된 클라우드 네이티브 WAL로, 높은 처리량, 낮은 운영 오버헤드, 원활한 확장성을 제공합니다. 아키텍처 및 벤치마크에 대한 자세한 내용은 Woodpecker를 참조하십시오.

개요

• Milvus 3.x에서 Woodpecker는 기본 WAL/메시지 큐로, 로깅 서비스로서 순차적 쓰기 및 복구 기능을 제공합니다. Pulsar나 Kafka와 같은 외부 메시지 큐 서비스는 필요하지 않습니다.
• Woodpecker는 Milvus/스트리밍 노드에 내장된 형태로(기본값) 실행되거나, 자체 포드를 갖춘 전용 서비스로 (분산/클러스터 전용) 실행될 수 있습니다.
• 다음 세 가지 데이터 저장소( 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 만 지원됩니다. 경량 메타데이터를 저장하기 위해 Milvus와 동일한 etcd를 재사용하십시오.
  • prefix: 메타데이터의 키 접두사입니다. 기본값: woodpecker.
• woodpecker.client
  • 클라이언트 측에서 세그먼트 추가/롤링/감사 동작을 제어하여 처리량과 종단 간 지연 시간의 균형을 맞춥니다.
• woodpecker.logstore
  • 로그 세그먼트에 대한 동기화/플러시/압축/읽기 정책을 제어합니다. 이는 처리량 및 지연 시간 조정을 위한 주요 설정 항목입니다.
• woodpecker.storage
  • type: MinIO/S3 호환 오브젝트 스토리지(MinIO/S3/GCS/OSS 등)의 경우 minio; 로컬/공유 파일 시스템의 경우 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 의 경우, 단일 노드 로컬 디스크는 독립 실행형(Standalone) 모드에서만 적합합니다. 모든 파드(pod)가 공유 파일 시스템(예: NFS)에 액세스할 수 있는 경우, 클러스터(Cluster) 모드에서도 로컬 디스크( local)를 사용할 수 있습니다.
• service 이 모드는 Woodpecker를 별도로 독립적으로 확장 가능한 서비스로 실행하며, 분산/클러스터 배포에서만 사용할 수 있습니다. 독립형(Standalone) 배포는 내장 모드(minio 또는 local)를 사용합니다.

Woodpecker의 객체 스토리지 호환성 storage.type=minio

다음 표는 Woodpecker가 storage.type=minio 로 구성되었을 때 오브젝트 스토리지 백엔드의 현재 알려진 호환성을 요약한 것입니다. 이 정보는 GitHub 토론 #150을 기반으로 합니다.

프로바이더/서비스	상태	비고
Azure Blob Storage	지원됨	네이티브 Azure SDK를 사용합니다.
AWS S3	지원됨	조건부 쓰기(Conditional Write)를 완벽하게 지원하는 네이티브 S3.
MinIO (>= 2024-12)	지원됨	S3 조건부 쓰기 기능을 완벽하게 지원합니다.
Aliyun OSS	지원됨	S3 호환 인터페이스를 통해 지원됩니다.
Tencent COS	지원됨	S3 호환 인터페이스를 통해 지원됩니다.
Google Cloud Storage (GCS)	지원됨	S3 상호 운용성 모드를 통해 지원됩니다.
Huawei Cloud OBS	지원되지 않음	필요한 조건부 쓰기(Conditional Write) 기능이 없습니다.
VAST Data	지원됨	커뮤니티에서 검증됨; 버전 관리되지 않는 버킷에서만 작동합니다.
기타 S3 호환 스토리지	부분 지원	S3 조건부 쓰기(Conditional Write) 세манти크에 대한 완전한 지원 여부에 따라 다릅니다.

참고:

• 호환성은 네이티브 SDK 지원 또는 S3 조건부 쓰기(Conditional Write) 세미언틱 지원 여부에 따라 달라집니다.
• Woodpecker용 MinIO를 자체 호스팅하는 경우, RELEASE.2024-12-18T13-15-44Z 이상 버전을 사용하십시오.
• 이 매트릭스는 현재 논의 내용을 반영한 것이며, 백엔드 지원이 추가로 검증됨에 따라 변경될 수 있습니다.

배포 가이드

Kubernetes상의 Milvus 클러스터에서 Woodpecker 활성화 (Milvus Operator, storage=minio)

Milvus Operator를 설치한 후, 공식 샘플을 사용하여 Woodpecker가 활성화된 Milvus 클러스터를 시작합니다.

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

이 샘플은 Woodpecker를 메시지 큐로 구성하고 스트리밍 노드를 활성화합니다. 첫 실행 시 이미지 가져오기에 시간이 걸릴 수 있으므로, 모든 파드가 준비될 때까지 기다리십시오:

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 매개변수를 조정해야 하는 경우, ‘구성’ 섹션에 설명된 설정 방법을 따르십시오.

Kubernetes에서 Milvus 클러스터에 Woodpecker 활성화하기 (Helm 차트, storage=minio)

먼저 ‘Helm을 사용하여 Kubernetes에서 Milvus 실행’에 설명된 대로 Milvus Helm 차트를 추가하고 업데이트하십시오.

그런 다음 다음 예시 중 하나를 사용하여 배포하십시오:

– 클러스터 배포 (Woodpecker 및 스트리밍 노드 활성화 권장 설정):

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 매개변수를 조정하려면 ‘구성’ 섹션에 설명된 설정을 따르십시오.

Docker에서 Milvus 독립형(storage=local)용 Woodpecker 활성화

Milvus 3.x에서 Docker 독립형 배포는 기본적으로 로컬 파일 시스템을 WAL 백엔드로 사용하는 Woodpecker를 활용하므로 별도의 구성이 필요하지 않습니다. ‘Docker에서 Milvus 실행’을 따르십시오:

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

Docker Compose를 사용하여 Milvus Standalone에서 Woodpecker 활성화하기 (storage=minio)

'Docker Compose를 사용하여 Milvus 실행하기'를 따르세요. 예시:

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

Milvus 클러스터(Helm)에서 Woodpecker 서비스 모드 활성화

Woodpecker 서비스 모드는 Milvus 3.0의 기능입니다. 분산/클러스터 배포의 경우, ` streaming.woodpecker.embedded=false`를 설정하여 Woodpecker를 스트리밍 노드에 내장하는 대신 전용 서비스 (별도의 파드)로 실행할 수 있습니다:

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개의 복제본)으로 배포되며, 헤드리스 서비스가 전면에 배치되고, 포트 18080 (서비스), 17946 (고스핍), 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 호환): 동시 처리량과 오브젝트 크기를 늘리십시오(매우 작은 오브젝트는 피하십시오). 네트워크 및 버킷 대역폭 제한을 주의 깊게 확인하십시오. SSD에 구축된 단일 MinIO 노드는 로컬에서 대개 100 MB/s 정도로 제한되는 반면, 단일 EC2에서 S3로의 전송은 GB/s 수준에 도달할 수 있습니다.
  • 로컬/공유 파일 시스템(로컬): NVMe/고속 디스크를 우선적으로 사용하십시오. 파일 시스템이 소량 쓰기 작업과 fsync 지연 시간을 잘 처리하는지 확인하십시오.
• Woodpecker 조정 매개변수
  • logstore.segmentSyncPolicy.maxFlushSize 및 maxFlushThreads 값을 높여 더 큰 플러시 크기와 더 높은 병렬 처리를 구현하십시오.
  • 매체 특성에 따라 maxInterval 을 조정하십시오(집계 단위를 늘려 처리량을 확보하는 대신 지연 시간을 감수).
  • 오브젝트 스토리지의 경우, 세그먼트 전환을 줄이기 위해 segmentRollingPolicy.maxSize 값을 늘리는 것을 고려하십시오.
• 클라이언트/애플리케이션 측
  • 더 큰 배치 크기를 사용하고 더 많은 동시 쓰기 작업자/클라이언트를 활용하십시오.
  • 빈번한 소량 쓰기를 방지하기 위해 새로 고침/인덱스 구축 타이밍(트리거링 전 배치)을 제어하십시오.

서비스 모드(Milvus 3.0+)

서비스 모드는 오브젝트 스토리지를 기반으로 하는 WAL의 높은 쓰기 처리량을 유지하면서 낮은 지연 시간을 제공합니다( 지연 시간 참조). 위의 스토리지 측 및 클라이언트 측 튜닝은 여전히 적용되며, 또한 Woodpecker는 자체 서비스로 실행되므로 레플리카(woodpecker.replicaCount, 기본값 4)를 추가하여 쓰기 용량을 수평적으로 확장할 수 있고, 쓰기 작업은 1-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는 일괄 쓰기를 채택하며, 로컬 파일 시스템 스토리지 백엔드의 경우 기본 간격은 10ms이고, MinIO와 유사한 스토리지 백엔드의 경우 200ms입니다. 쓰기 작업 속도가 느릴 때 최대 지연 시간은 간격 시간에 플러시 시간을 더한 값과 같습니다.

배치 삽입은 시간 간격뿐만 아니라 배치 크기(기본값 2MB)에 의해서도 트리거된다는 점에 유의하십시오.

서비스 모드 (Milvus 3.0+)

서비스 모드는 비용을 낮게 유지하면서도 밀리초 수준의 쓰기 지연 시간을 제공하며, 이는 기존의 3개 복제본을 사용하는 로컬 디스크 WAL과 비슷한 수준입니다. 일반적인 3개 복제본, AZ 간 배포 환경에서 쓰기 지연 시간은 밀리초 범위를 유지합니다. 이는 다음을 통해 달성됩니다.

• 단일 RTT 쿼럼 쓰기 — 클라이언트 주도형 복제는 단일 왕복(RTT) 내에 쿼럼 쓰기를 완료하며, AZ 간 트래픽은 2개의 레플리카에 해당하는 데이터 양으로 고정됩니다(브로커/리더 기반 복제에서 일반적으로 발생하는 추가적인 약 1/3의 AZ 간 트래픽과 대비).
• 토폴로지를 고려한 단일 홉 읽기 — 각 읽기 요청은 브로커를 통해 전달되지 않고 가장 가까운 복제본으로 직접 전송되므로, 브로커 기반 시스템에서 발생하는 무작위 AZ 간 읽기(AZ 간 읽기 트래픽의 약 2/3)를 피할 수 있습니다.
• 세그먼트 롤링 후 즉시 오브젝트 스토리지 업로드 — 각 세그먼트는 전체 수명 주기를 추적하며, 롤링되는 즉시 오브젝트 스토리지에 업로드되므로, 지연 시간을 희생하지 않고도 로컬 디스크 사용량과 스토리지 비용을 낮게 유지합니다.
• 지속적인 노드 간 복제 없음 — 로그는 공유 스토리지 역할을 하는 오브젝트 스토리지에 영구 저장되므로, 장애 조치 시 생존한 복제본만 재업로드되며(전체 노드 복사 없음), 확장성이 노드 간 복제 대역폭에 제한받지 않고, 대규모 노드 교체 시에도 복제 폭주가 발생하지 않습니다.

AZ 간 배포 환경에서 서비스 모드는 브로커 기반 로그 시스템에 비해 AZ 간 쓰기 트래픽의 약 1/3, 읽기 트래픽의 약 2/3를 절감합니다. 전체 설계 및 비용 분석에 대해서는 Woodpecker 아키텍처를 참조하십시오.

아키텍처, 배포 모드(MemoryBuffer / QuorumBuffer) 및 성능에 대한 자세한 내용은 Woodpecker 아키텍처를 참조하십시오.

매개변수에 대한 자세한 내용은 Woodpecker GitHub 저장소를 참조하십시오.