복제

복제 (Replication)

Weaviate 인스턴스는 복제(replication)할 수 있어요. 복제는 읽기 처리량을 높이고, 가용성을 개선하며, 무중단 업그레이드를 가능하게 합니다. 기본적으로는 꺼져 있고, 컬렉션별로 켜서 데이터셋 안에서 클래스마다 다른 복제 팩터를 둘 수 있어요.

출처: 공식문서 — Replication

복제 활성화

복제는 기본적으로 비활성화되어 있어요. 컬렉션 구성에서 컬렉션별로 켤 수 있고, 데이터셋의 클래스마다 다른 복제 팩터를 설정할 수 있습니다. 활성화하려면 다음 중 하나 또는 둘 다 설정합니다.

  • 전체 Weaviate 인스턴스의 REPLICATION_MINIMUM_FACTOR 환경변수
  • 컬렉션의 replicationFactor 파라미터

REPLICATION_MINIMUM_FACTOR 환경변수는 인스턴스의 모든 컬렉션에 대한 최소 복제 팩터를 설정해요. 컬렉션에 복제 팩터를 설정하면 그 값이 최소 복제 팩터를 덮어씁니다.

복제 팩터 변경은 컬렉션 정의를 업데이트해 바꿀 수 없어요. v1.32부터 레플리카 이동으로 샤드의 복제 팩터를 변경할 수 있습니다.

다음과 같이 복제 팩터 3으로 컬렉션을 만들면, 데이터를 가져오기 전에 설정했으므로 모든 데이터가 3번 복제됩니다.

from weaviate.classes.config import Configure
client.collections.create(
    "Article",
    replication_config=Configure.replication(
        factor=3,
    ),
)

복제 팩터는 컬렉션에 데이터를 추가한 뒤에도 수정할 수 있어요. 나중에 변경하면 새 데이터가 새 레플리카 노드와 기존 레플리카 노드에 모두 복사됩니다.

예제 데이터 스키마는 쓰기 일관성 레벨 ALL을 써요. 스키마를 업로드·업데이트하면 변경 사항은 (코디네이터 노드를 거쳐) ALL 노드로 전송됩니다. 코디네이터 노드는 ALL 노드의 성공 응답을 기다린 뒤에 클라이언트에 성공 메시지를 보내요. 그래서 분산 Weaviate 환경에서도 스키마가 높은 일관성을 유지합니다.

Weaviate가 노드 간 비일관 데이터를 감지하면 동기화되지 않은 데이터를 복구하려고 시도합니다.

Weaviate는 비동기 복제(async replication) 를 제공해 불일치를 사전에 감지해요. 이전 버전에서는 읽기 시점에 불일치를 복구하는 repair-on-read 전략을 썼습니다. Repair-on-read는 자동이에요.

비동기 복제 (Async Replication)

Weaviate v1.38부터 복제 팩터가 1보다 큰 어떤 컬렉션에서도 비동기 복제가 기본으로 활성화됩니다. 더 이상 켜는 컬렉션별 플래그가 없어요. 클러스터 차원에서 끄려면 ASYNC_REPLICATION_DISABLED 환경변수를 true로 설정합니다. replicationConfig 섹션은 복제 팩터를 설정하고 asyncConfig로 비동기 복제를 미세 조정하는 데 씁니다.

컬렉션 레벨 구성 — v1.36에 추가. 비동기 복제는 복제 팩터가 1보다 큰 컬렉션에서 기본으로 실행됩니다(v1.38 기준). 특정 컬렉션의 동작을 미세 조정하려면 replicationConfig의 asyncConfig 객체를 설정하면 돼요. 클러스터 차원의 환경변수 설정이 컬렉션별 설정을 덮어씁니다.

비동기 복제 관련 환경변수를 조정해 용도에 맞게 구성합니다.

  • 스케줄러 워커 풀 크기: ASYNC_REPLICATION_SCHEDULER_WORKERS — 모든 샤드·테넌트에서 비동기 복제 작업을 실행하는 클러스터 차원 풀의 워커 수. 기본 10, 최대 100. v1.38부터 제거된 ASYNC_REPLICATION_CLUSTER_MAX_WORKERS 변수와 컬렉션별 maxWorkers 옵션을 대체 — 컬렉션들이 이 단일 풀을 공유
  • 해시 트리 초기화 동시성: ASYNC_REPLICATION_HASHTREE_INIT_CONCURRENCY — 비동기 복제 시작 시 동시에 해시 트리를 만들 샤드 수. 기본 100
  • 로거 빈도: ASYNC_REPLICATION_LOGGING_FREQUENCY — 비동기 복제 백그라운드 프로세스가 이벤트를 로깅하는 빈도
  • 비교 빈도: ASYNC_REPLICATION_FREQUENCY — 각 노드가 자신의 로컬 데이터를 다른 노드와 비교하는 빈도
  • 비교 타임아웃: ASYNC_REPLICATION_DIFF_PER_NODE_TIMEOUT — 노드가 응답하지 않을 때 비교 중 기다리는 타임아웃
  • 해시 트리 높이: ASYNC_REPLICATION_HASHTREE_HEIGHT — 해시 트리 크기 지정. 전체 데이터셋을 스캔하는 대신 여러 레벨의 해시 다이제스트를 비교해 데이터 차이를 좁히는 데 도움
  • 다이제스트 비교 배치 크기: ASYNC_REPLICATION_DIFF_BATCH_SIZE — 실제 객체를 전파하기 전에 노드 간에 다이제스트(예: 마지막 업데이트 시각)를 비교하는 객체 수

v1.38에서 제거된 항목: ASYNC_REPLICATION_CLUSTER_MAX_WORKERS(ASYNC_REPLICATION_SCHEDULER_WORKERS로 대체)와 ASYNC_REPLICATION_ALIVE_NODES_CHECKING_FREQUENCY — 비동기 복제가 중앙 스케줄러로 이동하면서 제거.

노드 간 차이를 감지하면 Weaviate는 낡거나 빠진 데이터를 전파합니다. 동기화를 다음과 같이 구성해요.

  • 전파 중 빈도: ASYNC_REPLICATION_FREQUENCY_WHILE_PROPAGATING — 노드에서 동기화가 완료된 후 데이터 비교 빈도를 설정값으로 일시 조정
  • 전파 전 타임아웃: ASYNC_REPLICATION_PRE_PROPAGATION_TIMEOUT — 진행 중인 쓰기 연산이 노드 간 완료되도록 전파 시작 전 지연 설정
  • 전파 타임아웃: ASYNC_REPLICATION_PROPAGATION_TIMEOUT — 노드가 응답하지 않을 때 전파 중 기다리는 타임아웃
  • 전파 지연: ASYNC_REPLICATION_PROPAGATION_DELAY — 새/갱신 객체 전파 전에 비동기 쓰기가 모든 노드에 도달하도록 지연 기간 설정
  • 데이터 전파 배치 크기: ASYNC_REPLICATION_PROPAGATION_BATCH_SIZE — 전파 단계에서 각 동기화 배치로 보내는 객체 수
  • 전파 제한: ASYNC_REPLICATION_PROPAGATION_LIMIT — 복제 반복당 전파할 out-of-sync 객체 수 제한
  • 전파 동시성: ASYNC_REPLICATION_PROPAGATION_CONCURRENCY — 다른 노드로 객체 배치를 보낼 수 있는 동시 워커 수. 여러 전파 배치를 동시에 보낼 수 있게 함

tip: 클러스터 크기와 네트워크 지연에 맞춰 이 설정을 조정하세요. 고트래픽 클러스터에는 더 작은 배치 크기와 짧은 타임아웃이 유리하고, 더 큰 클러스터는 더 보수적인 설정이 필요할 수 있어요.

일관성 레벨 (Consistency Level)

데이터를 쓰거나 읽을 때 클러스터의 하나 이상의 레플리카 노드가 요청에 응답합니다. 코디네이터 노드에 성공 응답·확인을 보내야 하는 노드 수는 consistency_level에 따라 달라요. 사용 가능한 일관성 레벨은 ONE, QUORUM(replication_factor / 2 + 1), ALL입니다.

consistency_level은 쿼리 시점에 지정할 수 있어요.

# 일관성 레벨 ONE으로 ID로 객체 가져오기
curl "http://localhost:8080/v1/objects/{ClassName}/{id}?consistency_level=ONE"

note: v1.17에서는 ID로 데이터를 가져오는 읽기 쿼리만 일관성 레벨을 조절할 수 있었고, 다른 객체별 REST 엔드포인트(읽기·쓰기)는 ALL을 썼어요. v1.18부터 모든 쓰기·읽기 쿼리를 ONE, QUORUM(기본), ALL 중 하나로 조절할 수 있습니다. GraphQL 엔드포인트는 (두 버전 모두) ONE을 써요.

from weaviate.classes.config import ConsistencyLevel
questions = client.collections.use(collection_name).with_consistency_level(
    consistency_level=ConsistencyLevel.QUORUM
)
response = collection.query.fetch_object_by_id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
# withConsistencyLevel에 전달하는 값은 다음 중 하나:
#  * 'ALL'
#  * 'QUORUM' (기본), 또는
#  * 'ONE'
# 요청이 성공으로 간주되기 전에 몇 개의 레플리카가 확인해야 하는지를 결정한다.
for o in response.objects:
    print(o.properties)  # 반환된 객체 검사

레플리카 이동 (Replica Movement)

v1.32에 추가. 초기 복제 팩터 설정을 넘어, 클러스터 내 샤드 레플리카의 배치를 능동적으로 관리할 수 있어요. 확장 후 데이터 리밸런싱, 노드 폐기, 데이터 지역성 최적화에 유용합니다. 레플리카 이동은 전용 RESTful API 엔드포인트 또는 클라이언트 라이브러리로 관리합니다.

더 알아보기 (Learn more)