Model Reference Catalog

The Transformers model reference catalog is the reader’s map from a desired architecture, task, or checkpoint to the correct documentation page and loading API. The catalog is not a single list of every implementation detail. It is a documentation surface that combines model loading guidance, Auto Class reference pages, a timeline of architectures, and the main documentation table of contents. Use this page when you know you need a model but are deciding whether to start from a checkpoint, an architecture-specific page, an Auto Class, or the broader contribution and customization guides.

Sources: docs/source/en/models.md, docs/source/en/model_doc/auto.md, docs/source/en/models_timeline.md, docs/source/en/_toctree.yml

Purpose and Scope

The model catalog solves two related problems. First, it helps users load pretrained models without memorizing every architecture class name. Second, it gives maintainers and advanced users an entry point into model-specific documentation, customization pages, and contribution material. The loading guide explains the difference between an architecture, which is the model skeleton, and a checkpoint, which is the trained weights for that architecture. That distinction matters because a checkpoint name can often drive automatic class selection, while a model family page explains the design and supported tasks in more detail.

Sources: docs/source/en/models.md, docs/source/en/model_doc/auto.md

The catalog also separates everyday use from documentation discovery. If the reader is building an application, the most direct path is usually to load a task-oriented Auto Class from a Hub checkpoint. If the reader is comparing model families, the model documentation pages and the timeline provide better context. If the reader is adding or modifying a model implementation, the table of contents points from the Models section into contribution pages for modular Transformers, model structure rules, processing components, tests, and pull request checks.

Sources: docs/source/en/_toctree.yml, docs/source/en/models_timeline.md

Relevant Source Files

• docs/source/en/model_doc/auto.md - Defines the Auto Classes documentation page, including AutoConfig, AutoTokenizer, AutoProcessor, modality processors, generic model classes, pretraining classes, and task-specific AutoModel variants.
• docs/source/en/models.md - Provides the Loading models guide, including the relationship between configurations, modeling files, checkpoints, model classes, and from-pretrained loading patterns.
• docs/source/en/models_timeline.md - Publishes the Models Timeline page and embeds the interactive timeline for browsing architectures over time by modality, task, and date range.
• docs/source/en/_toctree.yml - Places Loading models, customization, contribution pages, preprocessing docs, generation docs, optimization docs, and model-related guides into the official documentation navigation tree.

Catalog Structure in Documentation

The main documentation navigation places model-related material under the broader Base classes area, with a Models subsection that includes dynamic weight loading, loading models, customization, heterogeneous configurations, monkey patching, fusion mapping, model component customization, sharing, and exporting to production. Inside that same Models area, a nested Contribute subsection links to model contribution, modular Transformers, multimodal processing, vision and audio processing components, model structure rules, tracing intermediate outputs, auto-generated docstrings, model tests, pull request checks, and legacy model contribution. This organization keeps user-facing loading tasks near maintainer-facing model authoring tasks without treating them as the same workflow.

Sources: docs/source/en/_toctree.yml

The Loading models page is the conceptual center for readers who are not sure which class to import. It explains that Transformers provides pretrained models that can be loaded with a model class and the pretrained loading method. It also describes the typical files behind a model implementation: a configuration file with attributes such as layer counts, vocabulary size, and activation functions, and a modeling file that uses those attributes to build the layers and mathematical operations. At that stage, the architecture exists, but useful behavior comes from loading trained checkpoint weights.

Sources: docs/source/en/models.md

Core Primitives and Loading Choices

The central loading primitive is the pretrained loading method on model classes. The guide emphasizes that weights can come from the Hugging Face Hub or a local directory, and that safetensors weights are preferred when available because they are safer and faster to load than traditional pickle-based PyTorch serialization. The reader’s first decision is whether they need a bare model that returns hidden states or a model with a task head. A bare model is useful for embeddings and custom heads, while a task model is the usual choice for generation, classification, question answering, and other end tasks.

Sources: docs/source/en/models.md

Auto Classes are the catalog’s convenience layer. The Auto Classes page explains that the architecture can often be inferred from the checkpoint name or path passed to the pretrained loading method. Instantiating AutoConfig, AutoModel, or AutoTokenizer creates the relevant architecture class automatically. The same idea extends beyond text: the page also documents AutoFeatureExtractor, AutoImageProcessor, AutoVideoProcessor, and AutoProcessor. For model classes, the catalog distinguishes generic base classes, generic pretraining classes, and task-specific classes grouped by domain, so readers can choose by task rather than by architecture internals.

Sources: docs/source/en/model_doc/auto.md

Compact Reference

A minimal catalog-driven loading example is:

from transformers import AutoModelForCausalLM
 
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    device_map="auto",
)

This pattern captures the normal reader workflow: select a checkpoint, select the task family, and let the Auto Class resolve the model implementation. If the task changes, the Auto Class often changes while the checkpoint may stay the same, provided the architecture supports the requested head. If the checkpoint changes, the import can often remain stable because the configuration drives class selection. This is why the catalog gives prominent placement to Auto Classes rather than requiring users to begin every project from a model-specific class name.

Sources: docs/source/en/models.md, docs/source/en/model_doc/auto.md

Model Families and Timeline

The Models Timeline page complements the reference catalog by helping readers browse the library historically and visually. It presents an interactive chart of architectures across text, vision, audio, video, and multimodal use cases. The page tells readers to filter by modality or task, choose custom date ranges, and open a model card to inspect capabilities, supported tasks, and documentation. This is especially useful when a user knows the problem domain but not the model family, or when they want to understand how newer architectures relate to older library additions.

Sources: docs/source/en/models_timeline.md

The timeline should not replace the loading guide or the Auto Classes reference. Instead, treat it as a discovery tool. After finding a promising model family, move to the relevant model documentation or use the loading guide to select an appropriate checkpoint and class. For example, a reader comparing multimodal architectures may start in the timeline, open a model’s documentation, then return to AutoProcessor and the task-specific AutoModel class needed for implementation. That flow keeps exploration separate from the concrete code path used in an application.

Sources: docs/source/en/models_timeline.md, docs/source/en/model_doc/auto.md

Extending and Navigating the Catalog

Advanced users can extend Auto Classes for custom models. The Auto Classes page shows that a custom configuration and model can be registered so the same automatic loading style works for a new architecture. The important contract is that the configuration has a model type matching the registration key, and the model class declares the matching configuration class. This keeps a custom model compatible with the catalog’s loading style, because the configuration remains the source of truth used to select the correct implementation when pretrained assets are loaded.

Sources: docs/source/en/model_doc/auto.md

The table of contents also shows where to go when a catalog entry is not enough. For model customization, use the Models subsection pages for custom models, heterogeneous configurations, monkey patching, fusion mapping, and custom model components. For production or sharing workflows, use the sharing and exporting entries near the loading guide. For adding a new model to the library, follow the Contribute subsection rather than copying only a loading example. That path points readers toward modular model authoring, processor components, structure rules, tests, and pull request checks.

Sources: docs/source/en/_toctree.yml

Practical Navigation Flow

Start with the task and the checkpoint. If you already have a Hub checkpoint and a known task, choose the closest AutoModel task class and load it with the pretrained loading method. If you need to inspect architecture details, open the model family documentation and read its configuration and modeling expectations. If you are exploring alternatives, use the Models Timeline to narrow by modality, task, and date range before choosing a checkpoint. If you are changing the library itself, follow the contribution links in the Models section so loading behavior, processors, tests, and documentation stay aligned.

Sources: docs/source/en/models.md, docs/source/en/model_doc/auto.md, docs/source/en/models_timeline.md, docs/source/en/_toctree.yml