Точки вывода

Inference Endpoints — это безопасное решение для продакшена, позволяющее легко развертывать любые модели transformers, sentence-transformers и diffusers на выделенной инфраструктуре с автоматическим масштабированием, управляемой Hugging Face. Inference Endpoint создается на основе модели из Hub. В этом руководстве мы узнаем, как программно управлять Inference Endpoints с помощью huggingface_hub. Чтобы узнать больше о самом продукте Inference Endpoints, обратитесь к его официальной документации.

В этом руководстве предполагается, что huggingface_hub корректно установлен, а на вашем компьютере выполнен вход в систему. Если это не так, обратитесь к руководству для быстрого старта. Минимальная версия, поддерживающая API Inference Endpoints, — v0.19.0.

Новое: теперь можно развернуть Inference Endpoint из каталога моделей HF с помощью простого вызова API. Каталог представляет собой тщательно отобранный список моделей, которые можно развернуть с оптимизированными настройками. Вам не нужно ничего настраивать — мы берем на себя всю сложную работу! Все модели и настройки гарантированно протестированы для обеспечения наилучшего соотношения стоимости и производительности. create_inference_endpoint_from_catalog() работает так же, как create_inference_endpoint(), но требует передачи значительно меньшего количества параметров. Вы можете использовать list_inference_catalog(), чтобы программно получить каталог.

Обратите внимание, что это всё ещё экспериментальная функция. Дайте нам знать, что вы о ней думаете, если воспользуетесь ею!

Каждая модель из каталога разворачивается с помощью рецепта: комбинации аппаратного обеспечения и движка, протестированной для неё. list_inference_catalog() возвращает модели вместе с их рецептами и принимает серверные фильтры (accelerator, engine, license, task, search, limit):

>>> from huggingface_hub import list_inference_catalog
>>> catalog = list_inference_catalog(task="text-generation", accelerator="neuron")
>>> catalog[0]
InferenceCatalogModel(repo_id='meta-llama/Llama-3.1-8B-Instruct', name='Llama-3.1-8B-Instruct', ...)
>>> catalog[0].recipes
[InferenceCatalogRecipe(id='sizzling-biryani-g4xsi1ac', accelerator='gpu', engine='vllm', gguf_file=None, revision=None),
 InferenceCatalogRecipe(id='artisanal-quinoa-yz9ynamx', accelerator='neuron', engine='vllmNeuron', gguf_file=None, revision=None)]

Передайте repo_id в create_inference_endpoint_from_catalog(), чтобы развернуть рецептуру по умолчанию для модели, при необходимости уточнив её с помощью accelerator ("cpu", "gpu" или "neuron") и gguf_file, либо передайте recipe_id, чтобы развернуть конкретную рецептуру:

>>> from huggingface_hub import create_inference_endpoint_from_catalog
>>> endpoint = create_inference_endpoint_from_catalog(repo_id="openai/gpt-oss-120b")
>>> endpoint = create_inference_endpoint_from_catalog(recipe_id="artisanal-quinoa-yz9ynamx")

Найдите оборудование для развертывания

Значения accelerator, vendor, region, instance_type и instance_size, принимаемые create_inference_endpoint(), зависят друг от друга. Используйте list_inference_endpoints_hardware(), чтобы получить список допустимых комбинаций, а также их стоимость в час и квоту на ускорители вашего пространства имён:

>>> from huggingface_hub import list_inference_endpoints_hardware

>>> for hw in list_inference_endpoints_hardware():
...     if hw.accelerator == "gpu" and hw.status == "available":
...         print(hw.vendor, hw.region, hw.instance_type, hw.instance_size, hw.price_per_hour)
aws us-east-1 nvidia-l4 x1 0.8
aws us-east-1 nvidia-l4 x4 3.8
...

Квота рассчитывается на пространство имён, поэтому передайте namespace, в который вы будете выполнять развёртывание (по умолчанию используется ваше собственное пространство имён):

>>> list_inference_endpoints_hardware(namespace="my-org")

Или через CLI:

hf endpoints hardware --accelerator gpu

Создание конечной точки вывода

Первый шаг — создать Inference Endpoint с помощью create_inference_endpoint():

>>> from huggingface_hub import create_inference_endpoint

>>> endpoint = create_inference_endpoint(
...     "my-endpoint-name",
...     repository="gpt2",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x2",
...     instance_type="intel-icl"
... )

Или через CLI:

hf endpoints deploy my-endpoint-name --repo gpt2 --framework pytorch --accelerator cpu --vendor aws --region us-east-1 --instance-size x2 --instance-type intel-icl --task text-generation

# Deploy from the catalog with a single command
hf endpoints catalog deploy --repo openai/gpt-oss-120b

# Deploy from the catalog with a specific accelerator
hf endpoints catalog deploy --repo openai/gpt-oss-120b --accelerator gpu

# Deploy an exact catalog recipe, as listed by 'hf endpoints catalog ls'
hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx

В этом примере мы создали authenticated Inference Endpoint с именем "my-endpoint-name" для обслуживания gpt2 в задаче text-generation. authenticated Inference Endpoint означает, что для доступа к API требуется ваш токен. Также необходимо предоставить дополнительную информацию для настройки аппаратных требований, таких как вендор, регион, ускоритель, тип и размер экземпляра. Список доступных ресурсов можно найти здесь. Альтернативно, для удобства вы можете создать Inference Endpoint вручную с помощью Web interface. Подробности о расширенных настройках и их использовании приведены в этом руководстве.

Значение, возвращаемое create_inference_endpoint(), представляет собой объект InferenceEndpoint:

>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

Или через CLI:

hf endpoints describe my-endpoint-name

Это dataclass, содержащий информацию об эндпоинте. Вы можете получить доступ к таким важным атрибутам, как name, repository, status, task, created_at, updated_at и т. д. При необходимости вы также можете получить доступ к необработанному ответу сервера с помощью endpoint.raw.

После создания Inference Endpoint вы можете найти его на своей личной панели управления.

Использование пользовательского образа

По умолчанию Inference Endpoint создаётся на основе docker-образа, предоставляемого Hugging Face. Однако можно указать любой docker-образ с помощью параметра custom_image. Распространённый сценарий — запуск LLM с использованием фреймворка text-generation-inference. Это можно сделать следующим образом:

# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import create_inference_endpoint
>>> endpoint = create_inference_endpoint(
...     "aws-zephyr-7b-beta-0486",
...     repository="HuggingFaceH4/zephyr-7b-beta",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x1",
...     instance_type="nvidia-a10g",
...     custom_image={
...         "healthRoute": "/health",
...         "env": {
...             "MAX_BATCH_PREFILL_TOKENS": "2048",
...             "MAX_INPUT_LENGTH": "1024",
...             "MAX_TOTAL_TOKENS": "1512",
...             "MODEL_ID": "/repository"
...         },
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
... )

Значение, передаваемое в качестве custom_image, представляет собой словарь, содержащий URL-адрес docker-контейнера и конфигурацию для его запуска. Дополнительные сведения см. в документации Swagger.

Для изображения, размещённого в частном реестре контейнеров, передайте container_registry_username и, если это требуется реестром, container_registry_password. Учётные данные поддерживаются только для обычного пользовательского контейнера:

>>> endpoint = create_inference_endpoint(
...     # Other endpoint and hardware arguments omitted for brevity.
...     custom_image={"url": "private.registry.example/my-image:latest", "port": 8080},
...     container_registry_username="user",
...     container_registry_password="password",
... )

Сопоставляемые параметры CLI — это --container-registry-username и --container-registry-password:

hf endpoints deploy my-endpoint ... --custom-image private.registry.example/my-image:latest \
  --container-registry-username user --container-registry-password password

custom_image также принимает специфичные для движка типы контейнеров, поддерживаемые API, если в словаре в качестве ключей используются имена движков (vLLM, vLLMNeuron, sGLang, tgi, tgiNeuron, tei, llamacpp, hfServe, …), а не плоская структура. Каждый движок принимает стандартные поля контейнера (url, port, healthRoute), а также собственные параметры настройки. Любое словари без верхнеуровневого url передается в API без изменений, поэтому движки, добавленные в API позже, будут работать без обновления huggingface_hub:

# Start an Inference Endpoint running the vLLM engine image
>>> endpoint = create_inference_endpoint(
...     "llama-3-1-8b-instruct-vllm",
...     repository="meta-llama/Llama-3.1-8B-Instruct",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     instance_size="x1",
...     instance_type="nvidia-l4",
...     custom_image={
...         "vLLM": {
...             "url": "vllm/vllm-openai:v0.23.0",
...             "healthRoute": "/health",
...             "port": 8000,
...             "tensorParallelSize": 1,
...         }
...     },
... )

Без ключа движка тот же словарь отправляется как обычный пользовательский контейнер, поэтому параметры, специфичные для движка (здесь tensorParallelSize), отбрасываются.

Для контейнеров, требующих пользовательского entrypoint или флагов времени выполнения, передайте container_command и/или container_args (каждый представляет собой список токенов). Они отображаются в model.command и model.args в API-запросе. Они не привязаны к пользовательским образам: управляемые образы движков (например, vLLM, SGLang) также принимают флаги движка через container_args. То же самое доступно из CLI через hf endpoints deploy ... --container-command "..." --container-args "...".

Параллелизм на инстансах с несколькими ускорителями

vLLM и SGLang по умолчанию используют один ускоритель, тогда как эндпоинту выделяются все ускорители его экземпляра, поэтому, если не задать параллелизм, модель будет загружена на один ускоритель, остальные останутся простаивать, при этом система будет сообщать о нормальном состоянии, и вы будете платить за все ускорители, но получать пропускную способность одного. Именно поэтому API теперь отклоняет такое развёртывание. (TGI вычисляет количество шардов на основе экземпляра и не подвержен этому эффекту.) Установите tensorParallelSize, чтобы распределить одну копию модели по ускорителям, или dataParallelSize (только vLLM), чтобы запустить по одной копии на каждый ускоритель:

>>> endpoint = create_inference_endpoint(
...     "gpt-oss-120b-vllm",
...     repository="openai/gpt-oss-120b",
...     framework="custom",
...     accelerator="gpu",
...     instance_size="x8",
...     instance_type="nvidia-h200",
...     region="us-east-1",
...     vendor="aws",
...     custom_image={"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "tensorParallelSize": 8}},
... )

Из CLI, --engine выбирает образ управляемого движка, а два флага записываются в его конфигурацию:

hf endpoints deploy gpt-oss-120b-vllm --repo openai/gpt-oss-120b --framework custom \
  --accelerator gpu --instance-size x8 --instance-type nvidia-h200 --region us-east-1 --vendor aws \
  --engine vllm --custom-image vllm/vllm-openai:v0.23.0 --tensor-parallel-size 8

Чтобы перенастроить развернутый эндпоинт, передайте tensor_parallel_size отдельно в update() или hf endpoints update. model.image отправляется целиком и требует url, поэтому текущий образ эндпоинта извлекается и обновляется на месте:

>>> endpoint.update(tensor_parallel_size=4)

container_args (--tp 8) не эквивалентен: он передаётся в движок в виде командной строки, а не в конфигурацию model.image, которую API проверяет по количеству акселераторов инстанса. Используйте его для флагов движка, не имеющих поля image, а также для обычных пользовательских контейнеров, у которых нет полей параллелизма.

Получение или список существующих Inference Endpoints

В некоторых случаях вам может потребоваться управлять Inference Endpoints, созданными ранее. Если вы знаете имя, вы можете получить его с помощью get_inference_endpoint(), который возвращает объект InferenceEndpoint. Альтернативно, вы можете использовать list_inference_endpoints(), чтобы получить список всех Inference Endpoints. Оба метода принимают необязательный параметр namespace. Вы можете установить namespace в любое имя организации, участником которой вы являетесь. В противном случае по умолчанию используется ваше имя пользователя.

>>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints

# Get one
>>> get_inference_endpoint("my-endpoint-name")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

# List all endpoints from an organization
>>> list_inference_endpoints(namespace="huggingface")
[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...]

# List all endpoints from all organizations the user belongs to
>>> list_inference_endpoints(namespace="*")
[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...]

Или через CLI:

hf endpoints describe my-endpoint-name
hf endpoints ls --namespace huggingface
hf endpoints ls --namespace '*'

Проверка статуса развертывания

В остальной части этого руководства мы будем исходить из того, что у нас есть объект InferenceEndpoint с именем endpoint. Возможно, вы заметили, что у эндпоинта есть атрибут status типа InferenceEndpointStatus. Когда Inference Endpoint развернут и доступен, статус должен быть "running", а атрибут url установлен:

>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')

Прежде чем перейти в состояние "running", Inference Endpoint обычно проходит фазу "initializing" или "pending". Вы можете получить новое состояние конечной точки, вызвав fetch(). Как и любой другой метод из InferenceEndpoint, выполняющий запрос к серверу, он изменяет внутренние атрибуты endpoint на месте:

>>> endpoint.fetch()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

Или через CLI:

hf endpoints describe my-endpoint-name

Вместо того чтобы запрашивать статус Inference Endpoint во время ожидания его запуска, можно напрямую вызвать wait(). Этот вспомогательный метод принимает в качестве входных параметров timeout и fetch_every (в секундах) и блокирует поток до тех пор, пока Inference Endpoint не будет развернут. Значения по умолчанию — None (без тайм-аута) и 5 секунд соответственно.

# Pending endpoint
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

# Wait 10s => raises a InferenceEndpointTimeoutError
>>> endpoint.wait(timeout=10)
    raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.")
huggingface_hub._inference_endpoints.InferenceEndpointTimeoutError: Timeout while waiting for Inference Endpoint to be deployed.

# Wait more
>>> endpoint.wait()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')

Если параметр timeout задан, а загрузка Inference Endpoint занимает слишком много времени, возникает ошибка тайм-аута InferenceEndpointTimeoutError.

Запуск вывода

Когда ваш Inference Endpoint запущен и работает, вы можете выполнять на нём инференс!

InferenceEndpoint имеет два свойства client и async_client, возвращающие объекты InferenceClient и AsyncInferenceClient соответственно.

# Run text_generation task:
>>> endpoint.client.text_generation("I am")
' not a fan of the idea of a "big-budget" movie. I think it\'s a'

# Or in an asyncio context:
>>> await endpoint.async_client.text_generation("I am")

Если Inference Endpoint не запущен, возникает исключение InferenceEndpointError:

>>> endpoint.client
huggingface_hub._inference_endpoints.InferenceEndpointError: Cannot create a client for this Inference Endpoint as it is not yet deployed. Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again.

Подробнее о том, как использовать InferenceClient, см. в руководстве по инференсу.

Управление жизненным циклом

Теперь, когда мы рассмотрели, как создать Inference Endpoint и выполнить на нём инференс, давайте посмотрим, как управлять его жизненным циклом.

В этом разделе мы рассмотрим методы pause(), resume(), scale_to_zero(), update() и delete(). Все эти методы являются алиасами, добавленными в InferenceEndpoint для удобства. При желании вы также можете использовать универсальные методы, определённые в HfApi: pause_inference_endpoint(), resume_inference_endpoint(), scale_to_zero_inference_endpoint(), update_inference_endpoint() и delete_inference_endpoint().

Приостановка или масштабирование до нуля

To reduce costs when your Inference Endpoint is not in use, you can choose to either pause it using pause() or scale it to zero using scale_to_zero().

Inference Endpoint, который приостановлен или масштабирован до нуля, не требует затрат. Разница между этими двумя состояниями заключается в том, что приостановленный endpoint необходимо явно возобновить с помощью resume(). В отличие от него, endpoint, масштабированный до нуля, автоматически запускается при поступлении запроса на инференс, но с дополнительной задержкой холодного старта. Inference Endpoint также можно настроить так, чтобы он автоматически масштабировался до нуля после определенного периода бездействия.

# Pause and resume endpoint
>>> endpoint.pause()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None)
>>> endpoint.resume()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)
>>> endpoint.wait().client.text_generation(...)
...

# Scale to zero
>>> endpoint.scale_to_zero()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='scaledToZero', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')
# Endpoint is not 'running' but still has a URL and will restart on first call.

Или через CLI:

hf endpoints pause my-endpoint-name
hf endpoints resume my-endpoint-name
hf endpoints scale-to-zero my-endpoint-name

Обновление требований к модели или оборудованию

В некоторых случаях вам может потребоваться обновить ваш Inference Endpoint, не создавая новый. Вы можете обновить размещенную модель или требования к аппаратному обеспечению для запуска модели. Это можно сделать с помощью update():

# Change target model
>>> endpoint.update(repository="gpt2-large")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

# Update number of replicas
>>> endpoint.update(min_replica=2, max_replica=6)
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

# Update to larger instance
>>> endpoint.update(accelerator="cpu", instance_size="x4", instance_type="intel-icl")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

# Update the container arguments, e.g. engine flags on an endpoint running vLLM or SGLang.
# Replaces the current value, it is not appended.
>>> endpoint.update(container_args=["--enable-auto-tool-choice", "--tool-call-parser", "lfm2"])
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

Или через CLI:

hf endpoints update my-endpoint-name --repo gpt2-large
hf endpoints update my-endpoint-name --min-replica 2 --max-replica 6
hf endpoints update my-endpoint-name --accelerator cpu --instance-size x4 --instance-type intel-icl
hf endpoints update my-endpoint-name --container-args "--enable-auto-tool-choice --tool-call-parser lfm2"
# Merged into the image currently configured on the endpoint.
hf endpoints update my-endpoint-name --tensor-parallel-size 8
# Or replace the image entirely, in which case pass back the settings you want to keep.
hf endpoints update my-endpoint-name --engine vllm --custom-image vllm/vllm-openai:v0.23.0 --port 8000

Удалить конечную точку

Наконец, если вы больше не будете использовать Inference Endpoint, вы можете просто вызвать ~InferenceEndpoint.delete().

Это необратимое действие, которое полностью удалит конечную точку, включая её конфигурацию, журналы и метрики использования. Удалённую Inference Endpoint невозможно восстановить.

Пример «от и до»

Типичный сценарий использования Inference Endpoints — обработка партии задач за один раз для ограничения затрат на инфраструктуру. Вы можете автоматизировать этот процесс с помощью того, что мы рассмотрели в этом руководстве:

>>> import asyncio
>>> from huggingface_hub import create_inference_endpoint

# Start endpoint + wait until initialized
>>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait()

# Run inference
>>> client = endpoint.client
>>> results = [client.text_generation(...) for job in jobs]

# Or with asyncio
>>> async_client = endpoint.async_client
>>> results = await asyncio.gather(*[async_client.text_generation(...) for job in jobs])

# Pause endpoint
>>> endpoint.pause()

Или если ваш Inference Endpoint уже существует и приостановлен:

>>> import asyncio
>>> from huggingface_hub import get_inference_endpoint

# Get endpoint + wait until initialized
>>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait()

# Run inference
>>> async_client = endpoint.async_client
>>> results = await asyncio.gather(*[async_client.text_generation(...) for job in jobs])

# Pause endpoint
>>> endpoint.pause()