크로스-인코더 출력 재사용

크로스-인코더 출력 재사용 (Cross-Encoder Output Reuse)

크로스-인코더 출력 재사용(Cross-Encoder output reuse)을 이용하면 한 Encoder가 계산한 이미지 임베딩을, 공유된 Mooncake Store에 저장해 두고 다른 Encoder가 그대로 불러와 쓸 수 있습니다. 로컬 캐시에 없으면 Store를 먼저 확인한 뒤 인코딩하고, 새로 계산된 출력은 비동기로 게시합니다. 두 경로 모두 기존 ECMooncakeConnector의 P2P 전달을 통해 Prefill로 전달됩니다.

출처: 문서

본문

요구 사항 (Requirements)

  • ECMooncakeConnector를 사용하는 동작 중인 disaggregated Encoder 배포가 있어야 합니다. 기본 E/PD 구성을 보려면 Mooncake 통합 예제를 참고하세요.
  • Model Runner V2(VLLM_USE_V2_MODEL_RUNNER=1), Encoder TP=1, 그리고 동적 LoRA를 쓰지 않아야 합니다.
  • 콘텐츠 식별자를 보존하려면 --mm-processor-cache-gb를 0보다 크게 설정해야 합니다.
  • Mooncake 0.3.12 이상과 동작 중인 RAM Store가 필요합니다. 디스크 오프로딩(enable_offload: true)은 지원되지 않습니다.

공유 재사용은 연속된(contiguous) 2D FP16, BF16 또는 FP32 인코더 출력을 가진 이미지를 지원합니다. 그 외 모달리티는 일반 인코딩을 사용하며, 연속되지 않은(non-contiguous) 출력은 게시되지 않습니다.

사용법 (Usage)

각 Encoder에서 기존 producer --ec-transfer-config에 cross_encoder_cache: true를 추가합니다. P2P 설정은 그대로 유지합니다.

{
  "ec_connector": "ECMooncakeConnector",
  "ec_role": "ec_producer",
  "ec_connector_extra_config": {
    "cross_encoder_cache": true
  }
}

Prefill은 기존 ECMooncakeConnector consumer 구성을 유지하며, Store 클라이언트는 필요하지 않습니다.

기존 Store를 가리키는 JSON 파일을 만듭니다. 독립적으로 관리되는 RAM 풀의 경우 standalone-store 모드에 global_segment_size를 0으로 설정합니다.

{
  "metadata_server": "http://STORE_HOST:2379/metadata",
  "master_server_address": "STORE_HOST:50051",
  "protocol": "tcp",
  "device_name": "",
  "mode": "standalone-store",
  "global_segment_size": 0,
  "local_buffer_size": "4GB"
}

주소를 여러분의 Store 엔드포인트로 바꾸고, 각 Encoder에서 vLLM을 시작하기 전에 경로를 설정합니다.

export MOONCAKE_CONFIG_PATH=/path/to/mooncake_config.json

이 설정은 기존 Store에 연결할 뿐, 스토리지 서비스를 시작하지는 않습니다. Store 설정과 테넌트 구성은 Mooncake Store 가이드를 참고하세요.

구성 (Configuration)

이 옵션들은 producer의 ec_connector_extra_config에 속합니다.

| Option | Default | Description | | cross_encoder_cache | false | Enable shared output reuse. | | embedding_cache_prefix | "" | Namespace prefix for shared embeddings. | | embedding_model_identity | Configured model path | Override the model field in Store keys. Matching multimodal identifiers are still required. | | store_max_pending_items | 32 | Maximum pending publications per Encoder. Must be positive. | | store_max_pending_bytes | 2147483648 (2 GiB) | Maximum retained tensor storage for pending publications per Encoder. Must be positive. | | store_read_buffer_bytes | 134217728 (128 MiB) | Maximum reusable CPU staging buffer per Encoder; pinned for CUDA outputs. Must be positive. |

출력을 공유하는 Encoder들은 동일한 불변 가중치(immutable weights), 호환되는 전처리, 그리고 일치하는 멀티모달 식별자를 사용해야 합니다. 자동 식별자를 만들려면 동일한 구성된 모델 경로를 사용하세요. embedding_model_identity만으로는 서로 다른 경로 간 재사용이 활성화되지 않습니다. 가중치를 제자리에서 교체하거나 출력에 영향을 주는 설정을 바꿀 때는 embedding_cache_prefix를 변경하세요. 호출자가 제공한 UUID는 항상 동일한 입력을 식별해야 합니다. 자세한 내용은 cached inputs를 참고하세요.

제한 사항 (Limitations)

  • Store 읽기는 동기적으로 동작합니다. 재사용 시 Encoder 연산은 건너뛰지만, 전처리, P2P 전달, 스케줄러의 Encoder 예산 예약은 건너뛰지 않습니다.
  • 히트(hit)는 하나의 지연 할당(lazily allocated)된 등록 CPU 스테이징 버퍼를 통해 배치로 읽힙니다. 각 청크는 버퍼가 재사용되기 전에 독립적인 출력 텐서로 복사됩니다. 읽기는 store_read_buffer_bytes 단위로 나뉘며, 이 용량(24바이트 헤더 포함)보다 큰 개별 객체는 인코딩으로 폴백합니다. 스테이징 메모리는 Store의 local_buffer_size에 추가되며 정상 종료 시 해제됩니다. 첫 로드에는 할당 및 등록 비용이 포함됩니다.
  • 게시는 best-effort입니다. 요청이 Store에 출력을 도달시키기 전에 끝날 수 있으므로, 동시에 들어온 냉(cold) 요청이 같은 이미지를 여전히 인코딩할 수 있습니다.
  • 게시 예산은 각 보유 백킹 스토리지를 보류 뷰(pending view) 전체에서 한 번만 계산합니다. 마지막 뷰가 안전하게 회수된 후에 해당 차지가 해제됩니다. 예산을 초과하면 쓰기를 건너뜁니다. Store 클라이언트 버퍼와 P2P 풀이 추가 메모리를 소비합니다.
  • 캐시 미스와 복구 가능한 읽기 오류는 인코딩으로 폴백합니다. 복구 가능한 게시 오류는 쓰기를 건너뜁니다. 예상치 못한 네이티브 오류나 확인되지 않은 I/O 완료·버퍼 해제는 워커를 실패시킬 수 있습니다.
  • 호환되지 않는 객체는 교체 없이 거부됩니다. 제거(evict)될 때까지 반복적인 폴백을 유발할 수 있습니다.
  • 독립 Store는 Encoder 재시작을 넘어 임베딩을 보존할 수 있습니다. 용량·제거·Store 실패 내성은 Store 배포에 달려 있습니다.
  • protocol:v3 네임스페이스는 간결한 임베딩 포맷을 이전 캐시 객체와 분리합니다. 서로 다른 포맷 버전을 쓰는 Encoder끼리는 히트를 공유하지 않습니다.

더 알아보기 (Learn more)