pydantic_ai.models.huggingface

Setup

For details on how to set up authentication with this model, see model configuration for Hugging Face.

HuggingFaceModelSettings

Bases: ModelSettings

Settings used for a Hugging Face model request.

HuggingFaceModel

Bases: Model

A model that uses Hugging Face Inference Providers.

Internally, this uses the HF Python client to interact with the API.

Apart from __init__, all methods are private or match those of the base class.

Attributes

base_url

The base URL of the provider.

Type: str

model_name

The model name.

Type: HuggingFaceModelName

system

The system / model provider.

Type: str

Methods

__init__

def __init__(
    model_name: str,
    provider: Literal['huggingface'] | Provider[AsyncInferenceClient] = 'huggingface',
    profile: ModelProfileSpec | None = None,
    settings: ModelSettings | None = None,
)

Initialize a Hugging Face model.

Parameters

model_name : str

The name of the Model to use. You can browse available models here.

provider : Literal[‘huggingface’] | Provider[AsyncInferenceClient] Default: 'huggingface'

The provider to use for Hugging Face Inference Providers. Can be either the string ‘huggingface’ or an instance of Provider[AsyncInferenceClient]. If not provided, the other parameters will be used.

profile : ModelProfileSpec | None Default: None

The model profile to use. Defaults to a profile picked by the provider based on the model name.

settings : ModelSettings | None Default: None

Model-specific settings that will be used as defaults for this model.

HuggingFaceStreamedResponse

Bases: StreamedResponse

Implementation of StreamedResponse for Hugging Face models.

Attributes

model_name

Get the model name of the response.

Type: str

provider_name

Get the provider name.

Type: str

provider_url

Get the provider base URL.

Type: str

timestamp

Get the timestamp of the response.

Type: datetime

LatestHuggingFaceModelNames

Latest Hugging Face models.

Default: Literal['deepseek-ai/DeepSeek-R1', 'meta-llama/Llama-3.3-70B-Instruct', 'meta-llama/Llama-4-Maverick-17B-128E-Instruct', 'meta-llama/Llama-4-Scout-17B-16E-Instruct', 'Qwen/QwQ-32B', 'Qwen/Qwen2.5-72B-Instruct', 'Qwen/Qwen3-235B-A22B', 'Qwen/Qwen3-32B']

HuggingFaceModelName

Possible Hugging Face model names.

You can browse available models here.

Default: str | LatestHuggingFaceModelNames