Hugging Face

Hugging Face

이 문서에서는 pydantic-ai에서 HuggingFaceModel을 설치하고 설정하는 방법을 알려드려요. Hugging Face Inference Providers를 통해 DeepSeek R1 같은 오픈소스 모델을 확장 가능한 서버리스 인프라에서 실행할 수 있어요. 계정과 액세스 토큰을 준비한 뒤 모델을 이름으로 사용하거나 직접 초기화하면 돼요.

출처: 문서

본문

Hugging Face는 주요 오픈소스 모델, 데이터셋, MCP, 데모가 모두 있는 AI 플랫폼이에요. Inference Providers를 사용해 DeepSeek R1 같은 오픈소스 모델을 확장 가능한 서버리스 인프라에서 실행할 수 있어요.

Sentence Transformers를 통한 로컬 임베딩

이 페이지는 Hugging Face Inference Providers를 통한 채팅 완성(chat completions)을 다뤄요. Hugging Face 임베딩 모델을 로컬에서 실행하려면(API 키 없이, 네트워크 호출 없이) Sentence Transformers 임베딩 모델을 참고하세요. 이 모델은 sentence-transformers 라이브러리의 어떤 모델과도 함께 동작해요.

Install

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

Terminal

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

Terminal

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

Configuration

Hugging Face 추론을 사용하려면 계정을 만들어야 하며, 계정에는 Inference Providers의 무료 티어 사용량이 부여돼요. 추론을 설정하려면 다음 단계를 따르세요:

  1. Hugging Face로 이동해서 계정을 만드세요.
  2. Hugging Face에서 새 액세스 토큰을 생성하세요.
  3. 방금 만든 토큰으로 HF_TOKEN 환경 변수를 설정하세요.

Hugging Face 액세스 토큰을 확보했다면 환경 변수로 설정할 수 있어요:

Terminal

export HF_TOKEN='hf_token'

Usage

그 다음 이름으로 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를 사용하는데, 이 프로바이더는 모델에 사용 가능한 inference providers(Cerebras, Together AI, Cohere 등) 중 https://hf.co/settings/inference-providers에서 선호하는 순서로 정렬된 첫 번째를 자동으로 선택해요.

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

Custom Hugging Face client

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

Streaming cancellation

전송 계층 취소

cancel()은 활성 로컬 스트림 pull을 안전하게 중단하며, 다른 태스크에서 실행 중인 것도 포함해요. huggingface_hub.AsyncInferenceClient는 HTTP 응답을 클라이언트가 소유한 exit stack에 보관하고 문서화된 per-stream 전송 핸들을 노출하지 않으므로, 반환된 iterator를 닫아도 즉각적인 HTTP teardown이나 원격 생성·청구 종료를 보장하지 않아요. huggingface/huggingface_hub#4224를 참고하세요.

더 알아보기 (Learn more)