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 — это процесс использования обученной модели для получения предсказаний на новых данных. Поскольку этот процесс может требовать значительных вычислительных ресурсов, запуск на выделенном или внешнем сервисе может быть интересным вариантом. Библиотека huggingface_hub предоставляет единый интерфейс для запуска inference для моделей, размещенных на Hugging Face Hub, через несколько сервисов:

  1. Поставщики инференса: упрощённый и единый доступ к сотням моделей машинного обучения, обеспечиваемый нашими партнёрами по serverless-инференсу. Этот новый подход развивает наш предыдущий Serverless Inference API, предлагая больше моделей, улучшенную производительность и повышенную надёжность благодаря поставщикам мирового уровня. Список поддерживаемых поставщиков приведён в документации.
  2. Inference Endpoints: продукт для простого развёртывания моделей в продакшене. Вывод выполняется Hugging Face на выделенной полностью управляемой инфраструктуре на облачном провайдере по вашему выбору.
  3. Локальные конечные точки: вы также можете выполнять инференс с помощью локальных серверов инференса, таких как llama.cpp, Ollama, vLLM, LiteLLM или Text Generation Inference (TGI), подключив клиент к этим локальным конечным точкам.

Эти сервисы можно вызывать с помощью объекта InferenceClient. Подробнее о том, как его использовать, см. в этом руководстве.

Клиент для инференса

класс huggingface_hub.InferenceClient

< >

( model: str | None = Noneprovider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = Nonetoken: str | None = Nonetimeout: float | None = Noneheaders: dict[str, str] | None = Nonecookies: dict[str, str] | None = Nonebill_to: str | None = Nonebase_url: str | None = Noneapi_key: str | None = None )

Параметры

  • model (str, optional) — Модель для выполнения инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, например meta-llama/Meta-Llama-3-8B-Instruct, или URL-адресом развернутого Inference Endpoint. По умолчанию None, в этом случае для задачи автоматически выбирается рекомендуемая модель. Примечание: для лучшей совместимости с клиентом OpenAI model имеет псевдоним base_url. Эти два аргумента взаимоисключающи. Если в качестве model или base_url для chat completion передан URL, к нему будет добавлен суффикс (/v1)/chat/completions.
  • provider (str, необязательный) — Название провайдера, используемого для инференса. Может быть "baseten", "cerebras", "cohere", "deepinfra", "fal-ai", "featherless-ai", "fireworks-ai", "groq", "hf-inference", "novita", "nscale", "openai", "ovhcloud", "publicai", "replicate", "scaleway", "together", "wavespeed" или "zai-org". По умолчанию — “auto”: автоматический роутинг, который по умолчанию выбирает “fastest” провайдера; вы можете переключиться на порядок “cheapest” или “preferred” на https://hf.co/settings/inference-providers. Если модель указана в виде URL или передан base_url, то provider не используется.
  • token (str, необязательный) — Токен Hugging Face. Если не указан, по умолчанию используется локально сохранённый токен. Примечание: для лучшей совместимости с клиентом OpenAI token имеет псевдоним api_key. Эти два аргумента взаимоисключающи и имеют абсолютно одинаковое поведение.
  • timeout (float, optional) — Максимальное время ожидания ответа от сервера в секундах. По умолчанию None, что означает ожидание в цикле до тех пор, пока сервер не станет доступен.
  • headers (dict[str, str], optional) — Дополнительные заголовки для отправки на сервер. По умолчанию отправляются только заголовки authorization и user-agent. Значения в этом словаре переопределяют значения по умолчанию.
  • bill_to (str, optional) — Аккаунт для выставления счетов за запросы. По умолчанию запросы тарифицируются на аккаунт пользователя. Счета могут выставляться только на организацию, членом которой является пользователь и которая подписала Enterprise Hub.
  • cookies (dict[str, str], optional) — Дополнительные cookies для отправки на сервер.
  • base_url (str, optional) — Базовый URL для запуска инференса. Это дублирующий аргумент из model, чтобы InferenceClient следовал тому же паттерну, что и клиент openai.OpenAI. Невозможно использовать, если задан model. По умолчанию — None.
  • api_key (str, optional) — Токен для аутентификации. Это дублирующий аргумент из token, чтобы InferenceClient следовал тому же паттерну, что и клиент openai.OpenAI. Невозможно использовать, если задан token. По умолчанию — None.

Инициализируйте новый Inference Client.

InferenceClient призван обеспечить единый опыт выполнения инференса. Клиентом можно бесшовно пользоваться как с (бесплатным) Inference API, так и с self-hosted Inference Endpoints или сторонними Inference Providers.

audio_classification

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None ) → list[AudioClassificationOutputElement]

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Аудиоконтент для классификации. Может представлять собой необработанные аудиоданные, локальный аудиофайл или URL, указывающий на аудиофайл.
  • model (str, необязательный) — Модель, используемая для классификации аудио. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для классификации аудио.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.
  • function_to_apply ("AudioClassificationOutputTransform", необязательный) — Функция, применяемая к выходным данным модели для получения оценок.

Возвращает

list[AudioClassificationOutputElement]

Список элементов AudioClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию аудио по предоставленному аудиоконтенту.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.audio_classification("audio.flac")
[
    AudioClassificationOutputElement(score=0.4976358711719513, label='hap'),
    AudioClassificationOutputElement(score=0.3677836060523987, label='neu'),
    ...
]

audio_to_audio

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → list[AudioToAudioOutputElement]

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Аудиоданные для модели. Могут представлять собой сырые байты аудио, локальный аудиофайл или URL, указывающий на аудиофайл.
  • model (str, необязательный) — Моделью может быть любая модель, которая принимает аудиофайл и возвращает другой аудиофайл. Это может быть идентификатор модели, размещённой на Hugging Face Hub, или URL развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для audio_to_audio.

Возвращает

list[AudioToAudioOutputElement]

Список элементов AudioToAudioOutputElement, содержащих метку аудио, тип содержимого и аудиоданные в формате blob.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполняет несколько задач, связанных с преобразованием аудио в аудио, в зависимости от модели (например: улучшение речи, разделение источников).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> audio_output = client.audio_to_audio("audio.flac")
>>> for i, item in enumerate(audio_output):
>>>     with open(f"output_{i}.flac", "wb") as f:
            f.write(item.blob)

automatic_speech_recognition

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneextra_body: dict | None = None ) → AutomaticSpeechRecognitionOutput

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Содержимое для транскрибации. Может представлять собой сырые аудиоданные, локальный аудиофайл или URL аудиофайла.
  • model (str, необязательный) — Модель, используемая для ASR. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для ASR.
  • extra_body (dict, необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. Список поддерживаемых параметров см. в документации провайдера.

Возвращает

AutomaticSpeechRecognitionOutput

Элемент, содержащий транскрибированный текст и, при необходимости, временные метки.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните автоматическое распознавание речи (ASR или преобразование аудио в текст) для указанного аудиоконтента.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.automatic_speech_recognition("hello_world.flac").text
"hello world"

chat_completion

< >

( messages: listmodel: str | None = Nonestream: bool = Falsefrequency_penalty: float | None = Nonelogit_bias: list[float] | None = Nonelogprobs: bool | None = Nonemax_tokens: int | None = Nonen: int | None = Nonepresence_penalty: float | None = Noneresponse_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = Noneseed: int | None = Nonestop: list[str] | None = Nonestream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = Nonetemperature: float | None = Nonetool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = Nonetool_prompt: str | None = Nonetools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = Nonetop_logprobs: int | None = Nonetop_p: float | None = Noneextra_body: dict | None = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput

Параметры

  • messages (список ChatCompletionInputMessage) — История диалога, состоящая из пар ролей и содержимого.
  • model (str, необязательный) — Модель, используемая для chat-completion. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для генерации текста в режиме чата. Подробнее см. https://huggingface.co/tasks/text-generation. Если model является идентификатором модели, он передаётся на сервер в качестве параметра model. Если вы хотите определить собственный URL, задавая model в теле запроса, необходимо установить base_url при инициализации InferenceClient.
  • frequency_penalty (float, необязательный) — Штрафует новые токены на основе их существующей частоты в тексте до этого момента. Диапазон: [-2.0, 2.0]. По умолчанию: 0.0.
  • logit_bias (list[float], необязательный) — Корректирует вероятность появления конкретных токенов в сгенерированном выводе.
  • logprobs (bool, необязательный) — Возвращать ли логарифмические вероятности выходных токенов. Если true, возвращает логарифмические вероятности каждого выходного токена, переданного в содержимом сообщения.
  • max_tokens (int, необязательный) — Максимальное количество токенов, разрешенных в ответе. По умолчанию — 100.
  • n (int, необязательный) — Количество завершений, которые нужно сгенерировать для каждого промпта.
  • presence_penalty (float, необязательный) — Число от -2.0 до 2.0. Положительные значения штрафуют новые токены в зависимости от того, встречаются ли они в тексте на данный момент, что повышает вероятность того, что модель будет говорить о новых темах.
  • response_format (ChatCompletionInputGrammarType(), необязательный) — Ограничения грамматики. Может быть JSONSchema или регулярным выражением.
  • seed (необязательныйint, optional) — Seed для воспроизводимого управления потоком выполнения. По умолчанию — None.
  • stop (list[str], необязательный) — До четырёх строк, которые запускают завершение ответа. По умолчанию — None.
  • stream (bool, необязательный) — Включает потоковую передачу ответов в реальном времени. По умолчанию False.
  • stream_options (ChatCompletionInputStreamOptions, необязательный) — Параметры для потоковой передачи ответов.
  • temperature (float, необязательный) — Управляет случайностью генерации. Меньшие значения обеспечивают менее случайные завершения. Диапазон: [0, 2]. По умолчанию: 1.0.
  • top_logprobs (int, необязательный) — Целое число от 0 до 5, задающее количество наиболее вероятных токенов, возвращаемых для каждой позиции токена, каждый из которых сопровождается соответствующей логарифмической вероятностью. Если используется этот параметр, параметр logprobs должен быть установлен в true.
  • top_p (float, необязательный) — Доля наиболее вероятных следующих слов, из которых выполняется выборка. Должно быть в диапазоне от 0 до 1. По умолчанию 1.0.
  • tool_choice (ChatCompletionInputToolChoiceClass или ChatCompletionInputToolChoiceEnum(), необязательный) — Инструмент, используемый для завершения. По умолчанию — «auto».
  • tool_prompt (str, необязательный) — Промпт, добавляемый перед инструментами.
  • tools (список ChatCompletionInputTool, необязательный) — Список инструментов, которые может вызывать модель. В настоящее время в качестве инструмента поддерживаются только функции. Используйте этот параметр, чтобы предоставить список функций, для которых модель может генерировать JSON-входные данные.
  • extra_body (dict, необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. Список поддерживаемых параметров см. в документации провайдера.

Возвращает

ChatCompletionOutput или итерируемый объект ChatCompletionStreamOutput

Сгенерированный текст, возвращенный с сервера:

  • Если stream=False, сгенерированный текст возвращается в виде ChatCompletionOutput (по умолчанию).
  • Если stream=True, сгенерированный текст возвращается по одному токену в виде последовательности ChatCompletionStreamOutput.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Метод для завершения диалогов с использованием указанной языковой модели.

Метод client.chat_completion имеет псевдоним client.chat.completions.create для обеспечения совместимости с клиентом OpenAI. Входные и выходные данные строго идентичны, и использование любого из синтаксисов даст одинаковый результат. Подробнее о совместимости с OpenAI см. в руководстве по инференсу.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

>>> from huggingface_hub import InferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> client.chat_completion(messages, max_tokens=100)
ChatCompletionOutput(
    choices=[
        ChatCompletionOutputComplete(
            finish_reason='eos_token',
            index=0,
            message=ChatCompletionOutputMessage(
                role='assistant',
                content='The capital of France is Paris.',
                name=None,
                tool_calls=None
            ),
            logprobs=None
        )
    ],
    created=1719907176,
    id='',
    model='meta-llama/Meta-Llama-3-8B-Instruct',
    object='text_completion',
    system_fingerprint='2.0.4-sha-f426a33',
    usage=ChatCompletionOutputUsage(
        completion_tokens=8,
        prompt_tokens=17,
        total_tokens=25
    )
)

Пример с использованием потоковой передачи:

>>> from huggingface_hub import InferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> for token in client.chat_completion(messages, max_tokens=10, stream=True):
...     print(token)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504)
(...)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504)

Пример с использованием синтаксиса OpenAI:

# instead of `from openai import OpenAI`
from huggingface_hub import InferenceClient

# instead of `client = OpenAI(...)`
client = InferenceClient(
    base_url=...,
    api_key=...,
)

output = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Count to 10"},
    ],
    stream=True,
    max_tokens=1024,
)

for chunk in output:
    print(chunk.choices[0].delta.content)

Пример использования стороннего провайдера напрямую с дополнительными (специфичными для провайдера) параметрами. Использование будет тарифицироваться на вашем аккаунте Together AI.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="together",  # Use Together AI provider
...     api_key="<together_api_key>",  # Pass your Together API key directly
... )
>>> client.chat_completion(
...     model="meta-llama/Meta-Llama-3-8B-Instruct",
...     messages=[{"role": "user", "content": "What is the capital of France?"}],
...     extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"},
... )

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="novita",  # Use Novita provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> client.chat_completion(
...     model="meta-llama/Meta-Llama-3-8B-Instruct",
...     messages=[{"role": "user", "content": "What is the capital of France?"}],
... )

Пример использования изображения и текста в качестве входных данных:

>>> from huggingface_hub import InferenceClient

# provide a remote URL
>>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
# or a base64-encoded image
>>> image_path = "/path/to/image.jpeg"
>>> with open(image_path, "rb") as f:
...     base64_image = base64.b64encode(f.read()).decode("utf-8")
>>> image_url = f"data:image/jpeg;base64,{base64_image}"

>>> client = InferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct")
>>> output = client.chat.completions.create(
...     messages=[
...         {
...             "role": "user",
...             "content": [
...                 {
...                     "type": "image_url",
...                     "image_url": {"url": image_url},
...                 },
...                 {
...                     "type": "text",
...                     "text": "Describe this image in one sentence.",
...                 },
...             ],
...         },
...     ],
... )
>>> output
The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day.

Пример с использованием инструментов:

>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
...     {
...         "role": "system",
...         "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
...     },
...     {
...         "role": "user",
...         "content": "What's the weather like the next 3 days in San Francisco, CA?",
...     },
... ]
>>> tools = [
...     {
...         "type": "function",
...         "function": {
...             "name": "get_current_weather",
...             "description": "Get the current weather",
...             "parameters": {
...                 "type": "object",
...                 "properties": {
...                     "location": {
...                         "type": "string",
...                         "description": "The city and state, e.g. San Francisco, CA",
...                     },
...                     "format": {
...                         "type": "string",
...                         "enum": ["celsius", "fahrenheit"],
...                         "description": "The temperature unit to use. Infer this from the users location.",
...                     },
...                 },
...                 "required": ["location", "format"],
...             },
...         },
...     },
...     {
...         "type": "function",
...         "function": {
...             "name": "get_n_day_weather_forecast",
...             "description": "Get an N-day weather forecast",
...             "parameters": {
...                 "type": "object",
...                 "properties": {
...                     "location": {
...                         "type": "string",
...                         "description": "The city and state, e.g. San Francisco, CA",
...                     },
...                     "format": {
...                         "type": "string",
...                         "enum": ["celsius", "fahrenheit"],
...                         "description": "The temperature unit to use. Infer this from the users location.",
...                     },
...                     "num_days": {
...                         "type": "integer",
...                         "description": "The number of days to forecast",
...                     },
...                 },
...                 "required": ["location", "format", "num_days"],
...             },
...         },
...     },
... ]

>>> response = client.chat_completion(
...     model="meta-llama/Meta-Llama-3-70B-Instruct",
...     messages=messages,
...     tools=tools,
...     tool_choice="auto",
...     max_tokens=500,
... )
>>> response.choices[0].message.tool_calls[0].function
ChatCompletionOutputFunctionDefinition(
    arguments={
        'location': 'San Francisco, CA',
        'format': 'fahrenheit',
        'num_days': 3
    },
    name='get_n_day_weather_forecast',
    description=None
)

Пример использования response_format:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
...     {
...         "role": "user",
...         "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?",
...     },
... ]
>>> response_format = {
...     "type": "json",
...     "value": {
...         "properties": {
...             "location": {"type": "string"},
...             "activity": {"type": "string"},
...             "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
...             "animals": {"type": "array", "items": {"type": "string"}},
...         },
...         "required": ["location", "activity", "animals_seen", "animals"],
...     },
... }
>>> response = client.chat_completion(
...     messages=messages,
...     response_format=response_format,
...     max_tokens=500,
... )
>>> response.choices[0].message.content
'{

y": "bike ride",
": ["puppy", "cat", "raccoon"],
_seen": 3,
n": "park"}'

document_question_answering

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonelang: str | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = Noneword_boxes: list[list[float] | str] | None = None ) → list[DocumentQuestionAnsweringOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO]) — Входное изображение для контекста. Может быть сырыми байтами, файлом изображения или URL онлайн-изображения.
  • question (str) — Вопрос, на который нужно ответить.
  • model (str, необязательный) — Модель, используемая для задачи документного вопросно-ответного взаимодействия. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для задачи документного вопросно-ответного взаимодействия. По умолчанию: None.
  • doc_stride (int, необязательный) — Если слова в документе слишком длинные, чтобы вместе с вопросом поместиться в модель, документ будет разбит на несколько фрагментов с перекрытием. Этот аргумент управляет размером перекрытия.
  • handle_impossible_answer (bool, необязательный) — Следует ли принимать «impossible» в качестве ответа
  • lang (str, необязательный) — Язык, используемый при выполнении OCR. По умолчанию — английский.
  • max_answer_len (int, необязательный) — Максимальная длина предсказанных ответов (например, учитываются только ответы с меньшей длиной).
  • max_question_len (int, необязательный) — Максимальная длина вопроса после токенизации. При необходимости будет усечена.
  • max_seq_len (int, необязательный) — Максимальная длина полного предложения (контекст + вопрос) в токенах для каждого фрагмента, передаваемого в модель. При необходимости контекст будет разбит на несколько фрагментов (с перекрытием doc_stride).
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Может вернуть меньше, чем top_k, если в контексте недостаточно вариантов.
  • word_boxes (list[Union[list[float], str, optional) — Список слов и ограничивающих прямоугольников (нормализованных 0->1000). Если указан, этап OCR пропускается, а вместо него используются предоставленные ограничивающие прямоугольники.

Возвращает

list[DocumentQuestionAnsweringOutputElement]

список элементов DocumentQuestionAnsweringOutputElement, содержащих предсказанную метку, связанную с ней вероятность, идентификаторы слов и номер страницы.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Отвечайте на вопросы по изображениям документов.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]

feature_extraction

< >

( text: str | list[str]normalize: bool | None = Noneprompt_name: str | None = Nonetruncate: bool | None = Nonetruncation_direction: typing.Optional[typing.Literal['left', 'right']] = Nonedimensions: int | None = Noneencoding_format: typing.Optional[typing.Literal['float', 'base64']] = Nonemodel: str | None = None ) → np.ndarray

Параметры

  • text (str или list[str]) — Текст или список текстов для эмбеддинга.
  • model (str, optional) — Модель, используемая для задачи извлечения признаков. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель извлечения признаков по умолчанию. По умолчанию: None.
  • normalize (bool, optional) — Нужно ли нормализовать эмбеддинги. Доступно только на сервере, работающем на базе Text-Embedding-Inference.
  • prompt_name (str, optional) — The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the Sentence Transformers configuration prompts dictionary. For example if prompt_name is “query” and the prompts is {“query”: “query: ”,…}, then the sentence “What is the capital of France?” will be encoded as “query: What is the capital of France?” because the prompt text will be prepended before any text to encode.
  • truncate (bool, optional) — Определяет, нужно ли усекать эмбеддинги. Доступно только на сервере, работающем на базе Text-Embedding-Inference.
  • truncation_direction (Literal[“left”, “right”], optional) — С какой стороны входных данных следует выполнять усечение при передаче truncate=True.
  • dimensions (int, optional) — Количество измерений, которое должны иметь результирующие выходные эмбеддинги. Доступно только для эндпоинтов эмбеддингов, совместимых с OpenAI.
  • encoding_format (Literal[“float”, “base64”], optional) — Формат выходных эмбеддингов. Допустимые значения: “float” или “base64”. Доступно только для эндпоинтов эмбеддингов, совместимых с OpenAI.

Возвращает

np.ndarray

Встраивание, представляющее входной текст(ы) в виде массива numpy с типом float32.

Исключения

[InferenceTimeoutError] или [HfHubHTTPError]

  • [InferenceTimeoutError] — Если модель недоступна или запрос завершается по таймауту.
  • [HfHubHTTPError] — Если запрос завершается ошибкой с кодом статуса HTTP, отличным от HTTP 503.

Создайте эмбеддинги для заданного текста или батча текстов.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.feature_extraction("Hi, who are you?")
array([[ 2.424802  ,  2.93384   ,  1.1750331 , ...,  1.240499, -0.13776633, -0.7889173 ],
[-0.42943227, -0.6364878 , -1.693462  , ...,  0.41978157, -2.4336355 ,  0.6162071 ],
...,
[ 0.28552425, -0.928395  , -1.2077185 , ...,  0.76810825, -2.1069427 ,  0.6236161 ]], dtype=float32)

fill_mask

< >

( text: strmodel: str | None = Nonetargets: list[str] | None = Nonetop_k: int | None = None ) → list[FillMaskOutputElement]

Параметры

  • text (str) — строка, из которой будет заполняться текст; должна содержать токен [MASK] (точное имя маски смотрите в карточке модели).
  • model (str, необязательный) — Модель, используемая для задачи fill mask. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель fill mask по умолчанию.
  • targets (list[str, optional) — Если передано, модель ограничит оценки переданными целями, вместо того чтобы искать их во всей словарной базе. Если предоставленные цели отсутствуют в словаре модели, они будут токенизированы, и будет использован первый полученный токен (с предупреждением, и это может быть медленнее).
  • top_k (int, необязательный) — Если передан, переопределяет количество возвращаемых предсказаний.

Возвращает

list[FillMaskOutputElement]

список элементов FillMaskOutputElement, содержащих предсказанную метку, связанную с ней вероятность, ссылку на токен и завершённый текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Заполните пропуск недостающим словом (точнее, токеном).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.fill_mask("The goal of life is <mask>.")
[
    FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
    FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]

get_endpoint_info

< >

( model: str | None = None ) → dict[str, Any]

Параметры

  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

dict[str, Any]

Информация об эндпоинте.

Получите информацию о развернутом конечном пункте.

Этот конечный пункт доступен только для конечных пунктов, работающих на базе Text-Generation-Inference (TGI) или Text-Embedding-Inference (TEI). Конечные пункты, работающие на базе transformers, возвращают пустой полезный груз.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> client.get_endpoint_info()
{
    'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct',
    'model_sha': None,
    'model_dtype': 'torch.float16',
    'model_device_type': 'cuda',
    'model_pipeline_tag': None,
    'max_concurrent_requests': 128,
    'max_best_of': 2,
    'max_stop_sequences': 4,
    'max_input_length': 8191,
    'max_total_tokens': 8192,
    'waiting_served_ratio': 0.3,
    'max_batch_total_tokens': 1259392,
    'max_waiting_tokens': 20,
    'max_batch_size': None,
    'validation_workers': 32,
    'max_client_batch_size': 4,
    'version': '2.0.2',
    'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214',
    'docker_label': 'sha-dccab72'
}

health_check

< >

( model: str | None = None ) → bool

Параметры

  • model (str, необязательный) — URL точки вывода (Inference Endpoint). Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

bool

Истина, если всё работает корректно.

Проверьте состояние развернутого конечного пункта.

Health check доступен только для Inference Endpoints, работающих на базе Text-Generation-Inference (TGI) или Text-Embedding-Inference (TEI).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient("https://jzgu0buei5.us-east-1.aws.endpoints.huggingface.cloud")
>>> client.health_check()
True

image_classification

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonefunction_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = Nonetop_k: int | None = None ) → list[ImageClassificationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение для классификации. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для классификации изображений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для классификации изображений.
  • function_to_apply ("ImageClassificationOutputTransform", необязательный) — Функция, применяемая к выводам модели для получения оценок.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.

Возвращает

list[ImageClassificationOutputElement]

список элементов ImageClassificationOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию изображения на данном изображении с использованием указанной модели.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...]

image_segmentation

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonemask_threshold: float | None = Noneoverlap_mask_area_threshold: float | None = Nonesubtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = Nonethreshold: float | None = None ) → list[ImageSegmentationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение для сегментации. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для сегментации изображений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для сегментации изображений.
  • mask_threshold (float, необязательный) — Порог, используемый при преобразовании предсказанных масок в бинарные значения.
  • overlap_mask_area_threshold (float, необязательный) — Порог перекрытия масок для удаления небольших, несвязанных сегментов.
  • subtask ("ImageSegmentationSubtask", необязательный) — Задача сегментации, выполняемая в зависимости от возможностей модели.
  • threshold (float, необязательный) — Порог вероятности для отсечения предсказанных масок.

Возвращает

list[ImageSegmentationOutputElement]

Список элементов ImageSegmentationOutputElement, содержащих сегментированные маски и связанные с ними атрибуты.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните сегментацию изображения на данном изображении с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_segmentation("cat.jpg")
[ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=<PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>), ...]

image_to_image

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]prompt: str | None = Nonenegative_prompt: str | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None**kwargs ) → Image

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для перевода. Может представлять собой сырые байты, файл изображения, URL онлайн-изображения или объект PIL Image.
  • prompt (str, необязательный) — Текстовый промпт для управления генерацией изображения.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое изображение.
  • num_inference_steps (int, необязательный) — Для диффузионных моделей. Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Для диффузионных моделей. Чем выше значение guidance scale, тем сильнее модель стремится генерировать изображения, тесно связанные с текстовым запросом, в ущерб качеству изображения.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • target_size (ImageToImageTargetSize, необязательный) — Размер выходного изображения в пикселях. Этот параметр поддерживается только некоторыми провайдерами и для конкретных моделей. Если параметр не поддерживается, он будет проигнорирован.

Возвращает

Image

Переведенное изображение.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните перевод изображения в изображение с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> image = client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
>>> image.save("tiger.jpg")

image_to_text

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → ImageToTextOutput

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации подписи. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

ImageToTextOutput

Сгенерированный текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Принимает входное изображение и возвращает текст.

В зависимости от задачи (описание изображений, оптическое распознавание символов (OCR), Pix2Struct и т. д.) модели могут выдавать очень разные результаты. Ознакомьтесь с карточкой модели, чтобы узнать о её особенностях.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_to_text("cat.jpg")
'a cat standing in a grassy field '
>>> client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
'a dog laying on the grass next to a flower pot '

image_to_video

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneprompt: str | None = Nonenegative_prompt: str | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Noneseed: int | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None**kwargs ) → bytes

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации видео. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • prompt (str, необязательный) — Текстовый промпт для управления генерацией видео.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое видео.
  • num_frames (float, необязательный) — Параметр num_frames определяет количество генерируемых кадров видео.
  • num_inference_steps (int, необязательный) — Для диффузионных моделей. Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Для диффузионных моделей. Чем выше значение guidance scale, тем сильнее модель стремится генерировать видео, тесно связанные с текстовым промптом, за счёт снижения качества изображения.
  • seed (int, необязательный) — Значение seed, используемое для генерации видео.
  • target_size (ImageToVideoTargetSize, необязательный) — Размер кадров выходного видео в пикселях.
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к более высокому качеству видео, но за счёт более медленного вывода.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.

Возвращает

bytes

Сгенерированное видео.

Сгенерируйте видео из входного изображения.

Примеры:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> video = client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger")
>>> with open("tiger.mp4", "wb") as f:
...     f.write(video)

object_detection

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonethreshold: float | None = None ) → list[ObjectDetectionOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение, на котором необходимо обнаружить объекты. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для обнаружения объектов. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для обнаружения объектов (DETR).
  • threshold (float, необязательный) — Вероятность, необходимая для принятия предсказания.

Возвращает

list[ObjectDetectionOutputElement]

Список элементов ObjectDetectionOutputElement, содержащих ограничивающие прямоугольники и связанные с ними атрибуты.

Исключения

InferenceTimeoutError или HfHubHTTPError или ValueError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.
  • ValueError — Если результат запроса не является List.

Выполните обнаружение объектов на указанном изображении с помощью заданной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.object_detection("people.jpg")
[ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...]

question_answering

< >

( question: strcontext: strmodel: str | None = Nonealign_to_words: bool | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = None ) → Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]

Параметры

  • question (str) — Вопрос, на который нужно ответить.
  • context (str) — Контекст вопроса.
  • model (str) — Модель, используемая для задачи ответа на вопросы. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint.
  • align_to_words (bool, необязательный) — Пытается выровнять ответ по реальным словам. Улучшает качество для языков с разделением слов пробелами. Может ухудшить результат для языков без пробельного разделения (например, японского или китайского)
  • doc_stride (int, необязательный) — Если контекст слишком длинный, чтобы вместе с вопросом поместиться в модель, он будет разбит на несколько фрагментов с некоторым перекрытием. Этот аргумент управляет размером этого перекрытия.
  • handle_impossible_answer (bool, необязательный) — Следует ли принимать «impossible» в качестве ответа.
  • max_answer_len (int, необязательный) — Максимальная длина предсказанных ответов (например, учитываются только ответы с меньшей длиной).
  • max_question_len (int, необязательный) — Максимальная длина вопроса после токенизации. При необходимости будет усечена.
  • max_seq_len (int, необязательный) — Максимальная длина полного предложения (контекст + вопрос) в токенах для каждого фрагмента, передаваемого в модель. При необходимости контекст будет разбит на несколько фрагментов (с перекрытием docStride).
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Обратите внимание, что если в контексте недостаточно вариантов, будет возвращено меньше, чем top_k ответов.

Возвращает

Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]

When top_k is 1 or not provided, it returns a single QuestionAnsweringOutputElement. When top_k is greater than 1, it returns a list of QuestionAnsweringOutputElement.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Получите ответ на вопрос из заданного текста.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.")
QuestionAnsweringOutputElement(answer='Clara', end=16, score=0.9326565265655518, start=11)

sentence_similarity

< >

( sentence: strother_sentences: listmodel: str | None = None ) → list[float]

Параметры

  • sentence (str) — Основное предложение, с которым сравниваются остальные.
  • other_sentences (list[str]) — Список предложений для сравнения.
  • model (str, необязательный) — Модель, используемая для задачи определения сходства предложений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для задачи определения сходства предложений. По умолчанию: None.

Возвращает

list[float]

Встраивание, представляющее входной текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Вычислите семантическое сходство между предложением и списком других предложений, сравнив их эмбеддинги.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.sentence_similarity(
...     "Machine learning is so easy.",
...     other_sentences=[
...         "Deep learning is so straightforward.",
...         "This is so difficult, like rocket science.",
...         "I can't believe how much I struggled with this.",
...     ],
... )
[0.7785726189613342, 0.45876261591911316, 0.2906220555305481]

суммаризация

< >

( text: strmodel: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonegenerate_parameters: dict[str, typing.Any] | None = Nonetruncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None ) → SummarizationOutput

Параметры

  • text (str) — Входной текст для суммаризации.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для суммаризации.
  • clean_up_tokenization_spaces (bool, необязательный) — Определяет, следует ли удалять возможные лишние пробелы в текстовом выводе.
  • generate_parameters (dict[str, Any], необязательный) — Дополнительная параметризация алгоритма генерации текста.
  • truncation ("SummarizationTruncationStrategy", необязательный) — Стратегия усечения, которую следует использовать.

Возвращает

SummarizationOutput

Сгенерированный текст резюме.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Сгенерируйте краткое содержание заданного текста с использованием указанной модели.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.summarization("The Eiffel tower...")
SummarizationOutput(generated_text="The Eiffel tower is one of the most famous landmarks in the world....")

table_question_answering

< >

( table: dictquery: strmodel: str | None = Nonepadding: typing.Optional[ForwardRef('Padding')] = Nonesequential: bool | None = Nonetruncation: bool | None = None ) → TableQuestionAnsweringOutputElement

Параметры

  • table (str) — Таблица данных, представленная в виде словаря списков, где ключи — это заголовки, а списки — все значения; все списки должны иметь одинаковую длину.
  • query (str) — Запрос в обычном тексте, который вы хотите задать таблице.
  • model (str) — Модель, используемая для задачи table-question-answering. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint.
  • padding ("Padding", необязательный) — Включает и управляет выравниванием.
  • sequential (bool, необязательный) — Выполнять ли вывод последовательно или батчами. Батчинг быстрее, но модели вроде SQA требуют последовательного выполнения вывода для извлечения связей внутри последовательностей, учитывая их диалоговый характер.
  • truncation (bool, необязательный) — Включает и управляет усечением.

Возвращает

TableQuestionAnsweringOutputElement

вывод задачи по ответам на вопросы по таблице, содержащий ответ, координаты, ячейки и используемый агрегатор.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Получите ответ на вопрос из информации, представленной в таблице.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> query = "How many stars does the transformers repository have?"
>>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
>>> client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE')

tabular_classification

< >

( table: dictmodel: str | None = None ) → List

Параметры

  • table (dict[str, Any]) — Набор атрибутов для классификации.
  • model (str, необязательный) — Модель, используемая для задачи табличной классификации. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель табличной классификации по умолчанию. По умолчанию: None.

Возвращает

List

список меток, по одной на каждую строку в исходной таблице.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Классификация целевой категории (группы) на основе набора атрибутов.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> table = {
...     "fixed_acidity": ["7.4", "7.8", "10.3"],
...     "volatile_acidity": ["0.7", "0.88", "0.32"],
...     "citric_acid": ["0", "0", "0.45"],
...     "residual_sugar": ["1.9", "2.6", "6.4"],
...     "chlorides": ["0.076", "0.098", "0.073"],
...     "free_sulfur_dioxide": ["11", "25", "5"],
...     "total_sulfur_dioxide": ["34", "67", "13"],
...     "density": ["0.9978", "0.9968", "0.9976"],
...     "pH": ["3.51", "3.2", "3.23"],
...     "sulphates": ["0.56", "0.68", "0.82"],
...     "alcohol": ["9.4", "9.8", "12.6"],
... }
>>> client.tabular_classification(table=table, model="julien-c/wine-quality")
["5", "5", "5"]

tabular_regression

< >

( table: dictmodel: str | None = None ) → List

Параметры

  • table (dict[str, Any]) — Набор атрибутов, хранящихся в таблице. Атрибуты, используемые для предсказания целевой переменной, могут быть как числовыми, так и категориальными.
  • model (str, необязательный) — Модель, используемая для задачи табличной регрессии. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель табличной регрессии по умолчанию. По умолчанию: None.

Возвращает

List

список предсказанных числовых значений целевой переменной.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Предсказание числового целевого значения по набору атрибутов/признаков в таблице.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> table = {
...     "Height": ["11.52", "12.48", "12.3778"],
...     "Length1": ["23.2", "24", "23.9"],
...     "Length2": ["25.4", "26.3", "26.5"],
...     "Length3": ["30", "31.2", "31.1"],
...     "Species": ["Bream", "Bream", "Bream"],
...     "Width": ["4.02", "4.3056", "4.6961"],
... }
>>> client.tabular_regression(table, model="scikit-learn/Fish-Weight")
[110, 120, 130]

text_classification

< >

( text: strmodel: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None ) → list[TextClassificationOutputElement]

Параметры

  • text (str) — Строка для классификации.
  • model (str, необязательный) — Модель, используемая для задачи классификации текста. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель классификации текста по умолчанию. По умолчанию: None.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.
  • function_to_apply ("TextClassificationOutputTransform", необязательный) — Функция, применяемая к выводам модели для получения оценок.

Возвращает

list[TextClassificationOutputElement]

список элементов TextClassificationOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию текста (например, анализ тональности) для заданного текста.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.text_classification("I like you")
[
    TextClassificationOutputElement(label='POSITIVE', score=0.9998695850372314),
    TextClassificationOutputElement(label='NEGATIVE', score=0.0001304351753788069),
]

text_generation

< >

( prompt: strdetails: bool | None = Nonestream: bool | None = Nonemodel: str | None = Noneadapter_id: str | None = Nonebest_of: int | None = Nonedecoder_input_details: bool | None = Nonedo_sample: bool | None = Nonefrequency_penalty: float | None = Nonegrammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = Nonemax_new_tokens: int | None = Nonerepetition_penalty: float | None = Nonereturn_full_text: bool | None = Noneseed: int | None = Nonestop: list[str] | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_n_tokens: int | None = Nonetop_p: float | None = Nonetruncate: int | None = Nonetypical_p: float | None = Nonewatermark: bool | None = None ) → Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]

Параметры

  • prompt (str) — Входной текст.
  • details (bool, необязательный) — По умолчанию text_generation возвращает строку. Передайте details=True, если вам нужен подробный вывод (токены, вероятности, seed, причина завершения и т. д.). Доступно только для моделей, работающих с бэкендом text-generation-inference.
  • stream (bool, необязательный) — По умолчанию text_generation возвращает весь сгенерированный текст. Передайте stream=True, если вы хотите получить поток токенов. Доступно только для моделей, работающих с бэкендом text-generation-inference.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • adapter_id (str, необязательный) — Идентификатор адаптера Lora.
  • best_of (int, необязательный) — Сгенерировать best_of последовательностей и вернуть ту, у которой максимальные logprobs токенов.
  • decoder_input_details (bool, необязательный) — Возвращает logprobs и идентификаторы токенов входных данных декодера. Для того чтобы этот параметр учитывался, необходимо также установить details=True. По умолчанию False.
  • do_sample (bool, необязательный) — Включает выборку из логитов
  • frequency_penalty (float, необязательный) — Число от -2.0 до 2.0. Положительные значения штрафуют новые токены в зависимости от их частоты в тексте на данный момент, снижая вероятность того, что модель дословно повторит одну и ту же строку.
  • grammar (TextGenerationInputGrammarType, optional) — Ограничения грамматики. Может быть JSONSchema или регулярным выражением.
  • max_new_tokens (int, необязательный) — Максимальное количество генерируемых токенов. По умолчанию — 100.
  • repetition_penalty (float, необязательный) — Параметр штрафного коэффициента за повторения. Значение 1.0 означает отсутствие штрафа. Подробнее см. в этой статье.
  • return_full_text (bool, необязательный) — Следует ли добавлять промпт перед сгенерированным текстом
  • seed (int, необязательный) — Сид для случайной выборки
  • stop (list[str], необязательный) — Остановить генерацию токенов, если был сгенерирован элемент из stop.
  • temperature (float, необязательный) — Значение, используемое для модулирования распределения логитов.
  • top_n_tokens (int, необязательный) — Возвращает информацию о top_n_tokens наиболее вероятных токенах на каждом шаге генерации, а не только о сэмплированном токене.
  • top_k (int, *optional`) — Количество токенов словаря с наивысшей вероятностью, которые следует сохранить для фильтрации top-k.
  • top_p (float, *optional) -- If set to < 1, only the smallest set of most probable tokens with probabilities that add up to top_p` or higher are kept for generation.
  • truncate (int, *optional`) — Обрезает входные токены до указанного размера.
  • typical_p (float, *optional`) — Масса Typical Decoding Подробнее см. Typical Decoding for Natural Language Generation
  • watermark (bool, optional) — Watermarking with A Watermark for Large Language Models

Возвращает

Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]

Сгенерированный текст, возвращенный с сервера:

  • если stream=False и details=False, сгенерированный текст возвращается как str (по умолчанию)
  • Если stream=True и details=False, сгенерированный текст возвращается по одному токену в виде Iterable[str]
  • если stream=False и details=True, сгенерированный текст возвращается с дополнительными деталями в виде объекта TextGenerationOutput
  • Если details=True и stream=True, сгенерированный текст возвращается по одному токену в виде итерируемого объекта TextGenerationStreamOutput

Исключения

ValidationError или InferenceTimeoutError или HfHubHTTPError

  • ValidationError — Если входные значения недействительны. HTTP-запрос к серверу не выполняется.
  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

По заданному промпту сгенерируйте следующий текст.

Если вы хотите сгенерировать ответ на основе сообщений чата, используйте метод InferenceClient.chat_completion(). Он принимает список сообщений вместо одиночного текстового запроса и самостоятельно обрабатывает шаблонизацию чата.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

# Case 1: generate text
>>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
'100% open source and built to be easy to use.'

# Case 2: iterate over the generated tokens. Useful for large generation.
>>> for token in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
...     print(token)
100
%
open
source
and
built
to
be
easy
to
use
.

# Case 3: get more details about the generation process.
>>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
TextGenerationOutput(
    generated_text='100% open source and built to be easy to use.',
    details=TextGenerationDetails(
        finish_reason='length',
        generated_tokens=12,
        seed=None,
        prefill=[
            TextGenerationPrefillOutputToken(id=487, text='The', logprob=None),
            TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875),
            (...)
            TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625)
        ],
        tokens=[
            TokenElement(id=1425, text='100', logprob=-1.0175781, special=False),
            TokenElement(id=16, text='%', logprob=-0.0463562, special=False),
            (...)
            TokenElement(id=25, text='.', logprob=-0.5703125, special=False)
        ],
        best_of_sequences=None
    )
)

# Case 4: iterate over the generated tokens with more details.
# Last object is more complete, containing the full generated text and the finish reason.
>>> for details in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
...     print(details)
...
TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(
    id=25,
    text='.',
    logprob=-0.5703125,
    special=False),
    generated_text='100% open source and built to be easy to use.',
    details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None)
)

# Case 5: generate constrained output using grammar
>>> response = client.text_generation(
...     prompt="I saw a puppy a cat and a raccoon during my bike ride in the park",
...     model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1",
...     max_new_tokens=100,
...     repetition_penalty=1.3,
...     grammar={
...         "type": "json",
...         "value": {
...             "properties": {
...                 "location": {"type": "string"},
...                 "activity": {"type": "string"},
...                 "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
...                 "animals": {"type": "array", "items": {"type": "string"}},
...             },
...             "required": ["location", "activity", "animals_seen", "animals"],
...         },
...     },
... )
>>> json.loads(response)
{
    "activity": "bike riding",
    "animals": ["puppy", "cat", "raccoon"],
    "animals_seen": 3,
    "location": "park"
}

text_to_image

< >

( prompt: strnegative_prompt: str | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonescheduler: str | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → Image

Параметры

  • prompt (str) — Промпт для генерации изображения.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое изображение.
  • height (int, необязательный) — Высота выходного изображения в пикселях
  • width (int, необязательный) — Ширина выходного изображения в пикселях
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым запросом, однако слишком высокие значения могут привести к насыщению и другим артефактам.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-image по умолчанию. По умолчанию: None.
  • scheduler (str, необязательный) — Заменить планировщик на совместимый.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

Image

Сгенерированное изображение.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Сгенерируйте изображение на основе заданного текста с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> image = client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     negative_prompt="low resolution, blurry",
...     model="stabilityai/stable-diffusion-2-1",
... )
>>> image.save("better_astronaut.png")
Example using a third-party provider directly. Usage will be billed on your fal.ai account. 
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="fal-ai",  # Use fal.ai provider
...     api_key="fal-ai-api-key",  # Pass your fal.ai API key
... )
>>> image = client.text_to_image(
...     "A majestic lion in a fantasy forest",
...     model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     model="black-forest-labs/FLUX.1-dev",
... )
>>> image.save("astronaut.png")

Пример использования провайдера Replicate с дополнительными параметрами

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     model="black-forest-labs/FLUX.1-schnell",
...     extra_body={"output_quality": 100},
... )
>>> image.save("astronaut.png")

text_to_speech

< >

( text: strmodel: str | None = Nonedo_sample: bool | None = Noneearly_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = Noneepsilon_cutoff: float | None = Noneeta_cutoff: float | None = Nonemax_length: int | None = Nonemax_new_tokens: int | None = Nonemin_length: int | None = Nonemin_new_tokens: int | None = Nonenum_beam_groups: int | None = Nonenum_beams: int | None = Nonepenalty_alpha: float | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_p: float | None = Nonetypical_p: float | None = Noneuse_cache: bool | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes

Параметры

  • text (str) — Текст для синтеза.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-speech по умолчанию. По умолчанию: None.
  • do_sample (bool, необязательный) — Использовать ли выборку вместо жадного декодирования при генерации новых токенов.
  • early_stopping (Union[bool, "TextToSpeechEarlyStoppingEnum"], необязательный) — Управляет условием остановки для методов на основе beam search.
  • epsilon_cutoff (float, необязательный) — Если установлено значение float, строго находящееся между 0 и 1, будут выбораться только токены с условной вероятностью, превышающей epsilon_cutoff. В статье рекомендуемые значения варьируются от 3e-4 до 9e-4 в зависимости от размера модели. Подробнее см. Truncation Sampling as Language Model Desmoothing.
  • eta_cutoff (float, необязательный) — Сэмплинг Eta — это гибрид локально-типичного сэмплинга и epsilon-сэмплинга. Если значение установлено как float строго между 0 и 1, токен рассматривается только в том случае, если он больше либо eta_cutoff, либо sqrt(eta_cutoff)
    • exp(-entropy(softmax(next_token_logits))). Последний член интуитивно представляет собой ожидаемую вероятность следующего токена, масштабированную на sqrt(eta_cutoff). В статье рекомендуемые значения варьируются от 3e-4 до 2e-3 в зависимости от размера модели. Подробнее см. в Truncation Sampling as Language Model Desmoothing.
  • max_length (int, необязательный) — Максимальная длина (в токенах) генерируемого текста, включая входные данные.
  • max_new_tokens (int, необязательный) — Максимальное количество токенов для генерации. Имеет приоритет над max_length.
  • min_length (int, необязательный) — Минимальная длина (в токенах) генерируемого текста, включая входные данные.
  • min_new_tokens (int, необязательный) — Минимальное количество токенов для генерации. Имеет приоритет над min_length.
  • num_beam_groups (int, необязательный) — Количество групп, на которые следует разделить num_beams, чтобы обеспечить разнообразие между различными группами лучей. Подробнее см. в этой статье.
  • num_beams (int, необязательный) — Количество лучей, используемых для beam search.
  • penalty_alpha (float, необязательный) — Значение, балансирующее уверенность модели и штраф за дегенерацию при декодировании с контрастным поиском.
  • temperature (float, необязательный) — Значение, используемое для модуляции вероятностей следующего токена.
  • top_k (int, необязательный) — Количество токенов словаря с наивысшей вероятностью, которые следует сохранить для фильтрации top-k.
  • top_p (float, необязательный) — Если установлено значение float < 1, для генерации сохраняются только наименьшее множество наиболее вероятных токенов, сумма вероятностей которых равна top_p или больше.
  • typical_p (float, необязательный) — Локальная типичность измеряет, насколько условная вероятность предсказания целевого токена следующим близка к ожидаемой условной вероятности предсказания случайного токена следующим, с учётом уже сгенерированного частичного текста. Если установлено значение float < 1, для генерации сохраняются наименьшие множества наиболее локально типичных токенов, вероятности которых в сумме составляют typical_p или выше. Подробнее см. эту статью.
  • use_cache (bool, необязательный) — Должна ли модель использовать прошлые ключи/значения внимания для ускорения декодирования
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

bytes

Сгенерированный аудиофайл.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Синтезируйте аудио с голосом, произносящим заданный текст.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

>>> from pathlib import Path
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> audio = client.text_to_speech("Hello world")
>>> Path("hello_world.flac").write_bytes(audio)

Пример использования стороннего провайдера напрямую. Использование будет тарифицироваться на вашем аккаунте Replicate.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",
...     api_key="your-replicate-api-key",  # Pass your Replicate API key directly
... )
>>> audio = client.text_to_speech(
...     text="Hello world",
...     model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",
...     api_key="hf_...",  # Pass your HF token
... )
>>> audio =client.text_to_speech(
...     text="Hello world",
...     model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)
Example using Replicate provider with extra parameters 
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> audio = client.text_to_speech(
...     "Hello, my name is Kororo, an awesome text-to-speech model.",
...     model="hexgrad/Kokoro-82M",
...     extra_body={"voice": "af_nicole"},
... )
>>> Path("hello.flac").write_bytes(audio)

Пример генерации музыки с использованием «YuE-s1-7B-anneal-en-cot» на fal.ai

>>> from huggingface_hub import InferenceClient
>>> lyrics = '''
... [verse]
... In the town where I was born
... Lived a man who sailed to sea
... And he told us of his life
... In the land of submarines
... So we sailed on to the sun
... 'Til we found a sea of green
... And we lived beneath the waves
... In our yellow submarine

... [chorus]
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... '''
>>> genres = "pavarotti-style tenor voice"
>>> client = InferenceClient(
...     provider="fal-ai",
...     model="m-a-p/YuE-s1-7B-anneal-en-cot",
...     api_key=...,
... )
>>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres})
>>> with open("output.mp3", "wb") as f:
...     f.write(audio)

text_to_video

< >

( prompt: strmodel: str | None = Noneguidance_scale: float | None = Nonenegative_prompt: list[str] | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes

Параметры

  • prompt (str) — Промпт для генерации видео.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-video по умолчанию. По умолчанию: None.
  • guidance_scale (float, необязательный) — Более высокое значение guidance scale побуждает модель генерировать видео, тесно связанные с текстовым запросом, однако слишком высокие значения могут привести к насыщению и другим артефактам.
  • negative_prompt (list[str], необязательный) — Одно или несколько промптов, указывающих, что НЕ включать в генерируемое видео.
  • num_frames (float, необязательный) — Параметр num_frames определяет количество генерируемых кадров видео.
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к более высокому качеству видео, но за счёт более медленного вывода.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

bytes

Сгенерированное видео.

Сгенерируйте видео на основе заданного текста.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

Пример использования стороннего провайдера напрямую. Оплата за использование будет списана с вашего аккаунта fal.ai.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="fal-ai",  # Using fal.ai provider
...     api_key="fal-ai-api-key",  # Pass your fal.ai API key
... )
>>> video = client.text_to_video(
...     "A majestic lion running in a fantasy forest",
...     model="tencent/HunyuanVideo",
... )
>>> with open("lion.mp4", "wb") as file:
...     file.write(video)

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Using replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> video = client.text_to_video(
...     "A cat running in a park",
...     model="genmo/mochi-1-preview",
... )
>>> with open("cat.mp4", "wb") as file:
...     file.write(video)

token_classification

< >

( text: strmodel: str | None = Noneaggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = Noneignore_labels: list[str] | None = Nonestride: int | None = None ) → list[TokenClassificationOutputElement]

Параметры

  • text (str) — Строка для классификации.
  • model (str, необязательный) — Модель, используемая для задачи классификации токенов. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель классификации токенов по умолчанию. По умолчанию: None.
  • aggregation_strategy ("TokenClassificationAggregationStrategy", необязательный) — Стратегия, используемая для объединения токенов на основе предсказаний модели
  • ignore_labels (list[str, необязательный) — Список меток, которые следует игнорировать
  • stride (int, необязательный) — Количество перекрывающихся токенов между фрагментами при разбиении входного текста.

Возвращает

list[TokenClassificationOutputElement]

Список элементов TokenClassificationOutputElement, содержащих группу сущности, оценку уверенности, слово, начальный и конечный индексы.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию токенов в заданном тексте. Обычно используется для разбора предложений, грамматического или распознавания именованных сущностей (NER), чтобы понять ключевые слова, содержащиеся в тексте.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
    TokenClassificationOutputElement(
        entity_group='PER',
        score=0.9971321225166321,
        word='Sarah Jessica Parker',
        start=11,
        end=31,
    ),
    TokenClassificationOutputElement(
        entity_group='PER',
        score=0.9773476123809814,
        word='Jessica',
        start=52,
        end=59,
    )
]

перевод

< >

( text: strmodel: str | None = Nonesrc_lang: str | None = Nonetgt_lang: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonetruncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = Nonegenerate_parameters: dict[str, typing.Any] | None = None ) → TranslationOutput

Параметры

  • text (str) — Строка для перевода.
  • model (str, необязательный) — Модель, используемая для задачи перевода. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель перевода по умолчанию. По умолчанию: None.
  • src_lang (str, необязательный) — Исходный язык текста. Обязателен для моделей, способных переводить с нескольких языков.
  • tgt_lang (str, необязательный) — Целевой язык перевода. Обязателен для моделей, способных переводить на несколько языков.
  • clean_up_tokenization_spaces (bool, необязательный) — Определяет, следует ли удалять возможные лишние пробелы в текстовом выводе.
  • truncation ("TranslationTruncationStrategy", необязательный) — Стратегия усечения, которую следует использовать.
  • generate_parameters (dict[str, Any], необязательный) — Дополнительная параметризация алгоритма генерации текста.

Возвращает

TranslationOutput

Сгенерированный переведенный текст.

Исключения

InferenceTimeoutError или HfHubHTTPError или ValueError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.
  • ValueError — если задан только один из аргументов src_lang и tgt_lang.

Перевод текста с одного языка на другой.

Подробнее о том, как выбрать лучшую модель для вашей конкретной задачи, можно узнать на https://huggingface.co/tasks/translation. Исходный и целевой языки обычно зависят от модели. Однако для некоторых моделей можно указать исходный и целевой языки. Если вы работаете с одной из таких моделей, вы можете использовать аргументы src_lang и tgt_lang, чтобы передать соответствующую информацию.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.translation("My name is Wolfgang and I live in Berlin")
'Mein Name ist Wolfgang und ich lebe in Berlin.'
>>> client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.')

Указание языков:

>>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX")
"Mon nom est Sarah Jessica Parker mais vous pouvez m'appeler Jessica"

visual_question_answering

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonetop_k: int | None = None ) → list[VisualQuestionAnsweringOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для контекста. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • question (str) — Вопрос, на который нужно ответить.
  • model (str, необязательный) — Модель, используемая для задачи визуального ответа на вопросы. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель визуального ответа на вопросы по умолчанию. По умолчанию: None.
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Обратите внимание, что если в контексте недостаточно вариантов, будет возвращено меньше, чем top_k ответов.

Возвращает

list[VisualQuestionAnsweringOutputElement]

список элементов VisualQuestionAnsweringOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Ответы на открытые вопросы на основе изображения.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.visual_question_answering(
...     image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
...     question="What is the animal doing?"
... )
[
    VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'),
    VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'),
]

zero_shot_classification

< >

( text: strcandidate_labels: listmulti_label: bool | None = Falsehypothesis_template: str | None = Nonemodel: str | None = None ) → list[ZeroShotClassificationOutputElement]

Параметры

  • text (str) — Входной текст для классификации.
  • candidate_labels (list[str]) — Набор возможных меток классов, в которые классифицируется текст.
  • multi_label (bool, необязательный) — Указывает, может ли быть истинным несколько меток из числа кандидатов. Если значение равно false, оценки нормализуются так, чтобы сумма вероятностей меток для каждой последовательности была равна 1. Если значение равно true, метки считаются независимыми, а вероятности нормализуются для каждого кандидата.
  • hypothesis_template (str, необязательный) — Предложение, используемое вместе с candidate_labels для попытки классификации текста путём замены плейсхолдера на метки-кандидаты.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. Если не указан, будет использована модель классификации zero-shot по умолчанию.

Возвращает

list[ZeroShotClassificationOutputElement]

Список элементов ZeroShotClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

В качестве входных данных предоставьте текст и набор кандидатов для классификации входного текста.

Пример с multi_label=False:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> text = (
...     "A new model offers an explanation for how the Galilean satellites formed around the solar system's"
...     "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
...     " mysteries when he went for a run up a hill in Nice, France."
... )
>>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
>>> client.zero_shot_classification(text, labels)
[
    ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684),
    ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566),
    ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627),
    ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581),
    ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447),
]
>>> client.zero_shot_classification(text, labels, multi_label=True)
[
    ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311),
    ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844),
    ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714),
    ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327),
    ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
]

Пример с multi_label=True и пользовательским hypothesis_template:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.zero_shot_classification(
...    text="I really like our dinner and I'm very happy. I don't like the weather though.",
...    candidate_labels=["positive", "negative", "pessimistic", "optimistic"],
...    multi_label=True,
...    hypothesis_template="This text is {} towards the weather"
... )
[
    ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
    ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
    ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
    ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
]

zero_shot_image_classification

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]candidate_labels: listmodel: str | None = Nonehypothesis_template: str | None = None ) → list[ZeroShotImageClassificationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации подписи. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • candidate_labels (list[str]) — Кандидатские метки для этого изображения
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. Если не указан, будет использована модель по умолчанию для классификации изображений в режиме zero-shot.
  • hypothesis_template (str, необязательный) — Предложение, используемое вместе с candidate_labels для попытки классификации изображения путём замены плейсхолдера на метки-кандидаты.

Возвращает

list[ZeroShotImageClassificationOutputElement]

Список элементов ZeroShotImageClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Предоставьте входное изображение и текстовые метки, чтобы предсказать текстовые метки для изображения.

Пример:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> client.zero_shot_image_classification(
...     "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
...     candidate_labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]

Асинхронный клиент вывода

Также предоставляется асинхронная версия клиента, основанная на asyncio и httpx2.

класс huggingface_hub.AsyncInferenceClient

< >

( model: str | None = Noneprovider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = Nonetoken: str | None = Nonetimeout: float | None = Noneheaders: dict[str, str] | None = Nonecookies: dict[str, str] | None = Nonebill_to: str | None = Nonebase_url: str | None = Noneapi_key: str | None = None )

Параметры

  • model (str, optional) — Модель для выполнения инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, например meta-llama/Meta-Llama-3-8B-Instruct, или URL-адресом развернутого Inference Endpoint. По умолчанию None, в этом случае для задачи автоматически выбирается рекомендуемая модель. Примечание: для лучшей совместимости с клиентом OpenAI model имеет псевдоним base_url. Эти два аргумента взаимоисключающи. Если в качестве model или base_url для chat completion передан URL, к нему будет добавлен суффикс (/v1)/chat/completions.
  • provider (str, необязательный) — Название провайдера, используемого для инференса. Может быть "baseten", "cerebras", "cohere", "deepinfra", "fal-ai", "featherless-ai", "fireworks-ai", "groq", "hf-inference", "novita", "nscale", "openai", "ovhcloud", "publicai", "replicate", "scaleway", "together", "wavespeed" или "zai-org". По умолчанию — “auto”: автоматический роутинг, который по умолчанию выбирает “fastest” провайдера; вы можете переключиться на порядок “cheapest” или “preferred” на https://hf.co/settings/inference-providers. Если модель указана в виде URL или передан base_url, то provider не используется.
  • token (str, необязательный) — Токен Hugging Face. Если не указан, по умолчанию используется локально сохранённый токен. Примечание: для лучшей совместимости с клиентом OpenAI token имеет псевдоним api_key. Эти два аргумента взаимоисключающи и имеют абсолютно одинаковое поведение.
  • timeout (float, optional) — Максимальное время ожидания ответа от сервера в секундах. По умолчанию None, что означает ожидание в цикле до тех пор, пока сервер не станет доступен.
  • headers (dict[str, str], optional) — Дополнительные заголовки для отправки на сервер. По умолчанию отправляются только заголовки authorization и user-agent. Значения в этом словаре переопределяют значения по умолчанию.
  • bill_to (str, optional) — Аккаунт для выставления счетов за запросы. По умолчанию запросы тарифицируются на аккаунт пользователя. Счета могут выставляться только на организацию, членом которой является пользователь и которая подписала Enterprise Hub.
  • cookies (dict[str, str], optional) — Дополнительные cookies для отправки на сервер.
  • base_url (str, optional) — Базовый URL для запуска инференса. Это дублирующий аргумент из model, чтобы InferenceClient следовал тому же паттерну, что и клиент openai.OpenAI. Невозможно использовать, если задан model. По умолчанию — None.
  • api_key (str, optional) — Токен для аутентификации. Это дублирующий аргумент из token, чтобы InferenceClient следовал тому же паттерну, что и клиент openai.OpenAI. Невозможно использовать, если задан token. По умолчанию — None.

Инициализируйте новый Inference Client.

InferenceClient призван обеспечить единый опыт выполнения инференса. Клиентом можно бесшовно пользоваться как с (бесплатным) Inference API, так и с self-hosted Inference Endpoints или сторонними Inference Providers.

audio_classification

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None ) → list[AudioClassificationOutputElement]

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Аудиоконтент для классификации. Может представлять собой необработанные аудиоданные, локальный аудиофайл или URL, указывающий на аудиофайл.
  • model (str, необязательный) — Модель, используемая для классификации аудио. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для классификации аудио.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.
  • function_to_apply ("AudioClassificationOutputTransform", необязательный) — Функция, применяемая к выходным данным модели для получения оценок.

Возвращает

list[AudioClassificationOutputElement]

Список элементов AudioClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию аудио по предоставленному аудиоконтенту.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.audio_classification("audio.flac")
[
    AudioClassificationOutputElement(score=0.4976358711719513, label='hap'),
    AudioClassificationOutputElement(score=0.3677836060523987, label='neu'),
    ...
]

audio_to_audio

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → list[AudioToAudioOutputElement]

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Аудиоданные для модели. Могут представлять собой сырые байты аудио, локальный аудиофайл или URL, указывающий на аудиофайл.
  • model (str, необязательный) — Моделью может быть любая модель, которая принимает аудиофайл и возвращает другой аудиофайл. Это может быть идентификатор модели, размещённой на Hugging Face Hub, или URL развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для audio_to_audio.

Возвращает

list[AudioToAudioOutputElement]

Список элементов AudioToAudioOutputElement, содержащих метку аудио, тип содержимого и аудиоданные в формате blob.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполняет несколько задач, связанных с преобразованием аудио в аудио, в зависимости от модели (например: улучшение речи, разделение источников).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> audio_output = await client.audio_to_audio("audio.flac")
>>> async for i, item in enumerate(audio_output):
>>>     with open(f"output_{i}.flac", "wb") as f:
            f.write(item.blob)

automatic_speech_recognition

< >

( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneextra_body: dict | None = None ) → AutomaticSpeechRecognitionOutput

Параметры

  • audio (Union[str, Path, bytes, BinaryIO]) — Содержимое для транскрибации. Может представлять собой сырые аудиоданные, локальный аудиофайл или URL аудиофайла.
  • model (str, необязательный) — Модель, используемая для ASR. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для ASR.
  • extra_body (dict, необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. Список поддерживаемых параметров см. в документации провайдера.

Возвращает

AutomaticSpeechRecognitionOutput

Элемент, содержащий транскрибированный текст и, при необходимости, временные метки.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните автоматическое распознавание речи (ASR или преобразование аудио в текст) для указанного аудиоконтента.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.automatic_speech_recognition("hello_world.flac").text
"hello world"

chat_completion

< >

( messages: listmodel: str | None = Nonestream: bool = Falsefrequency_penalty: float | None = Nonelogit_bias: list[float] | None = Nonelogprobs: bool | None = Nonemax_tokens: int | None = Nonen: int | None = Nonepresence_penalty: float | None = Noneresponse_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = Noneseed: int | None = Nonestop: list[str] | None = Nonestream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = Nonetemperature: float | None = Nonetool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = Nonetool_prompt: str | None = Nonetools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = Nonetop_logprobs: int | None = Nonetop_p: float | None = Noneextra_body: dict | None = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput

Параметры

  • messages (список ChatCompletionInputMessage) — История диалога, состоящая из пар ролей и содержимого.
  • model (str, необязательный) — Модель, используемая для chat-completion. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для генерации текста в режиме чата. Подробнее см. https://huggingface.co/tasks/text-generation. Если model является идентификатором модели, он передаётся на сервер в качестве параметра model. Если вы хотите определить собственный URL, задавая model в теле запроса, необходимо установить base_url при инициализации InferenceClient.
  • frequency_penalty (float, необязательный) — Штрафует новые токены на основе их существующей частоты в тексте до этого момента. Диапазон: [-2.0, 2.0]. По умолчанию: 0.0.
  • logit_bias (list[float], необязательный) — Корректирует вероятность появления конкретных токенов в сгенерированном выводе.
  • logprobs (bool, необязательный) — Возвращать ли логарифмические вероятности выходных токенов. Если true, возвращает логарифмические вероятности каждого выходного токена, переданного в содержимом сообщения.
  • max_tokens (int, необязательный) — Максимальное количество токенов, разрешенных в ответе. По умолчанию — 100.
  • n (int, необязательный) — Количество завершений, которые нужно сгенерировать для каждого промпта.
  • presence_penalty (float, необязательный) — Число от -2.0 до 2.0. Положительные значения штрафуют новые токены в зависимости от того, встречаются ли они в тексте на данный момент, что повышает вероятность того, что модель будет говорить о новых темах.
  • response_format (ChatCompletionInputGrammarType(), необязательный) — Ограничения грамматики. Может быть JSONSchema или регулярным выражением.
  • seed (необязательныйint, optional) — Seed для воспроизводимого управления потоком выполнения. По умолчанию — None.
  • stop (list[str], необязательный) — До четырёх строк, которые запускают завершение ответа. По умолчанию — None.
  • stream (bool, необязательный) — Включает потоковую передачу ответов в реальном времени. По умолчанию False.
  • stream_options (ChatCompletionInputStreamOptions, необязательный) — Параметры для потоковой передачи ответов.
  • temperature (float, необязательный) — Управляет случайностью генерации. Меньшие значения обеспечивают менее случайные завершения. Диапазон: [0, 2]. По умолчанию: 1.0.
  • top_logprobs (int, необязательный) — Целое число от 0 до 5, задающее количество наиболее вероятных токенов, возвращаемых для каждой позиции токена, каждый из которых сопровождается соответствующей логарифмической вероятностью. Если используется этот параметр, параметр logprobs должен быть установлен в true.
  • top_p (float, необязательный) — Доля наиболее вероятных следующих слов, из которых выполняется выборка. Должно быть в диапазоне от 0 до 1. По умолчанию 1.0.
  • tool_choice (ChatCompletionInputToolChoiceClass или ChatCompletionInputToolChoiceEnum(), необязательный) — Инструмент, используемый для завершения. По умолчанию — «auto».
  • tool_prompt (str, необязательный) — Промпт, добавляемый перед инструментами.
  • tools (список ChatCompletionInputTool, необязательный) — Список инструментов, которые может вызывать модель. В настоящее время в качестве инструмента поддерживаются только функции. Используйте этот параметр, чтобы предоставить список функций, для которых модель может генерировать JSON-входные данные.
  • extra_body (dict, необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. Список поддерживаемых параметров см. в документации провайдера.

Возвращает

ChatCompletionOutput или итерируемый объект ChatCompletionStreamOutput

Сгенерированный текст, возвращенный с сервера:

  • Если stream=False, сгенерированный текст возвращается в виде ChatCompletionOutput (по умолчанию).
  • Если stream=True, сгенерированный текст возвращается по одному токену в виде последовательности ChatCompletionStreamOutput.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Метод для завершения диалогов с использованием указанной языковой модели.

Метод client.chat_completion имеет псевдоним client.chat.completions.create для обеспечения совместимости с клиентом OpenAI. Входные и выходные данные строго идентичны, и использование любого из синтаксисов даст одинаковый результат. Подробнее о совместимости с OpenAI см. в руководстве по инференсу.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> await client.chat_completion(messages, max_tokens=100)
ChatCompletionOutput(
    choices=[
        ChatCompletionOutputComplete(
            finish_reason='eos_token',
            index=0,
            message=ChatCompletionOutputMessage(
                role='assistant',
                content='The capital of France is Paris.',
                name=None,
                tool_calls=None
            ),
            logprobs=None
        )
    ],
    created=1719907176,
    id='',
    model='meta-llama/Meta-Llama-3-8B-Instruct',
    object='text_completion',
    system_fingerprint='2.0.4-sha-f426a33',
    usage=ChatCompletionOutputUsage(
        completion_tokens=8,
        prompt_tokens=17,
        total_tokens=25
    )
)

Пример с использованием потоковой передачи:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> async for token in await client.chat_completion(messages, max_tokens=10, stream=True):
...     print(token)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504)
(...)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504)

Пример с использованием синтаксиса OpenAI:

# Must be run in an async context
# instead of `from openai import OpenAI`
from huggingface_hub import AsyncInferenceClient

# instead of `client = OpenAI(...)`
client = AsyncInferenceClient(
    base_url=...,
    api_key=...,
)

output = await client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Count to 10"},
    ],
    stream=True,
    max_tokens=1024,
)

for chunk in output:
    print(chunk.choices[0].delta.content)

Пример использования стороннего провайдера напрямую с дополнительными (специфичными для провайдера) параметрами. Использование будет тарифицироваться на вашем аккаунте Together AI.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="together",  # Use Together AI provider
...     api_key="<together_api_key>",  # Pass your Together API key directly
... )
>>> client.chat_completion(
...     model="meta-llama/Meta-Llama-3-8B-Instruct",
...     messages=[{"role": "user", "content": "What is the capital of France?"}],
...     extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"},
... )

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="novita",  # Use Novita provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> client.chat_completion(
...     model="meta-llama/Meta-Llama-3-8B-Instruct",
...     messages=[{"role": "user", "content": "What is the capital of France?"}],
... )

Пример использования изображения и текста в качестве входных данных:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient

# provide a remote URL
>>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
# or a base64-encoded image
>>> image_path = "/path/to/image.jpeg"
>>> with open(image_path, "rb") as f:
...     base64_image = base64.b64encode(f.read()).decode("utf-8")
>>> image_url = f"data:image/jpeg;base64,{base64_image}"

>>> client = AsyncInferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct")
>>> output = await client.chat.completions.create(
...     messages=[
...         {
...             "role": "user",
...             "content": [
...                 {
...                     "type": "image_url",
...                     "image_url": {"url": image_url},
...                 },
...                 {
...                     "type": "text",
...                     "text": "Describe this image in one sentence.",
...                 },
...             ],
...         },
...     ],
... )
>>> output
The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day.

Пример с использованием инструментов:

# Must be run in an async context
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
...     {
...         "role": "system",
...         "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
...     },
...     {
...         "role": "user",
...         "content": "What's the weather like the next 3 days in San Francisco, CA?",
...     },
... ]
>>> tools = [
...     {
...         "type": "function",
...         "function": {
...             "name": "get_current_weather",
...             "description": "Get the current weather",
...             "parameters": {
...                 "type": "object",
...                 "properties": {
...                     "location": {
...                         "type": "string",
...                         "description": "The city and state, e.g. San Francisco, CA",
...                     },
...                     "format": {
...                         "type": "string",
...                         "enum": ["celsius", "fahrenheit"],
...                         "description": "The temperature unit to use. Infer this from the users location.",
...                     },
...                 },
...                 "required": ["location", "format"],
...             },
...         },
...     },
...     {
...         "type": "function",
...         "function": {
...             "name": "get_n_day_weather_forecast",
...             "description": "Get an N-day weather forecast",
...             "parameters": {
...                 "type": "object",
...                 "properties": {
...                     "location": {
...                         "type": "string",
...                         "description": "The city and state, e.g. San Francisco, CA",
...                     },
...                     "format": {
...                         "type": "string",
...                         "enum": ["celsius", "fahrenheit"],
...                         "description": "The temperature unit to use. Infer this from the users location.",
...                     },
...                     "num_days": {
...                         "type": "integer",
...                         "description": "The number of days to forecast",
...                     },
...                 },
...                 "required": ["location", "format", "num_days"],
...             },
...         },
...     },
... ]

>>> response = await client.chat_completion(
...     model="meta-llama/Meta-Llama-3-70B-Instruct",
...     messages=messages,
...     tools=tools,
...     tool_choice="auto",
...     max_tokens=500,
... )
>>> response.choices[0].message.tool_calls[0].function
ChatCompletionOutputFunctionDefinition(
    arguments={
        'location': 'San Francisco, CA',
        'format': 'fahrenheit',
        'num_days': 3
    },
    name='get_n_day_weather_forecast',
    description=None
)

Пример использования response_format:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
...     {
...         "role": "user",
...         "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?",
...     },
... ]
>>> response_format = {
...     "type": "json",
...     "value": {
...         "properties": {
...             "location": {"type": "string"},
...             "activity": {"type": "string"},
...             "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
...             "animals": {"type": "array", "items": {"type": "string"}},
...         },
...         "required": ["location", "activity", "animals_seen", "animals"],
...     },
... }
>>> response = await client.chat_completion(
...     messages=messages,
...     response_format=response_format,
...     max_tokens=500,
... )
>>> response.choices[0].message.content
'{

y": "bike ride",
": ["puppy", "cat", "raccoon"],
_seen": 3,
n": "park"}'

закрыть

< >

( )

Закройте клиент.

Этот метод вызывается автоматически при использовании клиента в качестве менеджера контекста.

document_question_answering

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonelang: str | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = Noneword_boxes: list[list[float] | str] | None = None ) → list[DocumentQuestionAnsweringOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO]) — Входное изображение для контекста. Может быть сырыми байтами, файлом изображения или URL онлайн-изображения.
  • question (str) — Вопрос, на который нужно ответить.
  • model (str, необязательный) — Модель, используемая для задачи документного вопросно-ответного взаимодействия. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для задачи документного вопросно-ответного взаимодействия. По умолчанию: None.
  • doc_stride (int, необязательный) — Если слова в документе слишком длинные, чтобы вместе с вопросом поместиться в модель, документ будет разбит на несколько фрагментов с перекрытием. Этот аргумент управляет размером перекрытия.
  • handle_impossible_answer (bool, необязательный) — Следует ли принимать «impossible» в качестве ответа
  • lang (str, необязательный) — Язык, используемый при выполнении OCR. По умолчанию — английский.
  • max_answer_len (int, необязательный) — Максимальная длина предсказанных ответов (например, учитываются только ответы с меньшей длиной).
  • max_question_len (int, необязательный) — Максимальная длина вопроса после токенизации. При необходимости будет усечена.
  • max_seq_len (int, необязательный) — Максимальная длина полного предложения (контекст + вопрос) в токенах для каждого фрагмента, передаваемого в модель. При необходимости контекст будет разбит на несколько фрагментов (с перекрытием doc_stride).
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Может вернуть меньше, чем top_k, если в контексте недостаточно вариантов.
  • word_boxes (list[Union[list[float], str, optional) — Список слов и ограничивающих прямоугольников (нормализованных 0->1000). Если указан, этап OCR пропускается, а вместо него используются предоставленные ограничивающие прямоугольники.

Возвращает

list[DocumentQuestionAnsweringOutputElement]

список элементов DocumentQuestionAnsweringOutputElement, содержащих предсказанную метку, связанную с ней вероятность, идентификаторы слов и номер страницы.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Отвечайте на вопросы по изображениям документов.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]

feature_extraction

< >

( text: str | list[str]normalize: bool | None = Noneprompt_name: str | None = Nonetruncate: bool | None = Nonetruncation_direction: typing.Optional[typing.Literal['left', 'right']] = Nonedimensions: int | None = Noneencoding_format: typing.Optional[typing.Literal['float', 'base64']] = Nonemodel: str | None = None ) → np.ndarray

Параметры

  • text (str или list[str]) — Текст или список текстов для эмбеддинга.
  • model (str, optional) — Модель, используемая для задачи извлечения признаков. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель извлечения признаков по умолчанию. По умолчанию: None.
  • normalize (bool, optional) — Нужно ли нормализовать эмбеддинги. Доступно только на сервере, работающем на базе Text-Embedding-Inference.
  • prompt_name (str, optional) — The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the Sentence Transformers configuration prompts dictionary. For example if prompt_name is “query” and the prompts is {“query”: “query: ”,…}, then the sentence “What is the capital of France?” will be encoded as “query: What is the capital of France?” because the prompt text will be prepended before any text to encode.
  • truncate (bool, optional) — Определяет, нужно ли усекать эмбеддинги. Доступно только на сервере, работающем на базе Text-Embedding-Inference.
  • truncation_direction (Literal[“left”, “right”], optional) — С какой стороны входных данных следует выполнять усечение при передаче truncate=True.
  • dimensions (int, optional) — Количество измерений, которое должны иметь результирующие выходные эмбеддинги. Доступно только для эндпоинтов эмбеддингов, совместимых с OpenAI.
  • encoding_format (Literal[“float”, “base64”], optional) — Формат выходных эмбеддингов. Допустимые значения: “float” или “base64”. Доступно только для эндпоинтов эмбеддингов, совместимых с OpenAI.

Возвращает

np.ndarray

Встраивание, представляющее входной текст(ы) в виде массива numpy с типом float32.

Исключения

[InferenceTimeoutError] или [HfHubHTTPError]

  • [InferenceTimeoutError] — Если модель недоступна или запрос завершается по таймауту.
  • [HfHubHTTPError] — Если запрос завершается ошибкой с кодом статуса HTTP, отличным от HTTP 503.

Создайте эмбеддинги для заданного текста или батча текстов.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.feature_extraction("Hi, who are you?")
array([[ 2.424802  ,  2.93384   ,  1.1750331 , ...,  1.240499, -0.13776633, -0.7889173 ],
[-0.42943227, -0.6364878 , -1.693462  , ...,  0.41978157, -2.4336355 ,  0.6162071 ],
...,
[ 0.28552425, -0.928395  , -1.2077185 , ...,  0.76810825, -2.1069427 ,  0.6236161 ]], dtype=float32)

fill_mask

< >

( text: strmodel: str | None = Nonetargets: list[str] | None = Nonetop_k: int | None = None ) → list[FillMaskOutputElement]

Параметры

  • text (str) — строка, из которой будет заполняться текст; должна содержать токен [MASK] (точное имя маски смотрите в карточке модели).
  • model (str, необязательный) — Модель, используемая для задачи fill mask. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель fill mask по умолчанию.
  • targets (list[str, optional) — Если передано, модель ограничит оценки переданными целями, вместо того чтобы искать их во всей словарной базе. Если предоставленные цели отсутствуют в словаре модели, они будут токенизированы, и будет использован первый полученный токен (с предупреждением, и это может быть медленнее).
  • top_k (int, необязательный) — Если передан, переопределяет количество возвращаемых предсказаний.

Возвращает

list[FillMaskOutputElement]

список элементов FillMaskOutputElement, содержащих предсказанную метку, связанную с ней вероятность, ссылку на токен и завершённый текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Заполните пропуск недостающим словом (точнее, токеном).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.fill_mask("The goal of life is <mask>.")
[
    FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
    FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]

get_endpoint_info

< >

( model: str | None = None ) → dict[str, Any]

Параметры

  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

dict[str, Any]

Информация об эндпоинте.

Получите информацию о развернутом конечном пункте.

Этот конечный пункт доступен только для конечных пунктов, работающих на базе Text-Generation-Inference (TGI) или Text-Embedding-Inference (TEI). Конечные пункты, работающие на базе transformers, возвращают пустой полезный груз.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> await client.get_endpoint_info()
{
    'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct',
    'model_sha': None,
    'model_dtype': 'torch.float16',
    'model_device_type': 'cuda',
    'model_pipeline_tag': None,
    'max_concurrent_requests': 128,
    'max_best_of': 2,
    'max_stop_sequences': 4,
    'max_input_length': 8191,
    'max_total_tokens': 8192,
    'waiting_served_ratio': 0.3,
    'max_batch_total_tokens': 1259392,
    'max_waiting_tokens': 20,
    'max_batch_size': None,
    'validation_workers': 32,
    'max_client_batch_size': 4,
    'version': '2.0.2',
    'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214',
    'docker_label': 'sha-dccab72'
}

health_check

< >

( model: str | None = None ) → bool

Параметры

  • model (str, необязательный) — URL точки вывода (Inference Endpoint). Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

bool

Истина, если всё работает корректно.

Проверьте состояние развернутого конечного пункта.

Health check доступен только для Inference Endpoints, работающих на базе Text-Generation-Inference (TGI) или Text-Embedding-Inference (TEI).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("https://jzgu0buei5.us-east-1.aws.endpoints.huggingface.cloud")
>>> await client.health_check()
True

image_classification

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonefunction_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = Nonetop_k: int | None = None ) → list[ImageClassificationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение для классификации. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для классификации изображений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для классификации изображений.
  • function_to_apply ("ImageClassificationOutputTransform", необязательный) — Функция, применяемая к выводам модели для получения оценок.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.

Возвращает

list[ImageClassificationOutputElement]

список элементов ImageClassificationOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию изображения на данном изображении с использованием указанной модели.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...]

image_segmentation

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonemask_threshold: float | None = Noneoverlap_mask_area_threshold: float | None = Nonesubtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = Nonethreshold: float | None = None ) → list[ImageSegmentationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение для сегментации. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для сегментации изображений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для сегментации изображений.
  • mask_threshold (float, необязательный) — Порог, используемый при преобразовании предсказанных масок в бинарные значения.
  • overlap_mask_area_threshold (float, необязательный) — Порог перекрытия масок для удаления небольших, несвязанных сегментов.
  • subtask ("ImageSegmentationSubtask", необязательный) — Задача сегментации, выполняемая в зависимости от возможностей модели.
  • threshold (float, необязательный) — Порог вероятности для отсечения предсказанных масок.

Возвращает

list[ImageSegmentationOutputElement]

Список элементов ImageSegmentationOutputElement, содержащих сегментированные маски и связанные с ними атрибуты.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните сегментацию изображения на данном изображении с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_segmentation("cat.jpg")
[ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=<PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>), ...]

image_to_image

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]prompt: str | None = Nonenegative_prompt: str | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None**kwargs ) → Image

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для перевода. Может представлять собой сырые байты, файл изображения, URL онлайн-изображения или объект PIL Image.
  • prompt (str, необязательный) — Текстовый промпт для управления генерацией изображения.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое изображение.
  • num_inference_steps (int, необязательный) — Для диффузионных моделей. Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Для диффузионных моделей. Чем выше значение guidance scale, тем сильнее модель стремится генерировать изображения, тесно связанные с текстовым запросом, в ущерб качеству изображения.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • target_size (ImageToImageTargetSize, необязательный) — Размер выходного изображения в пикселях. Этот параметр поддерживается только некоторыми провайдерами и для конкретных моделей. Если параметр не поддерживается, он будет проигнорирован.

Возвращает

Image

Переведенное изображение.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните перевод изображения в изображение с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> image = await client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
>>> image.save("tiger.jpg")

image_to_text

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → ImageToTextOutput

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации подписи. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.

Возвращает

ImageToTextOutput

Сгенерированный текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Принимает входное изображение и возвращает текст.

В зависимости от задачи (описание изображений, оптическое распознавание символов (OCR), Pix2Struct и т. д.) модели могут выдавать очень разные результаты. Ознакомьтесь с карточкой модели, чтобы узнать о её особенностях.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_to_text("cat.jpg")
'a cat standing in a grassy field '
>>> await client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
'a dog laying on the grass next to a flower pot '

image_to_video

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneprompt: str | None = Nonenegative_prompt: str | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Noneseed: int | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None**kwargs ) → bytes

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации видео. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • prompt (str, необязательный) — Текстовый промпт для управления генерацией видео.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое видео.
  • num_frames (float, необязательный) — Параметр num_frames определяет количество генерируемых кадров видео.
  • num_inference_steps (int, необязательный) — Для диффузионных моделей. Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Для диффузионных моделей. Чем выше значение guidance scale, тем сильнее модель стремится генерировать видео, тесно связанные с текстовым промптом, за счёт снижения качества изображения.
  • seed (int, необязательный) — Значение seed, используемое для генерации видео.
  • target_size (ImageToVideoTargetSize, необязательный) — Размер кадров выходного видео в пикселях.
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к более высокому качеству видео, но за счёт более медленного вывода.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.

Возвращает

bytes

Сгенерированное видео.

Сгенерируйте видео из входного изображения.

Примеры:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> video = await client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger")
>>> with open("tiger.mp4", "wb") as f:
...     f.write(video)

object_detection

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonethreshold: float | None = None ) → list[ObjectDetectionOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Изображение, на котором необходимо обнаружить объекты. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или объектом PIL Image.
  • model (str, необязательный) — Модель, используемая для обнаружения объектов. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для обнаружения объектов (DETR).
  • threshold (float, необязательный) — Вероятность, необходимая для принятия предсказания.

Возвращает

list[ObjectDetectionOutputElement]

Список элементов ObjectDetectionOutputElement, содержащих ограничивающие прямоугольники и связанные с ними атрибуты.

Исключения

InferenceTimeoutError или HfHubHTTPError или ValueError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.
  • ValueError — Если результат запроса не является List.

Выполните обнаружение объектов на указанном изображении с помощью заданной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.object_detection("people.jpg")
[ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...]

question_answering

< >

( question: strcontext: strmodel: str | None = Nonealign_to_words: bool | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = None ) → Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]

Параметры

  • question (str) — Вопрос, на который нужно ответить.
  • context (str) — Контекст вопроса.
  • model (str) — Модель, используемая для задачи ответа на вопросы. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint.
  • align_to_words (bool, необязательный) — Пытается выровнять ответ по реальным словам. Улучшает качество для языков с разделением слов пробелами. Может ухудшить результат для языков без пробельного разделения (например, японского или китайского)
  • doc_stride (int, необязательный) — Если контекст слишком длинный, чтобы вместе с вопросом поместиться в модель, он будет разбит на несколько фрагментов с некоторым перекрытием. Этот аргумент управляет размером этого перекрытия.
  • handle_impossible_answer (bool, необязательный) — Следует ли принимать «impossible» в качестве ответа.
  • max_answer_len (int, необязательный) — Максимальная длина предсказанных ответов (например, учитываются только ответы с меньшей длиной).
  • max_question_len (int, необязательный) — Максимальная длина вопроса после токенизации. При необходимости будет усечена.
  • max_seq_len (int, необязательный) — Максимальная длина полного предложения (контекст + вопрос) в токенах для каждого фрагмента, передаваемого в модель. При необходимости контекст будет разбит на несколько фрагментов (с перекрытием docStride).
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Обратите внимание, что если в контексте недостаточно вариантов, будет возвращено меньше, чем top_k ответов.

Возвращает

Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]

When top_k is 1 or not provided, it returns a single QuestionAnsweringOutputElement. When top_k is greater than 1, it returns a list of QuestionAnsweringOutputElement.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Получите ответ на вопрос из заданного текста.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.")
QuestionAnsweringOutputElement(answer='Clara', end=16, score=0.9326565265655518, start=11)

sentence_similarity

< >

( sentence: strother_sentences: listmodel: str | None = None ) → list[float]

Параметры

  • sentence (str) — Основное предложение, с которым сравниваются остальные.
  • other_sentences (list[str]) — Список предложений для сравнения.
  • model (str, необязательный) — Модель, используемая для задачи определения сходства предложений. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для задачи определения сходства предложений. По умолчанию: None.

Возвращает

list[float]

Встраивание, представляющее входной текст.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Вычислите семантическое сходство между предложением и списком других предложений, сравнив их эмбеддинги.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.sentence_similarity(
...     "Machine learning is so easy.",
...     other_sentences=[
...         "Deep learning is so straightforward.",
...         "This is so difficult, like rocket science.",
...         "I can't believe how much I struggled with this.",
...     ],
... )
[0.7785726189613342, 0.45876261591911316, 0.2906220555305481]

суммаризация

< >

( text: strmodel: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonegenerate_parameters: dict[str, typing.Any] | None = Nonetruncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None ) → SummarizationOutput

Параметры

  • text (str) — Входной текст для суммаризации.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель по умолчанию, рекомендуемая для суммаризации.
  • clean_up_tokenization_spaces (bool, необязательный) — Определяет, следует ли удалять возможные лишние пробелы в текстовом выводе.
  • generate_parameters (dict[str, Any], необязательный) — Дополнительная параметризация алгоритма генерации текста.
  • truncation ("SummarizationTruncationStrategy", необязательный) — Стратегия усечения, которую следует использовать.

Возвращает

SummarizationOutput

Сгенерированный текст резюме.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Сгенерируйте краткое содержание заданного текста с использованием указанной модели.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.summarization("The Eiffel tower...")
SummarizationOutput(generated_text="The Eiffel tower is one of the most famous landmarks in the world....")

table_question_answering

< >

( table: dictquery: strmodel: str | None = Nonepadding: typing.Optional[ForwardRef('Padding')] = Nonesequential: bool | None = Nonetruncation: bool | None = None ) → TableQuestionAnsweringOutputElement

Параметры

  • table (str) — Таблица данных, представленная в виде словаря списков, где ключи — это заголовки, а списки — все значения; все списки должны иметь одинаковую длину.
  • query (str) — Запрос в обычном тексте, который вы хотите задать таблице.
  • model (str) — Модель, используемая для задачи table-question-answering. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint.
  • padding ("Padding", необязательный) — Включает и управляет выравниванием.
  • sequential (bool, необязательный) — Выполнять ли вывод последовательно или батчами. Батчинг быстрее, но модели вроде SQA требуют последовательного выполнения вывода для извлечения связей внутри последовательностей, учитывая их диалоговый характер.
  • truncation (bool, необязательный) — Включает и управляет усечением.

Возвращает

TableQuestionAnsweringOutputElement

вывод задачи по ответам на вопросы по таблице, содержащий ответ, координаты, ячейки и используемый агрегатор.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Получите ответ на вопрос из информации, представленной в таблице.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> query = "How many stars does the transformers repository have?"
>>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
>>> await client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE')

tabular_classification

< >

( table: dictmodel: str | None = None ) → List

Параметры

  • table (dict[str, Any]) — Набор атрибутов для классификации.
  • model (str, необязательный) — Модель, используемая для задачи табличной классификации. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель табличной классификации по умолчанию. По умолчанию: None.

Возвращает

List

список меток, по одной на каждую строку в исходной таблице.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Классификация целевой категории (группы) на основе набора атрибутов.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> table = {
...     "fixed_acidity": ["7.4", "7.8", "10.3"],
...     "volatile_acidity": ["0.7", "0.88", "0.32"],
...     "citric_acid": ["0", "0", "0.45"],
...     "residual_sugar": ["1.9", "2.6", "6.4"],
...     "chlorides": ["0.076", "0.098", "0.073"],
...     "free_sulfur_dioxide": ["11", "25", "5"],
...     "total_sulfur_dioxide": ["34", "67", "13"],
...     "density": ["0.9978", "0.9968", "0.9976"],
...     "pH": ["3.51", "3.2", "3.23"],
...     "sulphates": ["0.56", "0.68", "0.82"],
...     "alcohol": ["9.4", "9.8", "12.6"],
... }
>>> await client.tabular_classification(table=table, model="julien-c/wine-quality")
["5", "5", "5"]

tabular_regression

< >

( table: dictmodel: str | None = None ) → List

Параметры

  • table (dict[str, Any]) — Набор атрибутов, хранящихся в таблице. Атрибуты, используемые для предсказания целевой переменной, могут быть как числовыми, так и категориальными.
  • model (str, необязательный) — Модель, используемая для задачи табличной регрессии. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель табличной регрессии по умолчанию. По умолчанию: None.

Возвращает

List

список предсказанных числовых значений целевой переменной.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Предсказание числового целевого значения по набору атрибутов/признаков в таблице.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> table = {
...     "Height": ["11.52", "12.48", "12.3778"],
...     "Length1": ["23.2", "24", "23.9"],
...     "Length2": ["25.4", "26.3", "26.5"],
...     "Length3": ["30", "31.2", "31.1"],
...     "Species": ["Bream", "Bream", "Bream"],
...     "Width": ["4.02", "4.3056", "4.6961"],
... }
>>> await client.tabular_regression(table, model="scikit-learn/Fish-Weight")
[110, 120, 130]

text_classification

< >

( text: strmodel: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None ) → list[TextClassificationOutputElement]

Параметры

  • text (str) — Строка для классификации.
  • model (str, необязательный) — Модель, используемая для задачи классификации текста. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель классификации текста по умолчанию. По умолчанию: None.
  • top_k (int, необязательный) — Если указано, ограничивает вывод K наиболее вероятными классами.
  • function_to_apply ("TextClassificationOutputTransform", необязательный) — Функция, применяемая к выводам модели для получения оценок.

Возвращает

list[TextClassificationOutputElement]

список элементов TextClassificationOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию текста (например, анализ тональности) для заданного текста.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.text_classification("I like you")
[
    TextClassificationOutputElement(label='POSITIVE', score=0.9998695850372314),
    TextClassificationOutputElement(label='NEGATIVE', score=0.0001304351753788069),
]

text_generation

< >

( prompt: strdetails: bool | None = Nonestream: bool | None = Nonemodel: str | None = Noneadapter_id: str | None = Nonebest_of: int | None = Nonedecoder_input_details: bool | None = Nonedo_sample: bool | None = Nonefrequency_penalty: float | None = Nonegrammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = Nonemax_new_tokens: int | None = Nonerepetition_penalty: float | None = Nonereturn_full_text: bool | None = Noneseed: int | None = Nonestop: list[str] | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_n_tokens: int | None = Nonetop_p: float | None = Nonetruncate: int | None = Nonetypical_p: float | None = Nonewatermark: bool | None = None ) → Union[str, TextGenerationOutput, AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]

Параметры

  • prompt (str) — Входной текст.
  • details (bool, необязательный) — По умолчанию text_generation возвращает строку. Передайте details=True, если вам нужен подробный вывод (токены, вероятности, seed, причина завершения и т. д.). Доступно только для моделей, работающих с бэкендом text-generation-inference.
  • stream (bool, необязательный) — По умолчанию text_generation возвращает весь сгенерированный текст. Передайте stream=True, если вы хотите получить поток токенов. Доступно только для моделей, работающих с бэкендом text-generation-inference.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. По умолчанию — None.
  • adapter_id (str, необязательный) — Идентификатор адаптера Lora.
  • best_of (int, необязательный) — Сгенерировать best_of последовательностей и вернуть ту, у которой максимальные logprobs токенов.
  • decoder_input_details (bool, необязательный) — Возвращает logprobs и идентификаторы токенов входных данных декодера. Для того чтобы этот параметр учитывался, необходимо также установить details=True. По умолчанию False.
  • do_sample (bool, необязательный) — Включает выборку из логитов
  • frequency_penalty (float, необязательный) — Число от -2.0 до 2.0. Положительные значения штрафуют новые токены в зависимости от их частоты в тексте на данный момент, снижая вероятность того, что модель дословно повторит одну и ту же строку.
  • grammar (TextGenerationInputGrammarType, optional) — Ограничения грамматики. Может быть JSONSchema или регулярным выражением.
  • max_new_tokens (int, необязательный) — Максимальное количество генерируемых токенов. По умолчанию — 100.
  • repetition_penalty (float, необязательный) — Параметр штрафного коэффициента за повторения. Значение 1.0 означает отсутствие штрафа. Подробнее см. в этой статье.
  • return_full_text (bool, необязательный) — Следует ли добавлять промпт перед сгенерированным текстом
  • seed (int, необязательный) — Сид для случайной выборки
  • stop (list[str], необязательный) — Остановить генерацию токенов, если был сгенерирован элемент из stop.
  • temperature (float, необязательный) — Значение, используемое для модулирования распределения логитов.
  • top_n_tokens (int, необязательный) — Возвращает информацию о top_n_tokens наиболее вероятных токенах на каждом шаге генерации, а не только о сэмплированном токене.
  • top_k (int, *optional`) — Количество токенов словаря с наивысшей вероятностью, которые следует сохранить для фильтрации top-k.
  • top_p (float, *optional) -- If set to < 1, only the smallest set of most probable tokens with probabilities that add up to top_p` or higher are kept for generation.
  • truncate (int, *optional`) — Обрезает входные токены до указанного размера.
  • typical_p (float, *optional`) — Масса Typical Decoding Подробнее см. Typical Decoding for Natural Language Generation
  • watermark (bool, optional) — Watermarking with A Watermark for Large Language Models

Возвращает

Union[str, TextGenerationOutput, AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]

Сгенерированный текст, возвращенный с сервера:

  • если stream=False и details=False, сгенерированный текст возвращается как str (по умолчанию)
  • Если stream=True и details=False, сгенерированный текст возвращается по одному токену в виде AsyncIterable[str]
  • если stream=False и details=True, сгенерированный текст возвращается с дополнительными деталями в виде объекта TextGenerationOutput
  • Если details=True и stream=True, сгенерированный текст возвращается по одному токену в виде итерируемого объекта TextGenerationStreamOutput

Исключения

ValidationError или InferenceTimeoutError или HfHubHTTPError

  • ValidationError — Если входные значения недействительны. HTTP-запрос к серверу не выполняется.
  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

По заданному промпту сгенерируйте следующий текст.

Если вы хотите сгенерировать ответ на основе сообщений чата, используйте метод InferenceClient.chat_completion(). Он принимает список сообщений вместо одиночного текстового запроса и самостоятельно обрабатывает шаблонизацию чата.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

# Case 1: generate text
>>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
'100% open source and built to be easy to use.'

# Case 2: iterate over the generated tokens. Useful for large generation.
>>> async for token in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
...     print(token)
100
%
open
source
and
built
to
be
easy
to
use
.

# Case 3: get more details about the generation process.
>>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
TextGenerationOutput(
    generated_text='100% open source and built to be easy to use.',
    details=TextGenerationDetails(
        finish_reason='length',
        generated_tokens=12,
        seed=None,
        prefill=[
            TextGenerationPrefillOutputToken(id=487, text='The', logprob=None),
            TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875),
            (...)
            TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625)
        ],
        tokens=[
            TokenElement(id=1425, text='100', logprob=-1.0175781, special=False),
            TokenElement(id=16, text='%', logprob=-0.0463562, special=False),
            (...)
            TokenElement(id=25, text='.', logprob=-0.5703125, special=False)
        ],
        best_of_sequences=None
    )
)

# Case 4: iterate over the generated tokens with more details.
# Last object is more complete, containing the full generated text and the finish reason.
>>> async for details in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
...     print(details)
...
TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(
    id=25,
    text='.',
    logprob=-0.5703125,
    special=False),
    generated_text='100% open source and built to be easy to use.',
    details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None)
)

# Case 5: generate constrained output using grammar
>>> response = await client.text_generation(
...     prompt="I saw a puppy a cat and a raccoon during my bike ride in the park",
...     model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1",
...     max_new_tokens=100,
...     repetition_penalty=1.3,
...     grammar={
...         "type": "json",
...         "value": {
...             "properties": {
...                 "location": {"type": "string"},
...                 "activity": {"type": "string"},
...                 "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
...                 "animals": {"type": "array", "items": {"type": "string"}},
...             },
...             "required": ["location", "activity", "animals_seen", "animals"],
...         },
...     },
... )
>>> json.loads(response)
{
    "activity": "bike riding",
    "animals": ["puppy", "cat", "raccoon"],
    "animals_seen": 3,
    "location": "park"
}

text_to_image

< >

( prompt: strnegative_prompt: str | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonescheduler: str | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → Image

Параметры

  • prompt (str) — Промпт для генерации изображения.
  • negative_prompt (str, необязательный) — Одно промпт-описание, указывающее, что НЕ включать в генерируемое изображение.
  • height (int, необязательный) — Высота выходного изображения в пикселях
  • width (int, необязательный) — Ширина выходного изображения в пикселях
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.
  • guidance_scale (float, необязательный) — Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым запросом, однако слишком высокие значения могут привести к насыщению и другим артефактам.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-image по умолчанию. По умолчанию: None.
  • scheduler (str, необязательный) — Заменить планировщик на совместимый.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

Image

Сгенерированное изображение.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Сгенерируйте изображение на основе заданного текста с использованием указанной модели.

Для работы с изображениями необходимо установить PIL (pip install Pillow).

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

>>> image = await client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

>>> image = await client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     negative_prompt="low resolution, blurry",
...     model="stabilityai/stable-diffusion-2-1",
... )
>>> image.save("better_astronaut.png")
Example using a third-party provider directly. Usage will be billed on your fal.ai account. 
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="fal-ai",  # Use fal.ai provider
...     api_key="fal-ai-api-key",  # Pass your fal.ai API key
... )
>>> image = client.text_to_image(
...     "A majestic lion in a fantasy forest",
...     model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     model="black-forest-labs/FLUX.1-dev",
... )
>>> image.save("astronaut.png")

Пример использования провайдера Replicate с дополнительными параметрами

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     model="black-forest-labs/FLUX.1-schnell",
...     extra_body={"output_quality": 100},
... )
>>> image.save("astronaut.png")

text_to_speech

< >

( text: strmodel: str | None = Nonedo_sample: bool | None = Noneearly_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = Noneepsilon_cutoff: float | None = Noneeta_cutoff: float | None = Nonemax_length: int | None = Nonemax_new_tokens: int | None = Nonemin_length: int | None = Nonemin_new_tokens: int | None = Nonenum_beam_groups: int | None = Nonenum_beams: int | None = Nonepenalty_alpha: float | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_p: float | None = Nonetypical_p: float | None = Noneuse_cache: bool | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes

Параметры

  • text (str) — Текст для синтеза.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-speech по умолчанию. По умолчанию: None.
  • do_sample (bool, необязательный) — Использовать ли выборку вместо жадного декодирования при генерации новых токенов.
  • early_stopping (Union[bool, "TextToSpeechEarlyStoppingEnum"], необязательный) — Управляет условием остановки для методов на основе beam search.
  • epsilon_cutoff (float, необязательный) — Если установлено значение float, строго находящееся между 0 и 1, будут выбораться только токены с условной вероятностью, превышающей epsilon_cutoff. В статье рекомендуемые значения варьируются от 3e-4 до 9e-4 в зависимости от размера модели. Подробнее см. Truncation Sampling as Language Model Desmoothing.
  • eta_cutoff (float, необязательный) — Сэмплинг Eta — это гибрид локально-типичного сэмплинга и epsilon-сэмплинга. Если значение установлено как float строго между 0 и 1, токен рассматривается только в том случае, если он больше либо eta_cutoff, либо sqrt(eta_cutoff)
    • exp(-entropy(softmax(next_token_logits))). Последний член интуитивно представляет собой ожидаемую вероятность следующего токена, масштабированную на sqrt(eta_cutoff). В статье рекомендуемые значения варьируются от 3e-4 до 2e-3 в зависимости от размера модели. Подробнее см. в Truncation Sampling as Language Model Desmoothing.
  • max_length (int, необязательный) — Максимальная длина (в токенах) генерируемого текста, включая входные данные.
  • max_new_tokens (int, необязательный) — Максимальное количество токенов для генерации. Имеет приоритет над max_length.
  • min_length (int, необязательный) — Минимальная длина (в токенах) генерируемого текста, включая входные данные.
  • min_new_tokens (int, необязательный) — Минимальное количество токенов для генерации. Имеет приоритет над min_length.
  • num_beam_groups (int, необязательный) — Количество групп, на которые следует разделить num_beams, чтобы обеспечить разнообразие между различными группами лучей. Подробнее см. в этой статье.
  • num_beams (int, необязательный) — Количество лучей, используемых для beam search.
  • penalty_alpha (float, необязательный) — Значение, балансирующее уверенность модели и штраф за дегенерацию при декодировании с контрастным поиском.
  • temperature (float, необязательный) — Значение, используемое для модуляции вероятностей следующего токена.
  • top_k (int, необязательный) — Количество токенов словаря с наивысшей вероятностью, которые следует сохранить для фильтрации top-k.
  • top_p (float, необязательный) — Если установлено значение float < 1, для генерации сохраняются только наименьшее множество наиболее вероятных токенов, сумма вероятностей которых равна top_p или больше.
  • typical_p (float, необязательный) — Локальная типичность измеряет, насколько условная вероятность предсказания целевого токена следующим близка к ожидаемой условной вероятности предсказания случайного токена следующим, с учётом уже сгенерированного частичного текста. Если установлено значение float < 1, для генерации сохраняются наименьшие множества наиболее локально типичных токенов, вероятности которых в сумме составляют typical_p или выше. Подробнее см. эту статью.
  • use_cache (bool, необязательный) — Должна ли модель использовать прошлые ключи/значения внимания для ускорения декодирования
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

bytes

Сгенерированный аудиофайл.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Синтезируйте аудио с голосом, произносящим заданный текст.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

# Must be run in an async context
>>> from pathlib import Path
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

>>> audio = await client.text_to_speech("Hello world")
>>> Path("hello_world.flac").write_bytes(audio)

Пример использования стороннего провайдера напрямую. Использование будет тарифицироваться на вашем аккаунте Replicate.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",
...     api_key="your-replicate-api-key",  # Pass your Replicate API key directly
... )
>>> audio = client.text_to_speech(
...     text="Hello world",
...     model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",
...     api_key="hf_...",  # Pass your HF token
... )
>>> audio =client.text_to_speech(
...     text="Hello world",
...     model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)
Example using Replicate provider with extra parameters 
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Use replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> audio = client.text_to_speech(
...     "Hello, my name is Kororo, an awesome text-to-speech model.",
...     model="hexgrad/Kokoro-82M",
...     extra_body={"voice": "af_nicole"},
... )
>>> Path("hello.flac").write_bytes(audio)

Пример генерации музыки с использованием «YuE-s1-7B-anneal-en-cot» на fal.ai

>>> from huggingface_hub import InferenceClient
>>> lyrics = '''
... [verse]
... In the town where I was born
... Lived a man who sailed to sea
... And he told us of his life
... In the land of submarines
... So we sailed on to the sun
... 'Til we found a sea of green
... And we lived beneath the waves
... In our yellow submarine

... [chorus]
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... '''
>>> genres = "pavarotti-style tenor voice"
>>> client = InferenceClient(
...     provider="fal-ai",
...     model="m-a-p/YuE-s1-7B-anneal-en-cot",
...     api_key=...,
... )
>>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres})
>>> with open("output.mp3", "wb") as f:
...     f.write(audio)

text_to_video

< >

( prompt: strmodel: str | None = Noneguidance_scale: float | None = Nonenegative_prompt: list[str] | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes

Параметры

  • prompt (str) — Промпт для генерации видео.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель text-to-video по умолчанию. По умолчанию: None.
  • guidance_scale (float, необязательный) — Более высокое значение guidance scale побуждает модель генерировать видео, тесно связанные с текстовым запросом, однако слишком высокие значения могут привести к насыщению и другим артефактам.
  • negative_prompt (list[str], необязательный) — Одно или несколько промптов, указывающих, что НЕ включать в генерируемое видео.
  • num_frames (float, необязательный) — Параметр num_frames определяет количество генерируемых кадров видео.
  • num_inference_steps (int, необязательный) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к более высокому качеству видео, но за счёт более медленного вывода.
  • seed (int, необязательный) — Начальное значение для генератора случайных чисел.
  • extra_body (dict[str, Any], необязательный) — Дополнительные параметры, специфичные для провайдера, которые передаются модели. См. документацию провайдера для списка поддерживаемых параметров.

Возвращает

bytes

Сгенерированное видео.

Сгенерируйте видео на основе заданного текста.

Вы можете передать параметры, специфичные для провайдера, в модель, используя аргумент extra_body.

Пример:

Пример использования стороннего провайдера напрямую. Оплата за использование будет списана с вашего аккаунта fal.ai.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="fal-ai",  # Using fal.ai provider
...     api_key="fal-ai-api-key",  # Pass your fal.ai API key
... )
>>> video = client.text_to_video(
...     "A majestic lion running in a fantasy forest",
...     model="tencent/HunyuanVideo",
... )
>>> with open("lion.mp4", "wb") as file:
...     file.write(video)

Пример использования стороннего провайдера через Hugging Face Routing. Использование будет тарифицироваться на вашем аккаунте Hugging Face.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
...     provider="replicate",  # Using replicate provider
...     api_key="hf_...",  # Pass your HF token
... )
>>> video = client.text_to_video(
...     "A cat running in a park",
...     model="genmo/mochi-1-preview",
... )
>>> with open("cat.mp4", "wb") as file:
...     file.write(video)

token_classification

< >

( text: strmodel: str | None = Noneaggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = Noneignore_labels: list[str] | None = Nonestride: int | None = None ) → list[TokenClassificationOutputElement]

Параметры

  • text (str) — Строка для классификации.
  • model (str, необязательный) — Модель, используемая для задачи классификации токенов. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель классификации токенов по умолчанию. По умолчанию: None.
  • aggregation_strategy ("TokenClassificationAggregationStrategy", необязательный) — Стратегия, используемая для объединения токенов на основе предсказаний модели
  • ignore_labels (list[str, необязательный) — Список меток, которые следует игнорировать
  • stride (int, необязательный) — Количество перекрывающихся токенов между фрагментами при разбиении входного текста.

Возвращает

list[TokenClassificationOutputElement]

Список элементов TokenClassificationOutputElement, содержащих группу сущности, оценку уверенности, слово, начальный и конечный индексы.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Выполните классификацию токенов в заданном тексте. Обычно используется для разбора предложений, грамматического или распознавания именованных сущностей (NER), чтобы понять ключевые слова, содержащиеся в тексте.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
    TokenClassificationOutputElement(
        entity_group='PER',
        score=0.9971321225166321,
        word='Sarah Jessica Parker',
        start=11,
        end=31,
    ),
    TokenClassificationOutputElement(
        entity_group='PER',
        score=0.9773476123809814,
        word='Jessica',
        start=52,
        end=59,
    )
]

перевод

< >

( text: strmodel: str | None = Nonesrc_lang: str | None = Nonetgt_lang: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonetruncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = Nonegenerate_parameters: dict[str, typing.Any] | None = None ) → TranslationOutput

Параметры

  • text (str) — Строка для перевода.
  • model (str, необязательный) — Модель, используемая для задачи перевода. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель перевода по умолчанию. По умолчанию: None.
  • src_lang (str, необязательный) — Исходный язык текста. Обязателен для моделей, способных переводить с нескольких языков.
  • tgt_lang (str, необязательный) — Целевой язык перевода. Обязателен для моделей, способных переводить на несколько языков.
  • clean_up_tokenization_spaces (bool, необязательный) — Определяет, следует ли удалять возможные лишние пробелы в текстовом выводе.
  • truncation ("TranslationTruncationStrategy", необязательный) — Стратегия усечения, которую следует использовать.
  • generate_parameters (dict[str, Any], необязательный) — Дополнительная параметризация алгоритма генерации текста.

Возвращает

TranslationOutput

Сгенерированный переведенный текст.

Исключения

InferenceTimeoutError или HfHubHTTPError или ValueError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.
  • ValueError — если задан только один из аргументов src_lang и tgt_lang.

Перевод текста с одного языка на другой.

Подробнее о том, как выбрать лучшую модель для вашей конкретной задачи, можно узнать на https://huggingface.co/tasks/translation. Исходный и целевой языки обычно зависят от модели. Однако для некоторых моделей можно указать исходный и целевой языки. Если вы работаете с одной из таких моделей, вы можете использовать аргументы src_lang и tgt_lang, чтобы передать соответствующую информацию.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.translation("My name is Wolfgang and I live in Berlin")
'Mein Name ist Wolfgang und ich lebe in Berlin.'
>>> await client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.')

Указание языков:

>>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX")
"Mon nom est Sarah Jessica Parker mais vous pouvez m'appeler Jessica"

visual_question_answering

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonetop_k: int | None = None ) → list[VisualQuestionAnsweringOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для контекста. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • question (str) — Вопрос, на который нужно ответить.
  • model (str, необязательный) — Модель, используемая для задачи визуального ответа на вопросы. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Если не указано, будет использована модель визуального ответа на вопросы по умолчанию. По умолчанию: None.
  • top_k (int, необязательный) — Количество возвращаемых ответов (выбираются по убыванию вероятности). Обратите внимание, что если в контексте недостаточно вариантов, будет возвращено меньше, чем top_k ответов.

Возвращает

list[VisualQuestionAnsweringOutputElement]

список элементов VisualQuestionAnsweringOutputElement, содержащих предсказанную метку и связанную с ней вероятность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Ответы на открытые вопросы на основе изображения.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.visual_question_answering(
...     image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
...     question="What is the animal doing?"
... )
[
    VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'),
    VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'),
]

zero_shot_classification

< >

( text: strcandidate_labels: listmulti_label: bool | None = Falsehypothesis_template: str | None = Nonemodel: str | None = None ) → list[ZeroShotClassificationOutputElement]

Параметры

  • text (str) — Входной текст для классификации.
  • candidate_labels (list[str]) — Набор возможных меток классов, в которые классифицируется текст.
  • multi_label (bool, необязательный) — Указывает, может ли быть истинным несколько меток из числа кандидатов. Если значение равно false, оценки нормализуются так, чтобы сумма вероятностей меток для каждой последовательности была равна 1. Если значение равно true, метки считаются независимыми, а вероятности нормализуются для каждого кандидата.
  • hypothesis_template (str, необязательный) — Предложение, используемое вместе с candidate_labels для попытки классификации текста путём замены плейсхолдера на метки-кандидаты.
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. Если не указан, будет использована модель классификации zero-shot по умолчанию.

Возвращает

list[ZeroShotClassificationOutputElement]

Список элементов ZeroShotClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

В качестве входных данных предоставьте текст и набор кандидатов для классификации входного текста.

Пример с multi_label=False:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> text = (
...     "A new model offers an explanation for how the Galilean satellites formed around the solar system's"
...     "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
...     " mysteries when he went for a run up a hill in Nice, France."
... )
>>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
>>> await client.zero_shot_classification(text, labels)
[
    ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684),
    ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566),
    ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627),
    ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581),
    ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447),
]
>>> await client.zero_shot_classification(text, labels, multi_label=True)
[
    ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311),
    ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844),
    ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714),
    ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327),
    ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
]

Пример с multi_label=True и пользовательским hypothesis_template:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.zero_shot_classification(
...    text="I really like our dinner and I'm very happy. I don't like the weather though.",
...    candidate_labels=["positive", "negative", "pessimistic", "optimistic"],
...    multi_label=True,
...    hypothesis_template="This text is {} towards the weather"
... )
[
    ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
    ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
    ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
    ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
]

zero_shot_image_classification

< >

( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]candidate_labels: listmodel: str | None = Nonehypothesis_template: str | None = None ) → list[ZeroShotImageClassificationOutputElement]

Параметры

  • image (Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — Входное изображение для генерации подписи. Может быть сырыми байтами, файлом изображения, URL онлайн-изображения или изображением PIL.
  • candidate_labels (list[str]) — Кандидатские метки для этого изображения
  • model (str, необязательный) — Модель, используемая для инференса. Может быть идентификатором модели, размещённой на Hugging Face Hub, или URL-адресом развернутого Inference Endpoint. Этот параметр переопределяет модель, определённую на уровне экземпляра. Если не указан, будет использована модель по умолчанию для классификации изображений в режиме zero-shot.
  • hypothesis_template (str, необязательный) — Предложение, используемое вместе с candidate_labels для попытки классификации изображения путём замены плейсхолдера на метки-кандидаты.

Возвращает

list[ZeroShotImageClassificationOutputElement]

Список элементов ZeroShotImageClassificationOutputElement, содержащих предсказанные метки и их уверенность.

Исключения

InferenceTimeoutError или HfHubHTTPError

  • InferenceTimeoutError — Если модель недоступна или запрос завершается по таймауту.
  • HfHubHTTPError — Если запрос завершается ошибкой с кодом состояния HTTP, отличным от HTTP 503.

Предоставьте входное изображение и текстовые метки, чтобы предсказать текстовые метки для изображения.

Пример:

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

>>> await client.zero_shot_image_classification(
...     "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
...     candidate_labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]

InferenceTimeoutError

класс huggingface_hub.InferenceTimeoutError

< >

( message: str )

Ошибка, возникающая, когда модель недоступна или запрос завершается по таймауту.

Update on GitHub

←Типы инференса Точки вывода→