Transformers documentation
Использование инструментов
Использование инструментов
Модели чата обычно обучаются с поддержкой «вызова функций» или «использования инструментов». Инструменты — это функции, предоставляемые пользователем, которые модель может выбрать для вызова в рамках своего ответа. Например, модели могут иметь доступ к инструменту-калькулятору для выполнения арифметических операций без необходимости проводить вычисления внутри себя.
В этом руководстве показано, как определить инструменты, передать их чат-модели и обработать вывод модели при вызове инструмента.
Передача инструментов
Если модель поддерживает использование инструментов, передавайте функции в аргумент tools функции apply_chat_template().
Инструменты передаются в виде JSON-схемы или Python-функций. Если вы передаёте Python-функции,
их аргументы, типы аргументов и docstring анализируются для автоматической генерации JSON-схемы.
Хотя передача функций Python очень удобна, парсер может обрабатывать только строки документации в стиле Google. См. примеры ниже о том, как оформить функцию, готовую к использованию как инструмент.
def get_current_temperature(location: str, unit: str):
"""
Get the current temperature at a location.
Args:
location: The location to get the temperature for, in the format "City, Country"
unit: The unit to return the temperature in. (choices: ["celsius", "fahrenheit"])
"""
return 22. # A real function should probably actually get the temperature!
def get_current_wind_speed(location: str):
"""
Get the current wind speed in km/h at a given location.
Args:
location: The location to get the wind speed for, in the format "City, Country"
"""
return 6. # A real function should probably actually get the wind speed!
tools = [get_current_temperature, get_current_wind_speed]При необходимости можно добавить блок Returns: в docstring и тип возвращаемого значения в заголовок функции, но большинство моделей не будут использовать эту информацию. Парсер также игнорирует фактический код внутри функции!
Действительно важны имя функции, имена аргументов, типы аргументов и docstring, описывающий назначение функции и назначение её аргументов. Они формируют «сигнатуру», по которой модель решает, вызывать ли инструмент.
Пример вызова инструментов
Загрузите модель и токенизатор, поддерживающий использование инструментов, например NousResearch/Hermes-2-Pro-Llama-3-8B, но при возможности вашего оборудования можно рассмотреть и более крупные модели, такие как Command-R и Mixtral-8x22B.
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
checkpoint = "NousResearch/Hermes-2-Pro-Llama-3-8B"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
model = AutoModelForCausalLM.from_pretrained(checkpoint, dtype="auto", device_map="auto")Создайте историю чата.
messages = [
{"role": "system", "content": "You are a bot that responds to weather queries. You should reply with the unit used in the queried location."},
{"role": "user", "content": "Hey, what's the temperature in Paris right now?"}
]Далее передайте messages и список инструментов в apply_chat_template(). Токенизируйте чат и сгенерируйте ответ.
inputs = tokenizer.apply_chat_template(messages, tools=tools, add_generation_prompt=True, return_dict=True, return_tensors="pt")
outputs = model.generate(**inputs.to(model.device), max_new_tokens=128)
print(tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):]))<tool_call>
{"arguments": {"location": "Paris, France", "unit": "celsius"}, "name": "get_current_temperature"}
</tool_call><|im_end|>Модель чата вызвала инструмент get_current_temperature с правильными параметрами из docstring. Она определила Францию как местоположение на основе упоминания Парижа и решила использовать градусы Цельсия в качестве единиц измерения температуры.
Модель не может самостоятельно вызвать инструмент. Она запрашивает вызов инструмента, а ваша задача — обработать этот вызов и добавить его вместе с результатом в историю чата. Для моделей, поддерживающих разбор ответа, этот процесс выполняется автоматически, и вы можете просто использовать parse_response() для извлечения вызова инструмента. Для остальных моделей вам потребуется вручную преобразовать выходную строку в словарь вызова инструмента.
Независимо от выбранного подхода, вызов инструмента должен находиться в ключе tool_calls сообщения assistant. Это рекомендуемый API, который должен поддерживаться шаблонами чата большинства моделей, использующих инструменты.
Хотя
tool_callsпохож на OpenAI API, в OpenAI API в качестве форматаtool_callsиспользуется строка JSON. Это может привести к ошибкам или странному поведению модели при использовании в Transformers, который ожидает словарь.
tool_call = {"name": "get_current_temperature", "arguments": {"location": "Paris, France", "unit": "celsius"}}
messages.append({"role": "assistant", "tool_calls": [{"type": "function", "function": tool_call}]})Добавьте ответ инструмента в историю чата с ролью tool.
messages.append({"role": "tool", "content": "22"}) # Note that the returned content is always a string!Наконец, разрешите модели прочитать ответ инструмента и ответить пользователю.
inputs = tokenizer.apply_chat_template(messages, tools=tools, add_generation_prompt=True, return_dict=True, return_tensors="pt")
out = model.generate(**inputs.to(model.device), max_new_tokens=128)
print(tokenizer.decode(out[0][len(inputs["input_ids"][0]):]))The temperature in Paris, France right now is 22°C.<|im_end|>
Хотя ключ в сообщении ассистента называется
tool_calls, в большинстве случаев модели формируют только один вызов инструмента за раз. Некоторые более старые модели формируют несколько вызовов инструментов одновременно, но это значительно более сложный процесс, поскольку необходимо обрабатывать несколько ответов инструментов сразу и различать их, часто используя идентификаторы вызовов инструментов. Обратитесь к карточке модели, чтобы узнать точный формат, который модель ожидает для вызовов инструментов.
Схемы JSON
Ещё один способ определить инструменты — передать JSON-схему.
Вы также можете вручную вызывать низкоуровневые функции, которые преобразуют функции Python в JSON-схемы, а затем проверять или редактировать сгенерированные схемы. Обычно в этом нет необходимости, но это полезно для понимания внутренних механизмов. Это особенно важно для авторов шаблонов чата, которым необходимо получить доступ к JSON-схеме для отображения определений инструментов.
Метод apply_chat_template() использует функцию get_json_schema для преобразования вызываемых объектов Python в схему JSON. Сюда входят методы: self и cls рассматриваются как неявные аргументы-получатели и игнорируются.
Аннотации типов могут быть базовыми типами, такими как int, float, str и bool, классами Literal или Enum (оба они становятся enum с допустимыми значениями), а также типами list, tuple, dict и Union, содержащими эти типы. Другие классы, такие как dataclasses или модели Pydantic, вызывают ошибку при использовании в качестве типа аргумента, так как невозможно определить, какой JSON они ожидают. Если вашему инструменту требуется один из таких типов, вручную напишите его JSON-схему и передайте её вместо аннотации. Требования к типам возвращаемых значений менее строгие, поскольку модели никогда не приходится их генерировать: если аннотацию типа возвращаемого значения не удаётся преобразовать, она просто исключается из схемы.
from transformers.utils import get_json_schema
def multiply(a: float, b: float):
"""
A function that multiplies two numbers
Args:
a: The first number to multiply
b: The second number to multiply
"""
return a * b
schema = get_json_schema(multiply)
print(schema){
"type": "function",
"function": {
"name": "multiply",
"description": "A function that multiplies two numbers",
"parameters": {
"type": "object",
"properties": {
"a": {
"type": "number",
"description": "The first number to multiply"
},
"b": {
"type": "number",
"description": "The second number to multiply"
}
},
"required": ["a", "b"]
}
}
}Мы не будем подробно останавливаться на самом JSON-схеме, так как она уже хорошо задокументирована в других источниках. Однако отметим, что в аргумент tools функции apply_chat_template() можно передавать словари JSON-схем вместо Python-функций:
# A simple function that takes no arguments
current_time = {
"type": "function",
"function": {
"name": "current_time",
"description": "Get the current local time as a string.",
"parameters": {
'type': 'object',
'properties': {}
}
}
}
# A more complete function that takes two numerical arguments
multiply = {
'type': 'function',
'function': {
'name': 'multiply',
'description': 'A function that multiplies two numbers',
'parameters': {
'type': 'object',
'properties': {
'a': {
'type': 'number',
'description': 'The first number to multiply'
},
'b': {
'type': 'number', 'description': 'The second number to multiply'
}
},
'required': ['a', 'b']
}
}
}
model_input = tokenizer.apply_chat_template(
messages,
tools = [current_time, multiply]
)