推理
推理是使用训练好的模型对新数据进行预测的过程。由于这个过程可能非常计算密集,在一个专用服务器上运行可能是一个不错的选择。《huggingface_hub》库提供了一个轻松调用运行托管模型推理服务的简单方法。您可以连接到多个服务
- 推理API:一种允许您在Hugging Face的基础设施上免费运行加速推理的服务。这是一个快速上手、测试不同模型和原型AI产品的快捷方式。
- 推理端点:一种简单方便的产品,可以轻松部署模型到生产环境。推理在您选择的云服务提供商的专用、全管理基础设施上由Hugging Face运行。
您可以使用InferenceClient对象调用这些服务。请参阅本指南以获取如何使用它的更多信息。
Inference Client
类 huggingface_hub.InferenceClient
< 源代码 >( model: 可选 = None token: 联合 = None timeout: 可选 = None headers: 可选 = None cookies: 可选 = None proxies: 可选 = None base_url: 可选 = None api_key: 可选 = None )
参数
- model (
str
,optional
) — 运行推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID,例如meta-llama/Meta-Llama-3-8B-Instruct
或指向部署的推理端点的 URL。默认为 None,在这种情况下,将自动选择推荐的模型。注意:为了更好地兼容 OpenAI 的客户端,model
已被别名为base_url
。这两个参数互斥,并具有相同的操作行为。 - token (
str
或bool
, optional) — Hugging Face token。如果不提供,则默认为本地保存的 token。如果要向服务器发送 token,请传递token=False
。注意:为了更好地兼容 OpenAI 的客户端,token
已被别名为api_key
。这两个参数互斥,并具有相同的操作行为。 - timeout (
float
,可选
) — 等待服务器响应的最大秒数。在推理API中加载新模型可能需要几分钟。默认为 None,表示将循环直到服务器可用。 - headers (
Dict[str, str]
,可选
) — 向服务器发送的额外头信息。默认情况下,仅发送授权和用户代理头信息。此字典中的值将覆盖默认值。 - cookies (
Dict[str, str]
,可选
) — 向服务器发送的额外cookie。 - base_url (
str
,optional
) — 运行推理的基本URL。这是从model
对象中复制的参数,以使InferenceClient遵循与openai.OpenAI
客户端相同的模式。如果设置了model
,则无法使用。默认为None。 - api_key (
str
,optional
) — 用于认证的令牌。这是从token
中复制的参数,以使InferenceClient遵循与openai.OpenAI
客户端相同的模式。如果设置了token
,则无法使用。默认为None。
使用Inference Client初始化一个新的客户端。
InferenceClient旨在提供执行推理的统一体验。该客户端可以无缝地与(免费的)推理API或自托管的推理端点一起使用。
音频分类
< 源码 >( audio: 联合 model: 可选 = None ) → 列表[音频分类输出元素]
对提供的音频内容执行音频分类。
audio_to_audio
< source >( audio: Union model: Optional = None ) → List[AudioToAudioOutputElement]
参数
- audio (Union[str, Path, bytes, BinaryIO]) — 模型使用的音频内容。它可以是有声音频字节、本地音频文件或指向音频文件的URL。
- model (
str
, 可选) — 模型可以是任何接受音频文件并返回另一个音频文件的模型。可以是托管在Hugging Face Hub上的模型ID,或指向部署的推理端点的URL。如果未提供,将使用audio_to_audio推荐的默认模型。
返回
List[AudioToAudioOutputElement]
包含音频标签、内容类型和blob中音频内容的AudioToAudioOutputElement项目列表(请参阅AudioToAudioOutputElement)。
抛出
InferenceTimeoutError
或 HTTPError
InferenceTimeoutError
— 如果模型不可用或请求超时。HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
根据模型执行多种与音频到音频相关的任务(例如:语音增强、源分离)。
自动语音识别
< 源 >( audio: 联合类型 model: 可选 = None ) → AutomaticSpeechRecognitionOutput
对给定的音频内容执行自动语音识别(ASR或音频到文本)。
聊天完成
< 源 >( messages:列表 model:可选 = None stream:布尔值 = False frequency_penalty:可选 = None logit_bias:可选 = None logprobs:可选 = None max_tokens:可选 = None n:可选 = None presence_penalty:可选 = None response_format:可选 = None seed:可选 = None stop:可选 = None temperature:可选 = None tool_choice:Union = None tool_prompt:可选 = None tools:可选 = None top_logprobs:可选 = None top_p:可选 = None ) → ChatCompletionOutput 或 Iterable of ChatCompletionStreamOutput
参数
- messages (List[Union[
SystemMessage
,UserMessage
,AssistantMessage
]]) —— 由角色和内容对组成的对话历史记录。 - 模型 (
str
, 可选) — 用于聊天生成的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署推理端的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 (
浮点数列表
, 可选) — 修改指定标记在补全中出现的机会。接受一个 将标记映射到关联偏置值的 JSON 对象 (-100 到 100),偏置值由标记 ID(在词法分析器中指定)。在模型产生的 logit 前添加偏置。具体效果因模型而异,但 -1 到 1 之间的值应该会增加或减少选择的可能性;例如 -100 或 100 应该会造成禁用或独占选择相关标记。默认为 None。 - logprobs (
布尔值
, 可选) — 是否返回输出标记的对数概率。如果为真,则在消息内容中返回每个输出标记的对数概率。 - max_tokens (
整数
, 可选) — 响应中允许的最多标记数。默认为 20。 - n (
int
, optional) — 未使用。 - presence_penalty (
float
, optional) — 数值在 -2.0 到 2.0 之间。正值会根据新 token 是否出现在文本中来惩罚,增加模型讨论新话题的可能性。 - response_format (ChatCompletionInputGrammarType, optional) — 语法约束。可以是 JSONSchema 或正则表达式。
- seed (可选
int
, 可选) — 可复现控制流的随机数。默认为 None。 - stop (可选
str
, 可选) — 触发响应结束的四字符串。默认为 None。 - stream (
bool
, 可选) — 启用响应的实时流。默认为 False。 - temperature (
float
, 可选) — 控制生成的随机性。较低值确保更少的随机补全。范围:[0, 2]。默认为 1.0。 - top_logprobs (
int
,可选)—— 在每个位置返回可能性最高的token数量(每个token都有相关的对数概率)。如果使用此参数,则必须将logprobs设置为true。 - top_p (
float
,可选)—— 从最可能的下一个单词中采样的分数。必须在0和1之间。默认为1.0。 - tool_choice(《huggingface_hub.ChatCompletionInputToolTypeClass》或
str
,可选)—— 用于完成的工具。默认为“auto”。 - tool_prompt (
str
, 可选) — 在工具之前附加的提示。 - tools (ChatCompletionInputTool列表,可选) — 模型可能调用的工具列表。目前只支持作为工具的函数。使用此方法提供模型可能生成JSON输入的函数列表。
返回
从服务器返回的生成的文本
- 如果
stream=False
,则生成的文本作为 ChatCompletionOutput 返回(默认)。 - 如果
stream=True
,则生成的文本按顺序以一系列 ChatCompletionStreamOutput 返回。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
使用指定的语言模型完成对话的方法。
client.chat_completion
方法作为与 OpenAI 客户端兼容而别名为 client.chat.completions.create
。输入和输出严格相同,使用任一语法会产生相同的结果。有关 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
)
)
示例(stream=True)
>>> 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)
使用 tools 的示例
>>> 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"}'
conversational
< 源代码 >( text: str generated_responses: Optional = None past_user_inputs: Optional = None parameters: Optional = None model: Optional = None ) → Dict
参数
- text (
str
) — 对话中用户的最后输入。 - generated_responses (
List[str]
, optional) — 对应于模型早期回复的字符串列表。默认为 None。 - past_user_inputs (
List[str]
, 可选) — 用户之前回复的字符串列表。应与generated_responses
的长度相同。默认值为 None。 - parameters (
Dict[str, Any]
, 可选) — 对话任务的附加参数。默认值为 None。有关可用参数的更多详细信息,请参阅 此页面 - model (
str
, 可选) — 用于对话任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向推理端点的 URL。如果没有提供,将使用默认推荐的对话模型。默认值为 None。
返回
Dict
生成的对话输出。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
根据给定的输入文本生成对话响应(即与 API 聊天)。
InferenceClient.conversational() API 已弃用,将在未来的版本中删除。请使用 InferenceClient.chat_completion() 代替。
示例
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> output = client.conversational("Hi, who are you?")
>>> output
{'generated_text': 'I am the one who knocks.', 'conversation': {'generated_responses': ['I am the one who knocks.'], 'past_user_inputs': ['Hi, who are you?']}, 'warnings': ['Setting `pad_token_id` to `eos_token_id`:50256 for open-end generation.']}
>>> client.conversational(
... "Wow, that's scary!",
... generated_responses=output["conversation"]["generated_responses"],
... past_user_inputs=output["conversation"]["past_user_inputs"],
... )
document_question_answering
< source >( image: 联合 question: str model: 可选 = None ) → List[DocumentQuestionAnsweringOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 上下文输入的图像。它可以是最原始的字节、图像文件,或网络图像的URL。 - question (
str
) — 需要回答的问题。 - 模型(《code`optional)— 用于文档问答任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向推理端点的 URL。如果不提供,则将使用默认推荐文档问答模型。默认为 None。
返回
列表[DocumentQuestionAnsweringOutputElement]
包含预测标签、相关概率、单词 ID 和页码的 DocumentQuestionAnsweringOutputElement 项目列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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(score=0.42515629529953003, answer='us-001', start=16, end=16)]
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,或指向部署推断端点的URL。如果不提供,则使用默认推荐的对话模型。默认为None。
- normalize (bool, optional) — 是否对嵌入向量进行归一化。仅在由Text-Embedding-Inference提供支持的服务器上可用。默认为None。
- prompt_name (str, 可选) - 需要用于编码的提示名称。如果未设置,将不应用任何提示。必须在 Sentence Transformers 配置的 prompts 字典中是一个关键字。例如,如果
prompt_name
是 "query" 且prompts
为 {"query": "query: ",……},则句子 "法国的首都是什么?" 将编码为 "query: 法国首都是什么?",因为提示文本将添加到编码的任何文本之前。 - truncate (bool, 可选) - 是否截断嵌入。默认为 None。仅在由 Text-Embedding-Inference 服务的服务器上可用。
- truncation_direction (Literal["Left", "Right"], 可选) - 当传递 truncate=True 时应截断输入的哪一侧。
返回
np.ndarray
将输入文本表示为浮点32位 numpy 数组的嵌入。
抛出
[InferenceTimeoutError] 或 HTTPError
- [InferenceTimeoutError] - 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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 ) → 列表[填遮罩输出元素]
参数
- text (
str
) — 要填入的字符串,必须包含 [MASK] 标记(请查看模型卡片以获取 Mask 名称的准确名称)。 - model (
str
, 可选) — 用于填充遮罩任务的模式。可以是托管在 Hugging Face Hub 上的模型 ID 或部署的推理端点的 URL。如果没有提供,将使用默认推荐的填充遮罩模型。默认为 None。
返回
列表[填遮罩输出元素]
包含预测标签、相关概率、标记引用和完成文本的FillMaskOutputElement项列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
用缺失的词(精确来说是标记)填充空缺。
示例
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.fill_mask("The goal of life is <mask>.")
[
FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]
get_endpoint_info
< 源代码 >( 模型: 可选 = 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
< 源代码 >( 模型: 可选项 = None ) → 模型状态
参数
- 模型 (
str
, 可选) — 要检查状态的模型的标识符。如果没有提供模型,将使用与 InferenceClient 实例关联的模型。只能检查 InferenceAPI 服务,因此标识符不能是 URL。
返回
模型状态
ModelStatus 数据类的实例,包含有关模型状态的信息:加载、状态、计算类型和框架。
获取 Inference API 上托管模型的状态。
此端点在您已知想要使用的模型并希望检查其可用性时非常有用。如果您想发现已部署的模型,则应使用 list_deployed_models()。
get_recommended_model
< 源代码 >( 任务: str ) → str
参数
- task (
str
) — 获取Hugging Face推荐的模型的Hugging Face任务。所有可用的任务可在此处找到。此处。
返回
str
输入任务的推荐模型名称。
抛出
ValueError
ValueError
— 如果Hugging Face没有为输入任务提供推荐。
获取输入任务Hugging Face推荐的模型。
health_check
< source >( model: Optional = None ) → bool
检查部署端点的健康。
健康检查仅在由Text-Generation-Inference (TGI)或Text-Embedding-Inference (TEI)支持的推理端点可用。对于推理API,请使用InferenceClient.get_model_status()代替。
图像分类
< 源 >( image: 合并 model: 可选 = None ) → ImageClassificationOutputElement列表
参数
- image (
Union[str, 路径, bytes, BinaryIO]
) —要进行分类的图像。它可以是最原始的字节,一个图像文件,或指向在线图像的URL。 - 模型 (
str
, 可选) — 用于图像分类的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署的推理端点的URL。如果没有提供,将使用默认推荐的图像分类模型。
返回
ImageClassificationOutputElement的列表
包含预测标签和相关概率的ImageClassificationOutputElement项的列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
使用指定的模型在给定的图像上执行图像分类。
图像分割
< 源 >( 图像 : Union 模型 : Optional = None ) → ImageSegmentationOutputElement的列表
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 要分割的图像。可以是原始字节、图像文件或在线图像的URL。 - model (
str
, 可选) — 用于图像分割的模型。可以是托管在Hugging Face Hub上的模型ID或部署的推理端点的URL。如果没有提供,将使用默认推荐模型进行图像分割。
返回
ImageSegmentationOutputElement列表
包含分割掩码及其相关属性的ImageSegmentationOutputElement项的列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
使用指定的模型在给定图像上执行图像分割。
如果您想处理图像,您必须安装PIL
(执行pip install Pillow
)。
image_to_image
< source >( image: 联合 prompt: 可选 = None negative_prompt: 可选 = None height: 可选 = None width: 可选 = None num_inference_steps: 可选 = None guidance_scale: 可选 = None model: 可选 = None **kwargs ) → Image
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 输入图像进行翻译。可以是原始字节、图像文件或在线图像的URL。 - prompt (
str
, 可选) — 指导图像生成的文本提示。 - 负提示(str,可选):用于指导翻译过程的负提示。
- 高度(int,可选)- 生成图像的高度(以像素为单位)。
- 宽度(int,可选)- 生成图像的宽度(以像素为单位)。
- 推理步骤数量(int,可选)- 去噪步骤的数量。更多的去噪步骤通常会导致图像质量更高,但推理速度会变慢。
- 指导比例 (
float
, 可选) — 较高的指导比例鼓励生成与文本prompt
密切相关的图像,通常会牺牲图像质量。 - 模型 (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。此参数覆盖了实例级别定义的模型。默认值为 None。
返回
图像
翻译后的图像。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
使用指定的模型执行图像到图像的翻译。
如果您想处理图像,您必须安装PIL
(执行pip install Pillow
)。
image_to_text
< 来源 >( 图像: 联合 模型: 可选 = None ) → ImageToTextOutput
接收输入图像并返回文本。
模型的输出可能完全不同,具体取决于您的用例(图像标题、光学字符识别(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
< source >( frameworks: Union = None ) → Dict[str, List[str]]
列出在Serverless Inference API服务上部署的模型。
此辅助程序通过框架逐一检查已部署的模型。默认情况下,它将检查受支持的4个主要框架,这些框架占托管模型总数的95%。但是,如果您希望获得模型的完整列表,可以在输入中将 frameworks="all"
设置为“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', ...], ...}
目标检测
< 源码 >参数
返回
列表[ObjectDetectionOutputElement]
包含边界框和关联属性的ObjectDetectionOutputElement项目的列表。
抛出
推理超时错误或HTTPError
或ValueError
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。ValueError
— 如果请求输出不是列表。
使用指定模型在给定图像上执行目标检测。
如果您想处理图像,您必须安装PIL
(执行pip install Pillow
)。
POST
< 源代码 >( json: 联合 = None data: 联合 = None model: 可选 = None task: 可选 = None stream: 布尔 = False ) → bytes
参数
- json (
Union[str, Dict, List]
, 可选) — 请求体中要发送的JSON数据,具体到每个任务。默认为None。 - data (
Union[str, Path, bytes, BinaryIO]
, 可选) — 请求体中要发送的内容,针对每个任务特定。可以是原始字节数据、指向打开文件的指针、本地文件路径或在线资源(图像、音频文件等)的URL。如果同时传递了json
和data
,则data
将具有优先权。至少需要提供json
或data
。默认值为None。 - model (
str
, 可选) — 用于推理的模型。可以是托管在Hugging Face Hub上的模型ID或部署的推理端点的URL。将覆盖实例级别的模型定义。默认值为None。 - task (
str
, 可选) — 在推理过程中要执行的任务。所有可用的任务可以在这里找到。仅在未提供model
时用作默认推荐模型。至少需要提供model
或task
。默认值为None。 - stream (
bool
, optional) — 是否迭代流式API。
返回
bytes
服务器返回的原始字节。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
向推理服务器发起POST请求。
问答
< 源 >( 问题: str 上下文: str 模型: Optional = None ) → 问答输出元素
从给定文本中检索问题的答案。
句子相似度
< source >( sentence: str other_sentences: 列表 model: 可选 = None ) → 列表[float]
通过比较嵌入来计算句子与其他句子之间的语义相似度。
示例
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.sentence_similarity(
... "Machine learning is so easy.",
... other_sentences=[
... "Deep learning is so straightforward.",
... "This is so difficult, like rocket science.",
... "I can't believe how much I struggled with this.",
... ],
... )
[0.7785726189613342, 0.45876261591911316, 0.2906220555305481]
总结
< 源代码 >( text: str parameters: Optional = None model: Optional = None ) → SummarizationOutput
使用指定的模型对给定文本生成摘要。
table_question_answering
< 源代码 >( table: Dict query: str model: Optional = None ) → TableQuestionAnsweringOutputElement
从表中的信息检索问题的答案。
示例
>>> 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
< source >( table: Dict model: Optional = None ) → List
根据一组属性对目标类别(组)进行分类。
示例
>>> 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
< source >( table: Dict model: Optional = None ) → List
根据表格中一组属性/特征预测数值型目标值。
示例
>>> 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: str model: Optional = None ) → List[TextClassificationOutputElement]
参数
- text (
str
) — 要分类的字符串。 - model (
str
, 可选) — 用于文本分类任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。如果不提供,则默认推荐使用文本分类模型。默认为 None。
返回
List[TextClassificationOutputElement]
包含预测标签和相关概率的 TextClassificationOutputElement 元素列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
在给定文本上执行文本分类(例如,情感分析)。
text_generation
< source >( 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_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返回一个字符串。如果需要详细输出(标记、概率、种子、完成原因等),请传递details=True
。仅当模型运行在使用text-generation-inference
的后端时可用。 - stream (
bool
, 可选) — 默认情况下,text_generation返回全部生成的文本。如果需要返回标记流,请传递stream=True
。仅当模型在运行text-generation-inference
后端时可用。 - 模型 (
str
, 可选) — 用于推理的模型。可以是托管在Hugging Face Hub上的模型ID或者指向部署的推理端点的URL。此参数将覆盖实例级别的模型定义。默认为None。 - adapter_id (
str
, 可选) — Lora适配器ID。 - best_of (
int
, 可选) — 生成最佳序列并返回拥有最高token logprob的序列。 - decoder_input_details (
bool
, 可选) — 返回解码器输入标记的对数概率和ids。您还必须设置details=True
,以便将其考虑在内。默认为False
。 - do_sample (
bool
, 可选) — 激活logits采样 - frequency_penalty (
float
, 可选) — 在-2.0和2.0之间的数字。正值根据新标记到目前为止在文本中的频率进行惩罚,减少模型重复同一行的可能性。 - 语法 (TextGenerationInputGrammarType, 可选) — 语法约束。可以是 JSONSchema 或正则表达式。
- max_new_tokens (
int
, 可选) — 生成令牌的最大数量 - repetition_penalty (
float
, 可选) — 重复惩罚参数。1.0 表示没有惩罚。详见 这份论文。 - return_full_text (
bool
, optional) — 是否将提示添加到生成的文本之前 - seed (
int
, optional) — 随机抽样种子 - stop_sequences (
List[str]
, optional) — 在生成stop_sequences
中的成员时停止生成标记 - temperature (
float
, optional) — 用于模型 logit 分布的值 - top_n_tokens (
int
, 可选) — 返回每个生成步骤中概率最高的 top_n_tokens 令牌的信息,而不是只返回采样的令牌。 - top_k (
int
, 可选) — 表示 top-k-filtering 保留的最高概率词汇令牌的数量。 - top_p (
float
, 可选) — 如果设置为 < 1,则只保留概率之和达到 top_p 或更高的最小概率令牌集进行生成。 - truncate (
int
, *可选`) — 将输入令牌截断到指定大小。 - typical_p (
float
, *可选`) — 特定解码质量。详见自然语言生成的典型解码获取更多更多信息 - watermark (
bool
, *可选`) — 使用大型语言模型的水印进行水印
返回
类型联合[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]
从服务器返回的生成的文本
- 如果
stream=False
并且details=False
,则生成的文本以str
形式返回(默认) - 如果
stream=True
并且details=False
,则生成的文本作为Iterable[str]
形式逐个令牌返回 - 如果
stream=False
并且details=True
,则生成的文本作为包含更多细节的 TextGenerationOutput 返回 - 如果
details=True
并且stream=True
,则生成的文本作为 TextGenerationStreamOutput 的可迭代序列逐个令牌返回
抛出
ValidationError
或 InferenceTimeoutError 或 HTTPError
ValidationError
— 如果输入值无效。不会向服务器发起HTTP调用。- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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
< 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 **kwargs ) → Image
参数
- prompt (
str
) — 用于生成图像的提示信息。 - negative_prompt (
str
, 可选) — 用于图像生成的可选负面提示信息。 - height (
float
, 可选) — 生成图像的像素高度。 - width (
float
, 可选) — 生成图像的宽度(像素)。 - num_inference_steps (
int
, 可选) — 鼓噪声步数。更多的降噪步骤通常会使图像质量更高,但推理速度会变慢。 - guidance_scale (
float
, 可选) — 较高的指导尺度倾向于生成与文本提示
密切相关的图像,通常以牺牲图像质量为代价。 - model (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 的模型 ID 或指向已部署推理端点的 URL。此参数覆盖在实例级别定义的模型。默认为 None。
返回
图像
生成的图像。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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
< source >( text: str model: Optional = None ) → bytes
合成给定文本的语音音频。
token_classification
< 源代码 >( text: str model: Optional = None ) → List[TokenClassificationOutputElement]
参数
- text (
str
) — 需要分类的字符串。 - 模型 (
str
, 可选) — 用于标记分类任务的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署的推理端点的URL。如果未提供,将使用默认推荐的标记分类模型。默认为None。
返回
TokenClassificationOutputElement列表
包含实体组、置信度分数、单词、起始和结束索引的TokenClassificationOutputElement项目列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且HTTP错误状态码不是HTTP 503。
对给定的文本执行标记分类。通常用于句子解析,无论是语法还是命名实体识别(NER),以便理解文本中的关键字。
示例
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
TokenClassificationOutputElement(
entity_group='PER',
score=0.9971321225166321,
word='Sarah Jessica Parker',
start=11,
end=31,
),
TokenClassificationOutputElement(
entity_group='PER',
score=0.9773476123809814,
word='Jessica',
start=52,
end=59,
)
]
翻译
< source >( text: str model: Optional = None src_lang: Optional = None tgt_lang: Optional = None ) →
参数
- text (
str
) — 要翻译的字符串。 - model (
str
, 可选) — 用于翻译任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向部署的推理端点的 URL。如果未提供,将使用默认推荐翻译模型。默认为 None。 - src_lang (
str
, 可选) — 翻译任务的源语言,即输入语言。必须与tgt_lang
一起传递。 - tgt_lang (
str
, 可选) — 翻译任务的目标语言,即输出语言。在没有src_lang
的情况下不能传递。
返回
生成的翻译文本。
抛出
推理超时错误或HTTPError
或ValueError
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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.')
可视化问答
< source >( 图像: Union 问题: str 模型: Optional = None ) → List[VisualQuestionAnsweringOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 传入图像的上下文。可以是原始字节、图像文件或在线图像的URL。 - question (
str
) — 要回答的问题。 - model (
str
, 可选) — 用于视觉问答任务的模型。可以是托管在Hugging Face Hub上的模型ID或部署推理端点的URL。如果未提供,将使用默认推荐的视觉问答模型。默认为None。
返回
List[VisualQuestionAnsweringOutputElement]
一个包含预测标签和关联概率的VisualQuestionAnsweringOutputElement项目列表。
抛出
InferenceTimeoutError
或 HTTPError
InferenceTimeoutError
— 如果模型不可用或请求超时。HTTP错误
— 如果请求失败,并且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
< 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
, 可选) — 带有花括号的模板句子字符串,其中的标签字符串将被添加。标签字符串将被添加到花括号 “{}” 所在的位置。零样本分类器基于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。此参数覆盖实例级定义的模型。默认为None。
返回
List[ZeroShotClassificationOutputElement]
包含预测标签和它们置信度的ZeroShotClassificationOutputElement项目列表。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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: 列表 model: 可选 = None ) → List[ZeroShotImageClassificationOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 输入图像以进行标题。它可以原始字节,图像文件或在线图像的URL。 - labels (
List[str]
) — 可能标签的字符串列表。必须有至少2个标签。 - model (
str
, optional) — 用于推理的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署的推理端点的URL。此参数将覆盖实例级别上定义的模型。默认为None。
返回
ZeroShotImageClassificationOutputElement列表
ZeroShotImageClassificationOutputElement项目列表,包含预测标签及其置信度。
抛出
推理超时错误或HTTP错误
- 推理超时错误 — 如果模型不可用或请求超时。
HTTP错误
— 如果请求失败,并且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
< source >( model: 可选 = None token: 联合 = None timeout: 可选 = None headers: 可选 = None cookies: 可选 = None proxies: 可选 = None base_url: 可选 = None api_key: 可选 = None )
参数
- model (
str
,optional
)— 要进行推断的模型。可以是托管在 Hugging Face Hub 上的模型 id,例如meta-llama/Meta-Llama-3-8B-Instruct
,或者指向部署的 Inference Endpoints 的 URL。默认为 None,在这种情况下,将自动选择推荐模型完成任务。注意:为了更好地与 OpenAI 的客户端兼容,model
已别名为base_url
。这两个参数互斥且具有完全相同的处理方式。 - token (
str
或bool
,optional)— Hugging Face token。若未提供,则默认为本地保存的 token。传递token=False
如果您不希望将您的 token 发送到服务器。注意:为了更好地与 OpenAI 的客户端兼容,token
已别名为api_key
。这两个参数互斥,且具有完全相同的处理方式。 - timeout (
float
,optional
)— 等待从服务器获取响应的最大秒数。在 Inference API 中加载新的模型可能需要几分钟。默认为 None,表示将继续循环直到服务器可用。 - headers (
Dict[str, str]
,optional
) — 发送到服务器的额外请求头。默认情况下,只发送授权和用户代理头。此字典中的值将覆盖默认值。 -
cookies ( Dict[str, str]
,optional
) — 发送到服务器的额外Cookies。 - base_url (
str
,optional
) — 运行推理的基础URL。这是从model
复制的参数,以便使InferenceClient
的样式与openai.OpenAI
客户端一致。如果设置了model
,则不能使用。默认为None。 - api_key (
str
,optional
) — 用于身份验证的Token。这是从token
复制的参数,使 InferenceClient 遵循与openai.OpenAI
客户端相同的模式。如果设置了token
则不能使用。默认值为None。
使用Inference Client初始化一个新的客户端。
InferenceClient旨在提供执行推理的统一体验。该客户端可以无缝地与(免费的)推理API或自托管的推理端点一起使用。
音频分类
< source >( audio: 联合 model: 可选 = None ) → 列表[音频分类输出元素]
参数
- audio (Union[str, Path, bytes, BinaryIO]) — 要分类的音频内容。可以是原始音频字节、本地音频文件或指向音频文件的URL。
- 模型 (
str
, 可选) — 用于音频分类的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向推理端点的 URL。如果未提供,则将使用推荐的默认音频分类模型。
返回
列表[音频分类输出元素]
包含预测标签及其置信度的音频分类输出元素的列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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_to_audio
< 源 >( audio: Union model: Optional = None ) → List[AudioToAudioOutputElement]
参数
- audio (Union[str, Path, bytes, BinaryIO]) — 模型的音频内容。可以是原始音频字节、本地的音频文件,或指向音频文件的 URL。
- 模型 (
str
, 可选) — 模型可以是任何接受音频文件并返回另一个音频文件的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。如果未提供,将使用默认推荐的音频_to_audio 模型。
返回
List[AudioToAudioOutputElement]
包含音频标签、内容类型和blob中音频内容的AudioToAudioOutputElement项目列表(请参阅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)
自动语音识别
< 源 >( audio: 联合类型 model: 可选 = None ) → AutomaticSpeechRecognitionOutput
参数
- audio (Union[str, Path, bytes, BinaryIO]) — 要转录的内容。可以是原始音频字节数组,本地音频文件或指向音频文件的 URL。
- model (
str
, 可选) — 用于语音识别的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。如果未提供,将使用推荐的 ASR 默认模型。
返回
包含转录文本和可选的时间戳块的项。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
对给定的音频内容执行自动语音识别(ASR或音频到文本)。
聊天完成
< 来源 >( messages:列表 model:可选 = None stream:布尔值 = False frequency_penalty:可选 = None logit_bias:可选 = None logprobs:可选 = None max_tokens:可选 = None n:可选 = None presence_penalty:可选 = None response_format:可选 = None seed:可选 = None stop:可选 = None temperature:可选 = None tool_choice:Union = None tool_prompt:可选 = None tools:可选 = None top_logprobs:可选 = None top_p:可选 = None ) → ChatCompletionOutput 或 Iterable of ChatCompletionStreamOutput
参数
- messages (List[Union[
SystemMessage
,UserMessage
,AssistantMessage
]]) — 由角色和内容对组成的对话历史。 - logit_bias (
float列表
, 可选) — 修改特定标记在补全中出现 likelihood。接受一个 JSON 对象,将标记(以分词器中标记的 token ID 指定)映射到相关的 bias 值(从 -100 到 100)。在数学上,bias 在模型采样之前被添加到由模型生成的 logits。确切效果会根据模型而异,但 -1 和 1 之间的值应减少或增加选择的 likelihood;-100 或 100 这样的值应导致相关标记被禁用或独家选择。默认为 None。 - logprobs (
布尔值
, 可选) — 是否返回输出标记的 log probabilities。如果为 true,则在信息内容的主体中返回每个输出标记的 log probabilities。 - max_tokens (
整数
, 可选) — 允许在响应中出现的最大 token 数量。默认为 20。 - n (
int
, 可选) — 未使用。 - presence_penalty (
float
, 可选) — 在-2.0和2.0之间的数字。正数值根据新节点是否出现在文本中予以惩罚,增加模型谈论新主题的可能性。 - response_format (ChatCompletionInputGrammarType, 可选) — 语法约束。可以是JSONSchema或正则表达式。
- seed (可选
int
,可选) — 可重现控制流的种子。默认为 None。 - stop (可选
str
,可选) — 触发响应结束的上限四个字符串。默认为 None。 - stream (
bool
,可选) — 启用实时响应流。默认为 False。 - temperature (
float
,可选)—控制生成内容的随机性。值越小,生成的补充内容越不随机。范围:[0,2]。默认值为1.0。 - top_logprobs (
int
,可选)—指定在每个位置返回最有可能的标记数,每个标记都有一个关联的对数概率。如果使用此参数,则必须设置logprobs为true。 - top_p (
float
,可选)—从最有可能的下一个字中采样的分数。必须在0和1之间。默认值为1.0。 - tool_choice (ChatCompletionInputToolTypeClass 或
str
,可选) — 用于完成的工具。默认为“auto”。 - tool_prompt (
str
,可选) — 附加在工具之前的提示。 - tools (List of ChatCompletionInputTool,可选) — 模型可能调用的工具列表。目前,仅支持将函数作为工具。使用此功能提供模型可能生成 JSON 输入的函数列表。
返回
从服务器返回的生成的文本
- 如果
stream=False
,则生成的文本作为 ChatCompletionOutput 返回(默认)。 - 如果
stream=True
,则生成的文本按顺序以一系列 ChatCompletionStreamOutput 返回。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
使用指定的语言模型完成对话的方法。
client.chat_completion
方法作为与 OpenAI 客户端兼容而别名为 client.chat.completions.create
。输入和输出严格相同,使用任一语法会产生相同的结果。有关 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
)
)
示例(stream=True)
# 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)
使用 tools 的示例
# 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"}'
conversational
< 源代码 >( text: str generated_responses: Optional = None past_user_inputs: Optional = None parameters: Optional = None model: Optional = None ) → Dict
参数
- text (
str
) — 用户在会话中的最后一次输入。 - generated_responses (
List[str]
, 可选) — 与早期模型回复对应的字符串列表。默认为 None。 - past_user_inputs (
List[str]
, 可选) — 与用户之前回复对应的字符串列表。其长度应与generated_responses
相同。默认为None。 - parameters (
Dict[str, Any]
, 可选) — 对话任务的额外参数。默认为None。有关可用参数的更多详细信息,请参阅此页 - model (
str
, 可选) — 用于对话任务的模型。可以是托管在Hugging Face Hub上的模型ID或部署到推理端点的URL。如未提供,则默认推荐使用对话模型。默认为None。
返回
Dict
生成的对话输出。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
根据给定的输入文本生成对话响应(即与 API 聊天)。
InferenceClient.conversational() API 已弃用,将在未来的版本中删除。请使用 InferenceClient.chat_completion() 代替。
示例
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> output = await client.conversational("Hi, who are you?")
>>> output
{'generated_text': 'I am the one who knocks.', 'conversation': {'generated_responses': ['I am the one who knocks.'], 'past_user_inputs': ['Hi, who are you?']}, 'warnings': ['Setting `pad_token_id` to `eos_token_id`:50256 for open-end generation.']}
>>> await client.conversational(
... "Wow, that's scary!",
... generated_responses=output["conversation"]["generated_responses"],
... past_user_inputs=output["conversation"]["past_user_inputs"],
... )
document_question_answering
< 源代码 >( image: 联合 question: str model: 可选 = None ) → List[DocumentQuestionAnsweringOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 上下文输入图像。它可以是由原始字节、图像文件或指向在线图像的URL组成的。 - question (
str
) — 要回答的问题。
返回
列表[DocumentQuestionAnsweringOutputElement]
包含预测标签、相关概率、单词 ID 和页码的 DocumentQuestionAnsweringOutputElement 项目列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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(score=0.42515629529953003, answer='us-001', start=16, end=16)]
feature_extraction
( text: str normalize: Optional = None prompt_name: Optional = None truncate: Optional = None truncation_direction: Optional = None model: Optional = None ) → np.ndarray
参数
- model (str, 可选) — 用于会话任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向部署推理端点的 URL。如果未提供,将使用默认的推荐会话模型。默认为 None。
- normalize (bool, 可选) — 是否要归一化嵌入向量。默认为 None。仅在由 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, 可选) — 是否截断嵌入向量。默认为None。仅在由Text-Embedding-Inference服务的服务器上可用。
- truncation_direction (文字['Left', 'Right'], 可选) — 当传递 truncate=True 时,应该截断输入的哪一侧。
返回
np.ndarray
将输入文本表示为浮点32位 numpy 数组的嵌入。
抛出
【推理超时错误】或 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
< source >( text: str model: Optional = None ) → 列表[填遮罩输出元素]
参数
- text (
str
) — 需要从其中填充的内容的字符串,必须包含 [MASK] 标记(请在模型卡片中查看掩码的确切名称)。 - model (
str
,可选) — 用于填充掩码任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。如果不提供,将使用默认推荐的填充掩码模型。默认值为 None。
返回
列表[填遮罩输出元素]
包含预测标签、相关概率、标记引用和完成文本的FillMaskOutputElement项列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
用缺失的词(精确来说是标记)填充空缺。
示例
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.fill_mask("The goal of life is <mask>.")
[
FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]
get_endpoint_info
< source >( 模型: 可选 = None ) → Dict[str, Any]
获取部署端点信息。
此端点仅在由 Text-Generation-Inference (TGI) 或 Text-Embedding-Inference (TEI) 驱动的端点上可用。由 transformers
驱动的端点返回空有效负载。
示例
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> await client.get_endpoint_info()
{
'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct',
'model_sha': None,
'model_dtype': 'torch.float16',
'model_device_type': 'cuda',
'model_pipeline_tag': None,
'max_concurrent_requests': 128,
'max_best_of': 2,
'max_stop_sequences': 4,
'max_input_length': 8191,
'max_total_tokens': 8192,
'waiting_served_ratio': 0.3,
'max_batch_total_tokens': 1259392,
'max_waiting_tokens': 20,
'max_batch_size': None,
'validation_workers': 32,
'max_client_batch_size': 4,
'version': '2.0.2',
'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214',
'docker_label': 'sha-dccab72'
}
get_model_status
< 源代码 >( 模型: 可选项 = None ) → 模型状态
参数
- 模型 (
str
, 可选) — 将要检查其状态的模型的标识符。如果没有提供模型,则将使用与 InferenceClient 实例关联的模型。只能检查 InferenceAPI 服务,因此标识符不能是 URL。
返回
模型状态
ModelStatus 数据类的实例,包含有关模型状态的信息:加载、状态、计算类型和框架。
获取 Inference API 上托管模型的状态。
此端点在您已知想要使用的模型并希望检查其可用性时非常有用。如果您想发现已部署的模型,则应使用 list_deployed_models()。
get_recommended_model
< 源代码 >( 任务: str ) → str
参数
- 任务 (
str
) — 获取 Hugging Face 建议模型的 Hugging Face 任务。所有可用的任务可以在这里找到。
返回
str
输入任务的推荐模型名称。
抛出
ValueError
ValueError
— 如果Hugging Face没有为输入任务提供推荐。
获取输入任务Hugging Face推荐的模型。
health_check
< 源代码 >( model: Optional = None ) → bool
检查部署端点的健康。
健康检查仅在由Text-Generation-Inference (TGI)或Text-Embedding-Inference (TEI)支持的推理端点可用。对于推理API,请使用InferenceClient.get_model_status()代替。
图像分类
< source >( image: 合并 model: 可选 = None ) → ImageClassificationOutputElement列表
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 要分类的图像。可以是原始字节、图像文件或在线图像的URL。 - 模型 (
str
, 可选) — 用于图像分类的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向可部署推理端点的 URL。如果没有提供,将使用推荐默认模型进行图像分类。
返回
ImageClassificationOutputElement的列表
包含预测标签和相关概率的ImageClassificationOutputElement项的列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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(score=0.9779096841812134, label='Blenheim spaniel'), ...]
图像分割
< 源 >( 图像 : Union 模型 : Optional = None ) → ImageSegmentationOutputElement的列表
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 要分割的图像。可以是原始字节、图像文件或指向在线图像的 URL。 - model (
str
, 可选) — 用于图像分割的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署的推理端点的URL。如果没有提供,将使用默认推荐图像分割模型。
返回
ImageSegmentationOutputElement列表
包含分割掩码及其相关属性的ImageSegmentationOutputElement项的列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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
< source >( image: 联合 prompt: 可选 = None negative_prompt: 可选 = None height: 可选 = None width: 可选 = None num_inference_steps: 可选 = None guidance_scale: 可选 = None model: 可选 = None **kwargs ) → Image
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 译文输入的图像。可以是原始字节、图像文件或指向网络图像的URL。 - prompt (
str
, 可选) — 指导图像生成的文本提示。 - negative_prompt (
str
, 可选) — 指导翻译过程的负面提示。 - height (
int
, 可选) — 生成图像的像素高度。 - width (
int
, 可选) — 生成图像的像素宽度。 - num_inference_steps (
int
, 可选) — 降噪步骤数。更多的降噪步骤通常会导致图像质量更高,但推理速度更慢。 - guidance_scale (
float
, 可选) — 较高的指导比例鼓励生成与文本prompt
密切相关的图像,通常以牺牲图像质量为代价。 - 模型 (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向部署推理端点的 URL。此参数将覆盖实例级别定义的模型。默认为 None。
返回
图像
翻译后的图像。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
使用指定的模型执行图像到图像的翻译。
如果您想处理图像,您必须安装PIL
(执行pip install Pillow
)。
image_to_text
< 源码 >( 图像: 联合 模型: 可选 = None ) → ImageToTextOutput
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 用于生成描述的输入图像。可以是原始字节、图像文件或指向在线图像的 URL。 - model (
str
, 可选) — 用于推理的模型。可以是托管在Hugging Face Hub上的模型ID或部署推理端点的URL。此参数会覆盖实例级别定义的模型。默认值为None。
生成的文本。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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]]
列出在Serverless Inference API服务上部署的模型。
此辅助程序通过框架逐一检查已部署的模型。默认情况下,它将检查受支持的4个主要框架,这些框架占托管模型总数的95%。但是,如果您希望获得模型的完整列表,可以在输入中将 frameworks="all"
设置为“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', ...], ...}
目标检测
< source >参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 要检测目标的对象图像。可以是原始字节、图像文件或指向在线图像的URL。 - model (
str
, 可选) — 用于对象检测的模型。可以是托管在Hugging Face Hub上的模型ID或指向已部署的推理端点的URL。如果不提供,将使用默认推荐的对象检测模型(DETR)。
返回
列表[ObjectDetectionOutputElement]
包含边界框和关联属性的ObjectDetectionOutputElement项目的列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
或 ValueError
- 推理超时错误 — 如果模型不可用或请求超时。
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
< source >( json: 联合 = None data: 联合 = None model: 可选 = None task: 可选 = None stream: 布尔 = False ) → bytes
参数
- json (
Union[str, Dict, List]
, optional) — 请求体中发送的JSON数据,针对每个任务。默认值为None。 - data (
Union[str, Path, bytes, BinaryIO]
, optional) — 请求体中发送的内容,针对每个任务。可以是原始字节、指向打开文件的指针、本地文件路径或在线资源的URL(图像、音频文件等)。如果同时传递了json
和data
,则data
将优先。至少需要提供json
或data
中的一个。默认值为None。 - 模型 (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。将覆盖实例级别的模型定义。默认值为 None。 - 任务 (
str
, 可选) — 要在推理中执行的任务。所有可用任务可在此处找到:https://huggingface.co/tasks。仅在未提供model
时用于默认推荐模型。必须提供至少model
或task
。默认值为 None。 - 流 (
bool
, 可选) — 是否迭代流式 API。
返回
bytes
服务器返回的原始字节。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
向推理服务器发起POST请求。
问答
< 源代码 >( 问题: str 上下文: str 模型: Optional = None ) → 问答输出元素
参数
- question (
str
) — 需要回答的问题。 - context (
str
) — 问题的上下文。 - model (
str
) — 用于问答任务的模型。可以是托管在Hugging Face Hub上的模型ID或指向部署的推理端点的URL。
包含分数、起始索引、结束索引和答案的问答输出。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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(score=0.9326562285423279, start=11, end=16, answer='Clara')
句子相似度
< 源代码 >( sentence: str other_sentences: 列表 model: 可选 = None ) → 列表[float]
参数
- 句子 (
str
) — 要与之比较的主要句子。 - 其他句子 (
List[str]
) — 要比较的其他句子列表。 - 模型 (
str
, 可选) — 用于对话任务的模型。可以是托管在Hugging Face Hub上的模型ID或指向已部署推断端点的URL。如果不提供,则将使用默认推荐对话模型。默认为None。
返回
列表[float]
表示输入文本的嵌入。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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]
总结
< 源代码 >( text: str parameters: Optional = None model: Optional = None ) → SummarizationOutput
参数
- text (
str
) — 要总结的输入文本。 - 参数 (
Dict[str, Any]
, 可选) — 文摘的额外参数。有关更多详细信息,请参阅此页面。 - model (
str
, 可选) — 推理时要使用的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署的推理端点的 URL。此参数将覆盖实例级别定义的模型。默认为 None。
生成的摘要文本。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
使用指定的模型对给定文本生成摘要。
table_question_answering
< 源代码 >( table: Dict query: str model: Optional = None ) → TableQuestionAnsweringOutputElement
参数
- 表格(
str
) — 以字典列表形式表示数据表格,其中条目为表头,列表为所有值,所有列表必须具有相同的大小。 - 查询(
str
) — 您要向表格提出的问题的纯文本。 - 模型(
str
) — 用于表格问答任务的模型。可以是在Hugging Face Hub上托管的模型ID或指向部署的推理端点的URL。
包含答案、坐标、单元格和使用的聚合器的表格问答输出。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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。
返回
列表
初始表中每行的标签列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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
, 可选) — 用于表格回归任务的模型。可以是托管在Hugging Face Hub上的模型ID或指向已部署推理端点的URL。如果不提供,将使用默认推荐的表格回归模型。默认值为None。
返回
列表
一系列预测的数值型目标值。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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: str model: Optional = None ) → List[TextClassificationOutputElement]
参数
- text (
str
) — 待分类的字符串。 - model (
str
, 可选) — 用于文本分类任务的模型。可以是Hugging Face Hub上托管模型ID或部署的推理端点URL。如果未提供,将使用默认推荐文本分类模型。默认值为None。
返回
List[TextClassificationOutputElement]
包含预测标签和相关概率的 TextClassificationOutputElement 元素列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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_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 (
字符串
) — 输入文本。 - details (
布尔值,可选
) — 默认情况下,text_generation 返回一个字符串。如果您想获取详细信息(token、概率、种子、完成原因等),请传递details=True
。仅适用于在text-generation-inference
后端运行的模式。 - stream (
bool
, 可选) — 默认情况下,text_generation 返回完整的生成文本。如果你想返回一个标记流的文本,请传递stream=True
。仅适用于使用text-generation-inference
后端的模型。 - model (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端的 URL。此参数会覆盖实例级别定义的模型。默认为 None。 - adapter_id (
str
, 可选) — Lora 适配器 ID。 - best_of (
int
, 可选) — 输出最佳序列并在所有标记的 logprobs 中返回概率最高的一个。 - decoder_input_details (
bool
, 可选) — 返回解码器输入标记的 logprobs 和 ids。必须也设置details=True
才会被考虑。默认为False
。 - do_sample (
bool
, 可选) — 激活 logits 抽样。 - frequency_penalty (
float
, 可选) — 范围介于 -2.0 和 2.0 之间的数字。正值会根据文本中迄今为止现有频率惩罚新令牌,降低模型重复相同行的可能性。 - grammar (TextGenerationInputGrammarType, 可选) — 语法约束。可以是 JSONSchema 或正则表达式。
- max_new_tokens (
int
, 可选) — 生成令牌的最大数量 - repetition_penalty (
浮点数
,可选) — 重复惩罚参数。1.0代表没有惩罚。参见这篇文章获取更多详细信息。 - return_full_text (
布尔值
,可选) — 是否将提示内容加在生成的文本前面 - seed (
整数
,可选) — 随机抽样种子 - stop_sequences (
字符串列表
,可选) — 如果生成stop_sequences
的成员则停止生成令牌 - temperature(温度) (
float
,可选)—用于模块化 logits 分布的值。 - top_n_tokens(顶部 n 个标记) (
int
,可选)—在每个生成步骤返回关于top_n_tokens
最可能标记的信息,而不是仅返回采样的标记。 - top_k(顶部 k) (
int
,*可选)—用于 top-k 过滤器保持的最高概率词汇标记的数量。 - top_p (
float
, *optional) -- 当设置小于 1 时,只有加起来达到
top_p` 或更高的最小概率的 token 集合会被保留用于生成。 - truncate (
int
, *optional`) — 将输入 tokens 截断到给定大小。 - typical_p (
float
, *optional`) — 常见解码质量。请参阅 《自然语言生成的典型解码》 以获取更多信息 - 水印 (
bool
, *可选`) — 使用 大型语言模型的水印素材标签结束>
返回
类型联合[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]
从服务器返回的生成的文本
- 如果
stream=False
并且details=False
,则生成的文本以str
形式返回(默认) - 如果
stream=True
并且details=False
,则生成的文本作为Iterable[str]
形式逐个令牌返回 - 如果
stream=False
并且details=True
,则生成的文本作为包含更多细节的 TextGenerationOutput 返回 - 如果
details=True
并且stream=True
,则生成的文本作为 TextGenerationStreamOutput 的可迭代序列逐个令牌返回
抛出
ValidationError
或 InferenceTimeoutError 或 aiohttp.ClientResponseError
ValidationError
— 如果输入值无效。不会向服务器发起HTTP调用。- 推理超时错误 — 如果模型不可用或请求超时。
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
< 源代码 >( prompt: str negative_prompt: Optional = None height: Optional = None width: Optional = None num_inference_steps: Optional = None guidance_scale: Optional = None model: Optional = None **kwargs ) → Image
参数
- prompt (
str
) — 用于生成图像的提示 - negative_prompt (
str
, 可选) — 图像生成的可选否定提示 - height (
float
, 可选) — 要生成的图像的像素高度。 - width (
float
, 可选) — 要生成的图像的像素宽度。 - num_inference_steps (
int
, 可选) — 去噪步骤的数量。更多的去噪步骤通常会导致图像质量更高,但推理速度会变慢。 - guidance_scale (
float
, 可选) — 更高的指导尺度鼓励生成与文本prompt
密切相关的图像,通常以降低图像质量为代价。 - model (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向部署的推理端点的 URL。此参数覆盖在实例级别定义的模型。默认值为 None。
返回
图像
生成的图像。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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
< 来源 >( text: str model: Optional = None ) → bytes
参数
返回
bytes
生成的音频。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
合成给定文本的语音音频。
token_classification
( text: str model: Optional = None ) → List[TokenClassificationOutputElement]
参数
- model (
str
, 可选) — 用于token分类任务的模型。可以是托管在Hugging Face Hub上的模型ID或部署的推理端点URL。如果未提供,将默认使用推荐的token分类模型。默认为None。
返回
TokenClassificationOutputElement列表
包含实体组、置信度分数、单词、起始和结束索引的TokenClassificationOutputElement项目列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
aiohttp.ClientResponseError
— 如果请求失败且 HTTP 错误状态码不是 HTTP 503。
对给定的文本执行标记分类。通常用于句子解析,无论是语法还是命名实体识别(NER),以便理解文本中的关键字。
示例
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
TokenClassificationOutputElement(
entity_group='PER',
score=0.9971321225166321,
word='Sarah Jessica Parker',
start=11,
end=31,
),
TokenClassificationOutputElement(
entity_group='PER',
score=0.9773476123809814,
word='Jessica',
start=52,
end=59,
)
]
翻译
< 源码 >( text: str model: Optional = None src_lang: Optional = None tgt_lang: Optional = None ) →
参数
- text (
str
) — 要翻译的字符串。 - model (
str
, 可选) — 用于翻译任务的模型。可以是托管在Hugging Face Hub上的模型ID或部署的推理端点的URL。如未提供,将使用默认推荐的翻译模型。默认为None。 - src_lang (
str
, 可选) — 翻译任务的源语言,即输入语言。必须与tgt_lang
一起提供。 - tgt_lang (
str
, 可选) — 翻译任务的目标语言,即输出语言。必须与src_lang
一起提供。
返回
生成的翻译文本。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
或 ValueError
- 推理超时错误 — 如果模型不可用或请求超时。
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.')
可视化问答
< 来源 >( 图像: Union 问题: str 模型: Optional = None ) → List[VisualQuestionAnsweringOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 上下文输入的图像。可以是原始字节数据、图像文件或在线图像的URL。 - question (
str
) — 要回答的问题。 - model (
str
, optional) — 用于视觉问答任务的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。如果没有提供,将使用推荐的默认视觉问答模型。默认值为 None。
返回
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 (
字符串列表
) — 字符串列表。每个字符串是对输入文本可能标签的描述。 - multi_label (
布尔值
) — 布尔值。如果为 True,则独立评估每个标签的概率,并且可以同时有多个标签的概率接近 1 或所有概率都接近 0。如果为 False,则将这些标签视为互斥的,所有标签的概率总和始终为 1。默认为 False。 - hypothesis_template (
字符串
, 可选) — 一个带有花括号的模板句子字符串,其中标签字符串将被添加。这些标签字符串将添加到花括号“{}”的位置。零样本分类器基于 NLI 模型,它评估一个假设是否被其他文本蕴涵。例如,当 hypothesis_template="This text is about {}." 和 labels=["economics", "politics"] 时,系统内部创建两个假设:“This text is about economics.” 和 “This text is about politics.”。该模型随后评估这两个假设是否被提供的text
蕴涵。 - 模型 (
str
, 可选) — 用于推理的模型。可以是托管在 Hugging Face Hub 上的模型 ID 或指向已部署推理端点的 URL。此参数覆盖实例级别上定义的模型。默认为 None。
返回
List[ZeroShotClassificationOutputElement]
包含预测标签和它们置信度的ZeroShotClassificationOutputElement项目列表。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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
< 源 >( image: Union labels: 列表 model: 可选 = None ) → List[ZeroShotImageClassificationOutputElement]
参数
- image (
Union[str, Path, bytes, BinaryIO]
) — 加载图片的输入。可以是原始字节、图片文件或指向在线图片的 URL。 - 标签列表(
List[str]
) — 可能的标签列表。必须有至少2个标签。 - 模式(
str
,可选项) — 用来进行推理的模型。可以是托管在Hugging Face Hub上的模型ID,或指向已部署推理端点的URL。该参数会覆盖在实例级别上定义的模型。默认值是None。
返回
ZeroShotImageClassificationOutputElement列表
ZeroShotImageClassificationOutputElement项目列表,包含预测标签及其置信度。
抛出
InferenceTimeoutError 或 aiohttp.ClientResponseError
- 推理超时错误 — 如果模型不可用或请求超时。
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
当模型不可用或请求超时时引发错误。
ModelStatus
类 huggingface_hub.inference._common.ModelStatus
< 来源 >( loaded: bool state: str compute_type: Dict framework: str )
该Dataclass表示Hugging Face Inference API中的模型状态。
InferenceAPI
InferenceAPI
是调用Inference API的旧方法。该接口更简单,需要了解每个任务输入参数和输出格式。它还无法连接到其他服务,如Inference端点或AWS SageMaker。《code>InferenceAPI 将很快被弃用,因此我们建议尽可能使用 InferenceClient。查看此指南,了解如何将脚本中的 InferenceAPI
切换到 InferenceClient。
类 huggingface_hub.InferenceApi
< 源 >( repo_id: str task: Optional = None token: Optional = None gpu: bool = False )
客户端用于配置请求并对HuggingFace推理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__
< 来源 >( 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承载授权的API令牌。这不是认证令牌。您可以在https://huggingface.co/settings/token找到令牌。或者,您可以使用HfApi().whoami(token)找到您的组织和个人API令牌。
- gpu (bool, 可选, 默认False) — 是否使用GPU而不是CPU进行推理(需要至少启动计划)。
初始化头信息和API调用信息。
__call__
< 来源 >( inputs: 联合体 = None params: 可选的 = None data: 可选的 = None raw_response: bool = False )
调用推理 API。