跳转到内容

Hugging Face

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

安装

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

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

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

配置

要使用 Hugging Face 的推理服务，您需要注册一个账户，该账户会为您提供在 推理提供商 上的免费额度。请按照以下步骤设置推理服务：

  1. 前往 Hugging Face 并注册一个账户。
  2. 在 Hugging Face 中创建一个新的访问令牌。
  3. 将 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，它会根据您在 https://hugging-face.cn/settings/inference-providers 中设置的偏好顺序，为模型自动选择第一个可用的推理提供商（如 Cerebras、Together AI、Cohere 等）。

配置提供商

如果您想在代码中向提供商传递参数，可以以编程方式实例化 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 客户端，这样您就可以根据 Hugging Face Hub Python 库文档 中的定义，自定义 headers、bill_to（将账单发送到您所属的 HF 组织）、base_url 等参数。

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)
...