Вызвать функцию из модели

При работе с моделями вы можете обращаться к внешним инструментам, API и базам данных с помощью вызова функций.

Например, у вас есть функция weatherTool, которая в качестве входного параметра принимает название города и возвращает текущую температуру в нем. Обработку ответов модели, работу функции и формирование запросов вам нужно предусмотреть самостоятельно.

Чтобы модель могла вызвать функцию, если это будет необходимо:

  1. Сформируйте запрос к модели, например, в файле body.json:

    {
            "modelUri": "gpt://<идентификатор_каталога>/yandexgpt",
            "tools": [
                {
                    "function": {
                        "name": "weatherTool",
                        "description": "Получает текущую погоду в указанном городе.",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "city": {
                                    "type": "string",
                                    "description": "Название города, например, Москва"
                                }
                            },
                            "required": [
                                "city"
                            ]
                        }
                    }
                }
            ],
            "messages": [
                {
                    "role": "user",
                    "text": "Какая погода в Санкт-Петербурге?"
                }
            ]
        }

    Где:

    • messages — массив сообщений, которые задают контекст для модели:

      • role — роль отправителя сообщения:

        • user — предназначена для отправки пользовательских сообщений к модели.
        • system — позволяет задать контекст запроса и определить поведение модели.
        • assistant — используется для ответов, которые генерирует модель. При работе в режиме чата ответы модели, помеченные ролью assistant, включаются в состав сообщения для сохранения контекста беседы. Не передавайте сообщения пользователя с этой ролью.

      • text — текстовое содержимое сообщения.

  2. Отправьте запрос к модели:

    export FOLDER_ID=<идентификатор_каталога>
        export IAM_TOKEN=<IAM-токен>
        curl \
          --request POST \
          --header "Content-Type: application/json" \
          --header "Authorization: Bearer ${IAM_TOKEN}" \
          --header "x-folder-id: ${FOLDER_ID}" \
          --data "@<путь_до_файла_json>" \
          "https://ai.api.cloud.yandex.net/foundationModels/v1/completion"

    Где:

    • FOLDER_ID — идентификатор каталога, на который у вашего аккаунта есть роль ai.languageModels.user или выше.
    • IAM_TOKEN — IAM-токен вашего аккаунта.

  3. Модель вернет ответ с полем ToolCallList, содержащим обращение к вызываемой функции и необходимые параметры в виде JSON Schema.

    Пример ответа:

    {
            "result": {
              "alternatives": [
                {
                  "message": {
                    "role": "assistant",
                    "toolCallList": {
                      "toolCalls": [
                        {
                          "functionCall": {
                            "name": "weatherTool",
                            "arguments": {
                              "city": "Санкт-Петербург"
                            }
                          }
                        }
                      ]
                    }
                  },
                  "status": "ALTERNATIVE_STATUS_TOOL_CALLS"
                }
              ],
              "usage": {
                "inputTextTokens": "74",
                "completionTokens": "14",
                "totalTokens": "88",
                "completionTokensDetails": {
                  "reasoningTokens": "0"
                }
              },
              "modelVersion": "23.10.2024"
            }
        }

  4. Обработайте ответ модели (поле toolCallList) и инициируйте работу функции weatherTool, передав в нее пришедшие параметры.

  5. Дополните массив messages в файле body.json ответом модели и результатами вызова функции.

    Пример запроса
    {
            "modelUri": "gpt://<идентификатор_каталога>/yandexgpt",
            "tools": [
              {
                "function": {
                  "name": "weatherTool",
                  "description": "Получает текущую погоду в указанном городе.",
                  "parameters": {
                    "type": "object",
                    "properties": {
                      "city": {
                        "type": "string",
                        "description": "Название города, например, Москва"
                      }
                    },
                    "required": ["city"]
                  }
                }
              }
            ],
            "messages": [
              {
                "role": "user",
                "text": "Какая погода в Санкт-Петербурге?"
              },
              {
                "role": "assistant",
                "toolCallList": {
                  "toolCalls": [
                    {
                      "functionCall": {
                        "name": "weatherTool",
                        "arguments": {
                          "city": "Санкт-Петербург"
                        }
                      }
                    }
                  ]
                }
              },
              {
                "role": "user",
                "toolResultList": {
                  "toolResults": [
                    {
                      "functionResult": {
                        "name": "weatherTool",
                        "content": "8°C"
                      }
                    }
                  ]
                }
              }
            ]
        }

    Где toolResultList — результаты вызова функции.

  6. Отправьте новый запрос к модели, повторив второй шаг инструкции. Модель сформулирует ответ с учетом результатов вызова функции:

    {
          "result": {
            "alternatives": [
              {
                "message": {
                  "role": "assistant",
                  "text": "В Санкт-Петербурге сейчас 8°C."
                },
                "status": "ALTERNATIVE_STATUS_FINAL"
              }
            ],
            "usage": {
              "inputTextTokens": "108",
              "completionTokens": "10",
              "totalTokens": "118",
              "completionTokensDetails": {
                "reasoningTokens": "0"
              }
            },
            "modelVersion": "23.10.2024"
          }
        }
Предыдущая
Асинхронный запрос
Следующая
Пакетная обработка данных