Генерация аргументов
В этом разделе вы найдете примеры генерации аргументов для пользовательских функций в различных режимах, а также узнаете, как работает генерация аргументов в потоковом режиме и как вернуть в модель результат работы функции.
Пользовательские функции — это функции, реализованные в вашем приложении или стороннем сервисе.
Модели GigaChat могут генерировать аргументы для таких функций на основе их описания, полученного в массиве functions
, в запросе POST /chat/completions.
Используйте полученные аргументы для вызова функции, а результаты ее работы возвращайте в модель в сообщении с ролью function
.
Модели умеют генерировать аргументы автоматически, в зависимости от промпта, или принудительно. Подробнее — в разделе Режимы работы с функциями.
Рекомендации по описанию пользовательских функций и примеры — в разделе Описание пользовательских функций.
Быстрый старт
Чтобы модель сгенерировала аргументы для вашей функции, просто передайте ее описание в массиве functions
вместе с подходящим промптом:
curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
"model": "GigaChat-2-Pro",
"messages": [
{
"role": "user",
"content": "Погода в Манжероке на десять дней"
}
],
"functions": [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"num_days"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
]
}'
Генерация аргументов с помощью SDK:
from gigachat import GigaChat
from gigachat.models import Chat, Function, Messages, MessagesRole, FunctionParameters
from gigachat.models.few_shot_example import FewShotExample
giga = GigaChat(
credentials="<ключ_авторизации>",
)
weather_forecast_function=Function(
name="weather_forecast",
description="Возвращает температуру на заданный период",
parameters=FunctionParameters(
type="object",
properties={"location": {"type": "string", "description": "Местоположение, например, название города"}, "format": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Единицы измерения температуры"}, "num_days": {"type": "integer", "description": "Период, для которого нужно вернуть"}},
required=["location","format"],
few_shot_examples=[FewShotExample(
request="Какая погода в Москве в ближайшие три дня",
params={"location": "Moscow, Russia", "format": "celsius", "num_days": "3"}
)],
return_parameters=[{ "type": "object", "properties": {"location": {"type": "string", "description": "Местоположение, например, название города"}, "temperature": {"type": "integer", "description": "Температура для заданного местоположения"}, "forecast": {"type": "array", "items": {"type": "string"}, "description": "Описание погодных условий"}, "error": {"type": "string", "description": "Возвращается при возникновении ошибки. Содержит описание ошибки"}}}]
)
)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="погода в Манжероке на десять дней")],
functions=[weather_forecast_function]
)
response = giga.chat(payload)
print(response)
Генерация аргументов с помощью партнерского пакета langchain-gigachat:
from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate
llm = GigaChat(
credentials="<ключ_авторизации>",
verify_ssl_certs=False
)
weather_forecast = {
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=[weather_forecast])
# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
[
("user", """{topic}"""),
]
)
custom_functions_chain = prompt | llm
response = custom_functions_chain.invoke({"topic": "Погода в Манжероке на три дня"})
print(response)
Генерация аргументов с помощью SDK:
import { GigaChat } from 'gigachat';
const giga = new GigaChat({
credentials: '<ключ_авторизации>',
});
const weatherForecast = {
name: "weather_forecast",
description: "Возвращает температуру на заданный период",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
format: {
type: "string",
enum: [
"celsius",
"fahrenheit"
],
description: "Единицы измерения температуры"
},
num_days: {
type: "integer",
description: "Период, для которого нужно вернуть"
}
},
required: [
"location",
"num_days"
]
},
few_shot_examples: [
{
request: "Какая погода в Москве в ближайшие три дня",
params: {
location: "Moscow, Russia",
format: "celsius",
num_days: "3"
}
}
],
return_parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
temperature: {
type: "integer",
description: "Температура для заданного местоположения"
},
forecast: {
type: "array",
items: {
type: "string"
},
description: "Описание погодных условий"
},
error: {
type: "string",
description: "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
const resp = await giga.chat({
messages: [
{
role: "user",
content: "Погода в Манжероке на три дня",
},
],
functions: [
weatherForecast
]
});
console.log(resp.choices[0]?.message);
Автоматический режим
В этом режиме модель анализирует полученные сообщения (массив messages
) и сама решает, нужно генерировать аргументы или нет.
Для работы в автоматическом режиме достаточно передать в сообщение массив functions
с описанием функций.
Чтобы модели могли обращаться к встроенным функциям при работе с пользовательскими, явно активируйте автоматический режим и укажите необходимые функции в массиве functions
.
curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
"model": "GigaChat-2-Pro",
"messages": [
{
"role": "user",
"content": "Нарисуй горы"
}
],
"function_call": "auto",
"functions": [
{
"name": "text2image"
},
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
]
}'
Совместное использование функций с помощью SDK:
from gigachat import GigaChat
from gigachat.models import Chat, Function, Messages, MessagesRole, FunctionParameters
from gigachat.models.few_shot_example import FewShotExample
giga = GigaChat(credentials="<ключ_авторизации>", verify_ssl_certs=False)
weather_forecast_function=Function(
name="weather_forecast",
description="Возвращает температуру на заданный период",
parameters=FunctionParameters(
type="object",
properties={"location": {"type": "string", "description": "Местоположение, например, название города"}, "format": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Единицы измерения температуры"}, "num_days": {"type": "integer", "description": "Период, для которого нужно вернуть"}},
required=["location","format"],
few_shot_examples=[FewShotExample(
request="Какая погода в Москве в ближайшие три дня",
params={"location": "Moscow, Russia", "format": "celsius", "num_days": "3"}
)],
return_parameters=[{ "type": "object", "properties": {"location": {"type": "string", "description": "Местоположение, например, название города"}, "temperature": {"type": "integer", "description": "Температура для заданного местоположения"}, "forecast": {"type": "array", "items": {"type": "string"}, "description": "Описание погодных условий"}, "error": {"type": "string", "description": "Возвращается при возникновении ошибки. Содержит описание ошибки"}}}]
)
)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="Нарисуй горы")],
function_call="auto",
functions=[
Function(name="text2image"),
weather_forecast_function
]
)
response = giga.chat(payload)
print (response)
Совместное использование функций с помощью партнерского пакета langchain-gigachat:
from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate
llm = GigaChat(
credentials="<ключ_авторизации>",
verify_ssl_certs=False
)
tools = [
{
"name": "text2image",
},
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
]
llm = llm.bind_tools(tools=tools, tool_choice="auto")
prompt = ChatPromptTemplate.from_messages(
[
("user", """{topic}"""),
]
)
combined_functions_chain = prompt | llm
response = combined_functions_chain.invoke({"topic": "Нарисуй горы"})
print(response)
Генерация аргументов с помощью SDK:
import { GigaChat } from 'gigachat';
const giga = new GigaChat({
credentials: '<ключ_авторизации>',
});
const weatherForecast = {
name: "weather_forecast",
description: "Возвращает температуру на заданный период",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
format: {
type: "string",
enum: [
"celsius",
"fahrenheit"
],
description: "Единицы измерения температуры"
},
num_days: {
type: "integer",
description: "Период, для которого нужно вернуть"
}
},
required: [
"location",
"num_days"
]
},
few_shot_examples: [
{
request: "Какая погода в Москве в ближайшие три дня",
params: {
location: "Moscow, Russia",
format: "celsius",
num_days: "3"
}
}
],
return_parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
temperature: {
type: "integer",
description: "Температура для заданного местоположения"
},
forecast: {
type: "array",
items: {
type: "string"
},
description: "Описание погодных условий"
},
error: {
type: "string",
description: "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
const resp = await giga.chat({
messages: [
{
role: "user",
content: "Нарисуй горы",
},
],
functions: [
{"name": 'text2image',},
weatherForecast
],
function_call: 'auto'
});
console.log(resp.choices[0]?.message);
Принудительный режим
Чтобы модель гарантированно создала аргументы для функции, указанной в массиве functions
, добавьте ее название в поле function_call
:
curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "Как дела"
}
],
"function_call": {
"name": "weather_forecast"
},
"functions": [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
}
}
]
}'
Совместное использование функций с помощью SDK:
from gigachat import GigaChat
from gigachat.models import Chat, Function, Messages, MessagesRole, FunctionParameters
from gigachat.models.few_shot_example import FewShotExample
from gigachat.models.chat_function_call import ChatFunctionCall
giga = GigaChat(credentials="<ключ_авторизации>", verify_ssl_certs=False)
weather_forecast_function=Function(
name="weather_forecast",
description="Возвращает температуру на заданный период",
parameters=FunctionParameters(
type="object",
properties={"location": {"type": "string", "description": "Местоположение, например, название города"}, "format": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Единицы измерения температуры"}, "num_days": {"type": "integer", "description": "Период, для которого нужно вернуть"}},
required=["location","format"],
few_shot_examples=[FewShotExample(
request="Какая погода в Москве в ближайшие три дня",
params={"location": "Moscow, Russia", "format": "celsius", "num_days": "3"}
)],
return_parameters=[{ "type": "object", "properties": {"location": {"type": "string", "description": "Местоположение, например, название города"}, "temperature": {"type": "integer", "description": "Температура для заданного местоположения"}, "forecast": {"type": "array", "items": {"type": "string"}, "description": "Описание погодных условий"}, "error": {"type": "string", "description": "Возвращается при возникновении ошибки. Содержит описание ошибки"}}}]
)
)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="Нарисуй горы")],
function_call=ChatFunctionCall(name="weather_forecast"),
functions=[
weather_forecast_function
]
)
response = giga.chat(payload)
print (response)
Совместное использование функций с помощью партнерского пакета langchain-gigachat:
from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate
llm = GigaChat(
credentials="<ключ_авторизации>",
verify_ssl_certs=False
)
tools = [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
]
llm = llm.bind_tools(tools=tools, tool_choice="weather_forecast")
prompt = ChatPromptTemplate.from_messages(
[
("user", """{topic}"""),
]
)
combined_functions_chain = prompt | llm
response = combined_functions_chain.invoke({"topic": "Нарисуй горы"})
print(response)
Генерация аргументов с помощью SDK:
import { GigaChat } from 'gigachat';
const giga = new GigaChat({
credentials: '<ключ_авторизации>',
});
const weatherForecast = {
name: "weather_forecast",
description: "Возвращает температуру на заданный период",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
format: {
type: "string",
enum: [
"celsius",
"fahrenheit"
],
description: "Единицы измерения температуры"
},
num_days: {
type: "integer",
description: "Период, для которого нужно вернуть"
}
},
required: [
"location",
"num_days"
]
},
few_shot_examples: [
{
request: "Какая погода в Москве в ближайшие три дня",
params: {
location: "Moscow, Russia",
format: "celsius",
num_days: "3"
}
}
],
return_parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "Местоположение, например, название города"
},
temperature: {
type: "integer",
description: "Температура для заданного местоположения"
},
forecast: {
type: "array",
items: {
type: "string"
},
description: "Описание погодных условий"
},
error: {
type: "string",
description: "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
const resp = await giga.chat({
messages: [
{
role: "user",
content: "Нарисуй горы",
},
],
function_call: {name: "weather_forecast"},
functions: [
weatherForecast
]
});
console.log(resp.choices[0]?.message);
Если в массиве functions
нет описания функции с подходящим названием, в ответ вернется ошибка с кодом 422:
{
"status": 422,
"message": "Invalid params: explicit_call function name must exist in functions"
}
Ответ модели
При работе с пользовательскими функциями, модель возвращает ответ с результатом "finish_reason": "function_call"
.
Сгенерированные аргументы для вызова пользовательской функции передаются в объекте message.function_call.arguments
:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
"function_call": {
"name": "weather_forecast",
"arguments": {
"location": "Москва",
"format": "celsius"
}
}
},
"index": 0,
"finish_reason": "function_call"
}
],
"created": 1700471392,
"model": "GigaChat",
"usage": {
"prompt_tokens": 150,
"completion_tokens": 35,
"total_tokens": 185
},
"object": "chat.completion"
}
Значение поля "finish_reason": "error"
, сообщает о том, что ответ модели содержит невалидные аргументы функции.
Потоковая генерация токенов
При генерации аргументов в потоковом режиме ("stream": true
) название функции (function_call.name
) и ее аргументы всегда передаются в одном фрагменте:
data: {"choices":[{"delta":{"content":"Манжерок — живописная деревня в Республике Алтай, расположенная у подножия горы с одноимённым названием, популярное место отдыха туристов.","role":"assistant"},"index":0}],"created":1750325298,"model":"GigaChat-2-Max:2.0.28.2","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"\n\n"},"index":0}],"created":1750325300,"model":"GigaChat-2-Max:2.0.28.2","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"","function_call":{"name":"weather_forecast","arguments":{"format":"celsius","location":"Манжерок","num_days":5}},"functions_state_id":"3e17f506-7a17-4fef-88d9-28109f1bb3a2"},"index":0,"finish_reason":"function_call"}],"created":1750325300,"model":"GigaChat-2-Max:2.0.28.2","object":"chat.completion","usage":{"prompt_tokens":135,"completion_tokens":73,"total_tokens":208,"precached_prompt_tokens":0}}
data: [DONE]
Передача результатов работы пользовательской функции
После исполнения пользовательской функции, передайте результат ее работы обратно в модель.
Для этого используйте сообщение с ролью function
в контексте диалога (массив messages
).
Поле content
должно содержать обернутый в строку валидный JSON-объект с результатом выполнения функции, имя которой указано в поле function_call.name
.
Пример:
{
"model": "GigaChat",
"messages": [
{
"role": "user",
"content": "Какая погода в Москве сегодня?"
},
{
"role": "assistant",
"content": "",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
"function_call": {
"name": "weather_forecast",
"arguments": {
"location": "Москва",
"format": "celsius"
}
}
},
{
"role": "function",
"content": "{\"temperature\": \"27\"}",
"name": "weather_forecast"
}
],
"functions": [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть прогноз"
}
},
"required": [
"location",
"num_days"
]
}
},
],
}
Подробнее о работе с контекстом диалога — в разделе Работа с историей чата.