Transformers documentation

Динамическая загрузка весов

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Динамическая загрузка весов

Чекпоинты часто сериализуются в формате, который не соответствует тому, что модель ожидает во время выполнения. Типичные сценарии включают:

  1. Слитые веса: В контрольных точках хранятся отдельные веса gate_proj и up_proj, но модель использует слитый gate_up_proj для повышения эффективности.
  2. Консолидация экспертов MoE: веса отдельных экспертов (experts.0.weight, experts.1.weight, …) необходимо объединить в единый трёхмерный тензор.
  3. Устаревшее именование: в старых контрольных точках используются другие соглашения об именовании (например, LayerNorm.gamma вместо LayerNorm.weight).
  4. Композитные модели: модель «зрение-язык» содержит два подмодуля PreTrainedModel, каждый из которых имеет собственную конвенцию для контрольных точек.
  5. Квантование: веса могут храниться в квантованных форматах, требующих десериализации.

Динамическая загрузка весов решает эту проблему, применяя запланированные обратимые операции к тензорам контрольных точек в процессе их загрузки. Transformers предоставляет для этого WeightConverter и WeightRenaming, которые описывают, как один или несколько ключей контрольной точки сопоставляются с одним или несколькими параметрами модели, и какие комбинируемые ConversionOps следует выполнить для соответствующих тензоров. Этот подход адаптируется к новым схемам размещения весов, поддерживает квантованные mixture-of-experts (MoE) и интегрируется с тензорным параллелизмом.

В этом руководстве показано, как использовать WeightConverter для преобразования тензоров. Соответствия для преобразования находятся в conversion_mapping.py; зарегистрированное соответствие привязывается либо к строке model_type (например, "mixtral"), либо к имени класса (например, "LlavaModel").

Полный конвейер загрузки

Все модели проходят через систему динамической загрузки весов. Маппинг конвертации — это необязательный шаг в рамках этой системы, который активируется только в том случае, если для имени класса модели или model_type зарегистрированы соответствующие записи.

Checkpoint File → from_pretrained() → convert_and_load_state_dict_in_model()
                                              ↓
                         ┌───────────────────────────────────────────────────────────┐
                         │  For each weight in checkpoint:                           │
                         │  1. Match renamed/processed source key to model parameter │
                         │  2. Shard the weight and send to device (async)           │
                         │  3. Collect tensors with the same source_pattern together │
                         │     (e.g. MoE experts, gate_up_proj)                      │
                         │  4. Apply dequantization/deserialization (if pre-quant)   │
                         │  5. Apply conversion (if defined)                         │
                         │  6. Apply quantization (if enabled and step 4 not used)   │
                         │  7. Set parameter on model                                │
                         └───────────────────────────────────────────────────────────┘
ШагКогда он активируется
Динамическая загрузкаВсегда, для всех моделей
Карта преобразованийТолько если класс модели или model_type зарегистрирован в _MODEL_TO_CONVERSION_PATTERN
Шардинг TPТолько при использовании DistributedConfig(tp_size=N) и наличии у модели base_model_tp_plan
Декуантизация/десериализацияТолько при загрузке предварительно квантованного чекпоинта
КвантованиеТолько если предоставлена конфигурация квантования, а веса не были предварительно квантованы

Плотные модели (например, Llama)

Для большинства плотных моделей формат контрольной точки напрямую совпадает с форматом модели, поэтому маппинг для преобразования не требуется. Для некоторых моделей может потребоваться переименование (например, из-за устаревших соглашений об именовании). При включённом TP шардирование по-прежнему применяется.

Checkpoint:                             Model:
model.layers.0.self_attn.q_proj.weight  →  model.layers.0.self_attn.q_proj.weight
model.layers.0.self_attn.k_proj.weight  →  model.layers.0.self_attn.k_proj.weight
model.layers.0.mlp.gate_proj.weight     →  model.layers.0.mlp.gate_proj.weight
model.layers.0.mlp.up_proj.weight       →  model.layers.0.mlp.up_proj.weight
model.layers.0.mlp.down_proj.weight     →  model.layers.0.mlp.down_proj.weight

Устаревшие контрольные точки могут использовать старые соглашения об именовании, которые обрабатываются встроенными переименованиями, применяемыми ко всем моделям:

Checkpoint:                          Model:
LayerNorm.gamma              →       LayerNorm.weight
LayerNorm.beta               →       LayerNorm.bias

Модели MoE (например, Mixtral)

Для MoE-моделей формат контрольной точки отличается от формата модели. Преобразование по соответствию (mapping) превращает отдельные веса экспертов в объединённые 3D-тензоры, а шардирование по TP применяется после преобразования.

Checkpoint:                              Model:
experts.0.w1.weight  ─┐
experts.1.w1.weight   │ MergeModulelist
...                   ├───────────────→  experts.gate_up_proj (8, hidden, 2*intermediate)
experts.0.w3.weight   │ + Concatenate
experts.1.w3.weight  ─┘

Композитные модели (например, зрительно-языковые)

Модель PreTrainedModel может содержать другие подмодули PreTrainedModel. У каждой подмодели может быть собственное сопоставление для преобразования, зарегистрированное по имени её класса или по её model_type. При загрузке родительской модели функция get_model_conversion_mapping обходит подмодели в порядке обхода в глубину, собирает их сопоставления и автоматически ограничивает область действия каждого преобразования путём подмодуля с помощью scope_prefix.

Composite model:                              Per-submodel mappings (auto-scoped):
LlavaForConditionalGeneration
├── vision_model: SiglipVisionModel    →     SiglipVisionModel mapping (scope="vision_model")
└── language_model: LlamaForCausalLM   →     LlamaForCausalLM mapping  (scope="language_model")

scope_prefix — это путь с точками к подмодулю ("vision_model", "language_model.model" и т. д.). Преобразование с областью действия срабатывает только для ключей, начинающихся с f"{scope_prefix}."; префикс удаляется перед сопоставлением с шаблоном и добавляется обратно после подстановки, поэтому отображение каждого подмоделя записывается относительно подмоделя, точно так, как если бы он был корневым.

Архитектура

Система построена вокруг нескольких ключевых компонентов, определенных в core_model_loading.py:

Фаза 1 — обработка по ключам (итерация по ключам чекпоинта):

  1. Пройдите по списку трансформаций один раз. Срабатывает каждый подходящий WeightRenaming (например, block_sparse_moe → mlp), и не более одного WeightConverter может «заявить» ключ (например, experts.*.w1.weight).
  2. Разбить на шарды (TP) и отправить на устройство асинхронно с помощью ThreadPoolExecutor.
  3. Собирайте тензоры с одинаковым source_pattern в группы (например, все веса экспертов MoE, проекции gate + up).

Фаза 2 — обработка по каждому отображению (итерация по собранным отображениям):

  1. Декуантизация/десериализация (только для предварительно квантованных контрольных точек).
  2. Применить цепочку ConversionOps: Chunk, Concatenate, MergeModulelist, Transpose и т. д.
  3. Квантование на лету (если модель не была предварительно квантована).
  4. Установите параметр Set parameter для модели.

WeightTransform

Базовый класс, который обрабатывает сопоставление с образцом и сбор тензоров:

  • Компиляция шаблонов: исходные шаблоны — это полные регулярные выражения, сопоставляемые с помощью re.search(). Вилдкард * сопоставляет любой индексированный компонент и объединяет все совпадения для пакетных операций.
  • Группы захвата и обратные ссылки: группы захвата в исходных шаблонах можно использовать в целевых шаблонах как \1, \2, …, чтобы сохранить подстроки (например, индексы слоёв) при переименовании.
  • Ограничение области: scope_prefix (устанавливается автоматически для каждой подмодели функцией get_model_conversion_mapping) ограничивает преобразование ключами, находящимися по этому пути. Префикс удаляется перед сопоставлением и добавляется обратно после подстановки.
  • Переименование ключей: rename_source_key() применяет регулярное выражение (с учётом области видимости) и возвращает (renamed_key, source_pattern), чтобы загрузчик знал, какой конвертер, если таковой есть, «заявил» этот ключ.
  • Сбор тензоров: add_tensor() накапливает разрешённые тензоры (или Future) по их source_pattern, чтобы все тензоры, необходимые для одного преобразования (например, все веса экспертов MoE), были сгруппированы в пакет до запуска цепочки операций.
  • Обратимость: reverse_transform() меняет местами исходные и целевые паттерны и инвертирует каждую операцию, поэтому тот же список, прочитанный в обратном порядке, управляет сохранением.
  • Отслеживание: was_used() сообщает, совпал ли трансформ хотя бы с одним ключом при загрузке; это необходимо для того, чтобы небиективные переименования (например, PrefixChange, добавляющий префикс, который может уже присутствовать) можно было симметрично применить повторно при сохранении.

WeightRenaming

WeightRenaming — это специализированный WeightTransform для простого переименования ключей без операций над тензорами. В отличие от WeightConverter, WeightRenaming не claim ключ, поэтому несколько переименований могут свободно выполняться последовательно. На пути загрузки все переименования выполняются до конвертера; на пути сохранения (инвертированный список) все инвертированные переименования выполняются после инвертированного конвертера — см. правило порядка выше.

# Legacy checkpoint compatibility
WeightRenaming("LayerNorm.gamma", "LayerNorm.weight")

# Module path changes
WeightRenaming(".block_sparse_moe.", ".mlp.")

PrefixChange — это высокоуровневая обёртка над WeightRenaming для распространённого случая удаления или добавления целого компонента пути. Необязательный параметр model_prefix ограничивает область действия операции ключами в соответствующем пространстве имён:

# "model.layers.bad_prefix.weight" → "model.layers.weight"
PrefixChange(prefix_to_remove="bad_prefix", model_prefix="model.layers")
# "layers.0.weight" → "model.layers.0.weight"
PrefixChange(prefix_to_add="model")

WeightConverter

WeightConverter расширяет WeightTransform, добавляя цепочку ConversionOps, которые применяются к собранным тензорам. Поддерживаются четыре кардинальности:

КардинальностьИсходные шаблоныЦелевые паттерныТипичная операция
один к одному11Transpose, PermuteForRope
один ко многим1>1Фрагмент (например, распаковка qkv_proj)
многие-к-одному>11Concatenate, MergeModulelist (например, объединение экспертов)
многие-ко-многим>1>1только с операциями, которые явно это поддерживают (например, ErnieFuseAndSplitTextVisionExperts)
WeightConverter(
    source_patterns=[".experts.*.w1.weight", ".experts.*.w3.weight"],
    target_patterns=".experts.gate_up_proj",
    operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
)

Объект WeightConverter также обратим: reverse_transform() меняет местами источник и целевой объект и заменяет каждую операцию на её reverse_op, поэтому зарегистрированное отображение преобразования является двунаправленным по построению (при загрузке используется список как есть, при сохранении — в обратном порядке).

Порядок переименований и конвертеров

Размещайте записи WeightRenaming перед записями WeightConverter и следите за тем, чтобы их листья не пересекались: переименования нормализуют ключи, которые потребляют конвертеры, но никогда не должны нацеливаться на лист, создаваемый конвертером. Путь сохранения опирается на это, чтобы инвертировать отображение в два этапа (сначала обратные конвертеры, затем обратные переименования).

Список трансформаций обходится последовательно, по одному разу для каждого ключа контрольной точки. Для каждого ключа:

  • Каждый WeightRenaming, который совпадает, срабатывает; несколько переименований могут выполняться последовательно.
  • Первый WeightConverter, который претендует на ключ. Последующие конвертеры пропускаются — это гарантирует, что тензор будет направлен в один конвертер для шага слияния/разделения, и именно поэтому наличие двух конвертеров с пересекающимися намерениями является ошибкой конфигурации.
weight_mapping = [
    WeightRenaming("^old_prefix", "encoder"),              # rename runs always
    WeightConverter(                                       # converter claims the key
        "attn.qkv_proj.weight",
        ["attn.q_proj.weight", "attn.k_proj.weight", "attn.v_proj.weight"],
        operations=[Chunk(dim=0)],
    ),
]
# Load:  "old_prefix.attn.qkv_proj.weight"
#   → WeightRenaming  → "encoder.attn.qkv_proj.weight"
#   → WeightConverter → "encoder.attn.{q,k,v}_proj.weight"
#
# Save: list reversed, each transform inverted:
#   → rev(WeightConverter) repacks QKV → "encoder.attn.qkv_proj.weight"
#   → rev(WeightRenaming)  fixes prefix → "old_prefix.attn.qkv_proj.weight"

Операции преобразования

Класс WeightConverter содержит несколько операций, которые выполняются при вызове from_pretrained() для преобразования исходных тензоров контрольной точки в целевые тензоры модели.

Операции полностью обратимы. Сохранение отменяет преобразования и возвращает исходную контрольную точку, что позволяет легко работать с различными фреймворками.

ОперацияОбратный
Chunk(dim)Concatenate(dim)
Concatenate(dim)Chunk(dim)
MergeModulelist(dim)SplitModulelist(dim)
SplitModulelist(dim)MergeModulelist(dim)
Transpose(d0, d1)Transpose(d1, d0)
PermuteForRope()PermuteForRope()
Conv3dToLinear(...)LinearToConv3d(...)

Фрагмент

Операция Chunk разбивает тензор на равные части вдоль заданного измерения. Например, если модель ожидает Q, K и V в виде трёх отдельных тензоров, а не одного.

WeightConverter(
    "self_attn.qkv_proj",
    ["self_attn.q_proj", "self_attn.k_proj", "self_attn.v_proj"],
    operations=[Chunk(dim=0)],
)

Соединить

Операция Concatenate объединяет отдельные тензоры в один. Например, если модель ожидает Q, K и V в виде единого тензора, а не отдельных тензоров.

WeightConverter(
    ["self_attn.q_proj", "self_attn.k_proj", "self_attn.v_proj"],
    "self_attn.qkv_proj",
    operations=[Concatenate(dim=0)],
)

MergeModulelist

MergeModulelist объединяет список 2D-тензоров в один 3D-тензор. Например, вы можете использовать MergeModulelist вместе с Concatenate, чтобы сложить эксперты в MoE и упаковать их в один тензор.

WeightConverter(
    ["block_sparse_moe.experts.*.w1.weight", "block_sparse_moe.experts.*.w3.weight"],
    "mlp.experts.gate_up_proj",
    operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
)

SplitModulelist

SplitModulelist разбивает трёхмерный тензор обратно на список двумерных тензоров. Например, можно разделить стопку экспертов на отдельных экспертов.

WeightConverter(
    "mlp.experts.down_proj",
    "block_sparse_moe.experts.*.w2.weight",
    operations=[SplitModulelist(dim=0)],
)

PermuteForRope

PermuteForRope преобразует веса из перемешанного формата в формат sin/cos. Например, вы можете объединить Chunk с PermuteForRope, чтобы разделить объединённый тензор QKV и применить перестановку RoPE в формате sin/cos к Q и K.

WeightConverter(
    ["model.layers.*.self_attn.qkv_proj.weight"],
    [
        "model.layers.*.self_attn.q_proj.weight",
        "model.layers.*.self_attn.k_proj.weight",
        "model.layers.*.self_attn.v_proj.weight",
    ],
    operations=[Chunk(dim=0), PermuteForRope()],
)

Транспонирование

Transpose меняет местами измерения тензора. Полезно для преобразования раскладок весов между различными соглашениями.

WeightConverter(
    source_patterns="mlp.gate.weight",
    target_patterns="mlp.text_moe.gate.weight",
    operations=[Transpose(dim0=0, dim1=1)],
)

Цепочки операций

Операции можно объединять в цепочки для выполнения сложных преобразований. Операции выполняются последовательно, при этом выход каждой операции становится входом для следующей.

Пример: конвертация Mixtral MoE

WeightConverter(
    source_patterns=[
        ".experts.*.w1.weight",  # gate_proj per expert
        ".experts.*.w3.weight",  # up_proj per expert
    ],
    target_patterns=".experts.gate_up_proj",
    operations=[
        MergeModulelist(dim=0),  # Stack all experts: (n_experts, in, out)
        Concatenate(dim=1),      # Fuse gate+up: (n_experts, in, 2*out)
    ],
)

Поток данных:

Input:
  ".experts.*.w1.weight": [tensor_0, tensor_1, ..., tensor_7]  # 8 experts
  ".experts.*.w3.weight": [tensor_0, tensor_1, ..., tensor_7]  # 8 experts

After MergeModulelist(dim=0):
  ".experts.*.w1.weight": (8, 4096, 14336)  # stacked gate
  ".experts.*.w3.weight": (8, 4096, 14336)  # stacked up

After Concatenate(dim=1):
  ".experts.gate_up_proj": (8, 4096, 28672)  # fused gate_up

Правила сопоставления

  • Исходные шаблоны — это полные регулярные выражения, обрабатываемые с помощью re.search(). ^ привязывает выражение к началу scoped-ключа (после удаления scope_prefix).
  • * — это подстановочный символ для каждого индекса, который собирает все соответствующие тензоры под одним и тем же исходным шаблоном (сохраняя порядок контрольной точки для корректного объединения).
  • Группы, захваченные в исходных шаблонах, можно ссылаться как \1, \2, … в целевых шаблонах, чтобы сохранить части исходного ключа (например, индексы слоёв).
  • Ограниченные трансформации (установлен scope_prefix) сопоставляются только с ключами, начинающимися с f"{scope_prefix}.".

Регистрация отображения для преобразования

Список преобразований регистрируется по строковому ключу — либо model_type (например, "mixtral"), либо имени класса (например, "LlavaModel"):

from transformers.conversion_mapping import register_checkpoint_conversion_mapping

register_checkpoint_conversion_mapping(
    "my_model_type",
    [
        WeightRenaming(".old.", ".new."),
        WeightConverter(
            ".experts.*.w1.weight",
            ".experts.gate_proj",
            operations=[MergeModulelist(dim=0)],
        ),
    ],
)

Правила поиска

При обработке PreTrainedModel функцией get_model_conversion_mapping каждый подмодуль PreTrainedModel посещается в порядке обхода в глубину (DFS) (nn.Module.named_modules(), отфильтрованный по экземплярам PreTrainedModel). Каждый подмодель разрешается в два этапа: сначала выполняется пользовательский фильтр кода, затем выполняется поиск зарегистрированного отображения.

Модели с пользовательским кодом пропускаются до начала любого поиска. Подмодель считается написанной на пользовательском коде, если is_custom_code() возвращает True. Это касается моделей, загруженных с Hub с параметром trust_remote_code=True, а также любых классов моделей, отсутствующих в Transformers. Модели с пользовательским кодом не наследуют отображение для преобразования, поскольку имя их класса или model_type может совпадать с именем нативной модели. Например, пользовательская архитектура, задающая model_type="mixtral", не получит встроенные преобразования для слияния экспертов Mixtral.

Явно зарегистрируйте модель с пользовательским кодом с помощью register_checkpoint_conversion_mapping, чтобы применить отображение для преобразования. При регистрации имя класса или model_type добавляется в набор пользовательских отображений, что освобождает модель от пропуска пользовательского кода и направляет её через стандартный поиск, описанный ниже.

Для каждой подмодели, проходящей фильтр пользовательского кода:

  1. Сначала выполняется поиск по имени класса, затем по model_type. Если для одного и того же модуля зарегистрированы оба варианта, преимущество имеет сопоставление по имени класса, а вариант model_type для этого модуля игнорируется — это позволяет задаче (например, LlavaForConditionalGeneration) переопределять общую базовую настройку model_type ("llava").
  2. Выбранное сопоставление имеет scope_prefix, установленное в виде точечного пути подмодуля ("" для корневого).
  3. Ancestor-based deduplication определяет, следует ли сохранить отображение:
    • Если путь предка уже присвоил тот же идентификатор (имя класса или model_type), подмодуль пропускается — неограниченная или более широкая по области видимости маппинг предка уже покрывает это поддерево.
    • Если его присвоил только соседний модуль, подмодуль сохраняется со своим scope_prefix. Каждый соседний модуль получает собственное отображение с областью видимости.

Списки просмотренных имён классов и model_type отслеживаются отдельно, с одним нюансом: когда модуль сопоставляется по имени класса, его model_type не добавляется в список просмотренных. Это позволяет другим модулям, имеющим тот же model_type, но не имеющим сопоставления, специфичного для класса (например, DetrModel в рамках DetrForSegmentation), оставаться доступными через поиск по model_type.

Сопоставления на основе классов и псевдонимы model_type

Оба стиля сосуществуют в _MODEL_TO_CONVERSION_PATTERN:

_MODEL_TO_CONVERSION_PATTERN = {
    # model_type aliases (lookup by config.model_type)
    "minimax": "mixtral",
    "qwen3_moe": "qwen2_moe",
    "mistral3": "llava",
    # class-name aliases (lookup by type(submodule).__name__)
    "PaliGemmaModel": "LlavaModel",
    "MaskFormerDetrDecoder": "DetrModel",
    ...
}

Ключи с именем класса предпочтительны, когда model_type общий, но для конкретного класса требуется иное поведение.

Интеграция тензорного параллелизма

Система динамической загрузки интегрируется с тензорным параллелизмом (TP) через иерархию TensorParallelLayer, определённую в src/transformers/integrations/tensor_parallel.py.

Когда включён TP, тензоры разбиваются во время материализации, а не после. Это означает, что каждый ранг загружает только ту часть тензора, которая ему нужна.

def spawn_tp_materialize(thread_pool, tensor, sharding_method, tensor_idx, device, dtype):
    def _job():
        return sharding_method.shard_tensor(tensor, tensor_idx=tensor_idx, device=device, dtype=dtype)
    return thread_pool.submit(_job)

Доступные стили параллелизма

СтильРазмерность фрагмента весовОписание
colwise-2По столбцам: разделение выходных признаков
rowwise-1По строкам: входные признаки разбиты на фрагменты
packed_colwise-2Для объединённых весов (gate_up_proj)
packed_rowwise-1Для объединённых весов
embedding_rowwise0Параллелизм словаря
grouped_gemm0Экспертная параллельность для MoE
sequence_parallelNoneБез шардирования весов

Обработка упакованных весов

Для объединённых весов, таких как gate_up_proj, необходимо проявить особую тщательность при их корректном разбитии:

def get_packed_weights(param, empty_param, device_mesh, rank, dim):
    """
    Interleaves gate and up shards correctly.

    Packed tensor: [G0 G1 G2 G3 | U0 U1 U2 U3]

    With TP=2:
    - Rank 0 gets: [G0 G1 | U0 U1]
    - Rank 1 gets: [G2 G3 | U2 U3]
    """

Операция TP хранится в WeightTransform и применяется после операций преобразования:

if matched_tp_pattern := tp_plan_alt.search(renamed_key):
    tp_layer = ALL_PARALLEL_STYLES[model.tp_plan[matched_tp_pattern]]
    mapping.distributed_operation = tp_layer(
        device_mesh=device_mesh,
        rank=device_mesh.get_local_rank(),
        empty_param=empty_param.clone()
    )

Интеграция квантования

Квантование встраивается в процесс загрузки двумя способами, в зависимости от того, является ли контрольная точка уже квантованной:

  • Предварительно квантованные контрольные точки: квантизатор предоставляет экземпляры WeightConverter (через get_weight_conversions()), которые десериализуют квантованные тензоры. Типы данных контрольных точек сохраняются, чтобы избежать нежелательных приведений.
  • Квантование на лету: квантизатор предоставляет операцию квантования, которая применяется после операций преобразования и квантует веса по мере их загрузки.

Квантизатор также может переписать весь список преобразований в конце get_model_conversion_mapping с помощью update_weight_conversions(...) — например, FP8-деквантизатор добавляет операцию Fp8Dequantize в начало каждого существующего конвертера, чтобы масштабы по блокам применялись до того, как операции слияния экспертов / конкатенации выровняют структуру по экспертам.

Быстрая и эффективная загрузка моделей

Загрузка модели происходит быстрее и требует меньше памяти, поскольку загрузчик знает, какие тензоры необходимы для операций, и планирует их материализацию лениво.

Загрузчик просматривает контрольную точку один раз, чтобы найти совпадения с шаблоном и собрать тензоры. Он сохраняет их в виде объектов Future и отправляет в пул потоков для асинхронной загрузки без блокировки GIL. Загрузка параметра начинается сразу, как только для него становится доступен поток.

Если на вашей системе выполняются другие ресурсоёмкие процессы, использование нескольких потоков может замедлить загрузку, а не ускорить её. В этом случае установите переменную окружения HF_DEACTIVATE_ASYNC_LOAD=1, чтобы загружать веса последовательно.

По умолчанию используется 4 потока для асинхронной загрузки параметров. Это обеспечивает оптимальный баланс между различными сценариями загрузки и аппаратным обеспечением. Работа в основном ограничена операциями ввода-вывода, однако в зависимости от аппаратного обеспечения ускорителя и требуемого при загрузке dtype она может стать ограниченной по CPU/GPU, если dtype отличается от сериализованного (это требует дополнительной операции копирования).

Асинхронная и синхронная загрузка

def spawn_materialize(thread_pool, tensor, device, dtype) -> Future | Callable:
    def _job():
        return _materialize_copy(tensor, device, dtype)

    if thread_pool is not None:
        return thread_pool.submit(_job)  # Async: returns Future
    else:
        return _job  # Sync: returns Callable (deferred execution)

Синхронная загрузка используется в следующих случаях:

  • Установлена переменная окружения HF_DEACTIVATE_ASYNC_LOAD=1.
  • Включена выгрузка на диск (ограничения памяти требуют последовательной загрузки).
  • Квантование на лету включено (предотвращает опережение потоков-исполнителей шага квантования).

Поток материализации

1. Checkpoint iteration (Phase 1):
   - For each key, walk the transform list once
   - Submit materialization job to ThreadPoolExecutor
   - Job returns Future (async) or Callable (sync)
   - Collect into the matching WeightConverter / WeightRenaming

2. Per-mapping processing (Phase 2, one mapping at a time):
   - materialize_tensors() waits for this mapping's Futures only
   - Apply conversion operations chain (self.operations)
   - Apply quantization operation (if on-the-fly)
   - Set parameters on model
   - Delete realized tensors immediately

3. Cleanup:
   - Thread pool shutdown (with cancel_futures=True for interrupts)

Эффективность использования памяти

При преобразовании веса конвертер ожидает материализации всех необходимых тензоров, если они ещё не загружены. Например, операция MergeModulelist требует, чтобы все веса в ModuleList были загружены перед слиянием.

Слияние тензоров требует временной копии, поэтому такие операции, как MergeModulelist и Concatenate, требуют в 2 раза больше памяти, чем исходные тензоры, в процессе преобразования. После слияния в памяти остаётся только результирующий тензор. Теоретический пиковый расход памяти равен размеру модели плюс объём тензоров, необходимых для самой крупной операции MergeModulelist или Concatenate.

Этот худший случай возникает только тогда, когда все остальные параметры загружаются до запуска ресурсоёмкого преобразования. Его вызывают две сценария.

  1. Все параметры загружаются асинхронно до начала ресурсоемкого преобразования (пул потоков работал быстрее очереди преобразований).
  2. Самым требовательным к ресурсам является последний этап конвертации.

Например, для MoE-модели, использующей MergeModulelist для экспертов на каждом слое, теоретический пиковый расход памяти в худшем случае равен размеру модели плюс объём экспертов на одном слое.

Такие худшие сценарии встречаются редко. Фактический пик потребления памяти обычно остается близким к размеру модели.

Обратимость

Система поддерживает сохранение моделей с обратными преобразованиями, что обеспечивает циклическое сохранение и загрузку. Сохранение выполняется в два этапа: сначала применяются обратные конвертеры (каждый тензор соответствует не более чем одному), затем — обратные переименования, согласно описанному выше правилу порядка.

def revert_weight_conversion(model, state_dict):
    """Applies reverse conversions for saving."""
    weight_conversions = getattr(model, "_weight_conversions", None)

    # Reverse all transforms
    reverse_weight_conversion = [
        conversion.reverse_transform() for conversion in weight_conversions
    ]

    # Apply in reverse
    for first_param_name, reversed_converter in conversion_mapping.items():
        realized_value = reversed_converter.convert(first_param_name, model=model)

Список трансформаций, применяемых при загрузке, кэшируется в модели в поле _weight_conversions (сохраняются только те записи, которые действительно сработали, поэтому небиективные переименования, такие как PrefixChange, корректно применяются симметрично повторно). Если модель была создана без использования from_pretrained (и, следовательно, не имеет поля _weight_conversions), функция revert_weight_conversion переключается на пересчёт соответствия через get_model_conversion_mapping и исключает из него все PrefixChange (невозможно определить, был ли префикс в исходном чекпоинте).

Целевые шаблоны могут содержать элементы регулярных выражений, которые необходимо обработать для обратного направления:

def process_target_pattern(pattern: str) -> tuple[str, str | None]:
    """
    - Removes `^` and `$` anchors
    - Removes negative lookahead/lookbehind
    - Detects capturing groups, replaces with \1
    """

Реальные примеры

MoE в стиле Mixtral

Формат контрольной точки:

model.layers.0.block_sparse_moe.experts.0.w1.weight  # gate per expert
model.layers.0.block_sparse_moe.experts.0.w2.weight  # down per expert
model.layers.0.block_sparse_moe.experts.0.w3.weight  # up per expert
...
model.layers.0.block_sparse_moe.experts.7.w1.weight

Формат модели:

model.layers.0.mlp.experts.gate_up_proj  # (8, 4096, 28672)
model.layers.0.mlp.experts.down_proj     # (8, 14336, 4096)

Сопоставление для конвертации (из conversion_mapping.py):

"mixtral": [
    WeightRenaming(".block_sparse_moe.", ".mlp."),
    WeightConverter(
        source_patterns=[".experts.*.w1.weight", ".experts.*.w3.weight"],
        target_patterns=".experts.gate_up_proj",
        operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
    ),
    WeightConverter(
        source_patterns=[".experts.*.w2.weight"],
        target_patterns=".experts.down_proj",
        operations=[MergeModulelist(dim=0)],
    ),
],

Композитная модель «зрение-язык» (Gemma3)

В Gemma3 используется стандартная схема «разная логика префикса для head-модели и для базовой модели». Зарегистрированы две записи (здесь через алиасы, указывающие на общие списки "llava" / "LlavaModel"):

# model_type: applies to Gemma3ForConditionalGeneration / Gemma3ForSequenceClassification
"gemma3": "llava"           # → adds "model." in front of language_model / vision_tower / ...

# class:    applies to the inner Gemma3Model only
"Gemma3Model": "LlavaModel"  # → minimal rename inside the already-prefixed namespace

DFS-обход для Gemma3ForConditionalGeneration:

  1. Root — поиск класса не удаётся (Gemma3ForConditionalGeneration не зарегистрирован), поиск model_type удаётся ("gemma3") → преобразования с переписыванием префикса "llava" добавляются без области видимости, помещая language_model, vision_tower, multi_modal_projector под model.*.
  2. Внутренний model: Gemma3Model — поиск класса (Gemma3Model → LlavaModel) → применяется только маппинг LlavaModel, ограниченный областью "model". Гораздо более широкие переименования префикса "gemma3" (="llava") не применяются повторно, что и требуется: внутренняя модель находится в пространстве имён, где префикс уже корректен.

Та же форма пары используется всеми VLM семейства Llava (PaliGemma, InternVL, Mistral3, …). Запись model_type выполняет префиксную модификацию head-модели; запись class сохраняет минимальное отображение внутренней базовой модели.

Более глубокая вложенность с переопределением для конкретного head (DETR)

DetrForSegmentation демонстрирует переопределение, специфичное для конкретного head, наложенное поверх двух вложенных уровней:

DetrForSegmentation                  (class registered: segmentation-only renames)
├── detr: DetrForObjectDetection     (no mapping; just walked through)
│   └── model: DetrModel             (class registered: shared base transforms)
│       └── backbone, encoder, ...
└── mask_head, bbox_attention        (head-specific weights)

В этом участвуют два отображения (по одному на каждый зарегистрированный ключ):

"DetrModel":           [WeightRenaming("backbone.conv_encoder", "backbone"), ...]      # shared base
"DetrForSegmentation": [WeightRenaming("mask_head.lay1", "mask_head.conv1.conv"), ...] # head-specific

Обход в глубину (DFS):

  1. Корневой DetrForSegmentation сопоставляется по классу → добавлены переименования сегментации unscoped.
  2. detr: DetrForObjectDetection не зарегистрирован → трансформации не добавляются; DFS продолжает обход внутрь него.
  3. detr.model: DetrModel совпадает по классу → базовые трансформации добавляются с scope_prefix="detr.model".

Именно поэтому DetrForObjectDetection не требует собственного сопоставления: единственное зарегистрированное сопоставление в его поддереве (DetrModel) автоматически ограничивается нужным путём.

Алиасы, привязанные к классу, переиспользуют базовое сопоставление без дополнительной регистрации: "MaskFormerDetrDecoder": "DetrModel" позволяет декодеру MaskFormer использовать те же преобразования под собственным именем класса.

Пользовательские операции (ERNIE 4.5 VL MoE)

Если встроенных операций недостаточно, можно создать собственный подкласс ConversionOps. Например, для ERNIE 4.5 VL MoE необходимо разделить список общих экспертов между текстовой и визуальной модальностями — с этим не справляется ни одна из встроенных операций. Пользовательская операция ErnieFuseAndSplitTextVisionExperts разделяет и заново складывает экспертов по двум целевым ключам:

"ernie4_5_vl_moe": [
    WeightRenaming("vision_model", "vision_tower"),
    WeightConverter(
        source_patterns=["experts.*.down_proj.weight"],
        target_patterns=[
            "text_moe.experts.down_proj",
            "vision_moe.experts.down_proj",
        ],
        operations=[ErnieFuseAndSplitTextVisionExperts(stack_dim=0, concat_dim=1)],
    ),
],

Пользовательские операции должны реализовывать convert() и свойство reverse_op для поддержки циклического сохранения и загрузки.

Псевдонимы типов моделей

Многие модели используют общие паттерны конвертации:

_MODEL_TO_CONVERSION_PATTERN = {
    "mixtral": "mixtral",
    "minimax": "mixtral",
    "qwen2_moe": "qwen2_moe",
    "deepseek_v2": "qwen2_moe",
    "deepseek_v3": "qwen2_moe",
    "qwen3_moe": "qwen2_moe",
    "olmoe": "qwen2_moe",
    ...
}

Повторное использование компонентов динамической загрузки

Динамическая загрузка весов не ограничивается полными контрольными точками модели. Те же базовые элементы позволяют загрузить любой набор весов, если вы можете описать, как ключи контрольной точки сопоставляются с параметрами, и убедиться, что целевые модули существуют.

В общих чертах контракт выглядит так:

  1. Подготовьте пространство имён модели. Убедитесь, что модули/параметры, которые вы хотите загрузить, присутствуют и названы так, как их будет нацеливать ваша карта соответствия. Для адаптеров это означает вызов inject_adapter_in_model(...), чтобы модули адаптера существовали до загрузки. Для пользовательских головок или дополнительных модулей сначала создайте их экземпляры в модели.
  2. Describe how to map weights. Составьте список преобразований/переименований (например, в вспомогательной функции вроде _build_peft_weight_mapping(...)) с помощью WeightConverter или WeightRenaming. Здесь вы описываете, как ключи контрольной точки следует преобразовать, разделить, объединить или переименовать, чтобы они соответствовали пространству имён вашей модели. В основном можно выполнить три действия:
    • добавить операции в список конвертеров: они будут применяться ко всем весам, кроме тех, которые собраны в любом из WeightConverter. Как правило, это должны быть операции WeightRenaming
    • добавить операции в список операций каждого конвертера: именно так происходит для Quantization, где мы просто добавляем операцию квантования после списка операций любого WeightConverter.
    • замените операции replace / map на собственные: именно так работает peft. Мы заменяем операцию Concatenate, например, в mixtral, на PeftConcatenate (которая определена в PEFT). Таким образом, при чтении контрольной точки адаптера собираются веса, подлежащие конкатенации, и они корректно форматируются для peft
  3. Load + finalize + report. Используйте основной загрузчик для выполнения преобразования и заполнения тензоров, затем завершите загрузку и зафиксируйте результаты. Конкретно, этот процесс выглядит так:
    • LoadStateDictConfig(...) + _load_pretrained_model(...) для загрузки и конвертации.
    • _finalize_load_state_dict(...) — для перемещения отсутствующих или несовпадающих тензоров с meta, их инициализации и связывания весов.
    • log_state_dict_report(...) — для отчёта о недостающих/неожиданных/несовпадающих ключах (и ошибках преобразования).

Эти API предоставлены, чтобы вы могли работать с собственным кодом и форматами весов, при этом получая максимальную выгоду от наиболее эффективной загрузки весов, их шардирования и удобного использования API transformers!

Справочник по ключевым файлам

ФайлНазначение
src/transformers/core_model_loading.pyБазовая логика загрузки, WeightConverter, WeightRenaming, ConversionOps
src/transformers/conversion_mapping.pyВстроенные сопоставления и композиция по подмоделям (get_model_conversion_mapping)
src/transformers/integrations/tensor_parallel.pyКлассы и утилиты шардирования TP
src/transformers/quantizers/base.pyХуки квантования и базовый класс
Update on GitHub