参数

• 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 的标签列表。

参数

• every_n_layers (int，可选，默认为 1) — 仅对每 every_n_layers 个解码器层执行一次检查点，其余层保留其激活值。 1 表示对每一层都执行检查点，这是常见的全有或全无行为。较大的值会以速度换取内存，当完全检查点释放的内存未被使用时，这样做是值得的。
• offload (bool，可选，默认为 False) — 将用于重计算的激活值保存在固定的主机内存中，而不是加速器上。 这会释放 layers x sequence x hidden 字节的设备内存，在长序列长度下，这部分内存占用占主导地位，代价是在前向传播中产生一次设备到主机的拷贝，在反向传播中产生一次主机到设备的拷贝。这两次拷贝都在计算流上执行，因此步骤会变慢。
• activation_checkpointing_kwargs (dict, 可选) — 传递给 torch.utils.checkpoint.checkpoint 函数的其他关键字参数。

参数

• tags (Union[list[str], str]) — 要注入到模型中的目标标签

参数

• pretrained_model_name_or_path (str 或 os.PathLike, 可选) — 可以是以下之一：
  • 一个字符串，表示托管在 huggingface.co 模型仓库中的预训练模型的 model id。
  • 指向一个目录的路径，该目录包含使用 save_pretrained() 保存的模型权重，例如 ./my_model_directory/。使用 save_pretrained(..., distributed_checkpoint=True) 保存的目录会被检测并以分布式检查点（DCP）方式加载，从而保留模型当前的 mesh 和 placements。这需要 torch>=2.7，并且采用严格加载：检查点中必须包含所有模型键。
  • 如果同时提供了配置和状态字典（分别通过关键字参数 config 和 state_dict），则返回 None。
• model_args（位置参数序列，可选） — 所有剩余的位置参数都会传递给底层模型的 __init__ 方法。
• config (Union[PreTrainedConfig, str, os.PathLike], 可选) — 可以是以下之一：
  • PreTrainedConfig 派生类的实例，
  • 可作为 from_pretrained() 输入的字符串或路径。

  用于替代自动加载配置的模型配置。在以下情况下，配置可以自动加载：

  • 该模型是由库提供的模型（通过预训练模型的 model id 字符串加载）。
  • 该模型使用 save_pretrained() 保存，并通过提供保存目录来重新加载。
  • 通过提供本地目录作为 pretrained_model_name_or_path 来加载模型，并且在该目录中找到了名为 config.json 的配置文件。
• state_dict (dict[str, torch.Tensor], 可选) — 用于替代从保存的权重文件中加载的状态字典的状态字典。如果您想基于预训练配置创建模型但加载自己的权重，可以使用此选项。不过在这种情况下，您应该检查使用 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 上创建的拉取请求，可以传入 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 内核引用：

  /[@][:]
  • 和 是任何不包含"/"和":"的序列。
  • “@”是可选的（分支、标签或 commit-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, 可选) — 模型中使用的专家实现方式（如适用）。可以是以下任意值：
  • "eager"（专家矩阵乘法的顺序实现）。
  • "batched_mm"（使用 torch.bmm）。
  • "grouped_mm"（使用 torch.nn.functional.grouped_mm）。

  默认情况下，如果模型支持，将使用 "grouped_mm"。否则，默认使用手动实现的 "eager"。

大模型推理参数

• dtype (str 或 torch.dtype, 可选, ，默认为 "auto") — 覆盖默认的 torch_dtype ，以特定的 dtype. 加载模型。可选值如下：

  1. torch.float16 或 torch.bfloat16 或 torch.float：以指定的 dtype 加载，忽略模型的 config.dtype（如果存在）。如果未指定

     • 模型将以 torch.float（fp32）精度加载。

  2. "auto" - 将尝试使用模型 config.json 文件中的 dtype 或 torch_dtype 条目。如果未找到该条目，则接下来检查检查点中第一个浮点类型权重的 dtype，并将其用作 dtype。这将使用模型在训练结束时保存所用的 dtype 来加载模型。它不能作为模型训练方式的指示器，因为模型可能以某种半精度 dtype 进行训练，但最终以 fp32 保存。

  3. 一个有效的 torch.dtype 字符串。例如，“float32” 会以 torch.float32 加载模型，“float16” 会以 torch.float16 加载，依此类推。

  对于某些模型，其训练时使用的 dtype 是未知的——您可以尝试查阅该模型的论文，或联系作者，请他们在模型卡片中补充此信息，并在 Hub 上的 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"。有关每个选项的更多信息，请参阅 设计设备映射。

• max_memory (Dict, 可选) — 如果使用 device_map，则为设备标识符到最大内存的字典。如果未设置，默认值为每个 GPU 的最大可用内存和可用的 CPU 内存。
• distributed_config (DistributedConfig, 可选) — 用于原生分布式加载（支持张量并行或 FSDP2）的配置。传入 DistributedConfig(tp_size=N) 以使用模型预定义的张量并行方案， 传入 DistributedConfig(tp_plan=...) 以指定张量并行方案，或 传入 DistributedConfig(fsdp_size=N) 以使用 FSDP2。当 tp_size > 1 或 fsdp_size > 1 时，需要 torchrun 以及已初始化的进程组。与 device_map 互斥。
• device_mesh (torch.distributed.DeviceMesh, 可选) — 一个 torch 设备网格。如果未提供，则默认为 world size。目前仅用于张量并行。 如果提供了该参数，且其维度大于 1，则必须包含名为 "tp" 的维度，该维度将用于张量并行。
• 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-mount FUSE 文件系统上（由 HF Spaces/Endpoints 使用）， 则会自动检测并设置为 True，因为在该文件系统上，mmap 加上并行页面错误可能导致死锁。当为 True 时， 文件会被完整读入内存，并使用 safetensors.torch.load 进行解析。当为 False 时， 始终使用默认的内存映射加载器。
• fusion_config (dict[str, bool | dict[str, Any]], 可选) — 在模型实例化之前应用的可选融合配置。每个键用于启用一个融合族，其值可以是 True（表示使用默认选项启用该融合），也可以是一个包含该族特定选项的字典。例如，{"patch_embeddings": True} 会启用 patch embedding 融合。此参数仅应作为推理优化使用，因为它可能会轻微改变输出。如果省略，from_pretrained() 在可用时会回退到 config.fusion_config。有关更多详细信息，请参阅 docs/source/en/fusion_mapping.md 中的融合映射指南。
• key_mapping (`dict[str, str], 可选) — 如果使用的是 Hub 上与 Transformers 架构兼容但未进行相应转换的模型，则可能需要提供权重名称的映射。
• kwargs (其余关键字参数字典， 可选) — 可用于更新配置对象（在加载之后）并初始化模型（例如， output_attentions=True). 其行为取决于是否提供了 config ，或自动加载：
  • 如果通过 config 提供了配置，**kwargs 将直接传递给底层模型的 __init__ 方法（我们假设对配置的所有相关更新均已完成）
  • 如果未提供配置，kwargs 会首先传递给配置类的初始化函数（from_pretrained()）。kwargs 中每个对应配置属性的键，都会使用所提供的 kwargs 值来覆盖该属性。其余未对应任何配置属性的键，将传递给底层模型的 __init__ 函数。

参数

• return_buffers (bool，可选，默认为 True) — 是否在计算内存占用时返回缓冲区张量的大小。缓冲区是指不需要梯度且未注册为参数的张量。例如，批归一化层中的均值和标准差。请参阅：https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

参数

• auto_class (str 或 type，可选，默认为 "AutoModel") — 用于注册此新模型的 auto class。

参数

• new_num_tokens (int, 可选) — 嵌入矩阵中新的 token 数量。增大该值会在末尾添加新初始化的向量。减小该值会从末尾移除向量。如果未提供或为 None，则直接返回模型中输入 token 的 torch.nn.Embedding 模块的指针，而不执行任何操作。
• pad_to_multiple_of (int, 可选) — 如果设置，将把嵌入矩阵填充为所提供值的倍数。如果 new_num_tokens 被设置为 None ，则仅将嵌入填充为 pad_to_multiple_of.

  这在启用 NVIDIA 硬件（计算能力 >= 7.5，即 Volta 架构）上的 Tensor Cores 时尤为有用，或者在 TPU 上，序列长度为 128 的倍数时性能更佳。有关此功能的更多详细信息，或关于选择正确的调整大小值的帮助，请参阅此指南： https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

• mean_resizing (bool) — 是否使用具有旧嵌入的均值和协方差的多变量正态分布来初始化新增的嵌入，还是使用均值为零、标准差为 config.initializer_range.

  将 mean_resizing 设置为 True 在扩大因果语言模型嵌入维度时非常有用，因为使用旧嵌入的均值来初始化新嵌入，会减小添加新嵌入前后下一个 token 概率分布之间的 KL 散度，从而使得生成 token 的概率不受新增嵌入的影响。有关更多信息，请参阅此文章：https://nlp.stanford.edu/~johnhew/vocab-expansion.html

参数

• 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 库保持向后兼容，如果适配器权重已附加到模型上，则适配器状态字典中的所有键都需要加上 base_model.model 前缀。高级用户可以通过将 save_peft_format 设置为 False 来禁用此行为。
• save_original_format (bool，可选，默认为 True) — 为了与 transformers 的早期版本保持向后兼容，您可以使用反向映射来保存检查点。即使模型是从 None 遗留检查点加载的，反向映射也必须存在。
• distributed_checkpoint (bool，可选，默认为 False) — 在保存 FSDP 或 TP 分片模型时，使用分布式检查点（DCP）写入 safetensors，而不是先将权重聚合到 CPU。每个 rank 都必须调用此方法。 当 False 时，在写入之前会通过 gather_full_state_dict 在 rank 0 上将权重聚合到 CPU。 此参数仅用于保存和恢复训练，若需要完整的 save_pretrained 功能，请将其设置为 False。当 push_to_hub=True 时，rank 0 会在 consolidated/ 子目录中整合检查点，并上传该目录。 需要 torch>=2.7。
• kwargs (dict[str, Any]，可选) — 传递给 push_to_hub() 方法的额外关键字参数。

参数

• attn_implementation (str 或 dict) — 为此模型设置的注意力实现。它可以是一个 str，在这种情况下，如果适用，它将分派到所有子模型；也可以是一个 dict，其键为 sub_configs 的名称，在这种情况下，每个子模型将分派对应的值（分派给它自身以及嵌套在其中的所有子模型）。该值本身也可以是一个相同格式的 dict，用于针对该子模型的 sub_configs（类似于使用嵌套的 attn_implementation 字典初始化配置时）。
• allow_all_kernels (bool, 可选) — 如果 attn_implementation 是 kernels-community hub 仓库之外的自定义 kernel，是否从未经验证的 hub 仓库加载 kernel。

参数

• experts_implementation (str 或 dict) — 为此模型设置专家实现。它可以是 str，在这种情况下，如果适用，将分派到所有子模型；也可以是 dict，其中键为 sub_configs 的名称，在这种情况下，每个子模型将分派对应的值。

参数

• use_kernels (bool) — 是否使用 kernels 库对模型的部分层进行 kernelize 处理。
• kernel_config (KernelConfig, 可选) — 用于将模型 kernelize 的内核配置。如果为 None，则使用默认的内核映射。
• mode (Mode，可选) — 在 kernelize 期间应应用的模式。可选，默认根据内部的 training 标志设置为训练模式或推理模式。

参数

• only_trainable (bool，可选，默认为 False) — 是否仅返回可训练参数的数量
• exclude_embeddings (bool，可选，默认为 False) — 是否仅返回非嵌入参数的数量

参数

• repo_id (str) — 要推送 {object} 的目标仓库名称。推送到特定组织时，应包含该组织的名称。
• commit_message (str, 可选) — 推送时提交的提交信息。默认值为 "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 的标签列表。