На главную

Tool calling

Модель запрашивает вызов функции. Приложение проверяет аргументы, выполняет функцию и возвращает результат.

Содержание
  1. Задача
  2. Как это работает
  3. Первый запрос к модели
  4. Аргументы функции
  5. Как связать вызов с результатом
  6. Главное
LLM отправляет запрос на вызов функции приложению Node.js. Приложение возвращает результат модели.

Задача

Я загружаю в AI Playable Production трёхминутную запись геймплея в MP4. На выходе хочу получить геймдизайн-документ с описанием того, что делает игрок, какие правила видны на записи, как меняется интерфейс и когда игра переходит из одного состояния в другое.

Как это работает

  1. Приложение готовит кадры. Node.js запускает FFmpeg и берёт по одному кадру в секунду. Из трёхминутного видео получается 180 изображений с таймкодами. Короткое действие между двумя кадрами может остаться за пределами выборки. FFmpeg — фильтр fps
  2. Модель запрашивает кадры порциями. Node.js отправляет задачу и описание функции get_video_frames через OpenAI Responses API. Модель запрашивает кадры с 0 по 11, а приложение возвращает изображения с таймкодами. Следующая порция начинается с кадра 12.
  3. Модель составляет документ. Для каждой минуты записи Node.js начинает отдельный диалог и получает наблюдения по этому отрезку. В последний запрос идут текстовые наблюдения по всей записи. Из них модель собирает один геймдизайн-документ.
Видео геймплея MP4 · 3 минуты
Node.js Готовит и выдаёт кадры
Модель OpenAI Запрашивает и анализирует кадры
Геймдизайн-документ Механика, правила и интерфейс

В этом и состоит tool calling. Модель запрашивает вызов get_video_frames, Node.js выполняет его и отправляет результат обратно модели. OpenAI — цикл вызова функций

Первый запрос к модели

В input передаём текст задачи, в instructions — диапазон и размер порции, в tools — описание функции. Переменная model содержит ID модели, а объект getVideoFrames описан ниже.

import OpenAI from 'openai';

const client = new OpenAI();
const response = await client.responses.create({
	model,
	input: 'Разбери запись геймплея и составь геймдизайн-документ.',
	instructions: 'Для анализа подготовлено 180 кадров. Разбери кадры 0–59 по 12 за вызов.',
	tools: [getVideoFrames],
});

Аргументы функции

Формат описания инструмента задаёт OpenAI Responses API. Объект в массиве tools содержит поля type, name, description, strict и parameters. Внутри parameters мы сами описываем аргументы нашей функции по правилам JSON Schema. Здесь это fromFrame и count. OpenAI — описание функций

const getVideoFrames = {
	type: 'function',
	name: 'get_video_frames',
	description: 'Read consecutive frames from a 1 FPS sample of the uploaded video. Returns JPEG images and timestamps.',
	strict: true,
	parameters: {
		type: 'object',
		properties: {
			fromFrame: { type: 'integer', minimum: 0 },
			count: { type: 'integer', minimum: 1, maximum: 12 },
		},
		required: ['fromFrame', 'count'],
		additionalProperties: false,
	},
} satisfies OpenAI.Responses.FunctionTool;

fromFrame — индекс первого кадра в подготовленной выборке, count — сколько кадров прочитать подряд. Например, { fromFrame: 12, count: 12 } запрашивает кадры с 00:12 по 00:23. В этом примере приложение работает с одним видео, поэтому идентификатор файла в аргументах не нужен.

strict: true требует, чтобы аргументы соответствовали схеме. Перед чтением кадров Node.js дополнительно проверяет, что запрошенный индекс входит в текущий отрезок видео.

Как связать вызов с результатом

В первом ответе API модель может вернуть такой элемент в response.output. Идентификаторы в примере условные.

{
  "type": "function_call",
  "name": "get_video_frames",
  "call_id": "call_first",
  "arguments": "{\"fromFrame\":0,\"count\":12}"
}

arguments приходит строкой с JSON. Функция execute разбирает её, проверяет аргументы и читает JPEG-файлы. При успешном вызове она возвращает пары из таймкода (input_text) и изображения (input_image). В примере ниже call — элемент function_call из response.output, а options содержит настройки запроса, включая model, instructions и tools.

const output = execute(call, frames, delivered, start, end);
const next = await client.responses.create({
	...options,
	previous_response_id: response.id,
	input: [{
		type: 'function_call_output',
		call_id: call.call_id,
		output,
	}],
});
  • call_id связывает результат с конкретным вызовом функции. В function_call_output копирую его из function_call.
  • previous_response_id ссылается на предыдущий ответ API. Копирую его из response.id, чтобы следующий запрос продолжил тот же обмен.

Следующий ответ может содержать ещё один function_call. Когда модель присылает текстовые наблюдения по отрезку, приложение переходит к следующему. В каждом запросе внутри диалога мы заново передаём instructions и tools. Поле previous_response_id сохраняет связь с диалогом, а instructions действуют только на запрос, в котором переданы. OpenAI — результаты вызовов · Состояние разговора

Источники

Главное

  1. Модель запрашивает кадры.
  2. Node.js исполняет запрос.
  3. Модель пишет геймдизайн-документ.