Hugging Face

Hugging Face 是一个 AI 平台，拥有所有主流的开源模型、数据集、MCP 和演示。您可以使用推理提供程序 (Inference Providers) 在可扩展的无服务器基础设施上运行像 DeepSeek R1 这样的开源模型。

安装

要使用 HuggingFaceModel，您需要安装 pydantic-ai，或者安装带有 huggingface 可选组的 pydantic-ai-slim。

pipuv

pip install "pydantic-ai-slim[huggingface]"

uv add "pydantic-ai-slim[huggingface]"

配置

要使用 Hugging Face 推理，您需要设置一个账户，该账户将为您提供推理提供程序 (Inference Providers) 的免费套餐额度。要设置推理，请按以下步骤操作：

前往 Hugging Face 并注册一个账户。
在 Hugging Face 中创建一个新的访问令牌。
将 HF_TOKEN 环境变量设置为您刚刚创建的令牌。

一旦您有了 Hugging Face 访问令牌，就可以将其设置为环境变量：

export HF_TOKEN='hf_token'

用法

然后您可以通过名称使用 HuggingFaceModel：

from pydantic_ai import Agent

agent = Agent('huggingface:Qwen/Qwen3-235B-A22B')
...

或者直接用模型名称初始化模型

from pydantic_ai import Agent
from pydantic_ai.models.huggingface import HuggingFaceModel

model = HuggingFaceModel('Qwen/Qwen3-235B-A22B')
agent = Agent(model)
...

默认情况下，HuggingFaceModel 使用 HuggingFaceProvider，它会自动选择可用于该模型的第一个推理提供程序（Cerebras、Together AI、Cohere 等），并根据您在 https://hugging-face.cn/settings/inference-providers 中的首选顺序排序。

配置提供程序

如果您想在代码中向提供程序传递参数，可以以编程方式实例化 HuggingFaceProvider 并将其传递给模型：

from pydantic_ai import Agent
from pydantic_ai.models.huggingface import HuggingFaceModel
from pydantic_ai.providers.huggingface import HuggingFaceProvider

model = HuggingFaceModel('Qwen/Qwen3-235B-A22B', provider=HuggingFaceProvider(api_key='hf_token', provider_name='nebius'))
agent = Agent(model)
...

自定义 Hugging Face 客户端

HuggingFaceProvider 还通过 hf_client 参数接受一个自定义的 AsyncInferenceClient 客户端，这样您就可以自定义 headers、bill_to（支付给您所属的 HF 组织）、base_url 等参数，具体定义请参见 Hugging Face Hub Python 库文档。

from huggingface_hub import AsyncInferenceClient

from pydantic_ai import Agent
from pydantic_ai.models.huggingface import HuggingFaceModel
from pydantic_ai.providers.huggingface import HuggingFaceProvider

client = AsyncInferenceClient(
    bill_to='openai',
    api_key='hf_token',
    provider='fireworks-ai',
)

model = HuggingFaceModel(
    'Qwen/Qwen3-235B-A22B',
    provider=HuggingFaceProvider(hf_client=client),
)
agent = Agent(model)
...