퓨전 매핑

퓨전 매핑 (Fusion mapping) (실험 기능)

퓨전 매핑은 원래 체크포인트 형식을 보존하면서 로드 시점에 모델 서브모듈을 교체할 수 있는 옵트인(opt-in) 방식이에요.

이는 다음을 기반으로 해요:

  • Monkey patching: 모델 인스턴스화 전에 모듈 클래스를 교체해요.
  • Dynamic weight loading: 원래 런타임 레이아웃과 퓨전된 런타임 레이아웃 사이에서 가중치를 매핑해요.

[!WARNING] 퓨전 매핑은 실험적인 로딩 기능입니다. 런타임 모듈 구조를 바꾸고 모델 동작에 영향을 줄 수 있습니다. 명시적으로 퓨전된 런타임 레이아웃을 원할 때만 사용하세요.

출처: 문서

본문

빠른 시작

퓨전은 fusion_config와 함께 from_pretrained()을 통해 활성화돼요.

from transformers import AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)

기본적으로는 어떤 퓨전도 적용되지 않아요. fusion_config가 모델 config에 저장되어 있다면 from_pretrained()이 자동으로 이를 재사용해요.

작동 방식

퓨전 등록은 모델이 인스턴스화되기 전에 일어나요:

  1. from_pretrained()은 명시적 fusion_config 인자를 사용하거나 config.fusion_config로 폴백해요.
  2. 퓨전 레지스트리가 요청된 퓨전 이름을 검증해요.
  3. 각 활성 퓨전은 타깃 모델 클래스를 메타-초기화하고, 선택적으로 후보 모듈을 이름으로 필터링하며, is_fusable(...)로 호환 가능한 모듈 클래스를 발견해요.
  4. 퓨전된 교체 클래스는 register_patch_mapping()으로 등록돼요.
  5. config에서 일치하는 ~WeightTransform 규칙이 생성되어 체크포인트 로딩이 가중치를 퓨전된 런타임 레이아웃으로 매핑할 수 있게 해요.
  6. 기본적으로 save_pretrained()은 역변환 경로를 사용해서 원래 체크포인트 레이아웃을 복원해요. 변환된 런타임 레이아웃을 유지하려면 save_original_format=False를 전달해요.

이를 통해 퓨전은 원래 체크포인트 형식에서 여전히 로드하면서(그리고 기본적으로 그 형식으로 다시 저장하면서) 다른 런타임 모듈 구조를 사용할 수 있어요.

참고: 현재 monkey-patching 메커니즘에서 퓨전 등록은 클래스 수준이에요. 호환 모듈 클래스 하나가 퓨전된 교체 클래스 하나에 매핑돼요.

현재 퓨전 패밀리

현재 fusion_config는 하나의 퓨전 패밀리를 지원해요:

  • patch_embeddings 활성화:

    fusion_config = {"patch_embeddings": True}

    효과: 호환되는 nn.Conv3d 패치 임베딩 프로젝션을 런타임에서 동등한 평탄화된 nn.Linear 프로젝션으로 교체해요.

퓨전 매핑 확장하기

새 퓨전 패밀리를 추가하려면:

  1. is_fusable 프레디케이트를 추가해요. 발견된 모듈이 퓨전과 호환되는지 결정해요.
  2. 선택적으로 target_modules_patterns를 추가해요. 이는 is_fusable(...) 전에 후보 모듈 이름을 사전 필터링해서 발견 단계를 더 명시적으로 만들어요.
  3. make_fused_class 팩토리를 추가해요. 호환 모듈 클래스에 대한 런타임 교체 클래스를 반환해요.
  4. 퓨전된 레이아웃에 체크포인트 변환이 필요하면 make_transforms 팩토리를 추가해요. 주어진 config에 대해 원래 레이아웃과 퓨전된 레이아웃 사이에서 가중치를 매핑하는 ~WeightTransform 규칙을 반환해요.
  5. 새 ModuleFusionSpec을 fusion_mapping.py에 등록해요.

등록되면 새 퓨전은 fusion_config를 통해 사용 가능해져요.

내부 API[[transformers.fusion_mapping.ModuleFusionSpec]]

transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

transformers.fusion_mapping.ModuleFusionSpec()

Source

퓨전 패밀리의 기본 레시피예요.

퓨전 스펙은 어떤 모듈이 퓨전에 적합한지, 런타임 교체 클래스를 어떻게 만들지, 원래 레이아웃과 퓨전된 레이아웃 사이에서 체크포인트를 매핑하는 데 필요한 가중치 변환이 무엇인지 결정해요.

get_empty_log[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

get_empty_log(model_name: str)

Source

호환 모듈을 찾지 못했을 때 방출되는 로그 메시지를 반환해요.

is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

is_fusable(module: Module)

Source

module이 이 퓨전 패밀리와 호환되는지 반환해요.

make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

make_fused_class(original_cls: type)

Source

호환 모듈 클래스에 대한 런타임 교체 클래스를 만드세요.

make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

make_transforms(config: PretrainedConfig)

Source

퓨전된 런타임 레이아웃을 로드하고 저장하는 데 필요한 가중치 변환을 만드세요.

transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

transformers.fusion_mapping.PatchEmbeddingsFusionSpec()

Source

호환되는 Conv3d 패치 임베딩을 평탄화된 Linear 프로젝션으로 퓨전해요.

transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)

Source

cls에 대해 퓨전 패밀리 하나를 등록해요.

이 함수는 퓨전된 로딩에 사용되는 두 개의 전역 레지스트리를 업데이트해요:

  • monkey-patching 레지스트리: 호환 모듈 클래스가 초기화 전에 교체되도록 해요.
  • 체크포인트 변환 매핑: 퓨전된 런타임 모듈이 여전히 원래 체크포인트 레이아웃에서 로드되도록 해요.

참고:

  • 충돌하는 체크포인트 변환은 빠르게 실패해요(fail fast).

transformers.fusion_mapping.register_fusion_patches[[transformers.fusion_mapping.register_fusion_patches]]

transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)

Source

cls에 대해 요청된 런타임 퓨전을 등록해요.

이 함수는:

  • _FUSION_REGISTRY에 대해 fusion_config를 검증해요.
  • 사용자 순서대로 활성화된 퓨전 패밀리를 해석해요.
  • 모델 인스턴스화 전에 monkey patch와 체크포인트 변환을 등록해요.

더 알아보기 (Learn more)