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("http://localhost: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("http://localhost: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("http://localhost: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("http://localhost: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="http://localhost: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"
```
按函数名称指定工具调用:
- 您可以强制模型调用特定工具，方法是直接指定工具函数或使用对象定义。
- 有两种方法可以做到这一点
  1. 提供函数名称作为字符串
```
tool_choice="get_current_weather"
```
  2. 使用函数对象格式
```
tool_choice={
  "type": "function",
  "function": {
      "name": "get_current_weather"
  }
}
```

这些选项在将工具与聊天完成端点集成时提供了灵活性。您可以根据手头任务的需求，将模型配置为自动依赖工具或强制其遵循预定义的行为。

工具选择选项	描述	何时使用
`自动`	模型决定是调用工具还是生成消息。如果提供了工具，则这是默认设置。	当您希望模型决定何时需要工具时使用。
`无`	模型生成消息，而不调用任何工具。如果未提供工具，则这是默认设置。	当您不希望模型调用任何工具时使用。
`必需`	模型必须调用一个或多个工具，并且不会自行生成消息。	当强制进行工具调用，并且您不希望生成常规消息时使用。
指定工具调用 (`name` 或对象)	通过指定其名称 (`tool_choice="get_current_weather"`) 或使用对象来强制模型调用特定工具。	当您希望限制模型仅调用特定工具进行响应时使用。

< > 在 GitHub 上更新

text-generation-inference