Fusion 매핑 (실험적 기능)

Fusion mapping은 원래의 체크포인트 형식을 유지하면서 로드 시점에 모델의 서브모듈을 교체할 수 있는 선택적(opt-in) 방법을 제공합니다.

다음에 기반합니다:

• 모델 인스턴스화 전에 모듈 클래스를 교체하기 위한 Monkey patching.
• 원래 런타임 레이아웃과 병합된 런타임 레이아웃 사이에서 가중치를 매핑하기 위한 동적 가중치 로딩

Fusion mapping은 실험적 로딩 기능입니다. 런타임 모듈 구조를 변경하며 모델 동작에 영향을 줄 수 있습니다. 명시적으로 fused 런타임 레이아웃을 원할 때만 사용하세요.

빠른 시작

fusion_config를 사용하여 from_pretrained()를 통해 Fusion을 활성화합니다:

from transformers import AutoModelForImageTextToText


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

기본적으로 퓨전은 적용되지 않습니다. fusion_config가 모델 설정에 저장되어 있으면, from_pretrained()가 이를 자동으로 재사용합니다.

작동 방식

Fusion 등록은 모델이 인스턴스화되기 전에 수행됩니다:

1. from_pretrained()는 명시적인 fusion_config 인수를 사용하거나 config.fusion_config로 폴백합니다.
2. fusion registry는 요청된 fusion 이름을 검증합니다.
3. 각 활성화된 fusion은 대상 모델 클래스를 메타 초기화하고, 필요에 따라 모듈 이름을 기준으로 후보 모듈을 필터링하며, is_fusable(...)를 사용하여 호환되는 모듈 클래스를 탐색합니다.
4. Fused replacement classes는 register_patch_mapping()을 통해 등록됩니다.
5. config에서 ~WeightTransform 규칙을 생성하여 체크포인트 로드 시 가중치를 융합된 런타임 레이아웃으로 매핑할 수 있습니다.
6. 기본적으로 save_pretrained()는 원래의 체크포인트 레이아웃을 복원하기 위해 역방향 변환 경로를 사용합니다. 변환된 런타임 레이아웃을 유지하려면 save_original_format=False를 전달하세요.

이를 통해 fusion은 원래의 checkpoint 형식에서 로드하고 기본적으로 다시 저장하는 것을 유지하면서 다른 런타임 모듈 구조를 사용할 수 있습니다.

Note: 현재 monkey-patching 메커니즘에서는 fusion 등록이 클래스 수준입니다: 하나의 호환 가능한 모듈 클래스가 하나의 fused 대체 클래스에 매핑됩니다.

현재의 fusion 계열

현재 fusion_config는 하나의 fusion family를 지원합니다:

• patch_embeddings 활성화 방법:

  복사됨

  fusion_config = {"patch_embeddings": True}

  Effect: 호환되는 nn.Conv3d 패치 임베딩 투영을 런타임에 동등한 평탄화된 nn.Linear 투영으로 대체합니다.

퓨전 매핑 확장

새로운 fusion family를 추가하려면:

1. is_fusable 판정 조건을 추가합니다. 이 판정 조건은 발견된 모듈이 퓨전과 호환되는지 여부를 결정합니다.
2. target_modules_patterns를 선택적으로 추가할 수 있습니다. 이렇게 하면 is_fusable(...) 호출 전에 후보 모듈 이름을 사전 필터링하여 탐색 단계를 더 명시적으로 만듭니다.
3. make_fused_class 팩토리를 추가합니다. 호환되는 모듈 클래스에 대한 런타임 대체 클래스를 반환합니다.
4. fused layout에 checkpoint 변환이 필요한 경우 make_transforms 팩토리를 추가합니다. 이 팩토리는 주어진 config에 대해 원래 layout과 fused layout 사이에서 가중치를 매핑하는 ~WeightTransform 규칙을 반환합니다.
5. ModuleFusionSpec을 fusion_mapping.py에 등록합니다.

등록이 완료되면, 새로운 fusion은 fusion_config를 통해 사용할 수 있게 됩니다.

내부 API