ym88659208ym87991671
Генерация аргументов | Документация для разработчиков

Генерация аргументов

Обновлено 4 августа 2025

В этом разделе вы найдете примеры генерации аргументов для пользовательских функций в различных режимах, а также узнаете, как работает генерация аргументов в потоковом режиме и как вернуть в модель результат работы функции.

Пользовательские функции — это функции, реализованные в вашем приложении или стороннем сервисе.

Модели GigaChat могут генерировать аргументы для таких функций на основе их описания, полученного в массиве functions, в запросе POST /chat/completions. Используйте полученные аргументы для вызова функции, а результаты ее работы возвращайте в модель в сообщении с ролью function.

Модели умеют генерировать аргументы автоматически, в зависимости от промпта, или принудительно. Подробнее — в разделе Режимы работы с функциями.

Рекомендации по описанию пользовательских функций и примеры — в разделе Описание пользовательских функций.

Быстрый старт

Чтобы модель сгенерировала аргументы для вашей функции, просто передайте ее описание в массиве functions вместе с подходящим промптом:

Генерация аргументов с помощью 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)

Автоматический режим

В этом режиме модель анализирует полученные сообщения (массив 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": "Возвращается при возникновении ошибки. Содержит описание ошибки"
                    }
                }
            }
        }
    ]
}'

Принудительный режим

Чтобы модель гарантированно создала аргументы для функции, указанной в массиве 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"
                ]
            }
        }
    ]
}'

Если в массиве 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"
                ]
            }
        },
    ],
}

Подробнее о работе с контекстом диалога — в разделе Работа с историей чата.

Смотрите также
Описание пользовательских функций
Примеры, правила и рекомендации по описанию функций
Режимы работы с функциям
Описание того, как модели работают с функциями
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.