Hugging Face's logo

Transformers documentation

Mô hình

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Mô hình

Lớp cơ sở PreTrainedModel triển khai các phương thức chung để tải/lưu một mô hình từ một tệp hoặc thư mục cục bộ, hoặc từ cấu hình mô hình được huấn luyện trước do thư viện cung cấp (được tải xuống từ HuggingFace’s Hub).

PreTrainedModel cũng triển khai một số phương thức phổ biến giữa tất cả các mô hình để:

  • thay đổi kích thước các embedding token đầu vào khi có token mới được thêm vào từ vựng

Các phương thức khác phổ biến ở mỗi model được định nghĩa trong ModuleUtilsMixin và GenerationMixin.

PreTrainedModel

lớp transformers.PreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Lớp cơ sở cho tất cả các mô hình.

PreTrainedModel chịu trách nhiệm lưu trữ cấu hình của các mô hình và xử lý các phương thức để tải, tải xuống và lưu trữ mô hình, cũng như một số phương thức chung cho tất cả các mô hình:

  • thay đổi kích thước các embedding đầu vào

Thuộc tính lớp (được ghi đè bởi các lớp kế thừa):

  • config_class (PreTrainedConfig) — Một lớp con của PreTrainedConfig để sử dụng làm lớp cấu hình cho kiến trúc mô hình này.
  • base_model_prefix (str) — Chuỗi chỉ định thuộc tính liên quan đến mô hình cơ bản trong các lớp dẫn xuất cùng kiến trúc, thêm các module lên trên mô hình cơ bản.
  • main_input_name (str) — Tên của đầu vào chính của mô hình (thường là input_ids cho các mô hình NLP, pixel_values cho các mô hình thị giác và input_values cho các mô hình giọng nói).
  • can_record_outputs (dict):

push_to_hub

< >

( 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 )

Tham số

  • repo_id (str) — Tên của kho mà bạn muốn đẩy mô hình của mình lên. Nó nên chứa tên tổ chức của bạn khi đẩy lên một tổ chức cụ thể.
  • commit_message (str, tùy chọn) — Thông điệp để commit khi đẩy. Mặc định là "Upload model".
  • commit_description (str, tùy chọn) — Mô tả của commit sẽ được tạo
  • private (bool, optional) — Xác định có làm cho kho (repo) ở chế độ riêng tư hay không. Nếu là None (mặc định), kho sẽ ở chế độ công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại.
  • token (bool hoặc str, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True (mặc định), sẽ sử dụng token được tạo ra khi chạy hf auth login (được lưu trong ~/.huggingface).
  • revision (str, tùy chọn) — Nhánh để đẩy các tệp đã tải lên.
  • create_pr (bool, tùy chọn, mặc định là False) — Có tạo PR với các tệp đã tải lên hay commit trực tiếp hay không.
  • max_shard_size (int hoặc str, tùy chọn, mặc định là "50GB") — Chỉ áp dụng cho các model. Kích thước tối đa của một checkpoint trước khi được chia shard. Các checkpoint sau khi chia shard sẽ có kích thước nhỏ hơn giá trị này. Nếu được biểu diễn dưới dạng chuỗi, cần là các chữ số theo sau bởi một đơn vị (ví dụ "5MB").
  • tags (list[str], tùy chọn) — Danh sách các thẻ để đẩy lên Hub.

Tải tệp mô hình lên 🤗 Model Hub.

Ví dụ:

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")

add_model_tags

< >

( tags: list[str] | str )

Tham số

  • tags (Union[list[str], str]) — Các thẻ mong muốn để chèn vào mô hình

Thêm các thẻ tùy chỉnh vào mô hình được đẩy lên Hugging Face Hub. Sẽ không ghi đè lên các thẻ hiện có trong mô hình.

Ví dụ:

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

model.add_model_tags(["custom", "custom-bert"])

# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")

can_generate

< >

( ) → bool

Trả về

bool

Liệu mô hình này có thể tạo ra các chuỗi bằng .generate() hay không.

Trả về giá trị cho biết mô hình này có thể tạo ra các chuỗi bằng .generate() từ GenerationMixin hoặc một lớp có giao diện tương tự hay không.

Bên trong, trên các lớp mà hàm này trả về True, một số thay đổi cụ thể cho quá trình sinh sẽ được kích hoạt: ví dụ, instance mô hình sẽ có thuộc tính generation_config được gán giá trị.

cuda

( *args**kwargs )

Một giá trị giả lập cho một đường dẫn có dấu chấm (ví dụ: torch.float32): các chuỗi truy cập thuộc tính, các cuộc gọi hoạt động như các decorator pass-through, repr là đường dẫn có dấu chấm, và việc sử dụng nó như một lớp cơ sở sẽ thay thế bằng một lớp cơ sở type thông thường (PEP 560 __mro_entries__), do đó các lớp con thực sự vẫn giữ nguyên metaclass bình thường và inspect.signature sẽ đọc __init__ thực của chúng thay vì của một mock.

dequantize

< >

( dtype = None )

Có thể khử lượng tử hóa mô hình trong trường hợp nó đã được lượng tử hóa bằng một phương pháp lượng tử hóa hỗ trợ khử lượng tử hóa.

disable_input_require_grads

< >

( )

Xóa _require_grads_hook.

enable_input_require_grads

< >

( )

Bật gradient cho các embedding đầu vào. Điều này hữu ích để tinh chỉnh trọng số adapter trong khi giữ nguyên trọng số của mô hình.

from_pretrained

< >

( 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 )

Tham số

  • pretrained_model_name_or_path (str hoặc os.PathLike, tùy chọn) — Có thể là:
    • Một chuỗi, model id của một mô hình được huấn luyện trước được lưu trữ trong một kho mô hình trên huggingface.co.
    • Đường dẫn đến thư mục chứa trọng số mô hình được lưu bằng save_pretrained(), ví dụ: ./my_model_directory/. Các thư mục được lưu bằng save_pretrained(..., distributed_checkpoint=True) sẽ được phát hiện và tải bằng distributed checkpointing (DCP), giữ nguyên mesh và placements hiện tại của mô hình. Điều này yêu cầu torch>=2.7 và tải nghiêm ngặt: mọi khóa của mô hình phải có mặt trong checkpoint.
    • None nếu bạn cung cấp cả cấu hình và từ điển trạng thái (tương ứng với các tham số từ khóa config và state_dict).
  • model_args (chuỗi các đối số vị trí, tùy chọn) — Tất cả các đối số vị trí còn lại sẽ được truyền đến phương thức __init__ của model cơ sở.
  • config (Union[PreTrainedConfig, str, os.PathLike], tuỳ chọn) — Có thể là:

    Cấu hình cho mô hình cần sử dụng thay vì cấu hình được tải tự động. Cấu hình có thể được tải tự động khi:

    • Mô hình là một mô hình do thư viện cung cấp (được nạp bằng chuỗi model id của một mô hình đã được huấn luyện trước).
    • Mô hình đã được lưu bằng save_pretrained() và được nạp lại bằng cách cung cấp thư mục lưu.
    • Mô hình được nạp bằng cách cung cấp một thư mục cục bộ dưới dạng pretrained_model_name_or_path và một tệp cấu hình JSON có tên config.json được tìm thấy trong thư mục đó.
  • state_dict (dict[str, torch.Tensor], tuỳ chọn) — Một từ điển trạng thái để sử dụng thay cho từ điển trạng thái được tải từ tệp trọng số đã lưu. Tùy chọn này có thể được sử dụng nếu bạn muốn tạo một mô hình từ cấu hình được huấn luyện trước nhưng tải trọng số của riêng bạn. Tuy nhiên, trong trường hợp này, bạn nên kiểm tra xem việc sử dụng save_pretrained() và from_pretrained() có phải là tùy chọn đơn giản hơn hay không.

    Tùy chọn này có thể được sử dụng nếu bạn muốn tạo một model từ một cấu hình đã được huấn luyện trước nhưng tải trọng số của riêng bạn. Tuy nhiên, trong trường hợp này, bạn nên kiểm tra xem việc sử dụng save_pretrained() và from_pretrained() có phải là một tùy chọn đơn giản hơn hay không.

  • cache_dir (Union[str, os.PathLike], tùy chọn) — Đường dẫn đến thư mục mà cấu hình mô hình được huấn luyện trước đã tải xuống sẽ được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn.
  • ignore_mismatched_sizes (bool, tùy chọn, mặc định là False) — Có nên gây ra lỗi nếu một số trọng số từ checkpoint không có cùng kích thước với trọng số của mô hình hay không (ví dụ, nếu bạn khởi tạo một mô hình với 10 nhãn từ một checkpoint có 3 nhãn).
  • force_download (bool, tùy chọn, mặc định là False) — Có nên buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
  • proxies (dict[str, str], tuỳ chọn) — Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Các proxy này được sử dụng cho mỗi yêu cầu.
  • output_loading_info(bool, optional, mặc định là False) — Có nên trả về một từ điển chứa các khóa bị thiếu, các khóa không mong đợi và thông báo lỗi hay không.
  • local_files_only(bool, tuỳ chọn, mặc định là False) — Có chỉ xem các tệp cục bộ hay không (tức là không cố gắng tải xuống mô hình).
  • token (str hoặc bool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True, hoặc không được chỉ định, sẽ sử dụng token được tạo khi chạy hf auth login (được lưu trong ~/.huggingface).
  • revision (str, tuỳ chọn, mặc định là "main") — Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên tag hoặc id commit, vì chúng tôi sử dụng hệ thống dựa trên git để lưu trữ mô hình và các artifact khác trên huggingface.co, do đó revision có thể là bất kỳ định danh nào được git cho phép.

    Để kiểm tra một pull request bạn đã tạo trên Hub, bạn có thể truyền revision="refs/pr/<pr_number>".

  • attn_implementation (str, tuỳ chọn) — Cài đặt attention cần sử dụng trong mô hình (nếu có liên quan). Có thể là một trong các giá trị

    Chấp nhận các tham chiếu kernel HF dưới dạng:

    /[@][:]
    • và là các chuỗi không chứa "/" và không chứa ":" bất kỳ.
    • “@” là tùy chọn (branch, tag, hoặc commit-ish), ví dụ “@main”, “@v1.2.0”, “@abc123”.
    • ”:” là tùy chọn và dùng để chọn một hàm bên trong kho kernel.
    • Cả hai tùy chọn có thể xuất hiện cùng lúc và chỉ theo thứ tự này: @revision trước, sau đó là :kernel_name.
    • Chúng tôi cố ý cho phép tiền tố “|” ở đầu (ví dụ: “flash|…”) vì mã sẽ loại bỏ nó trước khi tải; ký tự ’|’ không bị loại trừ trong các lớp ký tự ở đây.

    Các ví dụ khớp: “org/model” “org/model@main” “org/model:custom_kernel” “org/[email protected]:custom_kernel”

  • experts_implementation (str, tùy chọn) — Cài đặt chuyên gia (experts) được sử dụng trong mô hình (nếu có liên quan). Có thể là một trong các tùy chọn sau:

    Mặc định, nếu model hỗ trợ, "grouped_mm" sẽ được sử dụng. Nếu không, mặc định sẽ là cài đặt "eager" thủ công.

Các tham số cho suy luận mô hình lớn

  • dtype (str hoặc torch.dtype, tuỳ chọn, mặc định là "auto") — Ghi đè torch_dtype và tải mô hình với dtype. Các tuỳ chọn khác nhau là:

    1. torch.float16 hoặc torch.bfloat16 hoặc torch.float: tải với dtype được chỉ định, bỏ qua config.dtype của mô hình nếu có. Nếu không được chỉ định

      • mô hình sẽ được nạp vào ở torch.float (fp32).

    2. "auto" - Một mục dtype hoặc torch_dtype trong tệp config.json của mô hình sẽ được cố gắng sử dụng. Nếu không tìm thấy mục này, hãy kiểm tra dtype của trọng số đầu tiên trong checkpoint có kiểu số dấu phẩy động và sử dụng nó làm dtype. Thao tác này sẽ tải mô hình bằng dtype mà nó được lưu ở cuối quá trình huấn luyện. Nó không thể được dùng làm chỉ báo cho cách mô hình được huấn luyện. Vì mô hình có thể được huấn luyện bằng một trong các dtype độ chính xác nửa, nhưng được lưu ở fp32.

    3. Một chuỗi là một torch.dtype hợp lệ. Ví dụ, “float32” sẽ tải mô hình ở torch.float32, “float16” sẽ tải ở torch.float16, v.v.

    Đối với một số mô hình, dtype mà chúng được huấn luyện là không rõ ràng - bạn có thể thử kiểm tra bài báo của mô hình hoặc liên hệ với các tác giả và yêu cầu họ thêm thông tin này vào thẻ mô hình và chèn mục dtype hoặc torch_dtype trong config.json trên hub.

  • device_map (str hoặc dict[str, Union[int, str, torch.device]] hoặc int hoặc torch.device, tuỳ chọn) — Một bản đồ chỉ định vị trí của từng submodule. Không cần chi tiết đến tên từng parameter/buffer; một khi tên module đã được đưa vào, mọi submodule của nó sẽ được chuyển đến cùng một thiết bị. Nếu chỉ truyền thiết bị (e.g., "cpu", "cuda:1", "mps", hoặc thứ tự GPU như 1) mà mô hình sẽ được cấp phát, bản đồ thiết bị sẽ ánh xạ toàn bộ mô hình sang thiết bị này. Truyền device_map = 0 có nghĩa là đặt toàn bộ mô hình trên GPU 0.

    Để Accelerate tự động tính toán device_map được tối ưu nhất, hãy đặt device_map="auto". Để biết thêm thông tin về từng tùy chọn, xem thiết kế bản đồ thiết bị.

  • max_memory (Dict, tùy chọn) — Một từ điển ánh xạ định danh thiết bị đến bộ nhớ tối đa khi sử dụng device_map. Nếu không được đặt, giá trị mặc định sẽ là bộ nhớ tối đa khả dụng cho mỗi GPU và RAM CPU khả dụng.
  • distributed_config (DistributedConfig, tùy chọn) — Cấu hình cho việc nạp phân phối bản địa với song song tensor hoặc FSDP2. Truyền DistributedConfig(tp_size=N) để sử dụng kế hoạch song song tensor được định nghĩa trước của mô hình, DistributedConfig(tp_plan=...) để chỉ định một kế hoạch song song tensor, hoặc DistributedConfig(fsdp_size=N) cho FSDP2. Yêu cầu torchrun và một nhóm tiến trình đã được khởi tạo khi tp_size > 1 hoặc fsdp_size > 1. Loại trừ lẫn nhau với device_map.
  • device_mesh (torch.distributed.DeviceMesh, tùy chọn) — Một torch device mesh. Nếu không được cung cấp, giá trị mặc định sẽ là world size. Hiện tại chỉ được sử dụng cho tensor parallel. Nếu được cung cấp, nó phải chứa chiều có tên là "tp" trong trường hợp nó có nhiều hơn 1 chiều, chiều này sẽ được sử dụng cho tensor parallelism
  • offload_folder (str hoặc os.PathLike, tùy chọn) — Nếu device_map chứa bất kỳ giá trị nào là "disk", đây là thư mục nơi chúng ta sẽ offload trọng số.
  • offload_buffers (bool, tùy chọn) — Có offload các buffer cùng với các tham số của mô hình hay không.
  • quantization_config (Union[QuantizationConfigMixin,Dict], tùy chọn) — Một từ điển các tham số cấu hình hoặc một đối tượng QuantizationConfigMixin cho lượng tử hóa (ví dụ bitsandbytes, gptq).
  • subfolder (str, tùy chọn, mặc định là "") — Trong trường hợp các tệp liên quan nằm trong một thư mục con của kho mô hình trên huggingface.co, bạn có thể chỉ định tên thư mục ở đây.
  • variant (str, tùy chọn) — Nếu được chỉ định, tải trọng số từ tên tệp variant, vd. pytorch_model..bin.
  • use_safetensors (bool, tùy chọn, mặc định là None) — Có sử dụng checkpoint safetensors hay không. Mặc định là None. Nếu không được chỉ định và safetensors chưa được cài đặt, giá trị sẽ được đặt thành False.
  • weights_only (bool, tùy chọn, mặc định là True) — Chỉ định xem unpickler có bị giới hạn để chỉ tải các tensor, các kiểu dữ liệu nguyên thủy, các từ điển và bất kỳ kiểu nào được thêm thông qua torch.serialization.add_safe_globals() hay không. Khi đặt thành False, chúng ta có thể tải trọng số của các lớp con tensor bọc (wrapper tensor subclass).
  • disable_mmap (bool, tùy chọn) — Có vô hiệu hóa ánh xạ bộ nhớ khi nạp checkpoint safetensors hay không. Khi None (mặc định), giá trị này được tự động phát hiện thành True khi checkpoint nằm trên hệ thống tệp FUSE hf-mount (được sử dụng bởi HF Spaces/Endpoints), nơi mà mmap + các lỗi trang song song có thể gây deadlock. Khi True, các tệp được đọc hoàn toàn vào bộ nhớ và được phân tích bằng safetensors.torch.load. Khi False, trình nạp ánh xạ bộ nhớ mặc định luôn được sử dụng.
  • fusion_config (dict[str, bool | dict[str, Any]], tuỳ chọn) — Cấu hình fusion tuỳ chọn được áp dụng trước khi khởi tạo mô hình. Mỗi key kích hoạt một nhóm fusion và giá trị của nó có thể là True để kích hoạt fusion đó với các tuỳ chọn mặc định, hoặc một từ điển chứa các tuỳ chọn cụ thể cho từng nhóm. Ví dụ, {"patch_embeddings": True} kích hoạt fusion patch embedding. Tham số này chỉ nên được sử dụng như một tối ưu hoá cho suy luận, vì nó có thể làm thay đổi nhẹ đầu ra. Nếu bị bỏ qua, from_pretrained() sẽ quay về dùng config.fusion_config khi có sẵn. Xem hướng dẫn ánh xạ fusion trong docs/source/en/fusion_mapping.md để biết thêm chi tiết.
  • key_mapping (`dict[str, str], tuỳ chọn) — Bản ánh xạ tiềm năng cho tên trọng số nếu sử dụng một mô hình trên Hub tương thích với kiến trúc của Transformers nhưng chưa được chuyển đổi tương ứng.
  • kwargs (từ điển các tham số keyword còn lại, tùy chọn) — Có thể được sử dụng để cập nhật đối tượng cấu hình (sau khi nó được tải) và khởi tạo mô hình (ví dụ, output_attentions=True). Hành vi khác nhau tùy thuộc vào việc có cung cấp config hay không hoặc được tải tự động:
    • Nếu một cấu hình được cung cấp thông qua config, **kwargs sẽ được truyền trực tiếp đến phương thức __init__ của model bên dưới (chúng tôi giả định rằng tất cả các cập nhật liên quan đến cấu hình đã được thực hiện)
    • Nếu không cung cấp cấu hình, kwargs sẽ được truyền trước tiên đến hàm khởi tạo của lớp cấu hình (from_pretrained()). Mỗi khóa của kwargs tương ứng với một thuộc tính cấu hình sẽ được dùng để ghi đè thuộc tính đó bằng giá trị kwargs được cung cấp. Các khóa còn lại không tương ứng với bất kỳ thuộc tính cấu hình nào sẽ được truyền đến hàm __init__ của mô hình cơ sở.

Tạo một mô hình pytorch được huấn luyện trước từ cấu hình của một mô hình đã được huấn luyện trước.

Mặc định, mô hình được đặt ở chế độ đánh giá bằng model.eval() (các module Dropout bị vô hiệu hóa). Để huấn luyện mô hình, bạn cần đặt lại nó về chế độ huấn luyện bằng model.train().

Cảnh báo Weights from XXX not initialized from pretrained model có nghĩa là trọng số của XXX không được khởi tạo từ mô hình được huấn luyện trước cùng với phần còn lại của mô hình. Bạn cần tự huấn luyện các trọng số này bằng một tác vụ tinh chỉnh (fine-tuning) cho nhiệm vụ cụ thể.

Cảnh báo Weights from XXX not used in YYY có nghĩa là lớp XXX không được sử dụng bởi YYY, do đó các trọng số đó sẽ bị loại bỏ.

Kích hoạt “offline-mode” đặc biệt để sử dụng phương pháp này trong môi trường có tường lửa.

Ví dụ:

>>> 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 == True

get_compiled_call

< >

( compile_config: transformers.generation.configuration_utils.CompileConfig | None )

Trả về phiên bản đã được torch.compile của self.__call__. Điều này hữu ích để lựa chọn động giữa forward không biên dịch/biên dịch trong quá trình suy luận, đặc biệt là để chuyển đổi giữa prefill (nơi chúng ta không muốn dùng phiên bản biên dịch để tránh tính toán lại đồ thị với các hình dạng mới) và giải mã lặp (nơi chúng ta muốn tận dụng tốc độ nhanh hơn của phiên bản biên dịch với các hình dạng tĩnh).

get_decoder

< >

( )

Tra cứu theo nỗ lực tốt nhất của module decoder.

Thứ tự các lần thử (bao phủ ~85 % các trường hợp sử dụng hiện tại):

  1. self.decoder/self.language_model/self.text_model
  2. self.base_model (nhiều lớp bọc lưu bộ giải mã tại đây)
  3. self.base_model.get_decoder() (các lớp bọc lồng nhau)
  4. fallback: raise cho một số ít mô hình đặc biệt cần quy tắc riêng

get_encoder

< >

( modality: str | None = None )

Tra cứu theo nỗ lực tốt nhất cho module encoder. Nếu được cung cấp đối số modality, nó sẽ tìm kiếm encoder cụ thể cho từng modality trong các model đa phương thức (ví dụ: “image_encoder”) Mặc định, hàm này trả về text encoder của model nếu có, nếu không sẽ trả về self.

Các giá trị modality có thể là “image”, “video” và “audio”.

get_expanded_tied_weights_keys

< >

( all_submodels: bool = False )

Trả về các khóa trọng lượng liên kết đã được mở rộng (trong trường hợp chúng chứa các module hoặc mẫu regex) chỉ cho model hiện tại, hoặc đệ quy cho tất cả các submodel nếu all_submodels=True (tức là nó sẽ kiểm tra lại các giá trị config cho tất cả các submodel).

Với hầu hết các mô hình, chúng ta chỉ cần liên kết các embedding, do đó mô hình có một thuộc tính nội bộ _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}. Trong trường hợp này, ánh xạ đã được “mở rộng”, tức là nó đã chứa các tham số đầy đủ, và hàm này sẽ đơn giản trả về một bản sao của thuộc tính đó. Với các mẫu phức tạp hơn, ví dụ với DFineForObjectDetection, chúng ta có thuộc tính sau

_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",
}
In this case, the function looks up all the model's parameters and buffers, and matches all the params,

trả về các giá trị sau:

{
    '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',
    ...
}
i.e. all the parameters matching the regex and modules patterns in `_tied_weights_keys`

get_experts_implementation

< >

( )

Trả về cài đặt chuyên gia của mô hình này và các mô hình con của nó, dưới dạng dict được chấp nhận bởi set_experts_implementation ("" cho mô hình này, và một mục cho mỗi sub_config). Đây là hàm tương ứng của set_experts_implementation, ví dụ để chụp lại cài đặt hiện tại và khôi phục nó sau đó.

get_memory_footprint

< >

( return_buffers = True )

Tham số

  • return_buffers (bool, tùy chọn, mặc định là True) — Có nên trả về kích thước của các tensor buffer trong quá trình tính toán mức sử dụng bộ nhớ hay không. Buffer là các tensor không yêu cầu gradient và không được đăng ký dưới dạng tham số. Ví dụ: mean và std trong các lớp batch norm. Vui lòng xem: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Lấy dấu chân bộ nhớ của một mô hình. Hàm này sẽ trả về dấu chân bộ nhớ của mô hình hiện tại tính bằng byte. Có ích để đo lường dấu chân bộ nhớ của mô hình hiện tại và thiết kế một số bài kiểm tra. Giải pháp được lấy cảm hứng từ các cuộc thảo luận trên PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

get_parameter_or_buffer

< >

( target: str )

Trả về tham số hoặc bộ đệm được chỉ định bởi target nếu nó tồn tại, nếu không sẽ ném ra một lỗi. Hàm này kết hợp get_parameter() và get_buffer() trong một hàm tiện dụng duy nhất. Nếu mục tiêu là thuộc tính _extra_state, nó sẽ trả về trạng thái bổ sung do module cung cấp. Lưu ý rằng nó chỉ hoạt động nếu target là một lá của mô hình.

gradient_checkpointing_disable

< >

( )

Tắt gradient checkpointing cho mô hình hiện tại.

gradient_checkpointing_enable

< >

( gradient_checkpointing_kwargs = Noneevery_n_layers: int = 1offload: bool = False )

Tham số

  • every_n_layers (int, tuỳ chọn, mặc định là 1) — Chỉ checkpoint mỗi every_n_layers lớp decoder, để các lớp còn lại giữ nguyên activation. 1 sẽ checkpoint mọi lớp, đây là hành vi tất cả hoặc không thông thường. Các giá trị lớn hơn đánh đổi bộ nhớ lấy tốc độ, điều này đáng giá khi bộ nhớ được giải phóng nhờ checkpoint toàn bộ sẽ không được sử dụng.
  • offload (bool, tuỳ chọn, mặc định là False) — Giữ các activation được lưu lại để recompute trong bộ nhớ host được ghim (pinned host memory) thay vì trên bộ tăng tốc. Điều này giải phóng layers x sequence x hidden byte bộ nhớ thiết bị, vốn là thành phần chiếm ưu thế ở độ dài sequence lớn, và phát sinh một bản sao từ thiết bị sang host trong bước forward và một bản sao từ host sang thiết bị trong bước backward. Cả hai bản sao đều chạy trên luồng tính toán, do đó bước này sẽ chậm hơn.
  • gradient_checkpointing_kwargs (dict, tùy chọn) — Các đối số từ khóa bổ sung được truyền đến hàm torch.utils.checkpoint.checkpoint.

Kích hoạt gradient checkpointing cho mô hình hiện tại.

Chúng ta truyền phương thức __call__ của các module thay vì forward vì __call__ gắn tất cả các hook của module. https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2

init_weights

< >

( )

Khởi tạo và liên kết các trọng số nếu cần. Nếu sử dụng PreTrainedModel tùy chỉnh, bạn cần triển khai bất kỳ logic khởi tạo nào trong _init_weights.

initialize_weights

< >

( )

Điều này tương đương với việc gọi self.apply(self._initialize_weights), nhưng xử lý đúng các mô hình tổ hợp. Hàm này phân phát động hàm init_weights đúng đến các module khi chúng ta tiến sâu trong đồ thị module dọc theo đệ quy. Nó có thể xử lý một số lượng tùy ý các mô hình con. Nếu không có nó, mọi mô hình tổ hợp sẽ phải đệ quy lần thứ hai trên tất cả các mô hình con một cách tường minh trong _init_weights ngoài cùng, điều này cực kỳ dễ gây lỗi và kém hiệu quả.

is_custom_code

< >

( )

Trả về giá trị cho biết mô hình hiện tại có phải là mã tùy chỉnh hay không, tức là mã được tải từ hub hoặc được định nghĩa trong bất kỳ module/phân vùng người dùng cụ thể nào.

is_remote_code

< >

( )

Trả về việc mô hình hiện tại có phải là mã tùy chỉnh, tức là mã được tải từ hub, hay là lớp mà chúng ta vừa đăng ký thông qua register_for_auto_class hay không.

mark_tied_weights_as_initialized

< >

( loading_info )

Thêm cờ _is_hf_initialized vào các tham số sẽ được liên kết, nhằm tránh việc khởi tạo chúng sau này vì chúng sẽ được liên kết (ghi đè) dù sao đi nữa. Điều này rất quan trọng vì hầu hết các embedding đều được liên kết, và chúng là các tham số rất lớn (bảng từ vựng thường là 256k), nên việc chạy khởi tạo trên chúng rất tốn kém.

named_non_persistent_buffers

< >

( recurse: bool = Trueremove_duplicate: bool = True )

Tương tự như named_buffers, nhưng chỉ trả về các buffer không bền vững. Tính năng này rất hữu ích vì không phải lúc nào cũng dễ dàng để biết chúng có bền vững hay không

post_init

< >

( )

Một phương thức được thực thi ở cuối quá trình khởi tạo của mỗi mô hình Transformer, nhằm chạy các đoạn mã cần các module của mô hình được khởi tạo đúng cách (chẳng hạn như khởi tạo trọng số). Nó cũng được sử dụng để thu thập tất cả các thuộc tính tĩnh chính xác (kế hoạch song song, tied_weights_keys, _keep_in_fp32_modules, v.v.) một cách đúng đắn trong trường hợp các mô hình tổ hợp (tức là, mô hình cấp trên cần biết về các thuộc tính đó từ các con của nó).

register_for_auto_class

< >

( auto_class = 'AutoModel' )

Tham số

  • auto_class (str hoặc type, tùy chọn, mặc định là "AutoModel") — Lớp auto để đăng ký mô hình mới này.

Đăng ký lớp này với một lớp auto cho trước. Chỉ nên sử dụng cho các mô hình tùy chỉnh vì các mô hình trong thư viện đã được ánh xạ với một lớp auto.

resize_token_embeddings

< >

( new_num_tokens: int | None = Nonepad_to_multiple_of: int | None = Nonemean_resizing: bool = True ) → torch.nn.Embedding

Tham số

  • new_num_tokens (int, tuỳ chọn) — Số lượng token mới trong ma trận nhúng. Việc tăng kích thước sẽ thêm các vector được khởi tạo mới vào cuối. Việc giảm kích thước sẽ loại bỏ các vector từ cuối. Nếu không được cung cấp hoặc là None, chỉ trả về con trỏ đến module torch.nn.Embedding của các token đầu vào của mô hình mà không thực hiện bất kỳ thao tác nào.
  • pad_to_multiple_of (int, tuỳ chọn) — Nếu được đặt, ma trận nhúng sẽ được đệm (pad) đến bội số của giá trị được cung cấp. Nếu new_num_tokens được đặt thành None thì chỉ đệm ma trận nhúng đến bội số của pad_to_multiple_of.

    Điều này đặc biệt hữu ích để cho phép sử dụng Tensor Cores trên phần cứng NVIDIA có khả năng tính toán >= 7.5 (Volta), hoặc trên TPU, nơi mà việc có độ dài chuỗi là bội số của 128 sẽ mang lại lợi ích. Để biết thêm chi tiết về điều này, hoặc cần hỗ trợ trong việc chọn giá trị phù hợp để thay đổi kích thước, hãy tham khảo hướng dẫn này: https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

  • mean_resizing (bool) — Liệu có khởi tạo các embedding được thêm vào từ một phân phối chuẩn đa biến có trung bình và hiệp phương sai của các embedding cũ, hay khởi tạo chúng bằng một phân phối chuẩn có trung bình bằng 0 và độ lệch chuẩn bằng config.initializer_range.

    Đặt mean_resizing thành True hữu ích khi tăng kích thước của các embedding trong các mô hình ngôn ngữ nhân quả, trong đó xác suất của các token được tạo ra sẽ không bị ảnh hưởng bởi các embedding được thêm vào, vì việc khởi tạo các embedding mới bằng giá trị trung bình của các embedding cũ sẽ làm giảm kl-divergence giữa xác suất token tiếp theo trước và sau khi thêm các embedding mới. Tham khảo bài viết này để biết thêm thông tin: https://nlp.stanford.edu/~johnhew/vocab-expansion.html

Trả về

torch.nn.Embedding

Trỏ đến Module Embedding của các token đầu vào của mô hình.

Đổi kích thước ma trận nhúng token đầu vào của mô hình nếu new_num_tokens != config.vocab_size.

Chịu trách nhiệm liên kết trọng số nhúng sau đó nếu lớp mô hình có phương thức tie_weights().

save_pretrained

< >

( 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 )

Tham số

  • save_directory (str hoặc os.PathLike) — Thư mục để lưu. Sẽ được tạo nếu chưa tồn tại.
  • is_main_process (bool, tùy chọn, mặc định là True) — Xác định xem tiến trình gọi hàm này có phải là tiến trình chính hay không. Hữu ích khi huấn luyện phân tán như trên TPU và cần gọi hàm này trên tất cả các tiến trình. Trong trường hợp này, chỉ đặt is_main_process=True trên tiến trình chính để tránh điều kiện đua.
  • state_dict (từ điển lồng nhau của torch.Tensor) — Từ điển trạng thái của mô hình cần lưu. Mặc định sẽ là self.state_dict(), nhưng có thể được dùng để chỉ lưu một phần của mô hình hoặc khi cần các biện pháp đặc biệt khi khôi phục từ điển trạng thái của mô hình (ví dụ khi sử dụng song song hóa mô hình).
  • push_to_hub (bool, tùy chọn, mặc định là False) — Có đẩy mô hình của bạn lên Hugging Face model hub sau khi lưu hay không. Bạn có thể chỉ định kho lưu trữ muốn đẩy đến bằng repo_id (mặc định sẽ là tên của save_directory trong namespace của bạn).
  • max_shard_size (int hoặc str, tuỳ chọn, mặc định là "50GB") — Kích thước tối đa của một checkpoint trước khi được chia shard. Các checkpoint shard sau đó sẽ có kích thước nhỏ hơn mức này. Nếu được biểu diễn dưới dạng chuỗi, cần là các chữ số theo sau bởi một đơn vị (như "5MB").

    Nếu một trọng số đơn lẻ của mô hình lớn hơn max_shard_size, nó sẽ nằm trong một shard checkpoint riêng, có kích thước lớn hơn max_shard_size.

  • variant (str, tùy chọn) — Nếu được chỉ định, trọng số sẽ được lưu ở định dạng model..safetensors.
  • token (str hoặc bool, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True, hoặc không được chỉ định, sẽ sử dụng token được tạo khi chạy hf auth login (được lưu trong ~/.huggingface).
  • save_peft_format (bool, tùy chọn, mặc định là True) — Để đảm bảo tương thích ngược với thư viện PEFT, trong trường hợp trọng số adapter được gắn vào mô hình, tất cả các khóa trong state dict của adapter cần được thêm tiền tố base_model.model. Người dùng nâng cao có thể tắt hành vi này bằng cách đặt save_peft_format thành False.
  • save_original_format (bool, tùy chọn, mặc định là True) — Để tương thích ngược với các phiên bản trước của transformers, bạn có thể lưu checkpoint với ánh xạ ngược của nó. Ánh xạ ngược cần phải tồn tại ngay cả khi mô hình được nạp từ một checkpoint legacy None.
  • distributed_checkpoint (bool, tùy chọn, mặc định là False) — Khi lưu một mô hình được chia shard bằng FSDP hoặc TP, hãy ghi safetensors bằng distributed checkpointing (DCP) thay vì gom các trọng số về CPU trước. Mọi rank đều phải gọi phương thức này. Khi False, các trọng số sẽ được gom về CPU trên rank 0 thông qua gather_full_state_dict trước khi ghi. Nó chỉ được thiết kế để lưu và tiếp tục huấn luyện, hãy đặt thành False nếu bạn muốn đầy đủ các tính năng của save_pretrained. Với push_to_hub=True, rank 0 sẽ hợp nhất checkpoint trong một thư mục con consolidated/ và tải lên thư mục đó. Yêu cầu torch>=2.7.
  • kwargs (dict[str, Any], tùy chọn) — Các đối số từ khóa bổ sung được truyền đến phương thức push_to_hub().

Lưu một mô hình và tệp cấu hình của nó vào một thư mục, để có thể tải lại bằng phương thức lớp from_pretrained().

set_attn_implementation

< >

( attn_implementation: str | dictallow_all_kernels: bool = False )

Tham số

  • attn_implementation (str hoặc dict) — Cài đặt thực hiện attention cho model này. Giá trị có thể là một str, khi đó nó sẽ được phân phối đến tất cả các submodel nếu liên quan, hoặc một dict trong đó các key là tên của sub_configs, khi đó mỗi submodel sẽ phân phối giá trị tương ứng (cho chính nó và tất cả các submodel lồng bên trong nó). Một giá trị có thể tự nó là một dict cùng định dạng, để nhắm đến các sub_configs của submodel đó (như khi khởi tạo một config với một dict attn_implementation lồng nhau).
  • allow_all_kernels (bool, tùy chọn) — Có nên nạp kernels từ các hub repos chưa được xác minh hay không, nếu attn_implementation là một kernel tùy chỉnh nằm ngoài hub repository kernels-community.

Đặt attn_implementation được yêu cầu cho mô hình này.

set_decoder

< >

( decoder )

Setter đối xứng. Phản ánh logic tra cứu được sử dụng trong get_decoder.

set_encoder

< >

( encodermodality: str | None = None )

Setter đối xứng. Phản ánh logic tra cứu được sử dụng trong get_encoder.

set_experts_implementation

< >

( experts_implementation: str | dict )

Tham số

  • experts_implementation (str hoặc dict) — Cài đặt chuyên gia (experts implementation) cho mô hình này. Nó có thể là một str, trong trường hợp đó nó sẽ được phân phối đến tất cả các mô hình con nếu phù hợp, hoặc một dict trong đó các khóa là tên của sub_configs, trong trường hợp đó mỗi mô hình con sẽ phân phối giá trị tương ứng.

Đặt experts_implementation được yêu cầu cho mô hình này.

set_use_kernels

< >

( use_kernelskernel_config: transformers.utils.kernel_config.KernelConfig | None = Nonemode: Mode | None = None )

Tham số

  • use_kernels (bool) — Có sử dụng thư viện kernels để kernelize một số lớp của mô hình hay không.
  • kernel_config (KernelConfig, tùy chọn) — Cấu hình kernel để sử dụng nhằm kernel hóa mô hình. Nếu là None, ánh xạ kernel mặc định sẽ được sử dụng.
  • mode (Mode, tùy chọn) — Chế độ cần được áp dụng trong quá trình kernelize. Tùy chọn, mặc định là chế độ huấn luyện hoặc suy luận dựa trên cờ training bên trong.

Đặt xem có sử dụng thư viện kernels để kernelize một số lớp của mô hình hay không.

tie_weights

< >

( missing_keys: set[str] | None = Nonerecompute_mapping: bool = True )

Gắn các trọng số mô hình. Nếu recompute_mapping=False (mặc định khi được gọi bên trong), nó sẽ dựa vào thuộc tính model.all_tied_weights_keys, chứa ánh xạ {target: source} cho các tham số được gắn. Nếu recompute_mapping=True, nó sẽ kiểm tra lại tất cả các mô hình con bên trong và cấu hình của chúng để xác định các tham số cần được gắn. Đây là mặc định khi model.tie_weights() được gọi độc lập, bên ngoài __init__ và from_pretrained, trong trường hợp các giá trị cấu hình đã bị thay đổi ở đâu đó.

Lưu ý rằng trong quá trình from_pretrained, việc liên kết là đối xứng: nếu ánh xạ ghi “tie target -> source” nhưng source không có trong checkpoint trong khi target tồn tại, chúng ta sẽ đảo source và target để vẫn có thể liên kết mọi thứ với tham số thực sự tồn tại.

đến

( *args**kwargs )

Một giá trị giả lập cho một đường dẫn có dấu chấm (ví dụ: torch.float32): các chuỗi truy cập thuộc tính, các cuộc gọi hoạt động như các decorator pass-through, repr là đường dẫn có dấu chấm, và việc sử dụng nó như một lớp cơ sở sẽ thay thế bằng một lớp cơ sở type thông thường (PEP 560 __mro_entries__), do đó các lớp con thực sự vẫn giữ nguyên metaclass bình thường và inspect.signature sẽ đọc __init__ thực của chúng thay vì của một mock.

warn_if_padding_and_no_attention_mask

< >

( input_idsattention_mask )

Hiển thị một cảnh báo một lần nếu input_ids dường như chứa padding và không có attention mask nào được cung cấp.

Các model tùy chỉnh cũng nên bao gồm _supports_assign_param_buffer, dùng để xác định xem superfast init có thể áp dụng cho model cụ thể đó hay không. Dấu hiệu cho thấy model của bạn cần thuộc tính này là khi test_save_and_load_from_pretrained bị lỗi. Nếu đúng như vậy, hãy đặt giá trị này thành False.

ModuleUtilsMixin

lớp transformers.modeling_utils.ModuleUtilsMixin

< >

( )

Một số tiện ích cho torch.nn.Modules, được sử dụng như một mixin.

số_tham_số

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Tham số

  • only_trainable (bool, tùy chọn, mặc định là False) — Có nên chỉ trả về số lượng tham số có thể huấn luyện hay không
  • exclude_embeddings (bool, tùy chọn, mặc định là False) — Có nên chỉ trả về số lượng tham số không phải là embeddings hay không

Trả về

int

Số lượng tham số.

Lấy số lượng tham số (tùy chọn, có thể huấn luyện hoặc không phải nhúng) trong module.

Đẩy lên Hub

lớp transformers.utils.PushToHubMixin

< >

( )

Một Mixin chứa chức năng để đẩy một model hoặc tokenizer lên hub.

push_to_hub

< >

( 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 )

Tham số

  • repo_id (str) — Tên của kho mà bạn muốn đẩy {object} đến. Nó nên chứa tên tổ chức của bạn khi đẩy đến một tổ chức cụ thể.
  • commit_message (str, tùy chọn) — Thông điệp để commit khi đẩy. Mặc định là "Upload {object}".
  • commit_description (str, tùy chọn) — Mô tả của commit sẽ được tạo
  • private (bool, optional) — Xác định có làm cho kho (repo) ở chế độ riêng tư hay không. Nếu là None (mặc định), kho sẽ ở chế độ công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại.
  • token (bool hoặc str, tùy chọn) — Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu True (mặc định), sẽ sử dụng token được tạo ra khi chạy hf auth login (được lưu trong ~/.huggingface).
  • revision (str, tùy chọn) — Nhánh để đẩy các tệp đã tải lên.
  • create_pr (bool, tùy chọn, mặc định là False) — Có tạo PR với các tệp đã tải lên hay commit trực tiếp hay không.
  • max_shard_size (int hoặc str, tùy chọn, mặc định là "50GB") — Chỉ áp dụng cho các model. Kích thước tối đa của một checkpoint trước khi được chia shard. Các checkpoint sau khi chia shard sẽ có kích thước nhỏ hơn giá trị này. Nếu được biểu diễn dưới dạng chuỗi, cần là các chữ số theo sau bởi một đơn vị (ví dụ "5MB").
  • tags (list[str], tùy chọn) — Danh sách các thẻ để đẩy lên Hub.

Tải {object_files} lên 🤗 Model Hub.

Ví dụ:

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")
Update on GitHub

←Ghi nhật ký Tạo văn bản→