Гайд · TNWS AI

Как получить JSON по схеме из Gemini API: Structured Outputs без парсинга текста

WindowsmacOSLinuxGemini#Gemini API #Structured Outputs #JSON Schema

11 сентября 2026 2 мин—

Рабочий JSON Schema для Gemini Structured Outputs, проверка результата через Zod, обязательные поля и обработка незавершённого ответа.

Задайте response_format с MIME-типом application/json и JSON Schema, затем повторно проверьте полученный объект валидатором приложения. Схема гарантирует структуру лучше текстовой просьбы «верни только JSON», но не подтверждает истинность значений.

Рабочий пример

import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const ai = new GoogleGenAI({});
const schema = {
  type: "object",
  properties: {
    intent: { type: "string", enum: ["order", "support", "other"] },
    order_id: { type: ["string", "null"] },
    confidence: { type: "number", minimum: 0, maximum: 1 }
  },
  required: ["intent", "order_id", "confidence"]
};

const r = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Где мой заказ 5412?", response_format: { type:"text", mime_type:"application/json", schema } });

const data = JSON.parse(r.output_text); console.log(data);


## Что означает каждая важная часть

- `enum` ограничивает класс заранее известными значениями и упрощает downstream-логику.
- Nullable `order_id` лучше выдуманной строки, когда номера нет.
- Диапазон confidence задаёт форму числа, но модельная уверенность не является статистически откалиброванной вероятностью без вашего теста.
- Сочетание Structured Outputs со встроенными tools официально поддерживается только на указанных Gemini 3 моделях; проверяйте матрицу возможностей.

## Порядок внедрения

1. Опишите минимальный контракт и примеры валидных/невалидных объектов.
2. Передайте schema и MIME-тип через `response_format`.
3. После ответа проверьте статус завершения, затем вызовите `JSON.parse`.
4. Провалите объект через Zod, Ajv или Pydantic; бизнес-правила проверяйте отдельно.
5. При ошибке не вырезайте фигурные скобки регулярным выражением — повторите запрос контролируемо или отправьте на ручную обработку.

## Как проверить результат

Набор должен включать обращение с номером заказа, без номера, с двумя номерами и нерелевантный текст. Проверяйте enum, nullable-поле и диапазон. Важный тест: строка «мой заказ миллион» не должна превращаться в выдуманный числовой ID.

## Ограничения

Не все конструкции JSON Schema могут поддерживаться одинаково. Очень сложную схему лучше разбить на этапы. Структурированный объект может быть фактически неверным, поэтому номера заказов, цены и даты сверяются с базой или источником.

## Чего не делать

Не записывайте JSON в базу до серверной проверки.
Не используйте confidence как доказательство истины.
Не делайте поле обязательным, если во входе его может не быть.

Частые вопросы

Можно ли использовать пример в production?

Как основу — да, но добавьте авторизацию, таймауты, обработку ошибок, лимиты и тесты из статьи.

Где проверять актуальное имя модели?

В официальном каталоге Gemini API и Google AI Studio непосредственно перед развёртыванием.

Нужно ли доверять ответу без проверки?

Нет. Формат проверяется кодом, а важные факты — источником или вашей базой данных.

Что делать при изменении API?

Зафиксировать версию SDK, прочитать release notes и прогнать сохранённый набор интеграционных тестов.

Официальный источник

Документация Google, проверена 11 сентября 2026 года: https://ai.google.dev/gemini-api/docs/structured-output

Как получить JSON по схеме из Gemini API: Structured Outputs без парсинга текста

Рабочий пример

Частые вопросы

Можно ли использовать пример в production?

Где проверять актуальное имя модели?

Нужно ли доверять ответу без проверки?

Что делать при изменении API?

Официальный источник

Читайте также

Как настроить function calling в Gemini API и не выполнить опасную команду

Как перейти с generateContent на Gemini Interactions API и не сломать приложение

Как подключить File Search в Gemini API и отвечать по своим документам

Комментарии