Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.
Практический гайд Продвинутый уровень До 12 минут

Длинные ответы Gemini в React-чате: продолжение генерации и контроль токенов

Длинные ответы Gemini в React-чате: продолжение генерации и контроль токенов
Temporary fallback cover; replace in editorial pass.

Потоковая генерация — это передача ответа по частям до завершения всей операции. Для коротких сообщений её достаточно подключить к интерфейсу. Для длинных ответов этого мало: модель может упереться в лимит вывода, соединение может закрыться, а приложение — ошибочно посчитать весь диалог новым контекстом.

В этой статье соберём воспроизводимую схему для React-чата на Next.js. Она решает три задачи:

1. Почему один длинный запрос ненадёжен

У запроса есть как минимум два независимых ограничения: размер входного контекста и максимальный объём генерируемого вывода. Если указать большой maxOutputTokens, это не гарантирует, что модель выдаст текст такого размера. Ответ может завершиться раньше по смыслу, по лимиту модели или из-за остановки соединения.

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

Безопасная модель состояния выглядит так:

{
  "conversationId": "conv_123",
  "answerId": "answer_456",
  "text": "Уже полученный текст...",
  "continuationToken": "opaque-server-token",
  "status": "truncated",
  "usage": {
    "promptTokens": 1840,
    "candidatesTokens": 4096,
    "totalTokens": 5936
  }
}

Сервер хранит не только текст. Ему нужно знать, какой пользовательский запрос породил ответ, какую модель использовали, на каком фрагменте остановились и какие значения usage уже подтверждены провайдером.

2. Контракт маршрута

Для примера используем маршрут app/api/chat/route.ts. Клиент отправляет либо новый запрос, либо continuationToken для продолжения. Сервер возвращает поток событий в формате NDJSON: каждая строка — отдельный JSON-объект.

POST /api/chat
Content-Type: application/json

{
  "message": "Объясни архитектуру очереди задач",
  "conversationId": "conv_123"
}

Запрос продолжения:

POST /api/chat
Content-Type: application/json

{
  "conversationId": "conv_123",
  "continuationToken": "opaque-server-token"
}

Примеры событий потока:

{"type":"delta","text":"Начнём с..."}
{"type":"usage","promptTokens":1840,"candidatesTokens":512,"totalTokens":2352}
{"type":"done","status":"truncated","continuationToken":"opaque-server-token"}

Событие done не означает, что ответ обязательно завершён по смыслу. Поле status должно различать нормальное завершение, остановку по лимиту и ошибку транспорта.

3. Безопасная конфигурация Next.js

Ключ Gemini должен находиться только на сервере. Не добавляйте его в переменные с префиксом NEXT_PUBLIC_ и не передавайте в браузер.

# .env.local
GEMINI_API_KEY=replace-with-your-server-side-secret
GEMINI_MODEL=gemini-2.5-flash

Файл .env.local не следует коммитить. Если проект уже содержит секрет в истории Git, простого удаления файла недостаточно: ключ нужно отозвать и выпустить новый в панели провайдера.

Минимальные команды для нового проекта:

npx create-next-app@latest gemini-chat
cd gemini-chat
npm install @google/genai
npm run dev

Команды выше — пример воспроизводимого окружения. Версии пакетов могут меняться, поэтому в рабочем проекте фиксируйте зависимости lock-файлом и проверяйте совместимость выбранной модели с используемым SDK.

4. Серверный маршрут с потоковой генерацией

Ниже показан каркас маршрута. Хранилище намеренно оставлено абстрактным: в продакшене это может быть база данных, Redis или другой серверный storage. Главное правило — continuation token не должен содержать секреты и не должен позволять клиенту произвольно подменить контекст.

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

type ChatRequest = {
  message?: string;
  conversationId: string;
  continuationToken?: string;
};

export async function POST(request: Request) {
  const body = (await request.json()) as ChatRequest;

  if (!body.conversationId) {
    return Response.json(
      { error: "conversationId is required" },
      { status: 400 }
    );
  }

  const state = body.continuationToken
    ? await loadContinuation(body.continuationToken)
    : await createConversationState({
        conversationId: body.conversationId,
        message: body.message ?? "",
      });

  if (!state) {
    return Response.json(
      { error: "Continuation state was not found" },
      { status: 404 }
    );
  }

  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      let text = "";

      try {
        const result = await ai.models.generateContentStream({
          model: process.env.GEMINI_MODEL ?? "gemini-2.5-flash",
          contents: state.contents,
          config: {
            maxOutputTokens: state.outputBudget,
          },
        });

        for await (const chunk of result) {
          const delta = chunk.text ?? "";

          if (delta) {
            text += delta;
            controller.enqueue(
              encoder.encode(JSON.stringify({
                type: "delta",
                text: delta
              }) + "\n")
            );
          }
        }

        const usage = await readUsageIfAvailable(result);

        await appendAnswer(state.answerId, text);
        await saveUsage(state.answerId, usage);

        const truncated = isContinuationRequired({
          text,
          usage,
          outputBudget: state.outputBudget,
        });

        const nextToken = truncated
          ? await issueContinuation({
              ...state,
              generatedText: text,
            })
          : null;

        controller.enqueue(
          encoder.encode(JSON.stringify({
            type: "usage",
            ...usage
          }) + "\n")
        );

        controller.enqueue(
          encoder.encode(JSON.stringify({
            type: "done",
            status: truncated ? "truncated" : "complete",
            continuationToken: nextToken
          }) + "\n")
        );

        controller.close();
      } catch (error) {
        controller.enqueue(
          encoder.encode(JSON.stringify({
            type: "error",
            message: "Generation failed"
          }) + "\n")
        );

        controller.error(error);
      }
    }
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "application/x-ndjson; charset=utf-8",
      "Cache-Control": "no-cache",
      "X-Content-Type-Options": "nosniff"
    }
  });
}

Функции loadContinuation, createConversationState и issueContinuation здесь являются границами приложения, а не готовыми функциями SDK. Их реализация зависит от выбранного хранилища.

5. Как формировать продолжение без повторения

При продолжении нельзя бездумно отправлять в модель весь уже полученный ответ и просить «продолжить». Лучше хранить структурированное состояние и явно обозначать границу уже выданного текста.

function buildContinuationContents(state: {
  userMessage: string;
  generatedText: string;
}) {
  return [
    {
      role: "user",
      parts: [{ text: state.userMessage }]
    },
    {
      role: "model",
      parts: [{ text: state.generatedText }]
    },
    {
      role: "user",
      parts: [{
        text:
          "Продолжи ответ с места остановки. " +
          "Не повторяй уже выданный текст. " +
          "Сохраняй тот же язык, структуру и формат."
      }]
    }
  ];
}

Важна идемпотентность. Если пользователь дважды нажал «Продолжить», сервер должен распознать повторное использование одного continuation token и вернуть уже созданный результат либо безопасную ошибку. Иначе два параллельных запроса могут породить две разные ветки ответа.

6. React-клиент: чтение NDJSON и кнопка продолжения

Браузер читает поток через ReadableStream. Поскольку граница сетевого чанка не обязана совпадать с границей строки, накопительный буфер нужно разбирать построчно.

"use client";

import { useState } from "react";

type Usage = {
  promptTokens: number;
  candidatesTokens: number;
  totalTokens: number;
};

export function Chat() {
  const [answer, setAnswer] = useState("");
  const [continuationToken, setContinuationToken] = useState<string | null>(null);
  const [usage, setUsage] = useState<Usage | null>(null);
  const [loading, setLoading] = useState(false);

  async function run(payload: Record<string, unknown>) {
    setLoading(true);

    const response = await fetch("/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload)
    });

    if (!response.ok || !response.body) {
      setLoading(false);
      throw new Error("Chat request failed");
    }

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const { value, done } = await reader.read();
      buffer += decoder.decode(value ?? new Uint8Array(), {
        stream: !done
      });

      const lines = buffer.split("\n");
      buffer = lines.pop() ?? "";

      for (const line of lines) {
        if (!line.trim()) continue;

        const event = JSON.parse(line);

        if (event.type === "delta") {
          setAnswer((current) => current + event.text);
        }

        if (event.type === "usage") {
          setUsage(event);
        }

        if (event.type === "done") {
          setContinuationToken(event.continuationToken ?? null);
        }

        if (event.type === "error") {
          throw new Error(event.message);
        }
      }

      if (done) break;
    }

    setLoading(false);
  }

  async function send(message: string) {
    setAnswer("");
    setContinuationToken(null);
    setUsage(null);

    await run({
      conversationId: crypto.randomUUID(),
      message
    });
  }

  async function continueAnswer() {
    if (!continuationToken) return;

    await run({
      conversationId: "current-conversation",
      continuationToken
    });
  }

  return (
    <section>
      <div aria-live="polite">{answer}</div>

      {continuationToken && (
        <button onClick={continueAnswer} disabled={loading}>
          {loading ? "Генерация..." : "Продолжить"}
        </button>
      )}

      {usage && (
        <small>
          Контекст: {usage.promptTokens}; вывод: {usage.candidatesTokens};
          всего: {usage.totalTokens}
        </small>
      )}
    </section>
  );
}

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

7. Корректный учёт токенов

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

Разделяйте минимум четыре величины:

Для цепочки из двух запросов правильная агрегированная статистика выглядит как сумма фактических usage-событий:

const aggregate = requests.reduce(
  (total, request) => ({
    promptTokens: total.promptTokens + request.promptTokens,
    candidatesTokens: total.candidatesTokens + request.candidatesTokens,
    totalTokens: total.totalTokens + request.totalTokens,
  }),
  {
    promptTokens: 0,
    candidatesTokens: 0,
    totalTokens: 0,
  }
);

Если SDK не возвращает usage в потоковом ответе, не подменяйте его числом символов или приблизительным коэффициентом без явной маркировки. Можно показывать статус «оценка недоступна» либо получать подтверждённые данные отдельным способом, если это поддерживает выбранная интеграция.

8. Ограничение размера сохранённого состояния

Continuation token должен ссылаться на состояние с ограниченным временем жизни. Храните в нём только необходимое: идентификатор ответа, пользователя, хэш параметров генерации, текущий текст и срок действия. Большой текст лучше держать отдельно, а токен делать коротким случайным идентификатором.

type ContinuationState = {
  tokenHash: string;
  userId: string;
  conversationId: string;
  answerId: string;
  generatedText: string;
  model: string;
  expiresAt: string;
  consumedAt: string | null;
};

При создании продолжения проверьте владельца состояния, срок действия, соответствие conversation ID и отсутствие уже использованного токена. Эти проверки должны выполняться на сервере, даже если интерфейс скрывает кнопку.

9. Проверка результата

Проверьте сценарий вручную в таком порядке:

  1. Отправьте запрос, достаточно длинный для выбранного лимита вывода.
  2. Убедитесь, что текст появляется постепенно, а не одной строкой после завершения.
  3. Проверьте, что после остановки показывается кнопка «Продолжить».
  4. Нажмите кнопку один раз и убедитесь, что новый фрагмент добавляется к старому.
  5. Повторно отправьте тот же continuation token и проверьте защиту от дублирования.
  6. Сравните usage первого и второго запросов с агрегированной статистикой интерфейса.
  7. Откройте инструменты разработчика и убедитесь, что API-ключ не попал в JavaScript-бандл или сетевые запросы браузера.

Для локальной проверки маршрута можно использовать безопасный запрос без передачи секрета в командной строке:

curl -N \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"local-test","message":"Короткий проверочный ответ"}' \
  http://localhost:3000/api/chat

Флаг -N отключает буферизацию вывода curl, чтобы потоковые строки было видно по мере поступления. Не вставляйте секреты в команду, историю shell или публичные issue.

10. Типовые ошибки

Клиент ждёт обычный JSON

Поток нельзя обрабатывать единственным вызовом response.json(), пока сервер не завершит ответ. Для NDJSON нужен reader и накопительный буфер.

Продолжение начинается с повторения

Обычно сервер не сохранил точную границу ответа или новый запрос не получил предыдущий model-фрагмент. Сохраняйте завершённый текст отдельно и передавайте явную инструкцию не повторять его.

Usage растёт после каждой перерисовки

Метрики должны обновляться только из серверных usage-событий. React state не является источником данных о токенах.

Кнопка создаёт несколько веток

Заблокируйте кнопку на время запроса, добавьте идемпотентность на сервере и помечайте continuation token использованным после успешной фиксации результата.

Слишком большой контекст продолжения

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

11. Ограничения схемы

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

Схема также не гарантирует идеальное продолжение по смыслу. Модель может изменить формулировку, добавить повтор или завершить мысль раньше. Поэтому continuation token — механизм управления состоянием, а не гарантия детерминированного декодирования.

Для потоков с важными данными добавьте отмену через AbortController, журналирование идентификаторов запросов и отдельную политику удаления незавершённых состояний. Не записывайте в логи полный пользовательский текст без необходимости.

Итог

Надёжный длинный ответ в React-чате строится вокруг серверного состояния, а не вокруг одной большой строки в браузере. Поток отдаёт пользователю уже готовые фрагменты, continuation token указывает на сохранённую точку продолжения, а usage считается по фактическим запросам Gemini.

Такая граница позволяет продолжать генерацию кнопкой, переживать остановку соединения и не выдавать повторный контекст за новый пользовательский ввод. Дополнительные практические материалы собраны в разделе гайдов, а термины можно сверить в глоссарии.