Transformers documentation
모델
모델
기본 클래스 PreTrainedModel은 로컬 파일 또는 디렉터리에서, 또는 라이브러리가 제공하는 사전 학습된 모델 구성( HuggingFace Hub에서 다운로드)에서 모델을 로드/저장하는 데 사용되는 공통 메서드를 구현합니다.
PreTrainedModel은 모든 모델에서 공통적으로 사용되는 몇 가지 메서드를 구현합니다:
- 새로운 토큰이 어휘에 추가되면 입력 토큰 임베딩을 리사이즈합니다
각 모델에 공통적으로 적용되는 다른 메서드는 ModuleUtilsMixin과 GenerationMixin에 정의되어 있습니다.
PreTrainedModel
모든 모델의 베이스 클래스입니다.
PreTrainedModel은 모델의 구성을 저장하는 역할을 하며, 모델의 로딩, 다운로드 및 저장과 모든 모델에 공통적인 몇 가지 메서드를 처리합니다:
- 입력 임베딩을 리사이즈합니다
클래스 속성(파생 클래스에 의해 재정의됨):
- config_class (PreTrainedConfig) — 이 모델 아키텍처의 구성 클래스로 사용할 PreTrainedConfig의 하위 클래스
- base_model_prefix (
str) — 같은 아키텍처의 파생 클래스에서 베이스 모델 위에 모듈을 추가할 때, 베이스 모델과 연관된 속성을 나타내는 문자열입니다. - main_input_name (
str) — 모델의 주요 입력 이름 (NLP 모델의 경우 보통input_ids, 비전 모델의 경우pixel_values, 음성 모델의 경우input_values입니다). - can_record_outputs (dict):
push_to_hub
< source >( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )
매개변수
- repo_id (
str) — 모델을 푸시하려는 저장소의 이름입니다. 특정 조직에 푸시할 경우 조직 이름을 포함해야 합니다. - commit_message (
str, 선택 사항) — 푸시할 때 커밋할 메시지입니다. 기본값은"Upload model"입니다. - commit_description (
str, 선택 사항) — 생성될 커밋의 설명 - private (
bool, 선택 사항) — 리포지토리를 비공개로 만들지 여부를 지정합니다.None(기본값)인 경우, 조직의 기본 설정이 비공개가 아닌 한 리포지토리는 공개됩니다. 리포지토리가 이미 존재하면 이 값은 무시됩니다. - token (
bool또는str, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True(기본값)인 경우,hf auth login실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다. - revision (
str, 선택 사항) — 업로드된 파일을 푸시할 브랜치. - create_pr (
bool, 선택 사항, 기본값False) — 업로드된 파일로 PR을 생성할지 아니면 직접 커밋할지 여부. - max_shard_size (
int또는str, 선택 사항, 기본값"50GB") — 모델에만 적용됩니다. 샤딩되기 전 체크포인트의 최대 크기입니다. 샤딩된 각 체크포인트의 크기는 이 크기보다 작아집니다. 문자열로 표현하는 경우, 숫자 뒤에 단위(예:"5MB")가 따라와야 합니다. - tags (
list[str], 선택) — Hub에 push할 태그 목록.
모델 파일을 🤗 Model Hub에 업로드합니다.
예:
from transformers import AutoModel
model = AutoModel.from_pretrained("google-bert/bert-base-cased")
# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")
# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")현재 모델에 대한 activation checkpointing을 비활성화합니다.
activation_checkpointing_enable
< source >( activation_checkpointing_kwargs = Noneevery_n_layers: int = 1offload: bool = False )
매개변수
- every_n_layers (
int, 선택 사항, 기본값 1) —every_n_layers번째 디코더 레이어만 체크포인트를 생성하고, 나머지 레이어는 활성화 값을 유지합니다.1은 모든 레이어에 대해 체크포인트를 생성하며, 이는 일반적인 전수 처리 동작입니다. 값이 커질수록 메모리를 절약하는 대신 속도가 느려지는데, 전체 체크포인트로 확보된 메모리가 유휴 상태인 경우에는 이러한 트레이드오프가 가치가 있습니다. - offload (
bool, 선택 사항, 기본값False) — 재계산을 위해 저장된 activations를 가속기 대신 고정된 호스트 메모리에 유지합니다. 이로써layers x sequence x hidden바이트의 디바이스 메모리가 해제되며, 이는 긴 시퀀스 길이에서 지배적인 요소입니다. 대신 forward에서는 디바이스에서 호스트로의 복사, backward에서는 호스트에서 디바이스로의 복사가 발생합니다. 두 복사 작업 모두 compute stream에서 실행되므로 step이 느려집니다. - activation_checkpointing_kwargs (dict, 선택 사항) —
torch.utils.checkpoint.checkpoint함수에 함께 전달되는 추가 키워드 인자입니다.
현재 모델에 대해 activation checkpointing을 활성화합니다.
모듈의 __call__ 메서드를 forward 대신 전달하는 이유는 __call__이 모듈의 모든 훅을 연결하기 때문입니다. https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2
Hugging Face Hub에 푸시되는 모델에 사용자 정의 태그를 추가합니다. 모델의 기존 태그는 덮어쓰지 않습니다.
.generate()를 통해 이 모델이 GenerationMixin 또는 유사한 인터페이스를 가진 것으로부터 시퀀스를 생성할 수 있는지 여부를 반환합니다.
내부적으로, 이 함수가 True를 반환하는 클래스에서는 생성 관련 변경 사항이 트리거됩니다. 예를 들어, 모델 인스턴스에 generation_config 속성이 설정됩니다.
점으로 구분된 경로(예: torch.float32)에 대한 mock 값: 속성 접근 체인, 호출은 pass-through 데코레이터처럼 동작하며, repr은 해당 점으로 구분된 경로입니다. 이를 베이스 클래스로 사용하면 plain-type 베이스로 대체됩니다(PEP 560 __mro_entries__). 따라서 실제 서브클래스는 일반적인 메타클래스를 유지하고, inspect.signature는 mock의 __init__가 아닌 실제 __init__를 읽습니다.
양자화 방법 중 역양자화를 지원하는 것으로 양자화된 경우, 모델을 역양자화할 수 있습니다.
_require_grads_hook를 제거합니다.
입력 임베딩의 기울기를 활성화합니다. 이는 모델 가중치를 고정 상태로 유지하면서 어댑터 가중치를 미세 조정하는 데 유용합니다.
from_pretrained
< source >( pretrained_model_name_or_path: str | os.PathLike | None*model_argsconfig: transformers.configuration_utils.PreTrainedConfig | str | os.PathLike | None = Nonecache_dir: str | os.PathLike | None = Noneignore_mismatched_sizes: bool = Falseforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'use_safetensors: bool | None = Noneweights_only: bool = Truefusion_config: dict[str, bool | dict[str, typing.Any]] | None = Nonedisable_mmap: bool | None = None**kwargs )
매개변수
- pretrained_model_name_or_path (
str또는os.PathLike, 선택 사항) — 다음 중 하나일 수 있습니다:- huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 model id를 나타내는 문자열입니다.
- save_pretrained()를 사용하여 모델 가중치를 저장한 디렉터리의 경로입니다. 예:
./my_model_directory/.save_pretrained(..., distributed_checkpoint=True)로 저장된 디렉터리는 분산 체크포인트(DCP)로 감지 및 로드되며, 모델의 현재 메시와 배치 설정이 유지됩니다. 이 기능은torch>=2.7이 필요하며, 모든 모델 키가 체크포인트에 존재해야 하는 엄격한 로드를 수행합니다. None는 구성과 상태 사전(각각config및state_dict키워드 인수로)을 모두 제공하는 경우입니다.
- model_args (위치 인자의 시퀀스, 선택 사항) —
나머지 모든 위치 인자는 기본 모델의
__init__메서드에 전달됩니다. - config (
Union[PreTrainedConfig, str, os.PathLike], 선택 사항) — 다음 중 하나일 수 있습니다:- PreTrainedConfig에서 파생된 클래스의 인스턴스,
- from_pretrained()의 입력으로 유효한 문자열 또는 경로
자동 로드된 구성 대신 사용할 모델의 구성입니다. 구성은 다음 경우에 자동으로 로드될 수 있습니다:
- 모델은 라이브러리가 제공하는 모델(사전 학습된 모델의 model id 문자열로 로드됨)입니다.
- 모델은 save_pretrained()를 사용하여 저장되었으며, 저장 디렉토리를 제공하여 다시 로드됩니다.
- 로컬 디렉토리를
pretrained_model_name_or_path로 제공하고 해당 디렉토리에 config.json이라는 이름의 구성 JSON 파일이 있으면 모델이 로드됩니다.
- state_dict (
dict[str, torch.Tensor], 선택 사항) — 저장된 가중치 파일에서 로드한 state dictionary 대신 사용할 state dictionary입니다. 사전 학습된 구성으로 모델을 생성하되 자체 가중치를 로드하려는 경우에 이 옵션을 사용할 수 있습니다. 이 경우 save_pretrained()와 from_pretrained()를 사용하는 것이 더 간단한 옵션인지 확인해야 합니다.이 옵션은 사전 학습된 구성을 기반으로 모델을 생성하되, 자체 가중치를 로드하려는 경우에 사용할 수 있습니다. 이 경우 save_pretrained()와 from_pretrained()를 사용하는 것이 더 간단한 옵션인지 확인해 보시기 바랍니다.
- cache_dir (
Union[str, os.PathLike], 선택) — 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성을 캐시할 디렉터리의 경로입니다. - ignore_mismatched_sizes (
bool, 선택 사항, 기본값False) — 체크포인트의 일부 가중치가 모델의 가중치와 크기가 다른 경우(예: 3개의 라벨이 있는 체크포인트에서 10개의 라벨을 가진 모델을 인스턴스화하는 경우) 에러를 발생시킬지 여부. - force_download (
bool, 선택 사항, 기본값False) — 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부입니다. 캐시된 버전이 존재하는 경우 이를 무시합니다. - proxies (
dict[str, str], 선택) — 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전, 예:{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. 각 요청에 프록시가 사용됩니다. - output_loading_info(
bool, optional, 기본값False) — 누락된 키, 예상치 못한 키 및 오류 메시지를 포함하는 사전도 함께 반환할지 여부. - local_files_only(
bool, 선택 사항, 기본값False) — 로컬 파일만 참조할지 여부(모델 다운로드를 시도하지 않음). - token (
str또는bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True이거나 지정되지 않은 경우,hf auth login실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다. - revision (
str, 선택 사항, 기본값은"main") — 사용할 특정 모델 버전입니다. huggingface.co에서 모델과 기타 아티팩트를 저장하기 위해 git 기반 시스템을 사용하므로, 브랜치 이름, 태그 이름, 커밋 ID일 수 있습니다. 따라서revision은 git에서 허용하는 모든 식별자를 사용할 수 있습니다.Hub에서 만든 pull request를 테스트하려면
revision="refs/pr/<pr_number>"를 전달할 수 있습니다. - attn_implementation (
str, 선택 사항) — 모델에서 사용할 어텐션 구현 방식(해당하는 경우). "eager"(어텐션의 수동 구현), "sdpa"(F.scaled_dot_product_attention 사용), "flash_attention_2"(Dao-AILab/flash-attention 사용), "flash_attention_3"(Dao-AILab/flash-attention/hopper 사용), "flash_attention_4"(Dao-AILab/flash-attention/flash_attn/cute 사용) 중 하나를 사용할 수 있습니다. 기본적으로 사용 가능한 경우 SDPA가 사용됩니다. 그렇지 않으면 수동 "eager" 구현이 기본값입니다. /[@][:] 형태의 HF 커널 참조를 허용하며, /와 :를 제외한 모든 문자열이 가능합니다. “@”는 선택 사항이며(브랜치, 태그 또는 커밋 유사 값), 예를 들어 “@main”, “@v1.2.0”, “@abc123”와 같습니다. ”:”는 선택 사항이며 커널 저장소 내의 함수를 선택합니다. 두 옵션은 함께 나타날 수 있으며, 이 순서로만 가능합니다: 먼저 @revision, 그 다음 :kernel_name. 코드가 로드 전에 이를 제거하기 때문에 선행 ”|” 접두사(예: “flash|…”)를 의도적으로 허용합니다. 여기의 문자 클래스에서 ’|’는 제외되지 않습니다. 일치하는 예시: “org/model” “org/model@main” “org/model:custom_kernel” “org/model@v1.2.3:custom_kernel”"eager"(attention의 수동 구현)"sdpa"(F.scaled_dot_product_attention사용)"flash_attention_2"(Dao-AILab/flash-attention 사용)"flash_attention_3"(Dao-AILab/flash-attention/hopper 사용)"flash_attention_4"(Dao-AILab/flash-attention/flash_attn/cute 사용). 기본적으로 사용 가능한 경우 SDPA가 사용됩니다. 그렇지 않으면 기본값은 수동"eager"구현입니다.
다음 형식의 HF 커널 참조를 허용합니다:
/ [@ ][: ] 과 은 "/"와 ":"가 아닌 임의의 문자열입니다. - “@
”은 선택 사항(브랜치, 태그 또는 커밋-ish)이며, 예를 들어 “@main”, “@v1.2.0”, “@abc123”과 같습니다. - ”:
”은 선택 사항이며 커널 저장소 내의 함수를 선택합니다. - 두 옵션은 함께 나타날 수 있으며, 이 순서로만 나타납니다: @revision이 먼저, 그 다음 :kernel_name입니다.
- 코드가 로딩 전에 이를 제거하기 때문에, 여기의 문자 클래스에서 '|'가 제외되지 않는다는 점을 고려하여, 의도적으로 "
|" 접두사(예: "flash|…")를 허용합니다.
다음과 일치하는 예시: “org/model” “org/model@main” “org/model:custom_kernel” “org/model@v1.2.3:custom_kernel”
- experts_implementation (
str, 선택 사항) — 모델에서 사용할 experts 구현 방식(해당하는 경우)입니다. 다음 중 하나를 사용할 수 있습니다:"eager"(전문가 행렬 곱셈의 순차적 구현)."batched_mm"(torch.bmm사용)."grouped_mm"(torch.nn.functional.grouped_mm사용).
기본적으로 모델이 지원하는 경우
"grouped_mm"가 사용됩니다. 그렇지 않으면 기본값은 수동"eager"구현입니다.
대형 모델 추론을 위한 매개변수
- dtype (
str또는torch.dtype, 선택 사항, 기본값은"auto") — 기본값을 재정의하여torch_dtype모델을 특정dtype. 다음과 같은 옵션이 있습니다:-
torch.float16또는torch.bfloat16또는torch.float: 지정된dtype로 로드하며, 모델에config.dtype이 있는 경우 이를 무시합니다. 지정되지 않은 경우- 모델은
torch.float(fp32)로 로드됩니다.
- 모델은
-
"auto"- 모델의config.json파일에 있는dtype또는torch_dtype항목을 사용하려고 시도합니다. 이 항목을 찾을 수 없으면, 체크포인트에서 플로팅 포인트 타입인 첫 번째 가중치의dtype를 확인하여 이를dtype으로 사용합니다. 이를 통해 모델은 학습이 끝난 시점에 저장되었던dtype으로 로드됩니다. 이는 모델이 어떻게 학습되었는지를 나타내는 지표로 사용할 수 없습니다. 반정밀도 dtype로 학습되었지만 fp32로 저장된 경우일 수 있기 때문입니다. -
torch.dtype로 유효한 문자열입니다. 예를 들어, “float32”는 모델을torch.float32로, “float16”은torch.float16로 로드합니다.
일부 모델의 경우 학습에 사용된
dtype이 알려져 있지 않습니다 - 모델의 논문을 확인하거나, 저자에게 연락하여 모델 카드에 이 정보를 추가하고 허브의config.json에dtype또는torch_dtype항목을 삽입해 달라고 요청해 볼 수 있습니다. -
- device_map (
str또는dict[str, Union[int, str, torch.device]]또는int또는torch.device, 선택 사항) — 각 서브모듈이 어디에 배치되어야 하는지 지정하는 맵입니다. 각 파라미터/버퍼 이름까지 세분화할 필요는 없으며, 특정 모듈 이름이 포함되면 해당 모듈의 모든 서브모듈이 동일한 장치로 전송됩니다. 장치만 전달하는 경우(e.g.,"cpu","cuda:1","mps", 또는 모델이 할당될 GPU 순서 순위, 예:1) )와 같이, 모델이 할당될 장치를 지정하면 디바이스 맵은 전체 모델을 해당 장치에 매핑합니다.device_map = 0을 전달하면 전체 모델을 GPU 0에 배치하는 것을 의미합니다. Accelerate가 가장 최적화된 device_map을 자동으로 계산하도록 하려면 device_map="auto"로 설정하세요. 각 옵션에 대한 자세한 내용은 디바이스 맵 설계 문서를 참고하세요.가장 최적화된
device_map을 Accelerate가 자동으로 계산하도록 하려면device_map="auto"를 설정하세요. 각 옵션에 대한 자세한 내용은 device map 설계를 참고하세요. - max_memory (
Dict, 선택 사항) —device_map을 사용하는 경우, 장치 식별자를 최대 메모리로 매핑하는 사전입니다. 설정하지 않으면 각 GPU의 사용 가능한 최대 메모리와 사용 가능한 CPU RAM이 기본값으로 사용됩니다. - distributed_config (DistributedConfig, 선택 사항) —
텐서 병렬 또는 FSDP2를 사용한 네이티브 분산 로딩에 대한 설정입니다. 모델의 사전 정의된 텐서 병렬 플랜을 사용하려면
DistributedConfig(tp_size=N)을, 텐서 병렬 플랜을 지정하려면DistributedConfig(tp_plan=...)을, FSDP2를 사용하려면DistributedConfig(fsdp_size=N)을 전달합니다.tp_size > 1또는fsdp_size > 1인 경우torchrun과 초기화된 프로세스 그룹이 필요합니다.device_map과 상호 배타적입니다. - device_mesh (
torch.distributed.DeviceMesh, 선택 사항) — torch device mesh입니다. 제공되지 않으면 world size를 기본값으로 사용합니다. 현재는 tensor parallel에만 사용됩니다. 제공하는 경우, 차원이 1보다 큰 경우"tp"라는 이름의 차원을 포함해야 하며, 이 차원이 tensor parallelism에 사용됩니다. - offload_folder (
str또는os.PathLike, 선택 사항) —device_map에"disk"값이 하나 이상 포함된 경우, 가중치를 오프로드할 폴더입니다. - offload_buffers (
bool, 선택 사항) — 모델 파라미터와 함께 버퍼를 오프로드할지 여부. - quantization_config (
Union[QuantizationConfigMixin,Dict], 선택 사항) — 양자화를 위한 구성 매개변수 사전 또는 QuantizationConfigMixin 객체 (예: bitsandbytes, gptq). - subfolder (
str, 선택 사항, 기본값"") — huggingface.co의 모델 저장소에서 관련 파일이 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다. - variant (
str, 선택 사항) — 지정된 경우variant파일명에서 가중치를 로드합니다. 예를 들어 pytorch_model..bin. - use_safetensors (
bool, 선택 사항, 기본값None) —safetensors체크포인트를 사용할지 여부입니다. 기본값은None입니다. 지정되지 않았고safetensors가 설치되어 있지 않은 경우False로 설정됩니다. - weights_only (
bool, 선택 사항, 기본값True) — unpickler가 텐서, 원시 타입, 딕셔너리 및 torch.serialization.add_safe_globals()를 통해 추가된 타입만 로드하도록 제한할지 여부를 나타냅니다. False로 설정하면 래퍼 텐서 서브클래스의 가중치를 로드할 수 있습니다. - disable_mmap (
bool, 선택 사항) — safetensors 체크포인트를 로드할 때 메모리 매핑을 비활성화할지 여부입니다.None(기본값)인 경우, 체크포인트가hf-mountFUSE 파일 시스템( HF Spaces/Endpoints에서 사용)에 위치하면 mmap과 병렬 페이지 폴트가 데드락을 일으킬 수 있으므로True로 자동 감지됩니다.True인 경우, 파일이 메모리에 완전히 로드되고safetensors.torch.load로 파싱됩니다.False인 경우, 항상 기본 메모리 매핑 로더가 사용됩니다. - fusion_config (
dict[str, bool | dict[str, Any]], 선택) — 모델 인스턴스화 전에 적용되는 선택적 fusion 구성입니다. 각 키는 fusion family를 활성화하며, 그 값은 해당 fusion을 기본 옵션으로 활성화하기 위한True또는 family별 옵션의 사전(dict)일 수 있습니다. 예를 들어,{"patch_embeddings": True}는 patch embedding fusion을 활성화합니다. 이는 출력을 약간 변경할 수 있으므로 추론 최적화 목적으로만 사용해야 합니다. 생략된 경우,from_pretrained()는 사용 가능한 경우config.fusion_config로 fallback합니다. 자세한 내용은docs/source/en/fusion_mapping.md의 fusion mapping 가이드를 참조하세요. - key_mapping (`dict[str, str], 선택) — Hub에서 Transformers 아키텍처와 호환되지만 해당 아키텍처에 맞게 변환되지 않은 모델을 사용할 경우, 가중치 이름의 매핑을 지정할 수 있습니다.
- kwargs (키워드 인수의 나머지 사전, 선택 사항) —
구성 객체를 업데이트(로드된 후)하고 모델을 초기화하는 데 사용할 수 있습니다(예:
output_attentions=True). 다음과 같이 동작하며,config이 제공되었는지 또는 자동으로 로드되었는지에 따라 다릅니다:config로 설정이 제공되면,**kwargs는 기본 모델의__init__메서드에 직접 전달됩니다(설정과 관련된 모든 업데이트가 이미 수행된 것으로 가정합니다).- 설정이 제공되지 않으면
kwargs가 먼저 설정 클래스의 초기화 함수(from_pretrained())에 전달됩니다.kwargs의 각 키 중 설정 속성에 해당하는 키는 제공된kwargs값으로 해당 속성을 덮어쓰는 데 사용됩니다. 설정 속성에 해당하지 않는 나머지 키는 기본 모델의__init__함수에 전달됩니다.
pytorch 사전 학습 모델 구성에서 사전 학습된 모델을 인스턴스화합니다.
model.eval()을 사용하여 기본적으로 모델이 평가 모드로 설정됩니다(Dropout 모듈은 비활성화됨). 모델을 학습하려면 먼저 model.train()을 사용하여 모델을 학습 모드로 되돌려야 합니다.
The warning Weights from XXX not initialized from pretrained model means that the weights of XXX do not come pretrained with the rest of the model. It is up to you to train those weights with a downstream fine-tuning task.
경고 Weights from XXX not used in YYY는 XXX 레이어가 YYY에서 사용되지 않으므로 해당 가중치가 폐기됨을 의미합니다.
방화벽이 있는 환경에서 이 방법을 사용하려면 특수 “offline-mode”를 활성화하세요.
예:
>>> from transformers import BertConfig, BertModel
>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == Trueget_compiled_call
< source >( compile_config: transformers.generation.configuration_utils.CompileConfig | None )
torch.compile된 self.__call__ 버전을 반환합니다. 이는 추론 중에 컴파일되지 않은/컴파일된 forward를 동적으로 선택하는 데 유용합니다. 특히, 새로운 shape으로 인해 그래프를 다시 계산하는 것을 피하기 위해 컴파일된 버전을 사용하지 않는 prefill과, 정적 shape을 가진 컴파일된 버전의 속도 향상을 원하는 반복적 디코딩 사이를 전환할 때 유용합니다.
decoder 모듈의 최선 노력 조회.
시도 순서 (현재 사용 사례의 약 85%를 포함):
self.decoder/self.language_model/self.text_modelself.base_model(많은 래퍼가 여기서 디코더를 저장합니다)self.base_model.get_decoder()(중첩 래퍼)- fallback: 맞춤형 규칙이 필요한 소수의 특수한 모델에 대해 예외를 발생시킵니다
encoder 모듈을 최선의 노력으로 조회합니다. modality 인수가 제공되면, 멀티모달 모델에서 모달리티별 인코더(예: “image_encoder”)를 찾습니다. 기본적으로 이 함수는 모델에 텍스트 인코더가 있으면 이를 반환하고, 그렇지 않으면 self를 반환합니다.
modality의 가능한 값은 “image”, “video”, “audio”입니다.
현재 모델에 대해서만, 또는 all_submodels=True인 경우 모든 서브모델에 대해 재귀적으로(즉, 모든 서브모델의 config 값을 다시 확인합니다) 확장된 tied weight 키(모듈이나 정규식 패턴을 포함하는 경우)를 반환합니다.
거의 모든 모델의 경우 임베딩을 묶는 것만 필요하므로, 모델에는 _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}라는 내부 속성이 있습니다. 이 경우 매핑은 이미 “확장”된 상태, 즉 전체 파라미터를 이미 포함하고 있으며, 이 함수는 해당 속성의 복사본을 단순히 반환합니다. DFineForObjectDetection과 같은 더 복잡한 패턴의 경우, 다음과 같은 속성이 있습니다
_tied_weights_keys = {
r"bbox_embed.(?![0])\d+": "bbox_embed.0",
r"class_embed.(?![0])\d+": "class_embed.0",
"model.decoder.class_embed": "class_embed",
"model.decoder.bbox_embed": "bbox_embed",
}다음과 같은 값을 반환합니다:
{
'bbox_embed.1.layers.0.bias': 'bbox_embed.0.layers.0.bias',
'bbox_embed.1.layers.0.weight': 'bbox_embed.0.layers.0.weight',
'bbox_embed.1.layers.1.bias': 'bbox_embed.0.layers.1.bias',
'bbox_embed.1.layers.1.weight': 'bbox_embed.0.layers.1.weight',
'bbox_embed.1.layers.2.bias': 'bbox_embed.0.layers.2.bias',
'bbox_embed.1.layers.2.weight': 'bbox_embed.0.layers.2.weight',
'bbox_embed.2.layers.0.bias': 'bbox_embed.0.layers.0.bias',
'bbox_embed.2.layers.0.weight': 'bbox_embed.0.layers.0.weight',
...
'class_embed.1.bias': 'class_embed.0.bias',
'class_embed.1.weight': 'class_embed.0.weight',
'class_embed.2.bias': 'class_embed.0.bias',
'class_embed.2.weight': 'class_embed.0.weight',
...
'model.decoder.class_embed.0.bias': 'class_embed.0.bias',
'model.decoder.class_embed.0.weight': 'class_embed.0.weight',
'model.decoder.class_embed.1.bias': 'class_embed.0.bias',
'model.decoder.class_embed.1.weight': 'class_embed.0.weight',
...
'model.decoder.bbox_embed.0.layers.0.bias': 'bbox_embed.0.layers.0.bias',
'model.decoder.bbox_embed.0.layers.0.weight': 'bbox_embed.0.layers.0.weight',
'model.decoder.bbox_embed.0.layers.1.bias': 'bbox_embed.0.layers.1.bias',
'model.decoder.bbox_embed.0.layers.1.weight': 'bbox_embed.0.layers.1.weight',
...
}이 모델 및 하위 모델의 experts 구현을 set_experts_implementation이 허용하는 형식의 dict로 반환합니다(이 모델은 "", 각 sub_config당 하나의 항목). 이는 set_experts_implementation의 대응 함수로, 예를 들어 현재 구현을 스냅샷으로 저장하고 나중에 복원하는 데 사용할 수 있습니다.
get_memory_footprint
< source >( return_buffers = True )
매개변수
- return_buffers (
bool, 선택 사항, 기본값True) — 메모리 사용량 계산 시 버퍼 텐서의 크기를 반환할지 여부입니다. 버퍼는 그래디언트가 필요하지 않고 파라미터로 등록되지 않은 텐서를 의미합니다. 예를 들어, 배치 정규화 레이어의 mean과 std가 해당됩니다. 자세한 내용은 https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2를 참고하세요.
모델의 메모리 사용량을 가져옵니다. 현재 모델의 메모리 사용량을 바이트 단위로 반환합니다. 현재 모델의 메모리 사용량을 벤치마크하고 테스트를 설계하는 데 유용합니다. PyTorch 토론에서 영감을 받은 솔루션: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2
target로 지정된 parameter 또는 buffer가 존재하면 반환하고, 그렇지 않으면 오류를 발생시킵니다. 이 함수는 get_parameter()와 get_buffer()를 하나의 편리한 함수로 결합합니다. 대상이 _extra_state 속성인 경우, 모듈이 제공하는 extra state를 반환합니다. target가 모델의 leaf여야만 작동한다는 점에 유의하세요.
activation_checkpointing_disable()의 비추천 별칭이며, v6에서 제거됩니다.
activation_checkpointing_enable()의 비추천되는 별칭이며, v6에서 제거됩니다.
필요한 경우 가중치를 초기화하고 연결합니다. 사용자 정의 PreTrainedModel을 사용하는 경우 _init_weights에 초기화 로직을 구현해야 합니다.
이것은 self.apply(self._initialize_weights)를 호출하는 것과 동일하지만, 복합 모델을 올바르게 처리합니다.
이 함수는 재귀를 따라 모듈 그래프를 진행하면서 각 모듈에 올바른 init_weights 함수를 동적으로 분기합니다. 임의의 개수의 서브모델을 처리할 수 있습니다. 이 함수가 없다면, 모든 복합 모델은 가장 바깥쪽 _init_weights에서 모든 서브모델에 대해 명시적으로 두 번째 재귀를 수행해야 하며, 이는 매우 오류가 많고 비효율적입니다.
현재 모델이 커스텀 코드인지 반환합니다. 즉, 허브에서 로드된 코드이거나 사용자 특정 모듈/세션에서 정의된 코드인 경우입니다.
현재 모델이 커스텀 코드인지, 즉 허브에서 로드된 코드인지, 아니면 register_for_auto_class를 통해 방금 등록한 클래스인지 여부를 반환합니다.
나중에 연결(overwritten)될 매개변수에 _is_hf_initialized 플래그를 추가하여, 이후 초기화를 실행하지 않도록 합니다. 대부분의 임베딩이 연결되어 있고, 이는 어휘 크기(종종 256k)만큼 큰 매개변수이므로, 이러한 매개변수에 초기화를 실행하는 것은 매우 비용이 많이 듭니다.
named_buffers와 유사하지만, 비영속적인 것만 반환합니다. 버퍼가 영속적인지 아닌지를 정확히 파악하기가 쉽지 않으므로 유용합니다.
각 Transformer 모델 초기화 끝에 실행되는 메서드로, 모델의 모듈이 올바르게 초기화된 후에 실행해야 하는 코드(가중치 초기화 등)를 실행합니다. 복합 모델(즉, 최상위 모델이 자식 모델로부터 해당 속성을 알아야 하는 경우)의 경우에도 모든 올바른 정적 속성(병렬화 계획, tied_weights_keys, _keep_in_fp32_modules 등)을 올바르게 가져오기 위해 사용됩니다.
register_for_auto_class
< source >( auto_class = 'AutoModel' )
이 클래스를 지정된 auto class에 등록합니다. 라이브러리에 포함된 모델은 이미 auto class에 매핑되어 있으므로, 이 메서드는 커스텀 모델에만 사용해야 합니다.
resize_token_embeddings
< source >( new_num_tokens: int | None = Nonepad_to_multiple_of: int | None = Nonemean_resizing: bool = True ) → torch.nn.Embedding
매개변수
- new_num_tokens (
int, 선택 사항) — 임베딩 행렬의 새 토큰 수입니다. 크기를 늘리면 끝 부분에 새로 초기화된 벡터가 추가됩니다. 크기를 줄이면 끝 부분의 벡터가 제거됩니다. 값이 제공되지 않거나None인 경우, 아무 작업도 수행하지 않고 모델의 입력 토큰torch.nn.Embedding모듈 포인터를 그대로 반환합니다. - pad_to_multiple_of (
int, 선택 사항) — 설정된 경우, 임베딩 행렬을 제공된 값의 배수로 패딩합니다.new_num_tokens이 값이None로 설정되면, 임베딩을pad_to_multiple_of.이 기능은 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다. 여기에는 컴퓨트 캐패빌리티가
>= 7.5(Volta)인 하드웨어나, 시퀀스 길이가 128의 배수일 때 성능 향상을 얻는 TPU가 포함됩니다. 이 기능에 대한 자세한 내용 또는 리사이징에 사용할 올바른 값을 선택하는 방법에 대한 도움이 필요하면 다음 가이드를 참고하세요: https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc - mean_resizing (
bool) — 기존 임베딩의 평균과 공분산을 가진 다변량 정규 분포로 추가된 임베딩을 초기화할지, 아니면 평균이 0이고 표준편차가config.initializer_range.mean_resizing을True로 설정하는 것은 인과 언어 모델의 임베딩 크기를 늘리는 경우에 유용합니다. 이 경우 새로운 임베딩을 기존 임베딩의 평균으로 초기화하면 새로운 임베딩을 추가하기 전후의 다음 토큰 확률 분포 사이의 KL 발산이 줄어들기 때문에, 생성된 토큰의 확률에 추가된 임베딩이 영향을 미치지 않습니다. 자세한 내용은 이 기사를 참고하세요: https://nlp.stanford.edu/~johnhew/vocab-expansion.html
반환값
torch.nn.Embedding
모델의 입력 토큰 임베딩 모듈에 대한 포인터입니다.
new_num_tokens != config.vocab_size인 경우 모델의 입력 토큰 임베딩 행렬을 리사이즈합니다.
모델 클래스에 tie_weights() 메서드가 있는 경우, 이후에 임베딩 가중치 연결을 처리합니다.
save_pretrained
< source >( save_directory: str | os.PathLikeis_main_process: bool = Truestate_dict: dict | None = Nonepush_to_hub: bool = Falsemax_shard_size: int | str = '50GB'variant: str | None = Nonetoken: str | bool | None = Nonesave_peft_format: bool = Truesave_original_format: bool = Truedistributed_checkpoint: bool = False**kwargs )
매개변수
- save_directory (
str또는os.PathLike) — 저장할 디렉터리입니다. 존재하지 않으면 생성됩니다. - is_main_process (
bool, 선택 사항, 기본값True) — 이 함수를 호출하는 프로세스가 메인 프로세스인지 여부입니다. TPU와 같은 분산 학습 환경에서 모든 프로세스에서 이 함수를 호출해야 할 때 유용합니다. 이 경우 레이스 조건을 방지하기 위해 메인 프로세스에서만is_main_process=True로 설정해야 합니다. - state_dict (
torch.Tensor의 중첩 딕셔너리) — 저장할 모델의 상태 딕셔너리입니다. 기본적으로self.state_dict()를 사용하지만, 모델의 일부만 저장하거나 모델의 상태 딕셔너리를 복원할 때 특별한 조치가 필요한 경우(예: 모델 병렬성 사용 시)에 사용할 수 있습니다. - push_to_hub (
bool, 선택 사항, 기본값False) — 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다.repo_id를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내save_directory의 이름이 기본값으로 사용됩니다. - max_shard_size (
int또는str, 선택 사항, 기본값은"50GB") — 샤딩되기 전 체크포인트의 최대 크기입니다. 샤딩된 각 체크포인트의 크기는 이 크기보다 작아집니다. 문자열로 표현할 경우, 숫자 뒤에 단위(예:"5MB").모델의 단일 가중치가
max_shard_size보다 크면, 해당 가중치는max_shard_size보다 큰 자체의 체크포인트 샤드에 저장됩니다. - variant (
str, 선택 사항) — 지정된 경우, 가중치가 model..safetensors 형식으로 저장됩니다. - token (
str또는bool, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True이거나 지정되지 않은 경우,hf auth login실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다. - save_peft_format (
bool, 선택 사항, 기본값True) — PEFT 라이브러리를 위한 하위 호환성을 위해, 어댑터 가중치가 모델에 연결된 경우 어댑터의 state dict 키 모두에base_model.model접두사가 붙어야 합니다. 고급 사용자는save_peft_format을False로 설정하여 이 동작을 비활성화할 수 있습니다. - save_original_format (
bool, 선택 사항, 기본값True) —transformers의 이전 버전과 하위 호환성을 위해 체크포인트를 역 매핑(reverse mapping)과 함께 저장할 수 있습니다. 모델이 None 레거시 체크포인트에서 로드된 경우에도 역 매핑은 존재해야 합니다. - distributed_checkpoint (
bool, 선택 사항, 기본값False) — FSDP 또는 TP 샤딩된 모델을 저장할 때, 가중치를 먼저 CPU로 수집하는 대신 분산 체크포인트(DCP) 방식으로 safetensors를 작성합니다. 모든 랭크가 이 메서드를 호출해야 합니다.False인 경우,gather_full_state_dict를 통해 랭크 0에서 가중치를 CPU로 수집한 후 작성합니다. 이 옵션은 학습을 저장하고 재개하는 용도로만 의도되었으며, 전체save_pretrained기능을 사용하려면False로 설정하세요.push_to_hub=True인 경우, 랭크 0이consolidated/하위 디렉터리에 체크포인트를 통합하고 해당 디렉터리를 업로드합니다.torch>=2.7이 필요합니다. - kwargs (
dict[str, Any], 선택) — push_to_hub() 메서드에 함께 전달되는 추가 키워드 인자입니다.
모델과 해당 구성 파일을 디렉토리에 저장하여 from_pretrained() 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.
set_attn_implementation
< source >( attn_implementation: str | dictallow_all_kernels: bool = False )
매개변수
- attn_implementation (
str또는dict) — 이 모델에 설정할 attention 구현입니다.str인 경우 관련이 있는 모든 submodel에 dispatch되며,dict인 경우 키가 sub_configs 이름이고 각 submodel이 해당 값(자기 자신과 그 안에 중첩된 모든 submodel)을 dispatch합니다. 값 자체도 동일한 형식의dict일 수 있으며, 이는 해당 submodel의 sub_configs를 대상으로 합니다(중첩된attn_implementationdict로 config를 초기화할 때와 같습니다). - allow_all_kernels (
bool, optional) —attn_implementation이kernels-communityhub 저장소 외부의 커스텀 커널인 경우, 검증되지 않은 hub 저장소에서 커널을 로드할지 여부
이 모델에 대해 요청된 attn_implementation을 설정합니다.
대칭 setter. get_decoder에서 사용되는 조회 로직을 따릅니다.
대칭 setter. get_encoder에서 사용되는 조회 로직을 따릅니다.
set_experts_implementation
< source >( experts_implementation: str | dict )
이 모델에 대해 요청된 experts_implementation을 설정합니다.
set_use_kernels
< source >( use_kernelskernel_config: transformers.utils.kernel_config.KernelConfig | None = Nonemode: Mode | None = None )
모델의 일부 레이어를 kernelize하기 위해 kernels 라이브러리를 사용할지 여부를 설정합니다.
모델 가중치를 연결합니다. recompute_mapping=False인 경우(내부 호출 시 기본값), model.all_tied_weights_keys 속성에 의존하며, 이 속성에는 연결된 파라미터의 {target: source} 매핑이 포함되어 있습니다.
recompute_mapping=True인 경우, 연결해야 할 파라미터를 결정하기 위해 모든 내부 서브모델과 해당 설정을 다시 확인합니다. 이는 __init__ 및 from_pretrained 외부에서 model.tie_weights()가 단독으로 호출될 때의 기본 동작이며, 설정 값이 어딘가에서 변경되었을 경우를 대비합니다.
from_pretrained 실행 중에는 tying이 대칭입니다. 매핑에 “tie target -> source”라고 되어 있지만 source가 체크포인트에 없고 target만 존재하는 경우, 실제로 존재하는 파라미터에 모든 것을 tie할 수 있도록 source와 target을 교체합니다.
점으로 구분된 경로(예: torch.float32)에 대한 mock 값: 속성 접근 체인, 호출은 pass-through 데코레이터처럼 동작하며, repr은 해당 점으로 구분된 경로입니다. 이를 베이스 클래스로 사용하면 plain-type 베이스로 대체됩니다(PEP 560 __mro_entries__). 따라서 실제 서브클래스는 일반적인 메타클래스를 유지하고, inspect.signature는 mock의 __init__가 아닌 실제 __init__를 읽습니다.
입력 input_ids에 패딩이 포함된 것으로 보이지만 어텐션 마스크가 제공되지 않은 경우, 일회성 경고를 표시합니다.
커스텀 모델에는 superfast init가 해당 모델에 적용될 수 있는지 여부를 결정하는 _supports_assign_param_buffer도 포함해야 합니다. test_save_and_load_from_pretrained가 실패하는 경우 모델에 이 기능이 필요하다는 신호입니다. 이 경우 해당 값을 False로 설정하세요.
ModuleUtilsMixin
torch.nn.Modules에서 믹스인(mixin)으로 사용할 수 있는 몇 가지 유틸리티입니다.
num_parameters
< source >( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int
모듈의 (선택적으로, 학습 가능하거나 임베딩이 아닌) 매개변수 수를 가져옵니다.
Hub에 푸시하기
hub에 모델 또는 토크나이저를 푸시하는 기능을 포함하는 Mixin입니다.
push_to_hub
< source >( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )
매개변수
- repo_id (
str) — {object}를 푸시하려는 저장소의 이름입니다. 특정 조직에 푸시할 경우 조직 이름을 포함해야 합니다. - commit_message (
str, 선택 사항) — push할 때 사용할 커밋 메시지입니다. 기본값은"Upload {object}"입니다. - commit_description (
str, 선택 사항) — 생성될 커밋의 설명 - private (
bool, 선택 사항) — 리포지토리를 비공개로 만들지 여부를 지정합니다.None(기본값)인 경우, 조직의 기본 설정이 비공개가 아닌 한 리포지토리는 공개됩니다. 리포지토리가 이미 존재하면 이 값은 무시됩니다. - token (
bool또는str, 선택 사항) — 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다.True(기본값)인 경우,hf auth login실행 시 생성된 토큰(~/.huggingface에 저장됨)을 사용합니다. - revision (
str, 선택 사항) — 업로드된 파일을 푸시할 브랜치. - create_pr (
bool, 선택 사항, 기본값False) — 업로드된 파일로 PR을 생성할지 아니면 직접 커밋할지 여부. - max_shard_size (
int또는str, 선택 사항, 기본값"50GB") — 모델에만 적용됩니다. 샤딩되기 전 체크포인트의 최대 크기입니다. 샤딩된 각 체크포인트의 크기는 이 크기보다 작아집니다. 문자열로 표현하는 경우, 숫자 뒤에 단위(예:"5MB")가 따라와야 합니다. - tags (
list[str], 선택) — Hub에 push할 태그 목록.
{object_files}를 🤗 Model Hub에 업로드합니다.
예:
from transformers import {object_class}
{object} = {object_class}.from_pretrained("google-bert/bert-base-cased")
# Push the {object} to your namespace with the name "my-finetuned-bert".
{object}.push_to_hub("my-finetuned-bert")
# Push the {object} to an organization with the name "my-finetuned-bert".
{object}.push_to_hub("huggingface/my-finetuned-bert")