Hugging Face's logo

Hub Python Library documentation

推論エンドポイント

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

推論エンドポイント

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に実装されています:

InferenceEndpoint

主なデータクラスはInferenceEndpointです。デプロイされたInferenceEndpointに関する情報、つまりその設定と現在の状態が含まれています。デプロイ後、InferenceEndpoint.clientプロパティとInferenceEndpoint.async_clientプロパティを使用してエンドポイント上で推論を実行できます。これらはそれぞれInferenceClientオブジェクトとAsyncInferenceClientオブジェクトを返します。

クラス huggingface_hub.InferenceEndpoint

< >

( namespace: strraw: dict_token: str | bool | None_api: HfApi )

パラメータ

  • name (str) — Inference Endpoint の一意の名前。
  • namespace (str) — Inference Endpoint が配置されている名前空間です。
  • 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

< >

( raw: dictnamespace: strtoken: str | bool | None = Noneapi: typing.Optional[ForwardRef('HfApi')] = None )

生の辞書からオブジェクトを初期化します。

クライアント

< >

( ) → InferenceClient

戻り値

InferenceClient

デプロイされたエンドポイントを指す推論クライアント。

例外

InferenceEndpointError

このInference Endpointで予測を行うためのクライアントを返します。

async_client

< >

( ) → AsyncInferenceClient

戻り値

AsyncInferenceClient

デプロイされたエンドポイントを指す、asyncio 互換の推論クライアント。

例外

InferenceEndpointError

このInference Endpointで予測を行うためのクライアントを返します。

削除

< >

( )

Inference Endpointを削除します。

この操作は元に戻せません。Inference Endpoint の課金を避けたい場合は、InferenceEndpoint.pause() で一時停止するか、InferenceEndpoint.scale_to_zero() でスケールをゼロにすることをお勧めします。

これはHfApi.delete_inference_endpoint()のエイリアスです。

fetch

< >

( ) → InferenceEndpoint

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

Inference Endpointの最新情報を取得します。

一時停止

< >

( ) → InferenceEndpoint

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

Inference Endpointを一時停止します。

一時停止されたInference Endpointには料金は発生しません。InferenceEndpoint.resume() を使用して、いつでも再開できます。 これは、InferenceEndpoint.scale_to_zero() を使用してInference Endpointをゼロにスケーリングすることとは異なり、後者の場合はリクエストが送信されると自動的に再起動されます。

これはHfApi.pause_inference_endpoint()のエイリアスです。現在のオブジェクトは、サーバーからの最新データでその場で変更されます。

再開

< >

( running_ok: bool = True ) → InferenceEndpoint

パラメータ

  • running_ok (bool, 省略可能) — True の場合、Inference Endpoint が既に実行中であってもエラーは発生しません。デフォルト値は True です。

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

Inference Endpointを再開します。

これはHfApi.resume_inference_endpoint()のエイリアスです。現在のオブジェクトは、サーバーからの最新データでその場で変更されます。

scale_to_zero

< >

( ) → InferenceEndpoint

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

Scale Inference Endpoint to zero.

スケールがゼロに設定された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.

を更新

< >

( 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, 任意) — 実行するコンテナイメージです。イメージのバリアントをキーとする辞書（例: {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}、sGLang、tgi、tei、llamacpp、hfServe など）として渡すことも、カスタムコンテナを記述するフラットな辞書（例: {"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, 省略可) — 単一のモデルコピーを分割して配置するアクセラレータの数 (vLLM および SGLang イメージ)。 custom_image が指定されていない場合、エンドポイントに現在設定されているイメージを取得し、API が model.image を全体として要求するため、その場で更新されます。
  • data_parallel_size (int, 省略可) — 1つのアクセラレーターごとに1つのモデルコピーを実行する、モデルコピーの数（vLLMイメージ）。
  • secrets (dict[str, str]、省略可) — コンテナ環境に注入するシークレット値。

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

Inference Endpointを更新します。

このメソッドでは、compute設定、デプロイされたモデル、またはその両方を更新できます。すべての引数は任意ですが、少なくとも1つは指定する必要があります。

これはHfApi.update_inference_endpoint()のエイリアスです。現在のオブジェクトは、サーバーからの最新データでその場で変更されます。

待機

< >

( timeout: int | None = Nonerefresh_every: int = 5 ) → InferenceEndpoint

パラメータ

  • timeout (int, 省略可) — Inference Endpoint のデプロイ完了を待機する最大時間（秒）。None の場合は、無期限に待機します。
  • refresh_every (int, 任意) — Inference Endpoint のステータスを取得する間隔（秒）です。デフォルトは 5 秒です。

戻り値

InferenceEndpoint

同じInference Endpointが、最新のデータでその場で変更された状態です。

例外

InferenceEndpointError または InferenceEndpointTimeoutError

  • InferenceEndpointError — Inference Endpoint が失敗状態になった場合。
  • InferenceEndpointTimeoutError — Inference Endpoint が timeout 秒以内にデプロイされない場合。

Inference Endpoint のデプロイが完了するまで待機します。

サーバーからの情報は1秒ごとに取得されます。timeout秒以内にInference Endpointがデプロイされない場合、InferenceEndpointTimeoutErrorが発生します。InferenceEndpointは最新のデータでインプレースに更新されます。

InferenceEndpointHardware

クラス huggingface_hub.InferenceEndpointHardware

< >

( 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レプリカあたりの1時間あたりのコスト（米ドル）。
  • 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', ...)

from_raw

< >

( raw: dictvendor: strregion: str )

APIレスポンス内のベンダーとリージョンにネストされた生コンピュート辞書からオブジェクトを初期化します。

InferenceCatalogModel

クラス huggingface_hub.InferenceCatalogModel

< >

( 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', ...)

from_raw

< >

( raw: dict )

生のカタログ項目の辞書からオブジェクトを初期化します。

InferenceCatalogRecipe

クラス huggingface_hub.InferenceCatalogRecipe

< >

( id: straccelerator: strengine: strgguf_file: str | Nonerevision: str | None )

パラメータ

  • id (str) — The public recipe id, to pass to create_inference_endpoint_from_catalog() as recipe_id.
  • accelerator (str) — レシピが実行されるハードウェアアクセラレータの種類です。例: "cpu"、"gpu"、または "neuron"。
  • engine (str) — レシピが実行する推論エンジンです。例: "vllm"、"llamacpp"、"tei"、"sglang"
  • gguf_file (str, 省略可) — レシピによってデプロイされる GGUF ファイル。"llamacpp" レシピの場合のみ設定されます。
  • revision (str, 任意) — レシピが固定されているモデルのリビジョン（該当する場合）。

Inference Catalogからモデルをデプロイするための事前テスト済みの方法に関する情報を含みます。

レシピとは、Inference Endpoints チームが特定のモデルに対してテスト済みのハードウェアとエンジンの組み合わせです。モデルには通常1つのレシピが割り当てられますが、複数存在することもあります（例：GPU用とNeuron用、またはGGUF量子化ごとに1つずつ）。

from_raw

< >

( raw: dict )

APIレスポンス内のモデルにネストされた生レシピ辞書からオブジェクトを初期化します。

InferenceEndpointStatus

クラス huggingface_hub.InferenceEndpointStatus

< >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

列挙型です。

InferenceEndpointType

クラス huggingface_hub.InferenceEndpointType

< >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

列挙型です。

InferenceEndpointError

クラス huggingface_hub.InferenceEndpointError

< >

( )

Inference Endpointsを扱う際に発生する汎用例外。

Update on GitHub

←推論クライアント MCPクライアント→