text-generation-inference 文档
指南
并获得增强的文档体验
开始使用
Guidance
Text Generation Inference (TGI) 现在支持 JSON 和正则表达式语法 以及 工具和函数,以帮助开发人员指导 LLM 响应以满足其需求。
这些功能从 1.4.3
版本开始可用。它们可以通过 huggingface_hub
库访问。该工具支持与 OpenAI 的客户端库兼容。以下指南将引导您了解新功能以及如何使用它们!
注意:guidance 在 /generate
端点中作为语法支持,在 v1/chat/completions
端点中作为工具支持。
它是如何工作的
TGI 利用 outlines 库来高效地解析和编译用户指定的语法结构和工具。这种集成将定义的语法转换为中间表示,作为指导和约束内容生成的框架,确保输出符合指定的语法规则。
如果您对 outlines 在 TGI 中的技术细节感兴趣,可以查看 概念指导文档。
目录 📚
语法和约束
- 语法参数:精确塑造 AI 的响应。
- 使用 Pydantic 进行约束:使用 Pydantic 模型定义语法。
- JSON Schema 集成:通过 JSON schema 对您的请求进行细粒度控制。
- 使用客户端:使用 TGI 的客户端库来塑造 AI 的响应。
工具和函数
- 工具参数:使用预定义函数增强 AI 的能力。
- 通过客户端:使用 TGI 的客户端库与 Messages API 和工具函数进行交互。
- OpenAI 集成:使用 OpenAI 的客户端库与 TGI 的 Messages API 和工具函数进行交互。
语法和约束 🛣️
语法参数
在 TGI 1.4.3
中,我们引入了语法参数,允许您指定希望从 LLM 获得的响应格式。
使用 curl,您可以向 TGI 的 Messages API 发出带有语法参数的请求。这是与 API 交互的最原始方式,建议使用 Pydantic 以方便使用和提高可读性。
curl localhost:3000/generate \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"inputs": "I saw a puppy a cat and a raccoon during my bike ride in the park",
"parameters": {
"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"]
}
}
}
}'
// {"generated_text":"{ \n\n\"activity\": \"biking\",\n\"animals\": [\"puppy\",\"cat\",\"raccoon\"],\n\"animals_seen\": 3,\n\"location\": \"park\"\n}"}
Hugging Face Hub Python 库
Hugging Face Hub Python 库提供了一个客户端,可以轻松地与 Messages API 进行交互。以下是如何使用客户端发送带有语法参数的请求的示例。
from huggingface_hub import InferenceClient
client = InferenceClient("https://127.0.0.1:3000")
schema = {
"properties": {
"location": {"title": "Location", "type": "string"},
"activity": {"title": "Activity", "type": "string"},
"animals_seen": {
"maximum": 5,
"minimum": 1,
"title": "Animals Seen",
"type": "integer",
},
"animals": {"items": {"type": "string"}, "title": "Animals", "type": "array"},
},
"required": ["location", "activity", "animals_seen", "animals"],
"title": "Animals",
"type": "object",
}
user_input = "I saw a puppy a cat and a raccoon during my bike ride in the park"
resp = client.text_generation(
f"convert to JSON: 'f{user_input}'. please use the following schema: {schema}",
max_new_tokens=100,
seed=42,
grammar={"type": "json", "value": schema},
)
print(resp)
# { "activity": "bike ride", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" }
可以使用 Pydantic 模型、JSON schema 或正则表达式定义语法。然后,LLM 将生成符合指定语法的响应。
注意:语法必须编译为中间表示才能约束输出。语法编译是计算密集型的,并且在首次请求时可能需要几秒钟才能完成。后续请求将使用缓存的语法,并且会快得多。
使用 Pydantic 进行约束
使用 Pydantic 模型,我们可以用更短、更易读的方式定义与之前示例类似的语法。
from huggingface_hub import InferenceClient
from pydantic import BaseModel, conint
from typing import List
class Animals(BaseModel):
location: str
activity: str
animals_seen: conint(ge=1, le=5) # Constrained integer type
animals: List[str]
client = InferenceClient("https://127.0.0.1:3000")
user_input = "I saw a puppy a cat and a raccoon during my bike ride in the park"
resp = client.text_generation(
f"convert to JSON: 'f{user_input}'. please use the following schema: {Animals.schema()}",
max_new_tokens=100,
seed=42,
grammar={"type": "json", "value": Animals.schema()},
)
print(resp)
# { "activity": "bike ride", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" }
将语法定义为正则表达式
from huggingface_hub import InferenceClient
client = InferenceClient("https://127.0.0.1:3000")
section_regex = "(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"
regexp = f"HELLO\.{section_regex}\.WORLD\.{section_regex}"
# This is a more realistic example of an ip address regex
# regexp = f"{section_regex}\.{section_regex}\.{section_regex}\.{section_regex}"
resp = client.text_generation(
f"Whats Googles DNS? Please use the following regex: {regexp}",
seed=42,
grammar={
"type": "regex",
"value": regexp,
},
)
print(resp)
# HELLO.255.WORLD.255
工具和函数 🛠️
工具参数
除了语法参数之外,我们还引入了一组工具和函数,以帮助您充分利用 Messages API。
工具是一组用户定义的函数,可以与聊天功能结合使用,以增强 LLM 的功能。函数与语法类似,被定义为 JSON schema,并且可以作为参数的一部分传递给 Messages API。
curl localhost:3000/v1/chat/completions \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"model": "tgi",
"messages": [
{
"role": "user",
"content": "What is the weather like in New York?"
}
],
"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"]
}
}
}
],
"tool_choice": "get_current_weather"
}'
// {"id":"","object":"text_completion","created":1709051640,"model":"HuggingFaceH4/zephyr-7b-beta","system_fingerprint":"1.4.3-native","choices":[{"index":0,"message":{"role":"assistant","tool_calls":{"id":0,"type":"function","function":{"description":null,"name":"tools","parameters":{"format":"celsius","location":"New York"}}}},"logprobs":null,"finish_reason":"eos_token"}],"usage":{"prompt_tokens":157,"completion_tokens":19,"total_tokens":176}}
使用工具进行聊天完成
语法在 /generate
端点中受支持,而工具在 /chat/completions
端点中受支持。以下是如何使用客户端发送带有工具参数的请求的示例。
from huggingface_hub import InferenceClient
client = InferenceClient("https://127.0.0.1:3000")
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"],
},
},
},
]
chat = client.chat_completion(
messages=[
{
"role": "system",
"content": "You're a helpful assistant! Answer the users question best you can.",
},
{
"role": "user",
"content": "What is the weather like in Brooklyn, New York?",
},
],
tools=tools,
seed=42,
max_tokens=100,
)
print(chat.choices[0].message.tool_calls)
# [ChatCompletionOutputToolCall(function=ChatCompletionOutputFunctionDefinition(arguments={'format': 'fahrenheit', 'location': 'Brooklyn, New York', 'num_days': 7}, name='get_n_day_weather_forecast', description=None), id=0, type='function')]
OpenAI 集成
TGI 公开了一个与 OpenAI 兼容的 API,这意味着您可以使用 OpenAI 的客户端库与 TGI 的 Messages API 和工具函数进行交互。
from openai import OpenAI
# Initialize the client, pointing it to one of the available models
client = OpenAI(
base_url="https://127.0.0.1:3000/v1",
api_key="_",
)
# NOTE: tools defined above and removed for brevity
chat_completion = client.chat.completions.create(
model="tgi",
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=tools,
tool_choice="auto", # tool selected by model
max_tokens=500,
)
called = chat_completion.choices[0].message.tool_calls
print(called)
# {
# "id": 0,
# "type": "function",
# "function": {
# "description": None,
# "name": "tools",
# "parameters": {
# "format": "celsius",
# "location": "San Francisco, CA",
# "num_days": 3,
# },
# },
# }
工具选择配置
在配置模型如何在聊天完成期间与工具交互时,有几个选项可以确定是否应调用工具或如何调用工具。这些选项由 tool_choice
参数控制,该参数指定模型在工具使用方面的行为。支持以下模式
自动
:- 模型决定是调用工具还是基于用户输入生成响应消息。
- 如果提供了工具,则这是默认模式。
- 使用示例
tool_choice="auto"
无
:- 模型永远不会调用任何工具,只会生成响应消息。
- 如果未提供工具,则这是默认模式。
- 使用示例
tool_choice="none"
必需
:- 模型必须调用一个或多个工具,并且不会自行生成响应消息。
- 使用示例
tool_choice="required"
按函数名称指定工具调用:
- 您可以强制模型调用特定工具,方法是直接指定工具函数或使用对象定义。
- 有两种方法可以做到这一点
- 提供函数名称作为字符串
tool_choice="get_current_weather"
- 使用函数对象格式
tool_choice={ "type": "function", "function": { "name": "get_current_weather" } }
- 提供函数名称作为字符串
这些选项在将工具与聊天完成端点集成时提供了灵活性。您可以根据手头任务的需求,将模型配置为自动依赖工具或强制其遵循预定义的行为。
工具选择选项 | 描述 | 何时使用 |
---|---|---|
自动 | 模型决定是调用工具还是生成消息。如果提供了工具,则这是默认设置。 | 当您希望模型决定何时需要工具时使用。 |
无 | 模型生成消息,而不调用任何工具。如果未提供工具,则这是默认设置。 | 当您不希望模型调用任何工具时使用。 |
必需 | 模型必须调用一个或多个工具,并且不会自行生成消息。 | 当强制进行工具调用,并且您不希望生成常规消息时使用。 |
指定工具调用 (name 或对象) | 通过指定其名称 (tool_choice="get_current_weather" ) 或使用对象来强制模型调用特定工具。 | 当您希望限制模型仅调用特定工具进行响应时使用。 |