Milvus 업그레이드 후 검색 속도 저하 문제 해결: WPS 팀의 교훈

이 게시물은 추천 시스템에서 Milvus를 사용하는 Kingsoft Office Software의 WPS 엔지니어링 팀에서 제공한 글입니다. Milvus 2.2.16에서 2.5.16으로 업그레이드하는 동안 검색 지연 시간이 3배에서 5배까지 증가했습니다. 이 문서에서는 이 문제를 조사하고 해결한 방법을 안내하며, 비슷한 업그레이드를 계획 중인 커뮤니티의 다른 사용자들에게 도움이 될 수 있습니다.

Milvus를 업그레이드한 이유

저희는 생산성 소프트웨어를 구축하는 WPS 엔지니어링 팀의 일원으로 온라인 추천 시스템에서 실시간 유사도 검색을 위한 벡터 검색 엔진으로 Milvus를 사용하고 있습니다. 우리의 프로덕션 클러스터에는 평균 768개의 차원으로 수천만 개의 벡터가 저장되어 있습니다. 데이터는 16개의 쿼리 노드에서 제공되었으며, 각 포드는 16개의 CPU 코어와 48GB의 메모리로 제한되어 구성되었습니다.

Milvus 2.2.16을 실행하는 동안 이미 비즈니스에 영향을 미치고 있는 심각한 안정성 문제가 발생했습니다. 쿼리 동시성이 높을 때 planparserv2.HandleCompare 에서 널 포인터 예외가 발생하여 프록시 구성 요소가 패닉 상태에 빠지고 자주 다시 시작될 수 있었습니다. 이 버그는 동시 접속자가 많은 시나리오에서 매우 쉽게 트리거되었으며 온라인 추천 서비스의 가용성에 직접적인 영향을 미쳤습니다.

아래는 이 인시던트의 실제 프록시 오류 로그와 스택 추적입니다:

[2025/12/23 10:43:13.581 +00:00] [ERROR] [concurrency/pool_option.go:53] ["Conc pool panicked"]
[panic="runtime error: invalid memory address or nil pointer dereference"]
[stack="...
github.com/milvus-io/milvus/internal/parser/planparserv2.HandleCompare
  /go/src/github.com/milvus-io/milvus/internal/parser/planparserv2/utils.go:331
github.com/milvus-io/milvus/internal/parser/planparserv2.(*ParserVisitor).VisitEquality
  /go/src/github.com/milvus-io/milvus/internal/parser/planparserv2/parser_visitor.go:345
...
github.com/milvus-io/milvus/internal/proxy.(*queryTask).PreExecute
  /go/src/github.com/milvus-io/milvus/internal/proxy/task_query.go:271
github.com/milvus-io/milvus/internal/proxy.(*taskScheduler).processTask
  /go/src/github.com/milvus-io/milvus/internal/proxy/task_scheduler.go:455
..."]
panic: runtime error: invalid memory address or nil pointer dereference [recovered]
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x8 pc=0x2f1a02a]
goroutine 989 [running]:
github.com/milvus-io/milvus/internal/parser/planparserv2.HandleCompare(…)
/go/src/github.com/milvus-io/milvus/internal/parser/planparserv2/utils.go:331 +0x2a
github.com/milvus-io/milvus/internal/parser/planparserv2.(*ParserVisitor).VisitEquality(…)
/go/src/github.com/milvus-io/milvus/internal/parser/planparserv2/parser_visitor.go:345 +0x7e5

스택 추적이 보여주는 내용: 패닉은 Proxy에서 쿼리 전처리 중 queryTask.PreExecute 내에서 발생했습니다. 호출 경로는 다음과 같습니다:

taskScheduler.processTask → queryTask.PreExecute → planparserv2.CreateRetrievePlan → planparserv2.HandleCompare

HandleCompare 이 주소 0x8 에서 잘못된 메모리에 액세스하려고 시도하여 SIGSEGV를 트리거하고 Proxy 프로세스가 충돌하면서 충돌이 발생했습니다.

이러한 안정성 위험을 완전히 제거하기 위해 Milvus 2.2.16에서 2.5.16으로 클러스터를 업그레이드하기로 결정했습니다.

업그레이드 전에 milvus-backup으로 데이터 백업하기

프로덕션 클러스터에 손을 대기 전에 공식 milvus-backup 도구를 사용하여 모든 것을 백업했습니다. 이 도구는 동일한 클러스터 내, 클러스터 간, Milvus 버전 간 백업 및 복원을 지원합니다.

버전 호환성 확인

milvus-backup에는 버전 간 복원에 대한 두 가지 버전 규칙이 있습니다:

1. 대상 클러스터는 동일한 Milvus 버전 또는 최신 버전을 실행해야 합니다. 2.2의 백업은 2.5로 로드할 수 있지만 그 반대는 불가능합니다.

2. 대상은 Milvus 2.4 이상이어야 합니다. 이전 복원 대상은 지원되지 않습니다.

저희 경로(2.2.16에서 백업, 2.5.16에 로드)는 두 가지 규칙을 모두 충족했습니다.

다음에서 백업 ↓ \ 복원 대상 →	2.4	2.5	2.6
2.2	✅	✅	✅
2.3	✅	✅	✅
2.4	✅	✅	✅
2.5	❌	✅	✅
2.6	❌	❌	✅

Milvus 백업 작동 방식

Milvus 백업은 Milvus 인스턴스 전반에서 메타데이터, 세그먼트 및 데이터의 백업과 복원을 용이하게 합니다. 백업 및 복원 프로세스의 유연한 조작을 위해 CLI, API, gRPC 기반 Go 모듈과 같은 노스바운드 인터페이스를 제공합니다.

Milvus Backup은 소스 Milvus 인스턴스에서 컬렉션 메타데이터와 세그먼트를 읽어 백업을 생성합니다. 그런 다음 소스 Milvus 인스턴스의 루트 경로에서 컬렉션 데이터를 복사하여 백업 루트 경로에 저장합니다.

백업에서 복원하려면 Milvus 백업은 백업의 컬렉션 메타데이터 및 세그먼트 정보를 기반으로 대상 Milvus 인스턴스에 새 컬렉션을 만듭니다. 그런 다음 백업 루트 경로에서 대상 인스턴스의 루트 경로로 백업 데이터를 복사합니다.

백업 실행

전용 구성 파일인 configs/backup.yaml 을 준비했습니다. 주요 필드는 아래와 같으며 민감한 값은 제거되어 있습니다:

milvus:
  address: 1.1.1.1  # Source Milvus address
  port: 19530  # Source Milvus port
  user: root  # Source Milvus username (must have backup permissions)
  password: <PASS> # Source Milvus user password
etcd:
endpoints: “2.2.2.1:2379,2.2.2.2:2379,2.2.2.3:2379” # Endpoints of the etcd cluster connected to Milvus
rootPath: “by-dev”  # Prefix of Milvus metadata in etcd. If not modified, the default is by-dev. It is recommended to check etcd before proceeding.
minio:
# Source Milvus object storage bucket configuration
storageType: “aliyun” # support storage type: local, minio, s3, aws, gcp, ali(aliyun), azure, tc(tencent), gcpnative
address: ks3-cn-beijing-internal.ksyuncs.com # Address of MinIO/S3
port: 443   # Port of MinIO/S3
accessKeyID: object storage AK>

secretAccessKey: object storage SK>
useSSL: true
bucketName: “”
rootPath: “file” # Root directory prefix under the source object storage bucket where the current Milvus data is stored. If Milvus is installed using Helm Chart, the default prefix is file. It is recommended to log in to the object storage and verify before proceeding.
# Object storage bucket configuration for storing backup data
backupStorageType: “aliyun” # support storage type: local, minio, s3, aws, gcp, ali(aliyun), azure, tc(tencent)
backupAddress: ks3-cn-beijing-internal.ksyuncs.com # Address of MinIO/S3
backupPort: 443   # Port of MinIO/S3
backupAccessKeyID: 
backupSecretAccessKey: 
backupBucketName: 
backupRootPath: “backup” # Root path to store backup data. Backup data will be stored in backupBucketName/backupRootPath
backupUseSSL: true # Access MinIO/S3 with SSL
crossStorage: “true”  # Must be set to true when performing cross-storage backup

그런 다음 이 명령을 실행했습니다:

# Create a backup using milvus-backup
./milvus-backup create --config configs/backup.yaml -n backup_v2216

milvus-backup 핫 백업은 핫 백업을 지원하므로 일반적으로 온라인 트래픽에 거의 영향을 미치지 않습니다. 리소스 경합을 피하려면 사용량이 많지 않은 시간에 실행하는 것이 더 안전합니다.

백업 확인

백업이 완료된 후 백업이 완료되고 사용 가능한지 확인했습니다. 주로 백업의 컬렉션 수와 세그먼트 수가 소스 클러스터의 컬렉션 수와 일치하는지 확인했습니다.

./milvus-backup list --config configs/backup.yaml
# View backup details and confirm the number of Collections and Segments
./milvus-backup get --config configs/backup.yaml -n backup_v2216

일치했으므로 업그레이드로 넘어갔습니다.

헬름 차트로 업그레이드하기

수천만 개의 벡터가 있는 세 가지 주요 버전(2.2 → 2.5)을 이동하는 것은 너무 위험했습니다. 대신 새 클러스터를 구축하고 데이터를 마이그레이션했습니다. 이전 클러스터는 롤백을 위해 온라인 상태를 유지했습니다.

새 클러스터 배포

헬름으로 새로운 Milvus 2.5.16 클러스터를 배포했습니다:

# Add the Milvus Helm repository
: helm repo add milvus https://zilliztech.github.io/milvus-helm/
helm repo update  
# Check the Helm chart version corresponding to the target Milvus version
: helm search repo milvus/milvus -l | grep 2.5.16
milvus/milvus        4.2.58               2.5.16                    Milvus is an open-source vector database built ...
# Deploy the new version cluster (with mmap disabled)
helm install milvus-v25 milvus/milvus 

–namespace milvus-new 

–values values-v25.yaml 

–version 4.2.58 

–wait

주요 구성 변경 (values-v25.yaml)

성능 비교를 공정하게 하기 위해 새 클러스터를 가능한 한 이전 클러스터와 유사하게 유지했습니다. 이 워크로드에 중요한 몇 가지 설정만 변경했습니다:

• Mmap 비활성화 (mmap.enabled: false): 권장 워크로드는 지연 시간에 민감합니다. Mmap을 활성화하면 필요할 때 일부 데이터를 디스크에서 읽을 수 있으며, 이로 인해 디스크 I/O 지연이 추가되어 지연 시간이 급증할 수 있습니다. 데이터가 메모리에 완전히 유지되고 쿼리 지연 시간이 더 안정적으로 유지되도록 이 기능을 해제했습니다.

• 쿼리 노드 수: 이전 클러스터와 동일하게 16개로 유지됨.

• 리소스 제한: 각 파드에는 여전히 이전 클러스터와 동일하게 16개의 CPU 코어가 있습니다.

메이저 버전 업그레이드를 위한 팁:

• 기존 클러스터를 업그레이드하는 대신 새 클러스터를 구축한다. 메타데이터 호환성 위험을 피하고 깨끗한 롤백 경로를 유지할 수 있습니다.

• 마이그레이션하기 전에 백업을 확인하세요. 데이터가 새 버전의 형식으로 바뀌면 쉽게 되돌릴 수 없습니다.

• 전환하는 동안 두 클러스터를 모두 계속 실행하세요. 트래픽을 점진적으로 전환하고 완전히 확인된 후에만 이전 클러스터를 해제하세요.

Milvus-백업 복원을 사용하여 업그레이드 후 데이터 마이그레이션하기

milvus-backup restore 을 사용하여 백업을 새 클러스터에 로드했습니다. 밀버스-백업의 용어에서 "복원"은 "백업 데이터를 대상 클러스터에 로드"하는 것을 의미합니다. 대상은 동일한 Milvus 버전 또는 최신 버전을 실행해야 하므로 이름과 상관없이 복원은 항상 데이터를 앞으로 이동합니다.

복원 실행

복원 구성 파일인 configs/restore.yaml 은 새 클러스터와 해당 클러스터의 스토리지 설정을 가리켜야 했습니다. 주요 필드는 다음과 같습니다:

# Restore target Milvus connection information
milvus:
  address: 1.1.1.1  # Milvus address
  port: 19530  # Milvus port
  user: root  # Milvus username (must have restore permissions)
  password: <PASS> # Milvus user password  
  etcd:
    endpoints: "2.2.2.1:2379,2.2.2.2:2379,2.2.2.3:2379" # Endpoints of the etcd cluster connected to the target Milvus
    rootPath: "by-dev"  # Prefix of Milvus metadata in etcd. If not modified, the default is by-dev. It is recommended to check etcd before proceeding.
minio:
# Target Milvus object storage bucket configuration
storageType: “aliyun” # support storage type: local, minio, s3, aws, gcp, ali(aliyun), azure, tc(tencent), gcpnative
address: ks3-cn-beijing-internal.ksyuncs.com # Address of MinIO/S3
port: 443   # Port of MinIO/S3
accessKeyID: