JSON-streaming van OpenAI en Together AI: NDJSON, TTFT-validatie en meting
Taak
De applicatie genereert via LLM een lijst met kaarten (producten, taken, testvragen) en wil deze weergeven zoals ze verschijnen, in plaats van te wachten op het volledige antwoord. U moet een provider kiezen en ervoor zorgen dat de streaminguitvoer veilig kan worden geparseerd.
Er zal hier geen tabel zijn met ‘wie is sneller’. De snelheid is afhankelijk van het model, de promptlengte, de regio, de providerbelasting en het tijdstip van de dag, en de cijfers van anderen betekenen weinig voor uw scenario. Hieronder leest u hoe u de code onafhankelijk van de aanbieder kunt maken en hoe u deze zelf kunt meten.
Eén klant voor twee providers
Together AI biedt een OpenAI-compatibele API, dus de officiële SDK openai werkt ermee bij het wijzigen van baseURL:
// lib/llm.ts
import OpenAI from "openai";
export const providers = {
openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
together: new OpenAI({ apiKey: process.env.TOGETHER_API_KEY, baseURL: "https://api.together.xyz/v1" }),
};
export const models = {
openai: process.env.OPENAI_MODEL!, // идентификатор модели из каталога OpenAI
together: process.env.TOGETHER_MODEL!, // идентификатор модели из каталога Together
};Bewaar model-ID's in omgevingsvariabelen: catalogi worden bijgewerkt en voor het wisselen van modellen hoeft geen code te worden geïmplementeerd.
Waarom stream je niet één grote JSON
Als je het model vraagt om {"items":[...]} terug te sturen, komen er stukken als {"items":[{"title":"Ко in de stream. JSON.parse genereert een uitzondering in zo'n fragment, en iets kan pas aan de gebruiker worden getoond na het afsluitende haakje. Er zijn bibliotheken voor het parseren van gedeeltelijke JSON, maar deze maken de code ingewikkelder en gedragen zich anders op bungelende lijnen.
Het is eenvoudiger om het formaat te wijzigen: één regel - één volledig JSON-object (NDJSON). Elke voltooide regel wordt onafhankelijk geparseerd en gecontroleerd.
Prompt en parseren
// lib/stream-cards.ts
import { z } from "zod";
import { providers, models } from "./llm";
const Card = z.object({
title: z.string().min(1).max(120),
description: z.string().max(500),
tags: z.array(z.string()).max(5),
});
export type Card = z.infer<typeof Card>;
const SYSTEM = `Отвечай только строками NDJSON. Каждая строка — один JSON-объект вида
{"title": string, "description": string, "tags": string[]}.
Без markdown, без обрамляющего массива, без пояснений до и после.`;
export async function* streamCards(provider: keyof typeof providers, topic: string) {
const stream = await providers[provider].chat.completions.create({
model: models[provider],
stream: true,
temperature: 0.4,
messages: [
{ role: "system", content: SYSTEM },
{ role: "user", content: `Сгенерируй 8 карточек по теме: ${topic}` },
],
});
let buffer = "";
for await (const chunk of stream) {
buffer += chunk.choices[0]?.delta?.content ?? "";
let nl: number;
while ((nl = buffer.indexOf("\n")) !== -1) {
const line = buffer.slice(0, nl).trim();
buffer = buffer.slice(nl + 1);
const card = parseLine(line);
if (card) yield card;
}
}
const last = parseLine(buffer.trim());
if (last) yield last;
}
function parseLine(line: string): Card | null {
if (!line || line.startsWith("```")) retourneert nul;
probeer {
const resultaat = Card.safeParse(JSON.parse(line));
resultaat retourneren.succes? resultaat.data: null;
} vangst {
retourneer nul; // gebroken lijn: sla de hele stream over in plaats van deze te laten vallen
}
}Модель иногда оборачивает ответ в markdown-блок, несмотря на инструкцию; строки с тройными обратными кавычками отбрасываются. Невалидные строки стоит логировать с указанием провайдера и модели — это лучший индикатор того, что модель плохо держит формат.
Structured Outputs и JSON mode
У OpenAI есть Structured Outputs: response_format: { type: "json_schema", json_schema: { name, schema, strict: true } } гарантирует соответствие ответа схеме. Это надёжнее инструкции в промпте, но результат — один JSON-документ, а не NDJSON, и проблема частичного разбора при стриминге возвращается. Вариант: схема с массивом, а для показа по мере генерации — парсер частичного JSON, понимая его ограничения.
У Together поддержка JSON mode и схем зависит от конкретной модели. Перед тем как полагаться на неё, проверьте в их документации список моделей с поддержкой и протестируйте на своих данных. Валидация Zod на вашей стороне нужна в любом случае: гарантия провайдера не отменяет проверку бизнес-ограничений вроде длины полей.
Измерение: TTFT и полное время
// scripts/bench.ts
importeer {streamCards} uit "../lib/stream-cards";
asynchrone functie maatregel(provider: "openai" | "samen", onderwerp: string) {
const t0 = prestatie.nu();
laat eerst = 0, tellen = 0;
voor wachten (const _ van streamCards(provider, onderwerp)) {
if (!eerste) eerst = performance.now() - t0;
tellen++;
}
return { provider, ttftCardMs: Math.round(first), totalMs: Math.round(performance.now() - t0), count };
}
const topics = ["CRM voor autoservice", "checklist voor het starten van een online winkel", "SQL-interviewvragen"];
voor (const p van ["openai", "samen"] als const) {
voor (const t van onderwerpen) console.log(wacht op maatregel(p, t));
}Здесь измеряется время до первой валидной карточки, а не до первого токена: для пользователя важно именно оно. Запускайте замер несколько раз в разное время суток из того же региона, где работает ваш сервер, и сравнивайте медианы, а не одиночные значения. Учитывайте и долю отброшенных строк: быстрый поток с невалидными объектами хуже медленного с валидными.
Отдача клиенту
Из Route Handler удобно отдавать тот же NDJSON:
exporteer asynchrone functie POST(req: Request) {
const { topic } = wacht op req.json();
const encoder = nieuwe TextEncoder();
const body = nieuwe ReadableStream({
async start(controller) {
probeer {
for await (const-kaart van streamCards("samen", onderwerp)) {
controller.enqueue(encoder.encode(JSON.stringify(kaart) + "\n"));
}
} eindelijk {
controller.close();
}
},
});
return new Response(body, { headers: { "Content-Type": "application/x-ndjson" } });
}Veelvoorkomende fouten
- De rest van de buffer na het einde van de stream wordt niet verwerkt en de laatste kaart gaat verloren.
- Door een verzoek te herhalen als er midden in de stream een storing optreedt, worden reeds getoonde kaarten gedupliceerd. Ontdubbel de koptekst, of begin opnieuw met genereren en wis de lijst.
- Overstappen naar een back-upprovider zonder te controleren of het model hetzelfde formaat ondersteunt.
Wanneer streaming niet nodig is
Als het antwoord kort is of het resultaat programmatisch wordt gebruikt (classificatie, veldextractie), maakt streaming de code alleen maar ingewikkelder. Een regelmatig verzoek met Structured Outputs of JSON-modus en één validatie aan het einde is eenvoudiger en betrouwbaarder.
Нужна реализация под ваш проект или аудит архитектуры?
Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.