Hub Python 库文档

推理

Hub Python 库

加入 Hugging Face 社区

并获取增强的文档体验

协作处理模型、数据集和 Spaces

通过加速推理获得更快的示例

切换文档主题

开始使用

推理

推理是使用训练好的模型对新数据进行预测的过程。由于此过程可能需要大量计算，因此在专用服务器上运行可能是一个有趣的选择。huggingface_hub 库提供了一种简单的方法来调用为托管模型运行推理的服务。您可以连接到以下几种服务

Inference API：一项服务，允许您在 Hugging Face 的基础设施上免费运行加速推理。此服务是快速入门、测试不同模型和构建 AI 产品原型的快捷方式。
Inference Endpoints：一种产品，可轻松将模型部署到生产环境。推理由 Hugging Face 在您选择的云提供商的专用、完全托管的基础设施中运行。

这些服务可以使用 InferenceClient 对象调用。有关如何使用它的更多信息，请参阅本指南。

Inference Client

class huggingface_hub.InferenceClient

( model: Optional = None token: Union = None timeout: Optional = None headers: Optional = None cookies: Optional = None proxies: Optional = None base_url: Optional = None api_key: Optional = None )

参数

model (str, optional) — 要运行推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，例如 meta-llama/Meta-Llama-3-8B-Instruct，也可以是已部署 Inference Endpoint 的 URL。默认为 None，在这种情况下，将为任务自动选择推荐的模型。注意：为了更好地与 OpenAI 的客户端兼容，model 已被别名为 base_url。这两个参数互斥。如果为聊天完成使用 base_url，则 /chat/completions 后缀路径将附加到基本 URL（有关详细信息，请参阅 TGI Messages API 文档）。当传递 URL 作为 model 时，客户端不会向其附加任何后缀路径。
token (str 或 bool, 可选) — Hugging Face 令牌。如果未提供，则默认为本地保存的令牌。如果您不想将令牌发送到服务器，请传递 token=False。注意：为了更好地与 OpenAI 的客户端兼容，token 已被别名为 api_key。这两个参数互斥且行为完全相同。
timeout (float, optional) — 等待服务器响应的最长秒数。在 Inference API 中加载新模型可能需要几分钟。默认为 None，表示它将循环直到服务器可用。
headers (Dict[str, str], optional) — 要发送到服务器的其他标头。默认情况下，仅发送授权和用户代理标头。此字典中的值将覆盖默认值。
cookies (Dict[str, str], optional) — 要发送到服务器的其他 Cookie。
proxies (Any, optional) — 请求要使用的代理。
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 或自托管 Inference Endpoints 无缝使用。

音频分类

( audio: Union model: Optional = None top_k: Optional = None function_to_apply: Optional = None ) → List[AudioClassificationOutputElement]

参数

audio (Union[str, Path, bytes, BinaryIO]) — 要分类的音频内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 用于音频分类的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署 Inference Endpoint 的 URL。如果未提供，将使用音频分类的默认推荐模型。
top_k (int, 可选) — 指定后，将输出限制为前 K 个最可能的类别。
function_to_apply ("AudioClassificationOutputTransform", 可选) — 要应用于输出的函数。

返回

List[AudioClassificationOutputElement]

包含预测标签及其置信度的 AudioClassificationOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union model: Optional = None ) → List[AudioToAudioOutputElement]

参数

audio (Union[str, Path, bytes, BinaryIO]) — 模型的音频内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 模型可以是任何接收音频文件并返回另一个音频文件的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用 audio_to_audio 的默认推荐模型。

返回

List[AudioToAudioOutputElement]

包含音频标签、content-type 和 blob 格式音频内容的 AudioToAudioOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union model: Optional = None ) → AutomaticSpeechRecognitionOutput

参数

audio (Union[str, Path, bytes, BinaryIO]) — 要转录的内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 用于 ASR 的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用 ASR 的默认推荐模型。

返回

AutomaticSpeechRecognitionOutput

包含转录文本以及可选的时间戳块的项目。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

对给定的音频内容执行自动语音识别（ASR 或音频到文本）。

示例

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

chat_completion

( messages: List model: Optional = None stream: bool = False frequency_penalty: Optional = None logit_bias: Optional = None logprobs: Optional = None max_tokens: Optional = None n: Optional = None presence_penalty: Optional = None response_format: Optional = None seed: Optional = None stop: Optional = None stream_options: Optional = None temperature: Optional = None tool_choice: Union = None tool_prompt: Optional = None tools: Optional = None top_logprobs: Optional = None top_p: Optional = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput

参数

messages (ChatCompletionInputMessage 列表) — 对话历史记录，包含角色和内容对。
model (str, 可选) — 用于聊天完成的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用基于聊天的文本生成的默认推荐模型。有关更多详细信息，请参阅 https://huggingface.co/tasks/text-generation。

如果 model 是模型 ID，则会将其作为 model 参数传递给服务器。如果你想在请求有效负载中设置 model 的同时定义自定义 URL，则必须在初始化 InferenceClient 时设置 base_url。
frequency_penalty (float, 可选) — 根据到目前为止文本中已存在的频率来惩罚新 token。范围：[-2.0, 2.0]。默认为 0.0。
logit_bias (List[float], 可选) — 修改完成中指定 token 出现的可能性。接受一个 JSON 对象，该对象将 token（由 tokenizer 中的 token ID 指定）映射到关联的偏差值，范围为 -100 到 100。从数学上讲，偏差被添加到模型在采样之前生成的 logits 中。确切的效果会因模型而异，但 -1 到 1 之间的值应降低或增加选择的可能性；像 -100 或 100 这样的值应导致禁止或独占选择相关 token。默认为 None。
logprobs (bool, 可选) — 是否返回输出 token 的对数概率。如果为 true，则返回消息内容中返回的每个输出 token 的对数概率。
max_tokens (int, 可选) — 响应中允许的最大 token 数。默认为 20。
n (int, 可选) — 未使用。
presence_penalty (float, 可选) — 介于 -2.0 和 2.0 之间的数字。正值会根据新 token 是否出现在到目前为止的文本中来惩罚新 token，从而增加模型谈论新主题的可能性。
response_format (ChatCompletionInputGrammarType, 可选) — 语法约束。可以是 JSONSchema 或正则表达式。
seed (Optionalint, 可选) — 用于可重现控制流的种子。默认为 None。
stop (Optionalstr, 可选) — 最多四个字符串，用于触发响应结束。默认为 None。
stream (bool, 可选) — 启用响应的实时流式传输。默认为 False。
stream_options (ChatCompletionInputStreamOptions, 可选) — 用于流式完成的选项。
temperature (float, 可选) — 控制生成结果的随机性。较低的值确保更少的随机完成。范围：[0, 2]。默认为 1.0。
top_logprobs (int, 可选) — 介于 0 和 5 之间的整数，指定在每个 token 位置返回的最有可能的 token 数量，每个 token 都有相关的对数概率。如果使用此参数，则必须将 logprobs 设置为 true。
top_p (float, 可选) — 从中最有可能的下一个词的分数进行采样。必须介于 0 和 1 之间。默认为 1.0。
tool_choice (ChatCompletionInputToolType 或 str, 可选) — 用于完成的工具。默认为 “auto”。
tool_prompt (str, 可选) — 要在工具之前附加的提示。
tools (ToolElement 列表, 可选) — 模型可以调用的工具列表。目前，仅支持将函数作为工具。使用此参数可提供模型可以为其生成 JSON 输入的函数列表。

返回

ChatCompletionOutput 或 ChatCompletionStreamOutput 的迭代器

从服务器返回的生成文本

如果 stream=False，则生成的文本将作为 ChatCompletionOutput 返回（默认）。
如果 stream=True，则生成的文本将逐个 token 作为 ChatCompletionStreamOutput 序列返回。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

一种使用指定语言模型完成对话的方法。

client.chat_completion 方法别名为 client.chat.completions.create，以便与 OpenAI 的客户端兼容。输入和输出完全相同，使用任一语法都会产生相同的结果。请查看 Inference guide 以获取有关 OpenAI 兼容性的更多详细信息。

示例

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

使用图像 + 文本作为输入的示例

>>> 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 saw 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: Union question: str model: Optional = None doc_stride: Optional = None handle_impossible_answer: Optional = None lang: Optional = None max_answer_len: Optional = None max_question_len: Optional = None max_seq_len: Optional = None top_k: Optional = None word_boxes: Optional = None ) → List[DocumentQuestionAnsweringOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 上下文的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
question (str) — 要回答的问题。
model (str, optional) — 用于文档问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的文档问答模型。默认为 None。
doc_stride (int, optional) — 如果文档中的单词太长而无法与问题一起放入模型，则会将其拆分为多个块，并带有一些重叠。此参数控制重叠的大小。
handle_impossible_answer (bool, optional) — 是否接受“不可能”作为答案。
lang (str, optional) — 运行 OCR 时使用的语言。
max_answer_len (int, optional) — 预测答案的最大长度（例如，仅考虑长度较短的答案）。
max_question_len (int, optional) — 令牌化后问题的最大长度。如果需要，将会被截断。
max_seq_len (int, optional) — 模型接收的每个块中总句子（上下文 + 问题）的最大令牌长度。如果需要，上下文将被拆分为多个块（使用 doc_stride 作为重叠）。
top_k (int, optional) — 要返回的答案数量（将按可能性顺序选择）。如果上下文中没有足够的选项，则可以返回少于 top_k 个答案。
word_boxes (List[Union[List[float], str]], optional) — 单词和边界框的列表（归一化为 0->1000）。如果提供，推理将跳过 OCR 步骤，而使用提供的边界框。

返回

List[DocumentQuestionAnsweringOutputElement]

包含预测标签、关联概率、单词 ID 和页码的 DocumentQuestionAnsweringOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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, words=None)]

feature_extraction

( text: str normalize: Optional = None prompt_name: Optional = None truncate: Optional = None truncation_direction: Optional = None model: Optional = None ) → np.ndarray

参数

text (str) — 要嵌入的文本。
model (str, optional) — 用于会话任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的会话模型。默认为 None。
normalize (bool, optional) — 是否标准化嵌入。仅在由 Text-Embedding-Inference 驱动的服务器上可用。
prompt_name (str, optional) — 应该用于编码的提示名称。如果未设置，则不会应用任何提示。必须是Sentence Transformers配置prompts字典中的键。例如，如果 prompt_name 为“query”，而 prompts 为 {“query”: “query: ”,…}，则句子“What is the capital of France?”将被编码为“query: What is the capital of France?”，因为提示文本将在任何要编码的文本之前添加。
truncate (bool, optional) — 是否截断嵌入。仅在由 Text-Embedding-Inference 驱动的服务器上可用。
truncation_direction (Literal[“Left”, “Right”], optional) — 当传递 truncate=True 时，应截断输入的哪一侧。

返回

np.ndarray

表示输入文本的嵌入，为 float32 numpy 数组。

引发

[InferenceTimeoutError] 或 HTTPError

[InferenceTimeoutError] — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: str model: Optional = None targets: Optional = None top_k: Optional = None ) → List[FillMaskOutputElement]

参数

text (str) — 要填充的字符串，必须包含 [MASK] 令牌（查看模型卡以获取掩码的确切名称）。
model (str, optional) — 用于填充掩码任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的填充掩码模型。
targets (List[str], optional) — 传入时，模型会将得分限制为传入的目标，而不是在整个词汇表中查找。如果提供的目标不在模型词汇表中，它们将被标记化，并使用第一个生成的标记（带有警告，并且可能会更慢）。
top_k (int, optional) — 传入时，覆盖要返回的预测数量。

返回

List[FillMaskOutputElement]

包含预测标签、相关概率、token 引用和完整文本的 FillMaskOutputElement 条目的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

用缺失的单词（准确来说是 token）填充空洞。

示例

>>> 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: Optional = None ) → Dict[str, Any]

参数

model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 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'
}

get_model_status

( model: Optional = None ) → ModelStatus

参数

model (str, optional) — 要检查状态的模型的标识符。如果未提供模型，则将使用与此 InferenceClient 实例关联的模型。仅可以检查 InferenceAPI 服务，因此标识符不能是 URL。

返回

ModelStatus

ModelStatus 数据类的实例，包含有关模型状态（加载、状态、计算类型和框架）的信息。

获取托管在 Inference API 上的模型的状态。

当您已经知道要使用的模型并想检查其可用性时，此端点非常有用。如果您想发现已部署的模型，则应使用 list_deployed_models()。

示例

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.get_model_status("meta-llama/Meta-Llama-3-8B-Instruct")
ModelStatus(loaded=True, state='Loaded', compute_type='gpu', framework='text-generation-inference')

get_recommended_model

( task: str ) → str

参数

task (str) — Hugging Face 任务，用于获取 Hugging Face 推荐的模型。所有可用任务都可以在此处找到。

返回

str

为输入任务推荐的模型的名称。

引发

ValueError

ValueError — 如果 Hugging Face 对输入任务没有推荐。

获取 Hugging Face 为输入任务推荐的模型。

health_check

( model: Optional = None ) → bool

参数

model (str, optional) — Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 None。

返回

bool

如果一切正常，则为 True。

检查已部署端点的健康状况。

健康检查仅适用于由 Text-Generation-Inference (TGI) 或 Text-Embedding-Inference (TEI) 驱动的 Inference Endpoint。对于 Inference API，请改用 InferenceClient.get_model_status()。

示例

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

image_classification

( image: Union model: Optional = None function_to_apply: Optional = None top_k: Optional = None ) → List[ImageClassificationOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要分类的图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于图像分类的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用图像分类的默认推荐模型。
function_to_apply (Literal["sigmoid", "softmax", "none"], optional) — 应用于输出分数的函数。
top_k (int, optional) — 指定时，将输出限制为前 K 个最可能的类别。

返回

List[ImageClassificationOutputElement]

包含预测标签和相关概率的 ImageClassificationOutputElement 条目的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union model: Optional = None mask_threshold: Optional = None overlap_mask_area_threshold: Optional = None subtask: Optional = None threshold: Optional = None ) → List[ImageSegmentationOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要分割的图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于图像分割的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用图像分割的默认推荐模型。
mask_threshold (float, optional) — 将预测的掩码转换为二进制值时要使用的阈值。
overlap_mask_area_threshold (float, optional) — 掩码重叠阈值，用于消除小的、不连接的片段。
subtask (Literal["instance", "panoptic", "semantic"], optional) — 要执行的分割任务，取决于模型的功能。
threshold (float, optional) — 概率阈值，用于滤除预测的掩码。

返回

List[ImageSegmentationOutputElement]

包含分割的掩码和相关属性的 ImageSegmentationOutputElement 条目的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union prompt: Optional = None negative_prompt: Optional = None height: Optional = None width: Optional = None num_inference_steps: Optional = None guidance_scale: Optional = None model: Optional = None **kwargs ) → Image

参数

image (Union[str, Path, bytes, BinaryIO]) — 用于翻译的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
prompt (str, optional) — 用于引导图像生成的文本提示。
negative_prompt (str, optional) — 用于引导翻译过程的负面提示。
height (int, optional) — 生成图像的像素高度。
width (int, optional) — 生成图像的像素宽度。
num_inference_steps (int, optional) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会牺牲推理速度。
guidance_scale (float, optional) — 较高的 guidance scale 鼓励生成与文本 prompt 紧密相关的图像，但通常会以降低图像质量为代价。
model (str, optional) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。此参数会覆盖在实例级别定义的模型。默认为 None。

返回

图像

翻译后的图像。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union model: Optional = None ) → ImageToTextOutput

参数

image (Union[str, Path, bytes, BinaryIO]) — 用于图像描述的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。此参数会覆盖在实例级别定义的模型。默认为 None。

返回

ImageToTextOutput

生成的文本。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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 '

list_deployed_models

( frameworks: Union = None ) → Dict[str, List[str]]

参数

frameworks (Literal["all"] or List[str] or str, optional) — 要过滤的框架。默认情况下，仅测试可用框架的子集。如果设置为“all”，将测试所有可用的框架。也可以提供单个框架或要检查的自定义框架集。

返回

Dict[str, List[str]]

一个字典，将任务名称映射到模型 ID 的排序列表。

列出部署在 Serverless Inference API 服务上的模型。

此助手逐框架检查已部署的模型。默认情况下，它将检查 4 个主要支持的框架，这些框架占托管模型的 95%。但是，如果您想要完整的模型列表，您可以指定 frameworks="all" 作为输入。或者，如果您事先知道您对哪个框架感兴趣，您也可以将搜索限制为该框架（例如 `frameworks="text-generation-inference"`）。检查的框架越多，所需时间就越长。

此端点方法不返回 Serverless Inference API 服务可用的所有模型的实时列表。它会在最近可用的模型缓存列表中搜索，并且该列表可能不是最新的。如果您想知道特定模型的实时状态，请使用 get_model_status()。

此端点方法主要用于发现。如果您已经知道要使用的模型并想检查其可用性，您可以直接使用 get_model_status()。

示例

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

# Discover zero-shot-classification models currently deployed
>>> models = client.list_deployed_models()
>>> models["zero-shot-classification"]
['Narsil/deberta-large-mnli-zero-cls', 'facebook/bart-large-mnli', ...]

# List from only 1 framework
>>> client.list_deployed_models("text-generation-inference")
{'text-generation': ['bigcode/starcoder', 'meta-llama/Llama-2-70b-chat-hf', ...], ...}

object_detection

( image: Union model: Optional = None threshold: Optional = None ) → List[ObjectDetectionOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要检测对象的图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于对象检测的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。如果未提供，将使用对象检测的默认推荐模型 (DETR)。
threshold (float, optional) — 进行预测所需的概率阈值。

返回

List[ObjectDetectionOutputElement]

包含边界框和相关属性的 ObjectDetectionOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError 或 ValueError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。
ValueError — 如果请求输出不是列表。

使用指定的模型在给定图像上执行对象检测。

如果要处理图像，则必须安装 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)), ...]

post

( json: Union = None data: Union = None model: Optional = None task: Optional = None stream: bool = False ) → bytes

参数

json (Union[str, Dict, List], optional) — 要在请求正文中发送的 JSON 数据，特定于每个任务。默认为 None。
data (Union[str, Path, bytes, BinaryIO], optional) — 要在请求正文中发送的内容，特定于每个任务。它可以是原始字节、指向已打开文件的指针、本地文件路径或在线资源（图像、音频文件等）的 URL。如果同时传递了 json 和 data，则 data 优先。必须至少提供 json 或 data 之一。默认为 None。
model (str, optional) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。将覆盖在实例级别定义的模型。默认为 None。
task (str, optional) — 要在推理上执行的任务。所有可用的任务都可以在这里找到。仅用于在未提供 model 时默认为推荐模型。必须至少提供 model 或 task 之一。默认为 None。
stream (bool, optional) — 是否迭代流式 API。

返回

bytes

服务器返回的原始字节。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

向推理服务器发出 POST 请求。

question_answering

( question: str context: str model: Optional = None align_to_words: Optional = None doc_stride: Optional = None handle_impossible_answer: Optional = None max_answer_len: Optional = None max_question_len: Optional = None max_seq_len: Optional = None top_k: Optional = None ) → Union[QuestionAnsweringOutputElement, ListQuestionAnsweringOutputElement]

参数

question (str) — 待回答的问题。
context (str) — 问题的上下文。
model (str) — 用于问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。
align_to_words (bool, optional) — 尝试将答案与实际单词对齐。提高以空格分隔的语言的质量。可能会损害非空格分隔的语言（如日语或中文）。
doc_stride (int, optional) — 如果上下文太长而无法与问题一起放入模型，则会将其拆分为多个块，并带有一定的重叠。此参数控制重叠的大小。
handle_impossible_answer (bool, optional) — 是否接受“不可能”作为答案。
max_answer_len (int, optional) — 预测答案的最大长度（例如，仅考虑长度较短的答案）。
max_question_len (int, optional) — 标记化后问题的最大长度。如果需要，将会被截断。
max_seq_len (int, optional) — 模型接收的每个块中，上下文+问题的总句子的最大长度（以 tokens 为单位）。如果需要，上下文将被拆分为多个块（使用 docStride 作为重叠）。
top_k (int, optional) — 返回的答案数量（将按可能性顺序选择）。请注意，如果上下文中没有足够的选项，我们返回的答案将少于 topk 个。

返回

Union[QuestionAnsweringOutputElement, ListQuestionAnsweringOutputElement]

当 top_k 为 1 或未提供时，它返回单个 QuestionAnsweringOutputElement。当 top_k 大于 1 时，它返回 QuestionAnsweringOutputElement 的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: str other_sentences: List model: Optional = None ) → List[float]

参数

sentence (str) — 要与其他句子比较的主句子。
other_sentences (List[str]) — 要比较的其他句子的列表。
model (str, optional) — 用于会话任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。如果未提供，将使用默认推荐的会话模型。默认为 None。

返回

List[float]

表示输入文本的嵌入向量。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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]

summarization

( text: str parameters: Optional = None model: Optional = None clean_up_tokenization_spaces: Optional = None generate_parameters: Optional = None truncation: Optional = None ) → SummarizationOutput

参数

text (str) — 要总结的输入文本。
parameters (Dict[str, Any], optional) — 用于摘要的其他参数。查看此页面以获取更多详细信息。
model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。如果未提供，将使用默认推荐的摘要模型。
clean_up_tokenization_spaces (bool, optional) — 是否清理文本输出中潜在的额外空格。
generate_parameters (Dict[str, Any], optional) — 文本生成算法的附加参数化。
truncation (Literal["do_not_truncate", "longest_first", "only_first", "only_second"], optional) — 要使用的截断策略。

返回

SummarizationOutput

生成的摘要文本。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Dict query: str model: Optional = None parameters: Optional = None ) → TableQuestionAnsweringOutputElement

参数

table (str) — 数据表格，表示为列表字典，其中条目是标题，列表是所有值，所有列表必须具有相同的大小。
query (str) — 您想要向表格提出的纯文本查询。
model (str) — 用于表格问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。
parameters (Dict[str, Any], optional) — 额外的推理参数。默认为 None。

返回

TableQuestionAnsweringOutputElement

一个表格问答输出，包含答案、坐标、单元格和使用的聚合器。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Dict model: Optional = None ) → List

参数

table (Dict[str, Any]) — 要分类的属性集。
model (str, 可选) — 用于表格分类任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。如果未提供，将使用默认推荐的表格分类模型。默认为 None。

返回

List

初始表格中每行标签的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Dict model: Optional = None ) → List

参数

table (Dict[str, Any]) — 存储在表格中的属性集。用于预测目标的属性可以是数值型和类别型。
model (str, 可选) — 用于表格回归任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。如果未提供，将使用默认推荐的表格回归模型。默认为 None。

返回

List

预测的数值目标值列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: str model: Optional = None top_k: Optional = None function_to_apply: Optional = None ) → List[TextClassificationOutputElement]

参数

text (str) — 要分类的字符串。
model (str, 可选) — 用于文本分类任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。如果未提供，将使用默认推荐的文本分类模型。默认为 None。
top_k (int, 可选) — 当指定时，将输出限制为最有可能的 K 个类别。
function_to_apply ("TextClassificationOutputTransform", 可选) — 应用于输出的函数。

返回

List[TextClassificationOutputElement]

包含预测标签和相关概率的 TextClassificationOutputElement 项的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: str details: bool = False stream: bool = False model: Optional = None adapter_id: Optional = None best_of: Optional = None decoder_input_details: Optional = None do_sample: Optional = False frequency_penalty: Optional = None grammar: Optional = None max_new_tokens: Optional = None repetition_penalty: Optional = None return_full_text: Optional = False seed: Optional = None stop: Optional = None stop_sequences: Optional = None temperature: Optional = None top_k: Optional = None top_n_tokens: Optional = None top_p: Optional = None truncate: Optional = None typical_p: Optional = None watermark: Optional = None ) → Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]

参数

prompt (str) — 输入文本。
details (bool, 可选) — 默认情况下，text_generation 返回一个字符串。如果您想要详细的输出（tokens, probabilities, seed, finish reason 等），请传递 details=True。仅适用于在 text-generation-inference 后端上运行的模型。
stream (bool, 可选) — 默认情况下，text_generation 返回完整的生成文本。如果您想要返回 tokens 流，请传递 stream=True。仅适用于在 text-generation-inference 后端上运行的模型。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的推理端点的 URL。此参数会覆盖实例级别定义的模型。默认为 None。
adapter_id (str, 可选) — Lora 适配器 ID。
best_of (int, 可选) — 生成 best_of 序列并返回 token logprobs 最高的那个。
decoder_input_details (bool, 可选) — 返回 decoder 输入 token logprobs 和 ids。您必须同时设置 details=True 才能使其生效。默认为 False。
do_sample (bool, 可选) — 激活 logits 采样
frequency_penalty (float, 可选) — 介于 -2.0 和 2.0 之间的数字。正值会根据新 tokens 在目前文本中已有的频率来惩罚它们，从而降低模型逐字重复同一行的可能性。
grammar (TextGenerationInputGrammarType, 可选) — 语法约束。可以是 JSONSchema 或正则表达式。
max_new_tokens (int, 可选) — 生成 tokens 的最大数量
repetition_penalty (float, 可选) — 重复惩罚的参数。 1.0 表示没有惩罚。有关更多详细信息，请参阅本文。
return_full_text (bool, 可选) — 是否将 prompt 添加到生成的文本前面
seed (int, 可选) — 随机采样的种子。
stop (List[str], 可选) — 如果生成了 stop 中的任何成员，则停止生成 tokens。
stop_sequences (List[str], 可选) — 已弃用的参数。请使用 stop 代替。
temperature (float, 可选) — 用于调整 logits 分布的值。
top_n_tokens (int, 可选) — 返回每个生成步骤中最有可能的 top_n_tokens 的信息，而不仅仅是采样的 token。
top_k (int, 可选) — 用于 top-k 过滤的最高概率词汇 tokens 的数量。
top_p (float, 可选) — 如果设置为 < 1, 则只保留概率总和达到 top_p 或更高的最小概率 tokens 集合，用于生成。
truncate (int, 可选) — 将输入 tokens 截断到给定的大小。
typical_p (float, 可选) — 典型解码质量。有关更多信息，请参阅自然语言生成的典型解码。
watermark (bool, 可选) — 使用水印技术，参见大型语言模型的水印。

返回

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

从服务器返回的生成文本

如果 stream=False 且 details=False，则生成的文本将作为 str 返回（默认）。
如果 stream=True 且 details=False，则生成的文本将逐个 token 作为 Iterable[str] 返回。
如果 stream=False 且 details=True，则生成的文本将作为 TextGenerationOutput 返回，其中包含更多详细信息。
如果 details=True 且 stream=True，则生成的文本将逐个 token 作为 TextGenerationStreamOutput 的 iterable 返回。

引发

ValidationError 或 InferenceTimeoutError 或 HTTPError

ValidationError — 如果输入值无效。不会向服务器发出 HTTP 调用。
InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

给定一个提示，生成以下文本。

API 端点应该与 text-generation-inference 后端（TGI）一起运行。此后端是在大规模运行大型语言模型的首选解决方案。但是，对于一些较小的模型（例如“gpt2”），默认的 transformers + api-inference 解决方案仍然在使用。两种方法都有非常相似的 API，但并非完全相同。此方法与两种方法都兼容，但某些参数仅适用于 text-generation-inference。如果某些参数被忽略，将触发警告消息，但该过程将继续正确执行。

要了解有关 TGI 项目的更多信息，请参阅 https://github.com/huggingface/text-generation-inference。

如果您想从聊天消息生成回复，则应使用 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: str negative_prompt: Optional = None height: Optional = None width: Optional = None num_inference_steps: Optional = None guidance_scale: Optional = None model: Optional = None scheduler: Optional = None target_size: Optional = None seed: Optional = None **kwargs ) → Image

参数

prompt (str) — 用于生成图像的提示文本。
negative_prompt (str, 可选) — 用于图像生成的可选负面提示。
height (float, 可选) — 要生成的图像的高度像素值。
width (float, 可选) — 要生成的图像的宽度像素值。
num_inference_steps (int, 可选) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会牺牲推理速度。
guidance_scale (float, 可选) — 较高的 guidance scale 鼓励生成与文本 prompt 紧密相关的图像，但通常以降低图像质量为代价。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的 text-to-image 模型。默认为 None。
scheduler (str, 可选) — 使用兼容的 scheduler 覆盖默认 scheduler。
target_size (TextToImageTargetSize, 可选) — 输出图像的像素大小。
seed (int, 可选) — 随机数生成器的种子。

返回

图像

生成的图像。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

使用指定的模型，根据给定的文本生成图像。

如果要处理图像，则必须安装 PIL (pip install Pillow)。

示例

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

text_to_speech

( text: str model: Optional = None do_sample: Optional = None early_stopping: Union = None epsilon_cutoff: Optional = None eta_cutoff: Optional = None max_length: Optional = None max_new_tokens: Optional = None min_length: Optional = None min_new_tokens: Optional = None num_beam_groups: Optional = None num_beams: Optional = None penalty_alpha: Optional = None temperature: Optional = None top_k: Optional = None top_p: Optional = None typical_p: Optional = None use_cache: Optional = None ) → bytes

参数

text (str) — 要合成的文本。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的 text-to-speech 模型。默认为 None。
do_sample (bool, 可选) — 在生成新 tokens 时，是否使用采样而不是贪婪解码。
early_stopping (Union[bool, "TextToSpeechEarlyStoppingEnum", 可选) — 控制基于束搜索方法的停止条件。
epsilon_cutoff (float, 可选) — 如果设置为严格介于 0 和 1 之间的浮点数，则仅对条件概率大于 epsilon_cutoff 的 tokens 进行采样。在论文中，建议值范围为 3e-4 到 9e-4，具体取决于模型的大小。有关更多详细信息，请参阅 Truncation Sampling as Language Model Desmoothing。
eta_cutoff (float, 可选) — Eta 采样是局部典型性采样和 epsilon 采样的混合。如果设置为严格介于 0 和 1 之间的浮点数，则仅当 token 大于 eta_cutoff 或 sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))) 时才会被考虑。后者在直觉上是预期的下一个 token 概率，由 sqrt(eta_cutoff) 缩放。在论文中，建议值范围为 3e-4 到 2e-3，具体取决于模型的大小。有关更多详细信息，请参阅 Truncation Sampling as Language Model Desmoothing。
max_length (int, 可选) — 生成文本的最大长度（以 tokens 为单位），包括输入。
max_new_tokens (int, 可选) — 要生成的最大 tokens 数量。优先于 maxLength。
min_length (int, 可选) — 生成文本的最小长度（以 tokens 为单位），包括输入。
min_new_tokens (int, 可选) — 要生成的最小 tokens 数量。优先于 maxLength。
num_beam_groups (int, 可选) — 将 num_beams 分成组的数量，以确保不同束组之间的多样性。有关更多详细信息，请参阅本文。
num_beams (int, 可选) — 用于束搜索的束数量。
penalty_alpha (float, 可选) — 该值平衡了模型置信度和对比搜索解码中的退化惩罚。
temperature (float, 可选) — 用于调节下一个 token 概率的值。
top_k (int, 可选) — 保留用于 top-k 过滤的最高概率词汇 tokens 的数量。
top_p (float, 可选) — 如果设置为小于 1 的浮点数，则仅保留概率总和达到 top_p 或更高的最小概率 tokens 集合用于生成。
typical_p (float, 可选) — 局部典型性衡量了在给定已生成的部分文本的情况下，预测下一个目标 token 的条件概率与预测下一个随机 token 的预期条件概率的相似程度。如果设置为小于 1 的浮点数，则仅保留概率总和达到 typical_p 或更高的最小局部典型 tokens 集合用于生成。有关更多详细信息，请参阅本文。
use_cache (bool, 可选) — 模型是否应使用过去的最后一个键/值注意力来加速解码

返回

bytes

生成的音频。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

合成一段语音，朗读给定的文本。

示例

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

token_classification

( text: str model: Optional = None aggregation_strategy: Optional = None ignore_labels: Optional = None stride: Optional = None ) → List[TokenClassificationOutputElement]

参数

text (str) — 要分类的字符串。
model (str, 可选) — 用于 token 分类任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的 token 分类模型。默认为 None。
aggregation_strategy (Literal["none", "simple", "first", "average", "max"], 可选) — 用于基于模型预测融合 tokens 的策略。
ignore_labels (List[str], 可选) — 要忽略的标签列表。
stride (int, 可选) — 当拆分输入文本时，块之间重叠 tokens 的数量。

返回

List[TokenClassificationOutputElement]

包含实体组、置信度分数、单词、起始和结束索引的 TokenClassificationOutputElement 条目的列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

对给定的文本执行 token 分类。通常用于句子解析，无论是语法解析还是命名实体识别 (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,
    )
]

translation

( text: str model: Optional = None src_lang: Optional = None tgt_lang: Optional = None clean_up_tokenization_spaces: Optional = None truncation: Optional = None generate_parameters: Optional = None ) → TranslationOutput

参数

text (str) — 要翻译的字符串。
model (str, 可选) — 用于翻译任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的翻译模型。默认为 None。
src_lang (str, 可选) — 文本的源语言。对于可以从多种语言进行翻译的模型是必需的。
tgt_lang (str, 可选) — 要翻译成的目标语言。对于可以翻译成多种语言的模型是必需的。
clean_up_tokenization_spaces (bool, 可选) — 是否清理文本输出中潜在的额外空格。
truncation (Literal["do_not_truncate", "longest_first", "only_first", "only_second"], 可选) — 要使用的截断策略。
generate_parameters (Dict[str, Any], 可选) — 文本生成算法的附加参数。

返回

TranslationOutput

生成的翻译文本。

引发

InferenceTimeoutError 或 HTTPError 或 ValueError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: Union question: str model: Optional = None top_k: Optional = None ) → List[VisualQuestionAnsweringOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 上下文的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
question (str) — 要回答的问题。
model (str, 可选) — 用于视觉问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的视觉问答模型。默认为 None。
top_k (int, 可选) — 要返回的答案数量（将按可能性顺序选择）。请注意，如果上下文中没有足够的选项，我们返回的答案将少于 topk 个。

返回

List[VisualQuestionAnsweringOutputElement]

包含预测标签和相关概率的 VisualQuestionAnsweringOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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: str labels: List multi_label: bool = False hypothesis_template: Optional = None model: Optional = None ) → List[ZeroShotClassificationOutputElement]

参数

text (str) — 要分类的输入文本。
labels (List[str]) — 字符串列表。每个字符串是输入文本的可能标签的文字描述。
multi_label (bool) — 布尔值。如果为 True，则独立评估每个标签的概率，并且多个标签可以同时具有接近 1 的概率，或者所有概率都可以接近 0。如果为 False，则标签被认为是互斥的，并且所有标签的概率总和始终为 1。默认为 False。
hypothesis_template (str, 可选) — 带有花括号的模板句子字符串，标签字符串将被添加到其中。标签字符串被添加到花括号“{}”的位置。零样本分类器基于 NLI 模型，该模型评估假设是否包含在另一段文本中。例如，使用 hypothesis_template=“This text is about {}.” 和 labels=[“economics”, “politics”]，系统内部创建两个假设“This text is about economics.” 和 “This text is about politics.”。然后模型评估这两个假设是否包含在提供的 text 中。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。如果未提供，将使用默认推荐的零样本分类模型。

返回

List[ZeroShotClassificationOutputElement]

包含预测标签及其置信度的 ZeroShotClassificationOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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.",
...    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: Union labels: List model: Optional = None hypothesis_template: Optional = None ) → List[ZeroShotImageClassificationOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要进行图像描述的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
labels (List[str]) — 可能的字符串标签列表。必须至少有 2 个标签。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。如果未提供，将使用默认推荐的零样本图像分类模型。
hypothesis_template (str, 可选) — 与 labels 结合使用的句子，通过将占位符替换为候选标签来尝试文本分类。

返回

List[ZeroShotImageClassificationOutputElement]

包含预测标签及其置信度的 ZeroShotImageClassificationOutputElement 项目列表。

引发

InferenceTimeoutError 或 HTTPError

InferenceTimeoutError — 如果模型不可用或请求超时。
HTTPError — 如果请求失败，并且 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",
...     labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]

异步推理客户端

还提供了客户端的异步版本，基于 asyncio 和 aiohttp。要使用它，您可以直接安装 aiohttp 或使用 [inference] 扩展

pip install --upgrade huggingface_hub[inference]
# or
# pip install aiohttp

class huggingface_hub.AsyncInferenceClient

( model: Optional = None token: Union = None timeout: Optional = None headers: Optional = None cookies: Optional = None trust_env: bool = False proxies: Optional = None base_url: Optional = None api_key: Optional = None )

参数

model (str, optional) — 用于运行推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，例如 meta-llama/Meta-Llama-3-8B-Instruct，或者是已部署的 Inference Endpoint 的 URL。默认为 None，在这种情况下，将为任务自动选择推荐模型。注意：为了更好地兼容 OpenAI 的客户端，model 已别名为 base_url。这两个参数互斥。如果为聊天补全使用 base_url，则 /chat/completions 后缀路径将附加到基本 URL（有关详细信息，请参阅 TGI Messages API 文档）。当将 URL 作为 model 传递时，客户端不会向其附加任何后缀路径。
token (str 或 bool, 可选) — Hugging Face 令牌。如果未提供，则默认为本地保存的令牌。如果您不想将令牌发送到服务器，请传递 token=False。注意：为了更好地兼容 OpenAI 的客户端，token 已别名为 api_key。这两个参数互斥，并且具有完全相同的行为。
timeout (float, optional) — 等待服务器响应的最长秒数。在 Inference API 中加载新模型可能需要几分钟时间。默认为 None，表示将循环直到服务器可用。
headers (Dict[str, str], optional) — 要发送到服务器的其他标头。默认情况下，仅发送授权和用户代理标头。此字典中的值将覆盖默认值。
cookies (Dict[str, str], optional) — 要发送到服务器的其他 Cookie。
trust_env (‘bool’, ‘optional’) — 如果参数为 True（默认为 False），则信任代理配置的环境设置。
proxies (Any, optional) — 用于请求的代理。
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 或自托管 Inference Endpoints 无缝使用。

音频分类

( audio: Union model: Optional = None top_k: Optional = None function_to_apply: Optional = None ) → List[AudioClassificationOutputElement]

参数

audio (Union[str, Path, bytes, BinaryIO]) — 要分类的音频内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 用于音频分类的模型。可以是 Hugging Face Hub 上托管的模型 ID，或者是已部署的 Inference Endpoint 的 URL。如果未提供，将使用音频分类的默认推荐模型。
top_k (int, 可选) — 指定时，将输出限制为前 K 个最可能的类别。
function_to_apply ("AudioClassificationOutputTransform", 可选) — 应用于输出的函数。

返回

List[AudioClassificationOutputElement]

包含预测标签及其置信度的 AudioClassificationOutputElement 项目列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Union model: Optional = None ) → List[AudioToAudioOutputElement]

参数

audio (Union[str, Path, bytes, BinaryIO]) — 模型的音频内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 该模型可以是任何接受音频文件并返回另一个音频文件的模型。可以是 Hugging Face Hub 上托管的模型 ID，或者是已部署的 Inference Endpoint 的 URL。如果未提供，将使用 audio_to_audio 的默认推荐模型。

返回

List[AudioToAudioOutputElement]

包含音频标签、content-type 和 blob 格式音频内容的 AudioToAudioOutputElement 项目列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Union model: Optional = None ) → AutomaticSpeechRecognitionOutput

参数

audio (Union[str, Path, bytes, BinaryIO]) — 要转录的内容。它可以是原始音频字节、本地音频文件或指向音频文件的 URL。
model (str, 可选) — 用于 ASR 的模型。可以是 Hugging Face Hub 上托管的模型 ID，或者是已部署的 Inference Endpoint 的 URL。如果未提供，将使用 ASR 的默认推荐模型。

返回

AutomaticSpeechRecognitionOutput

包含转录文本以及可选的时间戳块的项目。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: List model: Optional = None stream: bool = False frequency_penalty: Optional = None logit_bias: Optional = None logprobs: Optional = None max_tokens: Optional = None n: Optional = None presence_penalty: Optional = None response_format: Optional = None seed: Optional = None stop: Optional = None stream_options: Optional = None temperature: Optional = None tool_choice: Union = None tool_prompt: Optional = None tools: Optional = None top_logprobs: Optional = None top_p: Optional = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput

参数

messages (ChatCompletionInputMessage 列表) — 由角色和内容对组成的对话历史记录。
model (str, 可选) — 用于聊天补全的模型。可以是 Hugging Face Hub 上托管的模型 ID，或者是已部署的 Inference Endpoint 的 URL。如果未提供，将使用基于聊天的文本生成的默认推荐模型。有关更多详细信息，请参阅 https://huggingface.co/tasks/text-generation。

如果 model 是模型 ID，则会将其作为 model 参数传递给服务器。如果您想在请求负载中设置 model 的同时定义自定义 URL，则必须在初始化 InferenceClient 时设置 base_url。
frequency_penalty (float, 可选) — 根据到目前为止文本中现有频率来惩罚新标记。范围：[-2.0, 2.0]。默认为 0.0。
logit_bias (List[float], 可选) — 修改完成项中指定标记出现的可能性。接受一个 JSON 对象，该对象将标记（由其在 tokenizer 中的标记 ID 指定）映射到 -100 到 100 的关联偏差值。从数学上讲，偏差被添加到模型在采样之前生成的 logits 中。确切效果因模型而异，但 -1 到 1 之间的值应降低或增加选择的可能性；像 -100 或 100 这样的值应导致禁止或独占选择相关标记。默认为 None。
logprobs (bool, 可选) — 是否返回输出 tokens 的对数概率。如果为 true，则返回消息内容中返回的每个输出 token 的对数概率。
max_tokens (int, 可选) — 响应中允许的最大 tokens 数量。默认为 20。
n (int, 可选) — 未使用。
presence_penalty (float, 可选) — 介于 -2.0 和 2.0 之间的数字。正值会根据 token 是否已在文本中出现来惩罚新 token，从而增加模型讨论新话题的可能性。
response_format (ChatCompletionInputGrammarType, 可选) — 语法约束。可以是 JSONSchema 或正则表达式。
seed (Optionalint, 可选) — 用于可重现控制流的随机种子。默认为 None。
stop (Optionalstr, 可选) — 最多四个字符串，触发响应结束。默认为 None。
stream (bool, 可选) — 启用响应的实时流式传输。默认为 False。
stream_options (ChatCompletionInputStreamOptions, 可选) — 用于流式完成的选项。
temperature (float, 可选) — 控制生成结果的随机性。值越低，完成结果的随机性越小。范围：[0, 2]。默认为 1.0。
top_logprobs (int, 可选) — 一个介于 0 和 5 之间的整数，指定在每个 token 位置返回的最有可能的 token 数量，每个 token 都有一个关联的对数概率。如果使用此参数，则必须将 logprobs 设置为 true。
top_p (float, 可选) — 从中最有可能的下一个词的分数中进行抽样。必须介于 0 和 1 之间。默认为 1.0。
tool_choice (ChatCompletionInputToolType 或 str, 可选) — 用于完成的工具。默认为 “auto”。
tool_prompt (str, 可选) — 要在工具之前附加的提示。
tools (List of ToolElement, 可选) — 模型可以调用的工具列表。目前，仅支持将函数作为工具。使用此参数提供模型可以为其生成 JSON 输入的函数列表。

返回

ChatCompletionOutput 或 ChatCompletionStreamOutput 的迭代器

从服务器返回的生成文本

如果 stream=False，则生成的文本将作为 ChatCompletionOutput 返回（默认）。
如果 stream=True，则生成的文本将逐个 token 作为 ChatCompletionStreamOutput 序列返回。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

一种使用指定语言模型完成对话的方法。

client.chat_completion 方法别名为 client.chat.completions.create，以便与 OpenAI 的客户端兼容。输入和输出完全相同，使用任一语法都会产生相同的结果。请查看 Inference guide 以获取有关 OpenAI 兼容性的更多详细信息。

示例

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

使用图像 + 文本作为输入的示例

# 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 saw 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"}'

close

( )

关闭所有打开的会话。

默认情况下，当调用完成时，‘aiohttp.ClientSession’ 对象会自动关闭。但是，如果您正在从服务器流式传输数据，并且在流完成之前停止，则必须调用此方法才能正确关闭会话。

另一种可能性是使用异步上下文（例如，async with AsyncInferenceClient(): ...）。

document_question_answering

( image: Union question: str model: Optional = None doc_stride: Optional = None handle_impossible_answer: Optional = None lang: Optional = None max_answer_len: Optional = None max_question_len: Optional = None max_seq_len: Optional = None top_k: Optional = None word_boxes: Optional = None ) → List[DocumentQuestionAnsweringOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 上下文的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
question (str) — 要回答的问题。
model (str, 可选) — 用于文档问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的文档问答模型。默认为 None。
doc_stride (int, 可选) — 如果文档中的单词太长而无法与问题匹配模型，则会将其拆分为多个块，并带有一些重叠部分。此参数控制重叠部分的大小。
handle_impossible_answer (bool, 可选) — 是否接受“不可能”作为答案。
lang (str, 可选) — 运行 OCR 时使用的语言。
max_answer_len (int, 可选) — 预测答案的最大长度（例如，仅考虑长度较短的答案）。
max_question_len (int, 可选) — token 化后问题的最大长度。如果需要，将会被截断。
max_seq_len (int, 可选) — 传递给模型的每个块中，总句子（上下文 + 问题）的最大 token 长度。如果需要，上下文将被拆分为多个块（使用 doc_stride 作为重叠部分）。
top_k (int, 可选) — 要返回的答案数量（将按可能性顺序选择）。如果上下文中没有足够的选项，则返回的答案可能少于 top_k 个。
word_boxes (List[Union[List[float], str]], 可选) — 单词和边界框的列表 (归一化为 0->1000)。如果提供，推理将跳过 OCR 步骤，并使用提供的边界框。

返回

List[DocumentQuestionAnsweringOutputElement]

包含预测标签、关联概率、单词 ID 和页码的 DocumentQuestionAnsweringOutputElement 项目列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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, words=None)]

feature_extraction

( text: str normalize: Optional = None prompt_name: Optional = None truncate: Optional = None truncation_direction: Optional = None model: Optional = None ) → np.ndarray

参数

text (str) — 要嵌入的文本。
model (str, 可选) — 用于对话任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的对话模型。默认为 None。
normalize (bool, 可选) — 是否标准化嵌入。仅在由 Text-Embedding-Inference 驱动的服务器上可用。
prompt_name (str, 可选) — 应该用于编码的提示名称。如果未设置，则不会应用任何提示。必须是Sentence Transformers配置prompts字典中的键。例如，如果prompt_name是“query”并且prompts是{“query”: “query: ”,…}，那么句子“What is the capital of France?”将被编码为“query: What is the capital of France?”，因为提示文本将在任何要编码的文本之前添加。
truncate (bool, 可选) — 是否截断嵌入。仅在由 Text-Embedding-Inference 驱动的服务器上可用。
truncation_direction (Literal[“Left”, “Right”], 可选) — 当传递 truncate=True 时，应截断输入的哪一侧。

返回

np.ndarray

表示输入文本的嵌入，为 float32 numpy 数组。

引发

[InferenceTimeoutError] 或 aiohttp.ClientResponseError

[InferenceTimeoutError] — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: str model: Optional = None targets: Optional = None top_k: Optional = None ) → List[FillMaskOutputElement]

参数

text (str) — 要填充的字符串，必须包含 [MASK] 标记（检查模型卡以获取掩码的确切名称）。
model (str, 可选) — 用于填充掩码任务的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的填充掩码模型。
targets (List[str], 可选) — 传递时，模型将限制为传递的目标的分数，而不是在整个词汇表中查找。如果提供的目标不在模型词汇表中，它们将被标记化，并且将使用第一个结果标记（带有警告，并且可能会更慢）。
top_k (int, 可选) — 传递时，覆盖要返回的预测数。

返回

List[FillMaskOutputElement]

包含预测标签、相关概率、token 引用和完整文本的 FillMaskOutputElement 条目的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

用缺失的单词（准确来说是 token）填充空洞。

示例

# 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: Optional = None ) → Dict[str, Any]

参数

返回

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'
}

get_model_status

( model: Optional = None ) → ModelStatus

参数

model (str, 可选) — 要检查其状态的模型的标识符。如果未提供模型，将使用与此 InferenceClient 实例关联的模型。只能检查 InferenceAPI 服务，因此标识符不能是 URL。

返回

ModelStatus

ModelStatus 数据类的实例，包含有关模型状态（加载、状态、计算类型和框架）的信息。

获取托管在 Inference API 上的模型的状态。

当您已经知道要使用的模型并想检查其可用性时，此端点非常有用。如果您想发现已部署的模型，则应使用 list_deployed_models()。

示例

# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.get_model_status("meta-llama/Meta-Llama-3-8B-Instruct")
ModelStatus(loaded=True, state='Loaded', compute_type='gpu', framework='text-generation-inference')

get_recommended_model

( task: str ) → str

参数

task (str) — Hugging Face 任务，用于获取 Hugging Face 推荐的模型。所有可用的任务都可以在这里找到。

返回

str

为输入任务推荐的模型的名称。

引发

ValueError

ValueError — 如果 Hugging Face 对输入任务没有推荐。

获取 Hugging Face 为输入任务推荐的模型。

health_check

( model: Optional = None ) → bool

参数

model (str, 可选) — Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 None。

返回

bool

如果一切正常，则为 True。

检查已部署端点的健康状况。

健康检查仅适用于由 Text-Generation-Inference (TGI) 或 Text-Embedding-Inference (TEI) 驱动的 Inference Endpoint。对于 Inference API，请改用 InferenceClient.get_model_status()。

示例

# 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: Union model: Optional = None function_to_apply: Optional = None top_k: Optional = None ) → List[ImageClassificationOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要分类的图像。可以是原始字节、图像文件或在线图像的 URL。
model (str, 可选) — 用于图像分类的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的图像分类模型。
function_to_apply (Literal["sigmoid", "softmax", "none"], 可选) — 应用于输出分数的函数。
top_k (int, 可选) — 指定时，将输出限制为最有可能的 K 个类别。

返回

List[ImageClassificationOutputElement]

包含预测标签和相关概率的 ImageClassificationOutputElement 条目的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Union model: Optional = None mask_threshold: Optional = None overlap_mask_area_threshold: Optional = None subtask: Optional = None threshold: Optional = None ) → List[ImageSegmentationOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要分割的图像。可以是原始字节、图像文件或在线图像的 URL。
model (str, 可选) — 用于图像分割的模型。可以是 Hugging Face Hub 上托管的模型 ID 或部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的图像分割模型。
mask_threshold (float, 可选) — 将预测的掩码转换为二进制值时要使用的阈值。
overlap_mask_area_threshold (float, optional) — 用于消除小的、不连续的分割区域的掩码重叠阈值。
subtask (Literal["instance", "panoptic", "semantic"], optional) — 要执行的分割任务，取决于模型的功能。
threshold (float, optional) — 用于滤除预测掩码的概率阈值。

返回

List[ImageSegmentationOutputElement]

包含分割的掩码和相关属性的 ImageSegmentationOutputElement 条目的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Union prompt: Optional = None negative_prompt: Optional = None height: Optional = None width: Optional = None num_inference_steps: Optional = None guidance_scale: Optional = None model: Optional = None **kwargs ) → Image

参数

image (Union[str, Path, bytes, BinaryIO]) — 用于图像到图像转换的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
prompt (str, optional) — 用于引导图像生成的文本提示。
negative_prompt (str, optional) — 用于引导翻译过程的负面提示。
height (int, optional) — 生成图像的高度像素。
width (int, optional) — 生成图像的宽度像素。
num_inference_steps (int, optional) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会牺牲推理速度。
guidance_scale (float, optional) — 更高的 guidance scale 鼓励生成与文本 prompt 紧密相关的图像，但通常以降低图像质量为代价。
model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 None。

返回

图像

翻译后的图像。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Union model: Optional = None ) → ImageToTextOutput

参数

image (Union[str, Path, bytes, BinaryIO]) — 用于图像描述的输入图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 None。

返回

ImageToTextOutput

生成的文本。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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 '

list_deployed_models

( frameworks: Union = None ) → Dict[str, List[str]]

参数

frameworks (Literal["all"] or List[str] or str, optional) — 要过滤的框架。默认情况下，仅测试可用框架的子集。如果设置为“all”，将测试所有可用的框架。也可以提供单个框架或一组自定义框架进行检查。

返回

Dict[str, List[str]]

一个字典，将任务名称映射到模型 ID 的排序列表。

列出部署在 Serverless Inference API 服务上的模型。

此助手逐框架检查已部署的模型。默认情况下，它将检查 4 个主要支持的框架，这些框架占托管模型的 95%。但是，如果您想要完整的模型列表，您可以指定 frameworks="all" 作为输入。或者，如果您事先知道您对哪个框架感兴趣，您也可以将搜索限制为该框架（例如 `frameworks="text-generation-inference"`）。检查的框架越多，所需时间就越长。

此端点方法不返回 Serverless Inference API 服务可用的所有模型的实时列表。它会在最近可用的模型缓存列表中搜索，并且该列表可能不是最新的。如果您想知道特定模型的实时状态，请使用 get_model_status()。

此端点方法主要用于发现。如果您已经知道要使用的模型并想检查其可用性，您可以直接使用 get_model_status()。

示例

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

# Discover zero-shot-classification models currently deployed
>>> models = await client.list_deployed_models()
>>> models["zero-shot-classification"]
['Narsil/deberta-large-mnli-zero-cls', 'facebook/bart-large-mnli', ...]

# List from only 1 framework
>>> await client.list_deployed_models("text-generation-inference")
{'text-generation': ['bigcode/starcoder', 'meta-llama/Llama-2-70b-chat-hf', ...], ...}

object_detection

( image: Union model: Optional = None threshold: Optional = None ) → List[ObjectDetectionOutputElement]

参数

image (Union[str, Path, bytes, BinaryIO]) — 要检测物体的图像。它可以是原始字节、图像文件或在线图像的 URL。
model (str, optional) — 用于对象检测的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。如果未提供，将使用对象检测的默认推荐模型 (DETR)。
threshold (float, optional) — 做出预测所需的概率。

返回

List[ObjectDetectionOutputElement]

包含边界框和相关属性的 ObjectDetectionOutputElement 项目列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError 或 ValueError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。
ValueError — 如果请求输出不是列表。

使用指定的模型在给定图像上执行对象检测。

如果要处理图像，则必须安装 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)), ...]

post

( json: Union = None data: Union = None model: Optional = None task: Optional = None stream: bool = False ) → bytes

参数

json (Union[str, Dict, List], optional) — 要在请求正文中发送的 JSON 数据，特定于每个任务。默认为 None。
data (Union[str, Path, bytes, BinaryIO], optional) — 要在请求正文中发送的内容，特定于每个任务。它可以是原始字节、指向已打开文件的指针、本地文件路径或在线资源（图像、音频文件等）的 URL。如果同时传递了 json 和 data，则 data 优先。必须提供 json 或 data 中的至少一个。默认为 None。
model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID 或已部署的 Inference Endpoint 的 URL。将覆盖实例级别定义的模型。默认为 None。
task (str, optional) — 要在推理上执行的任务。所有可用的任务都可以在这里找到。仅在未提供 model 时，用于默认为推荐模型。必须提供 model 或 task 中的至少一个。默认为 None。
stream (bool, optional) — 是否迭代流式 API。

返回

bytes

服务器返回的原始字节。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

向推理服务器发出 POST 请求。

question_answering

( question: str context: str model: Optional = None align_to_words: Optional = None doc_stride: Optional = None handle_impossible_answer: Optional = None max_answer_len: Optional = None max_question_len: Optional = None max_seq_len: Optional = None top_k: Optional = None ) → Union[QuestionAnsweringOutputElement, ListQuestionAnsweringOutputElement]

参数

question (str) — 要回答的问题。
context (str) — 问题的上下文。
model (str) — 用于问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署推理端点的 URL。
align_to_words (bool, 可选) — 尝试将答案与真实单词对齐。提高以空格分隔语言的质量。可能会损害非空格分隔语言（如日语或中文）的质量。
doc_stride (int, 可选) — 如果上下文太长而无法与问题一起放入模型，则会将其拆分为几个块，并带有一些重叠。此参数控制重叠的大小。
handle_impossible_answer (bool, 可选) — 是否接受“不可能”作为答案。
max_answer_len (int, 可选) — 预测答案的最大长度（例如，仅考虑长度较短的答案）。
max_question_len (int, 可选) — 令牌化后问题的最大长度。如果需要，将会被截断。
max_seq_len (int, 可选) — 传递给模型的每个块中总句子（上下文+问题）的最大令牌长度。如果需要，上下文将被拆分为几个块（使用 docStride 作为重叠）。
top_k (int, 可选) — 要返回的答案数量（将按可能性顺序选择）。请注意，如果上下文中没有足够的选项可用，我们返回的答案将少于 topk 个。

返回

Union[QuestionAnsweringOutputElement, ListQuestionAnsweringOutputElement]

当 top_k 为 1 或未提供时，它返回单个 QuestionAnsweringOutputElement。当 top_k 大于 1 时，它返回 QuestionAnsweringOutputElement 的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: str other_sentences: List model: Optional = None ) → List[float]

参数

sentence (str) — 要与其他句子比较的主句子。
other_sentences (List[str]) — 要比较的句子列表。
model (str, 可选) — 用于对话任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署推理端点的 URL。如果未提供，将使用默认推荐的对话模型。默认为 None。

返回

List[float]

表示输入文本的嵌入向量。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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]

summarization

( text: str parameters: Optional = None model: Optional = None clean_up_tokenization_spaces: Optional = None generate_parameters: Optional = None truncation: Optional = None ) → SummarizationOutput

参数

text (str) — 要总结的输入文本。
parameters (Dict[str, Any], 可选) — 摘要的附加参数。查看此页面了解更多详情。
model (str, 可选) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署推理端点的 URL。如果未提供，将使用默认推荐的摘要模型。
clean_up_tokenization_spaces (bool, 可选) — 是否清理文本输出中潜在的额外空格。
generate_parameters (Dict[str, Any], 可选) — 文本生成算法的附加参数化。
truncation (Literal["do_not_truncate", "longest_first", "only_first", "only_second"], 可选) — 要使用的截断策略。

返回

SummarizationOutput

生成的摘要文本。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Dict query: str model: Optional = None parameters: Optional = None ) → TableQuestionAnsweringOutputElement

参数

table (str) — 以列表字典形式表示的数据表，其中条目是标题，列表是所有值，所有列表必须具有相同的大小。
query (str) — 您要询问表格的纯文本查询。
model (str) — 用于表格问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署推理端点的 URL。
parameters (Dict[str, Any], 可选) — 附加推理参数。默认为 None。

返回

TableQuestionAnsweringOutputElement

一个表格问答输出，包含答案、坐标、单元格和使用的聚合器。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Dict model: Optional = None ) → List

参数

table (Dict[str, Any]) — 要分类的属性集。
model (str, 可选) — 用于表格分类任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署推理端点的 URL。如果未提供，将使用默认推荐的表格分类模型。默认为 None。

返回

List

初始表格中每行标签的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: Dict model: Optional = None ) → List

参数

table (Dict[str, Any]) — 存储在表中的一组属性。用于预测目标的属性可以是数值型和类别型。
model (str, optional) — 用于表格回归任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的表格回归模型。默认为 None。

返回

List

预测的数值目标值列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: str model: Optional = None top_k: Optional = None function_to_apply: Optional = None ) → List[TextClassificationOutputElement]

参数

text (str) — 要分类的字符串。
model (str, optional) — 用于文本分类任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的文本分类模型。默认为 None。
top_k (int, optional) — 当指定时，将输出限制为前 K 个最可能的类别。
function_to_apply ("TextClassificationOutputTransform", optional) — 应用于输出的函数。

返回

List[TextClassificationOutputElement]

包含预测标签和相关概率的 TextClassificationOutputElement 项的列表。

引发

InferenceTimeoutError 或 aiohttp.ClientResponseError

InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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: str details: bool = False stream: bool = False model: Optional = None adapter_id: Optional = None best_of: Optional = None decoder_input_details: Optional = None do_sample: Optional = False frequency_penalty: Optional = None grammar: Optional = None max_new_tokens: Optional = None repetition_penalty: Optional = None return_full_text: Optional = False seed: Optional = None stop: Optional = None stop_sequences: Optional = None temperature: Optional = None top_k: Optional = None top_n_tokens: Optional = None top_p: Optional = None truncate: Optional = None typical_p: Optional = None watermark: Optional = None ) → Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]

参数

prompt (str) — 输入文本。
details (bool, optional) — 默认情况下，text_generation 返回一个字符串。如果您需要详细的输出（tokens、概率、种子、完成原因等），请传递 details=True。仅适用于在 text-generation-inference 后端上运行的模型。
stream (bool, optional) — 默认情况下，text_generation 返回完整的生成文本。如果您需要返回 token 流，请传递 stream=True。仅适用于在 text-generation-inference 后端上运行的模型。
model (str, optional) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是部署的 Inference Endpoint 的 URL。此参数会覆盖实例级别定义的模型。默认为 None。
adapter_id (str, optional) — Lora 适配器 ID。
best_of (int, optional) — 生成 best_of 个序列，并返回 token 对数概率最高的序列。
decoder_input_details (bool, optional) — 返回解码器输入 token 的对数概率和 ID。您必须同时设置 details=True 才能使其生效。默认为 False。
do_sample (bool, optional) — 激活 logits 采样
frequency_penalty (float, optional) — 介于 -2.0 和 2.0 之间的数字。正值会根据新 token 在到目前为止的文本中出现的频率来惩罚新 token，从而降低模型逐字重复同一行的可能性。
grammar (TextGenerationInputGrammarType, optional) — 语法约束。可以是 JSONSchema 或正则表达式。
max_new_tokens (int, optional) — 生成 token 的最大数量
repetition_penalty (float, optional) — 重复惩罚参数。1.0 表示没有惩罚。有关更多详细信息，请参阅本文。
return_full_text (bool, optional) — 是否将提示词添加到生成的文本前面
seed (int, optional) — 随机采样种子
stop (List[str], optional) — 如果生成了 stop 的成员，则停止生成 token。
stop_sequences (List[str], optional) — 已弃用的参数。请改用 stop。
temperature (float, optional) — 用于调整 logits 分布的值。
top_n_tokens (int, optional) — 返回每个生成步骤中最有可能的 top_n_tokens 的信息，而不仅仅是采样的 token。
top_k (int, *optional`) — 用于 Top-k 过滤的最高概率词汇 tokens 的数量。
top_p (float, *optional) -- 如果设置为 < 1，则只保留概率总和达到或高于 `top_p` 的最小概率 tokens 集合用于生成。
truncate (int, *optional`) — 将输入 tokens 截断到给定的大小。
typical_p (float, *optional`) — 典型解码质量。更多信息请参阅自然语言生成的典型解码。
watermark (bool, *optional`) — 使用大型语言模型的水印进行水印。

  返回
 


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


从服务器返回的生成文本

如果 stream=False 且 details=False，则生成的文本将作为 str 返回（默认）。
如果 stream=True 且 details=False，则生成的文本将逐个 token 作为 Iterable[str] 返回。
如果 stream=False 且 details=True，则生成的文本将作为 TextGenerationOutput 返回，其中包含更多详细信息。
如果 details=True 且 stream=True，则生成的文本将逐个 token 作为 TextGenerationStreamOutput 的 iterable 返回。

 引发
 


ValidationError 或 InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



ValidationError — 如果输入值无效。不会向服务器发出 HTTP 调用。
InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

 给定一个提示，生成以下文本。
 API 端点应该与 text-generation-inference 后端（TGI）一起运行。此后端是在大规模运行大型语言模型的首选解决方案。但是，对于一些较小的模型（例如“gpt2”），默认的 transformers + api-inference 解决方案仍然在使用。两种方法都有非常相似的 API，但并非完全相同。此方法与两种方法都兼容，但某些参数仅适用于 text-generation-inference。如果某些参数被忽略，将触发警告消息，但该过程将继续正确执行。
 要了解有关 TGI 项目的更多信息，请参阅 https://github.com/huggingface/text-generation-inference。
  如果您想从聊天消息生成回复，则应使用 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
  < source > ( prompt: str negative_prompt: Optional = None height: Optional = None width: Optional = None num_inference_steps: Optional = None guidance_scale: Optional = None model: Optional = None scheduler: Optional = None target_size: Optional = None seed: Optional = None **kwargs  ) → Image
   参数 
  prompt (str) — 用于生成图像的提示文本。 
 negative_prompt (str, optional) — 用于图像生成的 可选的负面提示文本。 
 height (float, optional) — 要生成的图像的高度，以像素为单位。 
 width (float, optional) — 要生成的图像的宽度，以像素为单位。 
 num_inference_steps (int, optional) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会以较慢的推理速度为代价。 
 guidance_scale (float, optional) — 较高的 guidance scale 鼓励生成与文本 prompt 紧密相关的图像，但通常会以降低图像质量为代价。 
 model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的 text-to-image 模型。默认为 None。 
 scheduler (str, optional) — 使用兼容的 scheduler 覆盖默认 scheduler。 
 target_size (TextToImageTargetSize, optional) — 输出图像的像素大小。 
 seed (int, optional) — 随机数生成器的种子。 
  返回
 


图像
 
 


生成的图像。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

 使用指定的模型，根据给定的文本生成图像。
  如果要处理图像，则必须安装 PIL (pip install Pillow)。
   示例
 
 # 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")
  text_to_speech
  < source > ( text: str model: Optional = None do_sample: Optional = None early_stopping: Union = None epsilon_cutoff: Optional = None eta_cutoff: Optional = None max_length: Optional = None max_new_tokens: Optional = None min_length: Optional = None min_new_tokens: Optional = None num_beam_groups: Optional = None num_beams: Optional = None penalty_alpha: Optional = None temperature: Optional = None top_k: Optional = None top_p: Optional = None typical_p: Optional = None use_cache: Optional = None  ) → bytes
   参数 
  text (str) — 要合成的文本。 
 model (str, optional) — 用于推理的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署的 Inference Endpoint 的 URL。如果未提供，将使用默认推荐的 text-to-speech 模型。默认为 None。 
 do_sample (bool, optional) — 是否在生成新 tokens 时使用采样而不是贪婪解码。 
 early_stopping (Union[bool, "TextToSpeechEarlyStoppingEnum", optional) — 控制基于 beam 的方法的停止条件。 
 epsilon_cutoff (float, optional) — 如果设置为严格介于 0 和 1 之间的浮点数，则只会采样条件概率大于 epsilon_cutoff 的 tokens。在论文中，建议值范围为 3e-4 到 9e-4，具体取决于模型的大小。 有关更多详细信息，请参阅 作为语言模型 Desmoothing 的截断采样。 
 eta_cutoff (float, optional) — Eta 采样是局部典型采样和 epsilon 采样的混合。如果设置为严格介于 0 和 1 之间的浮点数，则仅当 token 大于 eta_cutoff 或 sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))) 时才会被考虑。后一个术语在直觉上是预期的下一个 token 概率，按 sqrt(eta_cutoff) 缩放。在论文中，建议值范围为 3e-4 到 2e-3，具体取决于模型的大小。 有关更多详细信息，请参阅 作为语言模型 Desmoothing 的截断采样。 
 max_length (int, optional) — 生成文本的最大长度（以 tokens 为单位），包括输入。 
 max_new_tokens (int, optional) — 要生成的最大 tokens 数。优先于 maxLength。 
 min_length (int, optional) — 生成文本的最小长度（以 tokens 为单位），包括输入。 
 min_new_tokens (int, optional) — 要生成的最小 tokens 数。优先于 maxLength。 
 num_beam_groups (int, optional) — 将 num_beams 分成几组，以确保不同 beam 组之间的多样性。 有关更多详细信息，请参阅 本文。 
 num_beams (int, optional) — 用于 beam search 的 beam 数量。 
 penalty_alpha (float, optional) — 该值平衡了对比搜索解码中的模型置信度和退化惩罚。 
 temperature (float, optional) — 用于调整下一个 token 概率的值。 
 top_k (int, optional) — 用于top-k过滤的最高概率词汇 tokens 的数量。 
 top_p (float, optional) — 如果设置为小于 1 的浮点数，则仅保留概率总和达到 top_p 或更高的最小概率词汇 tokens 集合，用于生成。 
 typical_p (float, optional) — 局部典型性度量了预测下一个目标 token 的条件概率与预测下一个随机 token 的预期条件概率（给定已生成的部分文本）的相似程度。如果设置为小于 1 的浮点数，则仅保留概率总和达到 typical_p 或更高的最小局部典型 tokens 集合，用于生成。 详见这篇论文。 
 use_cache (bool, optional) — 模型是否应使用过去的最后一次 key/values attentions 以加速解码。 
  返回
 


bytes
 
 


生成的音频。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

 合成一段语音，朗读给定的文本。
   示例
 
 # 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)
  token_classification
  < source > ( text: str model: Optional = None aggregation_strategy: Optional = None ignore_labels: Optional = None stride: Optional = None  ) → List[TokenClassificationOutputElement]
   参数 
  text (str) — 要分类的字符串。 
 model (str, optional) — 用于 token 分类任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署 Inference Endpoint 的 URL。 如果未提供，将使用默认的推荐 token 分类模型。默认为 None。 
 aggregation_strategy (Literal["none", "simple", "first", "average", "max"], optional) — 用于基于模型预测融合 tokens 的策略。 
 ignore_labels (List[str], optional) — 要忽略的标签列表。 
 stride (int, optional) — 当分割输入文本时，chunks 之间的重叠 tokens 数量。 
  返回
 


List[TokenClassificationOutputElement]
 
 


包含实体组、置信度分数、单词、起始和结束索引的 TokenClassificationOutputElement 条目的列表。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 HTTP 错误状态代码不是 HTTP 503。

 对给定的文本执行 token 分类。 通常用于句子解析，无论是语法解析还是命名实体识别 (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,
    )
]
  translation
  < source > ( text: str model: Optional = None src_lang: Optional = None tgt_lang: Optional = None clean_up_tokenization_spaces: Optional = None truncation: Optional = None generate_parameters: Optional = None  ) → TranslationOutput
   参数 
  text (str) — 要翻译的字符串。 
 model (str, optional) — 用于翻译任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署 Inference Endpoint 的 URL。 如果未提供，将使用默认的推荐翻译模型。默认为 None。 
 src_lang (str, optional) — 文本的源语言。对于可以从多种语言翻译的模型是必需的。 
 tgt_lang (str, optional) — 要翻译成的目标语言。对于可以翻译成多种语言的模型是必需的。 
 clean_up_tokenization_spaces (bool, optional) — 是否清理文本输出中潜在的额外空格。 
 truncation (Literal["do_not_truncate", "longest_first", "only_first", "only_second"], optional) — 要使用的截断策略。 
 generate_parameters (Dict[str, Any], optional) — 文本生成算法的附加参数。 
  返回
 


TranslationOutput
 
 


生成的翻译文本。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError 或 ValueError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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
  < source > ( image: Union question: str model: Optional = None top_k: Optional = None  ) → List[VisualQuestionAnsweringOutputElement]
   参数 
  image (Union[str, Path, bytes, BinaryIO]) — 上下文的输入图像。它可以是原始字节、图像文件或在线图像的 URL。 
 question (str) — 要回答的问题。 
 model (str, optional) — 用于视觉问答任务的模型。可以是 Hugging Face Hub 上托管的模型 ID，也可以是已部署 Inference Endpoint 的 URL。 如果未提供，将使用默认的推荐视觉问答模型。默认为 None。 
 top_k (int, optional) — 要返回的答案数量（将按可能性顺序选择）。请注意，如果上下文中没有足够的选项，我们返回的答案将少于 topk 个。 
  返回
 


List[VisualQuestionAnsweringOutputElement]
 
 


包含预测标签和相关概率的 VisualQuestionAnsweringOutputElement 项目列表。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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
  < source > ( text: str labels: List multi_label: bool = False hypothesis_template: Optional = None model: Optional = None  ) → List[ZeroShotClassificationOutputElement]
   参数 
  text (str) — 要分类的输入文本。 
 labels (List[str]) — 字符串列表。每个字符串是输入文本的可能标签的文字描述。 
 multi_label (bool) — 布尔值。如果为 True，则独立评估每个标签的概率，并且多个标签可以同时具有接近 1 的概率，或者所有概率都可以接近 0。如果为 False，则标签被认为是互斥的，并且所有标签的概率总和始终为 1。默认为 False。 
 hypothesis_template (str, optional) — 带有花括号的模板句子字符串，标签字符串将添加到其中。标签字符串被添加到花括号“{}”的位置。 Zero-shot 分类器基于 NLI 模型，该模型评估一个假设是否在另一个文本中被蕴含。 例如，使用 hypothesis_template=“This text is about {}.” 和 labels=[“economics”, “politics”]，系统内部创建两个假设 “This text is about economics.” 和 “This text is about politics.”。 然后模型评估这两个假设是否在提供的 text 中被蕴含。 
 model (str, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是已部署推理端点的 URL。此参数会覆盖实例级别定义的模型。如果未提供，将使用默认推荐的零样本分类模型。 
  返回
 


List[ZeroShotClassificationOutputElement]
 
 


包含预测标签及其置信度的 ZeroShotClassificationOutputElement 项目列表。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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.",
...    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
  < source > ( image: Union labels: List model: Optional = None hypothesis_template: Optional = None  ) → List[ZeroShotImageClassificationOutputElement]
   参数 
  image (Union[str, Path, bytes, BinaryIO]) — 用于添加标题的输入图像。它可以是原始字节、图像文件或在线图像的 URL。 
 labels (List[str]) — 可能标签的字符串列表。必须至少有 2 个标签。 
 model (str, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID，也可以是已部署推理端点的 URL。此参数会覆盖实例级别定义的模型。如果未提供，将使用默认推荐的零样本图像分类模型。 
 hypothesis_template (str, 可选) — 与 labels 结合使用的句子，通过将占位符替换为候选标签来尝试文本分类。 
  返回
 


List[ZeroShotImageClassificationOutputElement]
 
 


包含预测标签及其置信度的 ZeroShotImageClassificationOutputElement 项目列表。
 引发
 


InferenceTimeoutError 或 aiohttp.ClientResponseError
 
 



InferenceTimeoutError — 如果模型不可用或请求超时。
aiohttp.ClientResponseError — 如果请求失败，并且 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",
...     labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]

   InferenceTimeoutError
  class huggingface_hub.InferenceTimeoutError
  < source > ( *args **kwargs  )
      
 当模型不可用或请求超时时引发的错误。
   ModelStatus
  class huggingface_hub.inference._common.ModelStatus
  < source > ( loaded: bool state: str compute_type: Dict framework: str  )
   参数 
  loaded (bool) — 如果模型当前已加载到 Hugging Face 的 InferenceAPI 中。模型是按需加载的，这会导致用户的首次请求花费更长的时间。如果模型已加载，则可以确保它处于健康状态。 
 state (str) — 模型的当前状态。可以是 ‘Loaded’、‘Loadable’、‘TooBig’。如果模型的状态为 ‘Loadable’，则表示它不太大并且具有受支持的后端。“Loadable” 模型会在用户首次请求端点上的推理时自动加载。这意味着用户加载模型是透明的，除了第一次调用需要更长的时间才能完成。 
 compute_type (Dict) — 关于模型正在使用或将要使用的计算资源的信息，例如 ‘gpu’ 类型和副本数量。 
 framework (str) — 构建模型所使用的框架的名称，例如 ‘transformers’ 或 ‘text-generation-inference’。 
   
 此 Dataclass 表示 Hugging Face Inference API 中的模型状态。
   InferenceAPI
 InferenceAPI 是调用 Inference API 的传统方法。该接口更简单，需要了解每个任务的输入参数和输出格式。它也缺乏连接到其他服务（如 Inference Endpoints 或 AWS SageMaker）的能力。InferenceAPI 即将弃用，因此我们建议尽可能使用 InferenceClient。查看本指南，了解如何在脚本中从 InferenceAPI 切换到 InferenceClient。
  class huggingface_hub.InferenceApi
  < source > ( repo_id: str task: Optional = None token: Optional = None gpu: bool = False  )
      
 用于配置请求并调用 HuggingFace Inference API 的客户端。
   示例
 
 >>> from huggingface_hub.inference_api import InferenceApi

>>> # Mask-fill example
>>> inference = InferenceApi("bert-base-uncased")
>>> inference(inputs="The goal of life is [MASK].")
[{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}]

>>> # Question Answering example
>>> inference = InferenceApi("deepset/roberta-base-squad2")
>>> inputs = {
...     "question": "What's my name?",
...     "context": "My name is Clara and I live in Berkeley.",
... }
>>> inference(inputs)
{'score': 0.9326569437980652, 'start': 11, 'end': 16, 'answer': 'Clara'}

>>> # Zero-shot example
>>> inference = InferenceApi("typeform/distilbert-base-uncased-mnli")
>>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!"
>>> params = {"candidate_labels": ["refund", "legal", "faq"]}
>>> inference(inputs, params)
{'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]}

>>> # Overriding configured task
>>> inference = InferenceApi("bert-base-uncased", task="feature-extraction")

>>> # Text-to-image
>>> inference = InferenceApi("stabilityai/stable-diffusion-2-1")
>>> inference("cat")
<PIL.PngImagePlugin.PngImageFile image (...)>

>>> # Return as raw response to parse the output yourself
>>> inference = InferenceApi("mio/amadeus")
>>> response = inference("hello world", raw_response=True)
>>> response.headers
{"Content-Type": "audio/flac", ...}
>>> response.content # raw bytes from server
b'(...)'
  __init__
  < source > ( repo_id: str task: Optional = None token: Optional = None gpu: bool = False  )
   参数 
  repo_id (str) — 仓库的 ID (例如 user/bert-base-uncased)。 
 task (str, 可选, 默认为 None) — 是否强制执行任务，而不是使用仓库中指定的任务。 
 token (str, 可选) — 用作 HTTP Bearer 授权的 API 令牌。这不是身份验证令牌。您可以在 https://huggingface.co/settings/token 中找到令牌。或者，您可以使用 HfApi().whoami(token) 找到您的组织和个人 API 令牌。 
 gpu (bool, 可选, 默认为 False) — 是否使用 GPU 而不是 CPU 进行推理（至少需要 Startup 计划）。 
   
 初始化标头和 API 调用信息。
  __call__
  < source > ( inputs: Union = None params: Optional = None data: Optional = None raw_response: bool = False  )
   参数 
  inputs (str 或 Dict 或 List[str] 或 List[List[str]], 可选) — 预测的输入。 
 params (Dict, 可选) — 模型的其他参数。将作为有效负载中的 parameters 发送。 
 data (bytes, 可选) — 请求的字节内容。在这种情况下，请将 inputs 和 params 留空。  
 raw_response (bool, 默认为 False) — 如果为 True，则返回原始的 Response 对象。您可以根据需要解析其内容。默认情况下，内容将被解析为更实用的格式（例如 json 字典或 PIL 图像）。  
   
 调用 Inference API。
 < > 在 GitHub 上更新


				←推理类型 推理端点→


		



推理 推理 客户端 异步 推理 客户端 推理超时错误 模型状态 推理API