Hugging Face

Hugging Face

Hugging Face는 주요 오픈소스 모델·데이터셋·MCP·데모를 모두 가진 AI 플랫폼이에요. PydanticAI에서는 HuggingFaceModel로 Hugging Face의 Inference Providers를 통해 DeepSeek R1 같은 오픈소스 모델을 스케일러블한 서버리스 인프라에서 실행할 수 있어요.

출처: 공식문서

이 페이지는 Hugging Face Inference Providers를 통한 채팅 완성을 다뤄요. Hugging Face 임베딩 모델을 로컬에서(API 키 없이, 네트워크 호출 없이) 돌리려면 Sentence Transformers 임베딩 모델을 보세요. sentence-transformers 라이브러리의 어떤 모델이든 동작해요.

설치

HuggingFaceModel을 쓰려면 pydantic-ai를 설치하거나 pydantic-ai-slim을 huggingface 옵션 그룹과 함께 설치해야 해요.

Terminal

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

Terminal

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

설정

Hugging Face 추론을 쓰려면 계정을 만들어서 Inference Providers에서 무료 티어 허용량을 받아야 해요. 추론을 설정하려면 다음 단계를 따르세요.

  1. Hugging Face에 가서 계정을 만들어요.
  2. Hugging Face에서 새 액세스 토큰을 만들어요.
  3. 만든 토큰으로 HF_TOKEN 환경 변수를 설정해요.

Hugging Face 액세스 토큰을 받았으면 환경 변수로 설정할 수 있어요.

Terminal

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://hf.co/settings/inference-providers에서 당신이 선호하는 순서로 정렬된, 모델에 사용 가능한 추론 provider(Cerebras, Together AI, Cohere 등) 중 첫 번째를 자동 선택해요.

Provider 구성

코드에서 provider에 파라미터를 넘기고 싶다면 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 파이썬 라이브러리 문서에 정의된 대로 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)
...

스트리밍 취소

cancel()은 다른 작업에서 실행 중인 활성 로컬 스트림 pull을 포함해 안전하게 중단해요. huggingface_hub.AsyncInferenceClient는 HTTP 응답을 클라이언트 소유의 exit stack에 보관하고 문서화된 스트림별 transport 핸들을 노출하지 않아서, 반환된 iterator를 닫아도 즉각적인 HTTP 철수가 보장되지 않고, 원격 생성과 청구가 언제 멈추는지도 알 수 없어요. huggingface/huggingface_hub#4224를 보세요.

더 알아보기 (Learn more)