Hub Python Library documentation
추론 엔드포인트
추론 엔드포인트
Inference Endpoints는 Hugging Face가 관리하는 전용 및 오토스케일링 인프라에서 모델을 쉽게 배포할 수 있는 안전한 프로덕션 솔루션을 제공합니다. Inference Endpoint는 Hub의 모델로 구성됩니다. 이 페이지는 huggingface_hub의 Inference Endpoints 통합에 대한 참고 자료입니다. Inference Endpoints 제품에 대한 자세한 내용은 공식 문서를 확인하세요.
huggingface_hub를 사용하여 Inference Endpoints를 프로그래매틱으로 관리하는 방법을 배우려면 관련 가이드를 확인하세요.
Inference Endpoints는 API를 통해 완전히 관리할 수 있습니다. 해당 엔드포인트는 Swagger로 문서화되어 있습니다. InferenceEndpoint 클래스는 이 API를 기반으로 구축된 간단한 래퍼입니다.
메서드
Inference Endpoint 기능의 일부가 HfApi에 구현되어 있습니다:
- get_inference_endpoint() 및 list_inference_endpoints()를 사용하여 Inference Endpoints에 대한 정보를 가져옵니다.
- Inference Endpoint를 배포할 수 있는 하드웨어를 나열하려면 list_inference_endpoints_hardware()를 사용하세요
- Inference Endpoints를 배포하고 관리하기 위해 create_inference_endpoint(), update_inference_endpoint() 및 delete_inference_endpoint()를 사용합니다
- list_inference_catalog() 및 create_inference_endpoint_from_catalog()를 사용하여 큐레이션된 Model Catalog를 탐색하고 배포합니다
- Inference Endpoint를 일시 중지하고 재개하려면 pause_inference_endpoint()와 resume_inference_endpoint()를 사용합니다
- scale_to_zero_inference_endpoint() to manually scale an Endpoint to 0 replicas
InferenceEndpoint
주요 dataclass는 InferenceEndpoint입니다. 배포된 InferenceEndpoint에 대한 정보, 즉 구성과 현재 상태를 포함합니다. 배포가 완료되면 InferenceEndpoint.client와 InferenceEndpoint.async_client 속성을 사용하여 Endpoint에서 추론을 실행할 수 있으며, 각각 InferenceClient와 AsyncInferenceClient 객체를 반환합니다.
class huggingface_hub.InferenceEndpoint
< source >( namespace: strraw: dict_token: str | bool | None_api: HfApi )
매개변수
- name (
str) — Inference Endpoint의 고유한 이름입니다. - namespace (
str) — Inference Endpoint가 위치한 namespace입니다. - repository (
str) — 이 Inference Endpoint에 배포된 모델 저장소의 이름입니다. - status (InferenceEndpointStatus) — Inference Endpoint의 현재 상태입니다.
- url (
str, 선택 사항) — 사용 가능한 경우 Inference Endpoint의 URL입니다. 배포된 Inference Endpoint만 URL을 가집니다. - framework (
str) — 모델에 사용되는 머신러닝 프레임워크입니다. - revision (
str) — Inference Endpoint에 배포된 특정 모델 리비전입니다. - task (
str) — 배포된 모델과 연관된 작업입니다. - created_at (
datetime.datetime) — Inference Endpoint가 생성된 시각의 타임스탬프입니다. - updated_at (
datetime.datetime) — Inference Endpoint의 마지막 업데이트 타임스탬프입니다. - type (InferenceEndpointType) — Inference Endpoint의 유형(public, authenticated, private).
- raw (
dict) — API에서 반환된 원시 딕셔너리 데이터입니다. - token (
str또는bool, 선택 사항) — API 요청 시 설정된 경우 Inference Endpoint에 대한 인증 토큰입니다. 제공되지 않으면 로컬에 저장된 토큰이 기본값으로 사용됩니다. 서버에 토큰을 보내고 싶지 않은 경우token=False를 전달하세요.
배포된 Inference Endpoint에 대한 정보를 포함합니다.
예:
>>> from huggingface_hub import get_inference_endpoint
>>> endpoint = get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)
# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://68a0f3b5c6ee5c9dcc0e0a01.endpoints.huggingface.cloud'
# Run inference
>>> endpoint.client.text_to_image(...)
# Pause endpoint to save $$$
>>> endpoint.pause()
# ...
# Resume and wait for deployment
>>> endpoint.resume()
>>> endpoint.wait()
>>> endpoint.client.text_to_image(...)from_raw
< source >( raw: dictnamespace: strtoken: str | bool | None = Noneapi: typing.Optional[ForwardRef('HfApi')] = None )
raw dictionary에서 객체를 초기화합니다.
클라이언트
< source >( ) → InferenceClient
반환값
배포된 엔드포인트를 가리키는 추론 클라이언트
다음 예외가 발생합니다
- InferenceEndpointError — Inference Endpoint가 아직 배포되지 않은 경우.
이 Inference Endpoint에서 예측을 수행하기 위한 클라이언트를 반환합니다.
async_client
< source >( ) → AsyncInferenceClient
배포된 엔드포인트를 가리키는 asyncio 호환 추론 클라이언트입니다.
다음 예외가 발생합니다
- InferenceEndpointError — Inference Endpoint가 아직 배포되지 않은 경우.
이 Inference Endpoint에서 예측을 수행하기 위한 클라이언트를 반환합니다.
Inference Endpoint를 삭제합니다.
이 작업은 되돌릴 수 없습니다. Inference Endpoint에 대한 요금이 부과되는 것을 원하지 않는다면, InferenceEndpoint.pause()로 일시중지하거나 InferenceEndpoint.scale_to_zero()로 규모를 0으로 줄이는 것이 좋습니다.
이것은 HfApi.delete_inference_endpoint()의 별칭입니다.
Inference Endpoint에 대한 최신 정보를 가져옵니다.
Inference Endpoint를 일시 중지합니다.
일시 중지된 Inference Endpoint에는 요금이 부과되지 않습니다. InferenceEndpoint.resume()을(를) 사용하여 언제든지 다시 시작할 수 있습니다. 이는 InferenceEndpoint.scale_to_zero()을(를) 사용하여 Inference Endpoint를 0으로 스케일링하는 것과 다릅니다. 후자의 경우 요청이 수신되면 자동으로 다시 시작됩니다.
이것은 HfApi.pause_inference_endpoint()의 별칭입니다. 현재 객체는 서버의 최신 데이터로 원자리에 변경됩니다.
재개
< source >( running_ok: bool = True ) → InferenceEndpoint
매개변수
the same Inference Endpoint, 최신 데이터로 mutated in place
Inference Endpoint를 재개합니다.
이것은 HfApi.resume_inference_endpoint()의 별칭입니다. 현재 객체는 서버의 최신 데이터로 제자리에서 변경됩니다.
scale_to_zero
< source >( ) → InferenceEndpoint
the same Inference Endpoint, 최신 데이터로 mutated in place
Scale Inference Endpoint을 0으로 축소합니다.
0으로 스케일링된 Inference Endpoint에는 요금이 부과되지 않습니다. 다음 요청 시 콜드 스타트 지연을 수반하여 재개됩니다. 이는 InferenceEndpoint.pause()를 사용하여 Inference Endpoint를 일시중지하는 경우와 다르며, 이 경우 InferenceEndpoint.resume()을 통한 수동 재개가 필요합니다.
This is an alias for HfApi.scale_to_zero_inference_endpoint(). The current object is mutated in place with the latest data from the server.
업데이트
< source >( accelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Nonesecrets: dict[str, str] | None = None ) → InferenceEndpoint
매개변수
- accelerator (
str, 선택 사항) — 추론에 사용할 하드웨어 가속기(예:"cpu"). - instance_size (
str, 선택 사항) — 모델 호스팅에 사용할 인스턴스의 크기 또는 유형(예:"x4"). - instance_type (
str, 선택 사항) — Inference Endpoint가 배포될 클라우드 인스턴스 유형(예:"intel-icl"). - min_replica (
int, 선택 사항) — Inference Endpoint에서 계속 실행할 최소 리플리카(인스턴스) 수입니다. - max_replica (
int, 선택 사항) — Inference Endpoint를 확장할 최대 리플리카(인스턴스) 수입니다. - scale_to_zero_timeout (
int, 선택 사항) — 비활성 상태의 엔드포인트가 제로 스케일링되기까지의 시간(분). - repository (
str, 선택 사항) — Inference Endpoint와 연결된 모델 저장소의 이름 (예:"gpt2"). - framework (
str, 선택 사항) — 모델에 사용되는 머신러닝 프레임워크(예:"custom"). - revision (
str, 선택 사항) — Inference Endpoint에 배포할 특정 모델 리비전(예:"6c0e6080953db56375760c0471a8c5f2929baf11"). - task (
str, 선택 사항) — 모델을 배포할 작업(예:"text-classification"). - custom_image (
dict, 선택 사항) — 실행할 컨테이너 이미지입니다. 이미지 변형별로 키를 가진 dict(예:{"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}},sGLang,tgi,tei,llamacpp,hfServe, …)로, 이 경우 그대로 전달되거나, 커스텀 컨테이너를 설명하는 평탄한 dict(예:{"url": ..., "port": ...})로, 이 경우{"custom": ...}로 전송됩니다. - container_command (
list[str], 선택 사항) — 컨테이너 엔트리포인트 명령을 재정의합니다(API 페이로드의model.command에 매핑됨). 관리형 엔진 이미지(vLLM, SGLang 등)와 커스텀 이미지 모두에서 작동합니다. - container_args (
list[str], 선택 사항) — 컨테이너 엔트리포인트에 추가되는 인자(API 페이로드의model.args에 매핑됨). 관리형 엔진 이미지(예: vLLM, SGLang)와 커스텀 이미지 모두에서 작동합니다. - tensor_parallel_size (
int, 선택 사항) — 단일 모델 복사본을 분할(shard)할 가속기 수(vLLM 및 SGLang 이미지).custom_image가 제공되지 않으면, 엔드포인트에 현재 구성된 이미지가 가져와져 API가model.image를 전체로 요구하기 때문에 해당 위치에 그대로 업데이트됩니다. - data_parallel_size (
int, 선택 사항) — 가속기당 하나씩 실행할 모델 사본의 수 (vLLM 이미지). - secrets (
dict[str, str], 선택) — 컨테이너 환경에 주입할 시크릿 값입니다.
the same Inference Endpoint, 최신 데이터로 mutated in place
Inference Endpoint를 업데이트합니다.
이 메서드를 사용하면 컴퓨트 구성, 배포된 모델, 또는 둘 다를 업데이트할 수 있습니다. 모든 인수는 선택 사항이지만, 최소한 하나는 제공해야 합니다.
이것은 HfApi.update_inference_endpoint()의 별칭입니다. 현재 객체는 서버의 최신 데이터로 원자리에 변경됩니다.
대기
< source >( timeout: int | None = Nonerefresh_every: int = 5 ) → InferenceEndpoint
매개변수
- timeout (
int, 선택 사항) — Inference Endpoint가 배포될 때까지 대기할 최대 시간(초).None인 경우 무한정 대기합니다. - refresh_every (
int, 선택 사항) — Inference Endpoint 상태를 가져오는 각 요청 사이의 대기 시간(초). 기본값은 5초입니다.
the same Inference Endpoint, 최신 데이터로 mutated in place
다음 예외가 발생합니다
InferenceEndpointError 또는 InferenceEndpointTimeoutError
- InferenceEndpointError — Inference Endpoint가 실패 상태로 종료된 경우.
InferenceEndpointTimeoutError— Inference Endpoint가timeout초 후에 배포되지 않은 경우.
Inference Endpoint가 배포될 때까지 기다립니다.
서버에서 가져온 정보는 1초마다 갱신됩니다. timeout초 후에도 Inference Endpoint가 배포되지 않으면 InferenceEndpointTimeoutError가 발생하며, InferenceEndpoint는 최신 데이터로原地 변경됩니다.
InferenceEndpointHardware
class huggingface_hub.InferenceEndpointHardware
< source >( id: strvendor: strregion: straccelerator: strinstance_type: strinstance_size: strarchitecture: strnum_accelerators: intnum_cpus: int | Nonememory_gb: floatgpu_memory_gb: int | Noneprice_per_hour: floatstatus: strmax_accelerators: intused_accelerators: int )
매개변수
- id (
str) — 고유한 하드웨어 식별자, 예:"aws-us-east-1-nvidia-l4-x1". - vendor (
str) — 하드웨어를 호스팅하는 클라우드 제공업체, 예:"aws". - region (
str) — 하드웨어가 사용 가능한 클라우드 리전입니다. 예:"us-east-1". - accelerator (
str) — 하드웨어 가속기의 유형, 예:"cpu","gpu"또는"neuron". - instance_type (
str) — 클라우드 인스턴스 유형, 예:"nvidia-l4". - instance_size (
str) — 인스턴스 크기 배율입니다. 예:"x1". - architecture (
str) — 사람이 읽을 수 있는 하드웨어 설명, 예:"Nvidia L4". - num_accelerators (
int) — 리플리카당 가속기 단위 수. - num_cpus (
int, 선택 사항) — 리플리카당 vCPU 수. - memory_gb (
float) — 리플리카당 RAM 용량(GB). - gpu_memory_gb (
int, 선택 사항) — 리플리카당 총 GPU 메모리(GB 단위, 즉num_accelerators에 대해 합산된 값). GPU가 아닌 하드웨어의 경우None. - price_per_hour (
float) — 1시간당 리플리카당 비용(USD). - status (
str) — 하드웨어 사용 가능 여부:"available","low_availability","not_available","reserved"또는"deprecated". - max_accelerators (
int) — 이 네임스페이스에서 실행할 수 있는 해당 유형의 가속기 최대 수입니다. - used_accelerators (
int) — 현재 네임스페이스에서 이 유형의 가속기가 사용 중인 개수.
Inference Endpoints에서 사용할 수 있는 하드웨어 구성에 대한 정보를 포함합니다.
vendor, region, accelerator, instance_type, instance_size 필드는 해당 하드웨어에 배포하기 위해 create_inference_endpoint()(또는 hf endpoints deploy)에 전달해야 하는 값과 정확히 일치합니다.
예:
>>> from huggingface_hub import list_inference_endpoints_hardware
>>> hardware = list_inference_endpoints_hardware()
>>> hardware[0]
InferenceEndpointHardware(id='aws-us-east-1-nvidia-l4-x1', vendor='aws', region='us-east-1', ...)API 응답에서 벤더와 리전 아래에 중첩된 원시 compute 사전에서 객체를 초기화합니다.
InferenceCatalogModel
class huggingface_hub.InferenceCatalogModel
< source >( repo_id: strname: strauthor: strlicense: strtask: strcreated_at: datetimerecipes: list )
매개변수
- repo_id (
str) — Hub의 모델 저장소 ID, 예:"meta-llama/Llama-3.1-8B-Instruct". - name (
str) — 모델 이름, 즉repo_id에서 저자 뒤에 오는 부분입니다. 예:"Llama-3.1-8B-Instruct". - author (
str) — 모델 저장소의 작성자, 예:"meta-llama". - license (
str) — 모델의 라이선스입니다. 예:"Apache 2.0". - task (
str) — 모델이 배포된 작업, 예:"text-generation". - created_at (
datetime) — 모델이 카탈로그에 추가된 날짜입니다. - recipes (
list[InferenceCatalogRecipe]) — 이 모델을 배포하는 검증된 방법들입니다.
Inference Catalog에서 사용할 수 있는 모델에 대한 정보를 포함합니다.
예:
>>> from huggingface_hub import list_inference_catalog
>>> catalog = list_inference_catalog(engine="vllm")
>>> catalog[0]
InferenceCatalogModel(repo_id='Qwen/Qwen2.5-Coder-7B-Instruct', name='Qwen2.5-Coder-7B-Instruct', ...)raw catalog item dictionary에서 객체를 초기화합니다.
InferenceCatalogRecipe
class huggingface_hub.InferenceCatalogRecipe
< source >( id: straccelerator: strengine: strgguf_file: str | Nonerevision: str | None )
매개변수
- id (
str) — The public recipe id, to pass to create_inference_endpoint_from_catalog() asrecipe_id. - accelerator (
str) — 레시피가 실행되는 하드웨어 가속기의 유형입니다. 예:"cpu","gpu"또는"neuron". - engine (
str) — 레시피가 실행되는 추론 엔진입니다. 예:"vllm","llamacpp","tei"또는"sglang". - gguf_file (
str, 선택 사항) — 레시피에 의해 배포되는 GGUF 파일입니다."llamacpp"레시피에서만 설정됩니다. - revision (
str, 선택 사항) — 레시피가 고정된 모델 리비전(해당하는 경우).
Inference Catalog의 모델 배포에 대한 사전 테스트된 방법에 대한 정보를 포함합니다.
레시피는 Inference Endpoints 팀이 특정 모델에 대해 테스트한 하드웨어와 엔진의 조합입니다. 모델에는 보통 하나의 레시피가 있지만, 여러 개가 있을 수도 있습니다(예: GPU용과 Neuron용, 또는 GGUF 양자화별 하나씩).
API 응답에서 모델 아래에 중첩된 원시 레시피 딕셔너리로부터 객체를 초기화합니다.
InferenceEndpointStatus
class huggingface_hub.InferenceEndpointStatus
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
열거형입니다.
InferenceEndpointType
class huggingface_hub.InferenceEndpointType
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
열거형입니다.
InferenceEndpointError
Inference Endpoints를 다룰 때 발생하는 일반적인 예외입니다.