Skip to content
Docs Pydantic Docs

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[AsyncInferenceClient]

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-V4-Pro', 'deepseek-ai/DeepSeek-V4.1-Flash', 'moonshotai/Kimi-K3', 'zai-org/GLM-5.3', 'Qwen/Qwen3.8-27B', 'MiniMaxAI/MiniMax-M3', 'openai/gpt-oss-120b', 'google/gemma-4-31B-it', 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8']

HuggingFaceModelName

Possible Hugging Face model names.

You can browse available models here.

Default: str | LatestHuggingFaceModelNames