Тема использования JSON в ответах OpenAI API звучала в анонсах примерно год назад и до некоторой степени описана в документации. В частности, Сэм Альтман на презентации одного из крупных релизов говорил о том что о такой фиче активно просили разработчики. Однако с тех пор мне не удалось найти целостных описаний решений, сценариев и паттернов, которые выглядели бы как практически полезные и на основе которых можно было бы быстро составить целостное понимание. Те материалы, которые попадались мне до сих пор, показались мне довольно абстрактными, недостаточно целостными, оторванными от реальности, иногда перегруженными техническими подробностями, за которыми теряется общая картина.

Вчера (6 августа) OpenAI выпустила обновление этого функционала и вместе с ним заметно обновила и дополнила документацию в этой части. С одной стороны, в новой версии документации стало больше конкретных и наглядных примеров. С другой, - в дополнение к понятию Function calling добавилось еще новое понятие Structured Outputs, которое для начинающего пользователя на первых шагах может усложнить понимание.

В этой статье я хотел на небольшом примере дать краткий поверхностный обзор того как, на мой взгляд, можно задействовать JSON-ответы для конкретной задачи. Сразу скажу, что мой пример оказался крайне примитивным (чуть сложнее чем "Hello, World!"). Я старался достичь наглядности за счет демонстрации всего цикла от идеи "продукта", до его рабочего прототипа. Свою задачу я реализовал в трех вариантах (по мере возрастания сложности): "Чат без Function calling", "Чат с Function calling" и "Assistant Function calling". Возможно, кто-то найдет для себя в этом что-то полезное.

Постановка задачи

Для демонстрации этой фичи я в качестве примера взял следующую задачу: На вход AI пользователь отдает некоторый текст (статью или главу из книги, например), а на выходе AI возвращает массив из, например, трех вопросов об этом тексте и своих версий ответов на эти вопросы. Собственно, для того что бы с возвращаемым от API массивом вопросов-ответов было удобнее работать в пользовательском интерфейсе веб-приложения я и использую JSON.

Мое приложение включает в себя интерфейс ввода текста, бэк-компонент для обращений к OpenAI API и часть интерфейса, которая структурированно отображает пользователю JSON-ответы.

Chat-реализация

В самом примитивном виде основной элемент реализации - это практически стандартный вызов Chat Completions API, который включает в себя:

• параметр response_format: { type: "json_object" }

• промпт примерно следующего содержания:

You are a tutor who is supposed to help me memorize a text. To do this, you should ask three questions about the key ideas explained in the text and provide answers to these questions. Your response must be in json format, which is an array of pairs of questions and answers with a parent element named questions_and_answers. Your questions and answers should be about the following text:

В виде кода это выглядит так:

import OpenAI from 'openai';

export default defineEventHandler(async (event) => {
    const body = await readBody(event)
    const openai = new OpenAI({apiKey: process.env.OPENAI_API_KEY});
    const response = await openai.chat.completions.create({
    messages: [        
        {
            role: "system",
            content: "You are a helpful tutor who is supposed to help me memorize a text. To do this, you should ask three questions about the key ideas explained in the text and provide answers to these questions. Your response must be in json format, which is an array of pairs of questions and answers with a parent element named questions_and_answers. Your questions and answers must be in the same language as the input text, but names of json tags must always be in English.",
          },
          { role: "user", content: "Please provide questions and answers about the following text: "+body.InputText },

        ],
        model: "gpt-4o-mini",
        response_format: { type: "json_object" },
    });
    return JSON.parse(response.choices[0].message.content||"{}");
  })

Разделение промпта на две части (role: "system" и role: "user"), судя по моим наблюдениям, является избыточным - если поместить весь промпт в одну content-строку role: "user", то кажется что работает не хуже.

Параметр InputText приходит с веб-интерфейса. В ответе от API приходит JSON в виде строки, которую нужно преобразовать с помощью JSON.parse и вернуть на UI:

{
  "questions_and_answers": [
    {
      "question": "What is JSON Schema?",
      "answer": "JSON Schema is a declarative language used to describe and validate the structure and content of JSON data."
    },
    {
      "question": "What does JSON Schema provide for JSON documents?",
      "answer": "JSON Schema provides a standardized way to define the expected format, data types, and constraints for JSON documents."
    },
    {
      "question": "What is required to validate a JSON document against a schema?",
      "answer": "To validate a JSON document against a schema, you need a JSON Schema validator that implements the JSON Schema specification."
    }
  ]
}

В UI вопросы отображаются сразу, а ответы скрыты что бы дать возможность пользователю сначала самому подумать, а потом уже посмотреть готовый "правильный" ответ (собственно, ради такого "интерактивного" представления в интерфейсе вся эта суматоха и затевалась):

<fwb-accordion>
  <fwb-accordion-panel v-for="(item, index) in qadata_json.questions_and_answers" :key="index">
      <fwb-accordion-header>{{item.question}}</fwb-accordion-header>
      <fwb-accordion-content>
        <div><p>{{item.answer}}</p></div>
      </fwb-accordion-content>
  </fwb-accordion-panel>
</fwb-accordion>

Тут можно посмотреть как приложение (Nuxt) выглядит в целом: GitHub & Prod. Реализацию вызова API можно найти в getqabasic.ts, а UI - в index.vue.

Это, вероятно, самый примитивный подход к работе с JSON. Перейдем к чуть более сложному варианту.

Function calling / Structured outputs

Function calling - это механизм с помощью которого можно заставить API возвращать не просто JSON, а JSON определенного формата (в общем случае это могут быть и другие структурированные форматы). Т.е. это замена абстрактного response_format: { type: "json_object" } на формальное описание конкретной структуры ответа API - названий полей, их типов и структуры вложенности. Делается это путем добавления в запрос параметра tools, в котором содержатся:

• заголовочные поля: type: "function", name и description

• раздел parameters, содержащий JSON-схему с описанием структуры полей, которые должны присутствовать в JSON-ответе при вызове Chat Completions API

• опциональный параметр strict: true, дополнительно указывающий на то что ответ должен обязательно в точности соответствовать JSON-схеме. Cудя по документации, без него могут быть галлюцинации в виде потерянных обязательных полей и некорректных enum-ов, а также какие-то проблемы из-за кэширования. Этот параметр как раз является элементом фичи "Structured outputs", выпущенной во вчерашнем релизе, про который я писал во введении.

Также в запрос API можно включить параметр tool_choice , в котором будет дополнительно явно указано на использование этой "функции" (т.е., другими словами, явно указать что именно этот формат JSON обязательно нужно использовать в ответе).

Таким образом обращение к API приобретает следующий вид (getqafunctioncalling.ts):

export default defineEventHandler(async (event) => {
    const body = await readBody(event)
    const openai = new OpenAI({apiKey: process.env.OPENAI_API_KEY});
    const response = await openai.chat.completions.create({
    messages: [
        {
            role: "system",
            content: "You are a helpful tutor who is supposed to help me memorize a text. To do this, you should ask three questions about the key ideas explained in the text and provide answers to these questions. Your response must be in json format, which is an array of pairs of questions and answers with a parent element named questions_and_answers. Your questions and answers must be in the same language as the input text, but names of json tags must always be in English.",
          },
          { role: "user", content: "Please provide questions and answers about the following text: "+body.InputText },

        ],
    model: "gpt-4o-mini",

    tools: [
        {
          type: "function",
          function: {
            name: "questions_and_answers",
            description: "Formulate three questions about the given text and provide answers to them",
            parameters: {
                type: "object",
                properties: {
                    questions_and_answers: {
                    type: "array",
                    items: {
                        type: "object",
                            properties: {
                                question: { type: "string" },
                                answer: { type: "string" }
                              },
                required: [ "question", "answer" ]
                      }
                      }
                  },
            required: [ "questions_and_answers"]
            },
            },
          strict: true,
        },
      ],

    tool_choice: {"type": "function", "function": {"name": "questions_and_answers"}},
    });

    return JSON.parse(response.choices[0].message.tool_calls[0].function.arguments || "{}");
  })

Как видно в этом примере, структура "функционального" ответа, получаемого от API, немного отличается от ответа "обычного чата":

//Chat & response_format: { type: "json_object" }:
response.choices[0].message.content
//vs
//Function calling:
response.choices[0].message.tool_calls[0].function.arguments

В моем примере ответы в обеих реализациях содержат полностью идентичные JSON-строки, которые возвращаются на UI и отображаются точно также как описано в предыдущем разделе.

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

Assistants Function calling

Вводную статью про "Ассистентов" OpenAI API я публиковал на Хабре несколько месяцев назад. Теперь на примере текущей задачи посмотрим как они работают с JSON-ответами.

Ассистента для моей задачи я создал вручную. Для этого в моем новом Ассистенте вместе со стандартными параметрами (название, модель) добавлены:

• Instructions - промпт, сходный с тем что был использован для двух предыдущих вариантов реализации

• "Функцию" - json-схему ответа, такую же какая была использована в предыдущем разделе:

  

• Параметр Response format - json_object (он становится доступным для выбора после того как в Ассистент добавлена хотя бы одна "функция"):

В таком виде настройка Response format стала отображаться буквально сегодня. Еще вчера это был переключатель между двумя значениями

А сегодня (в результате уже упомянутого релиза Structured outputs) она превратилась в выпадающий список и добавилась третья опция: json_schema.

Сначала проверяю результаты работы Ассистента в плэйграунде:

На первый взгляд, кажется что запрос отработал нормально, но если приглядеться, то можно увидеть, что после ответа появилось новое поле ввода "Submit output", которого нет, если использовать Ассистент в режиме текстового чата. При этом диалог заблокирован и постоянно отображает подсказку A Run is currently in progress.

Дело в том что после получения и обработки "функционального" запроса тред (а точнее говоря, Run) повисает в статусе status: "requires_action"  &  required_action.type = submit_tool_outputs. Это, видимо, означает что сформированный JSON должен быть использован в качестве входного параметра для вызова внешней функции, эта функция должна отработать, вернуть результат, который нужно вернуть Ассистенту, что бы он мог выйти из ступора (т.е. из статуса requires_action). Я пока до конца не понял как этим правильно пользоваться (в плейграунде мне отображаются ошибки) и какие тут предполагаются паттерны работы. Если у кого-то есть практический опыт, то прошу делиться в комментариях.

Если оставить в покое плейграунд, то с точки зрения программной реализации на начальных шагах также как и в случае "обычного Ассистента" нужно создать Тред с сообщением (message, который содержит только InputText) и запустить Run. Для этого вместо отдельных операций threads.create, messages.create и runs.createможно использовать метод openai.beta.threads.createAndRun, о существовании которого я раньше не знал (может быть он недавно появился?):

  const run = await openai.beta.threads.createAndRun({
        assistant_id: "asst_mOWx3RKHDMgmmKybwKvIHSGL",
        tool_choice: { type: "function", function: { name: "questions_and_answers" } },
        thread: {
          messages: [{ role: "user", content: body.InputText }],
        },
      });

Дальше ждем завершения Run'а. Ожидаемый статус, как я уже сказал, теперь будет requires_action (а не completedкак хотелось бы). Для перехода на следующий шаг я сделал следующее:

• получил идентификатор tool_calls

• использовал этот идентификатор (в сочетании с пустым параметром output: "") для вызова метода submitToolOutputs, который переводит Run в "нормальный" статус completed:

  const call_id = await openai.beta.threads.runs.retrieve(run.thread_id, run.id);
  const call_output = await openai.beta.threads.runs.submitToolOutputs(run.thread_id, run.id, 
        {tool_outputs: 
         [
           {tool_call_id: call_id.required_action?.submit_tool_outputs?.tool_calls[0].id, 
           output: ""}
         ]
        }
    );

В таком виде это, скорее, workaround. Но по крайней мере в итоге можно извлечь ответ из Треда штатными средствами (и при необходимости продолжить диалог с Ассистентом, если бы мое приложение было более сложным и предполагало бы несколько итераций "запрос-ответ").

const assistants_response = await openai.beta.threads.messages.list( run.thread_id );
return JSON.parse(assistants_response.data[0].content[0].text.value);

Всю реализацию этого вызова можно найти тут: getqaassistant.ts

В результате возвращается такой же JSON как и в двух предыдущих случаях.

Вместо заключения

В прошлой статье про Ассистентов в голосовании 17 человек указали что они или уже пользуются или знают как практически пользоваться этим инструментом. При этом никто не поделился конкретной информацией. Если вы используете JSON-ответы от AI-API (не обязательно OpenAI) для чего-то действительно полезного, то прошу активнее делиться своими практическими кейсами.

Материалы

Introduction to Structured Outputs - полезные примеры из новой документации (только чат)

Assistants API Overview (Python SDK) - пример Function call в Ассистенте