Schémy Zod v TypeScripte
Na tejto strane
Aktualizované 3. novembra 2026 po kompilácii so SDK
@mistralai/mistralaiverzie 3.5.0, Zod 4.6 a TypeScript 7.0.2. Pôvodný príklad importovalMistralako predvolený export, no SDK ponúka iba pomenovaný export. Tiež čítal premennúresponsevo funkciimain(), ktorá existovala len vnútriextractBook(). Prístup kparsedignoroval fakt, žechoicesamessagesú v typoch SDK voliteľné, a zaobchádzal sparsedako sBook, hoci jeho typ je v skutočnostiunknown. ImportZodErrorbol zbytočný:chat.parse()validuje pomocousafeParsea nikdy nevyhadzuje výnimku. API kľúč už nie je natvrdo zakódovaný. Zdroje: Mistral TypeScript SDK · oficiálny príkladchat.parse.
Zod: Ekvivalent Pydantic pre TypeScript
Ak pracuješ v TypeScripte alebo JavaScripte, Zod je knižnica na validáciu schém, ktorú SDK Mistral využíva pre vlastné štruktúrované výstupy. Hrá presne tú istú úlohu ako Pydantic v Pythone: definuje prísnu schému, ktorú musí model dodržať. Všetko, čo si sa naučil o schémach, platí aj tu, líši sa len syntax.
Nainštaluj si obe knižnice – SDK aj Zod – jedným príkazom:
npm install @mistralai/mistralai zod
Zod funguje natívne s TypeScriptom a poskytuje automatickú inferenciu typov – to je jeho hlavná výhoda oproti ručnému písaniu rozhraní.
Definovanie jednoduchej schémy
Schému Zod zostavíš pomocou z.object(), kde každému poľu priradíš validátor. Riadok so z.infer robí rozdiel: odvodí typ TypeScriptu priamo zo schémy, takže nemusíš udržiavať dve paralelné deklarácie, ktoré by sa mohli rozísť.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript automaticky odvodí typ
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Typy, ktoré budeš potrebovať
Zod pokrýva všetky potreby pre štruktúrované výstupy. Nižšie uvedená schéma lístka spája bežné prípady: základné polia, nullable pole pre nepriradený lístok, enum pre prioritu a typované polia.
import { z } from "zod";
const TicketSchema = z.object({
// Základné typy
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Voliteľné (môže byť null)
assignee: z.string().nullable(),
// Enum (obmedzené hodnoty)
priority: z.enum(["low", "medium", "high", "critical"]),
// Zoznamy
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Jeden detail si zaslúži pozornosť: zatiaľ čo Python rozlišuje int a float, Zod pozná len z.number(). Maj toto mapovanie na pamäti, keď prenášaš schému z jedného jazyka do druhého.
| Pydantic (Python) | Zod (TypeScript) |
|---|---|
str | z.string() |
int, float | z.number() |
bool | z.boolean() |
list[str] | z.array(z.string()) |
Optional[str] | z.string().nullable() |
Enum | z.enum([...]) |
Vnorené schémy
Rovnako ako pri Pydantic môže schéma obsahovať inú schému: stačí odkázať na konštantu. Kompozícia potom číta od vnútra von: adresa vo firme, firma v osobe.
import { z } from "zod";
const AddressSchema = z.object({
street: z.string(),
city: z.string(),
postalCode: z.string(),
country: z.string(),
});
const CompanySchema = z.object({
name: z.string(),
industry: z.string(),
address: AddressSchema,
});
const PersonSchema = z.object({
firstName: z.string(),
lastName: z.string(),
email: z.string(),
role: z.string(),
company: CompanySchema,
});
type Person = z.infer<typeof PersonSchema>;
Kompletné volanie s Mistral SDK
Tu je rovnaká extrakcia knihy z lekcie o Pythone, prenesená do TypeScriptu. Tri body si vyžadujú pozornosť. Parameter sa volá responseFormat (camelCase). Pred použitím musíš otestovať parsed: SDK validuje odpoveď proti schéme pomocou safeParse a ak je JSON orezaný alebo nezodpovedá schéme, nechá parsed ako undefined namiesto vyhodenia chyby. Nakoniec, SDK nenesie typ tvojej schémy: deklaruje parsed ako unknown. Prechod objektu cez BookSchema.parse() ho typuje ako Book a zároveň ho opätovne validuje.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definuj schému
const BookSchema = z.object({
title: z.string().describe("Názov knihy"),
authors: z.array(z.string()).describe("Zoznam autorov"),
year: z.number().nullable().describe("Rok vydania"),
genre: z.string().describe("Hlavný literárny žáner"),
summary: z.string().describe("Zhrnutie v 2–3 vetách"),
});
type Book = z.infer<typeof BookSchema>;
// 2. Vytvor klienta
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Zavolaj chat.parse()
async function extractBook(text: string): Promise<Book> {
const response = await client.chat.parse({
model: "mistral-large-latest",
messages: [
{
role: "system",
content: "Si expertný knihovník. Extrahuj informácie o knihe.",
},
{ role: "user", content: text },
],
responseFormat: BookSchema,
temperature: 0,
});
// 4. Prístup k analyzovanému objektu
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Chýbajúca, orezaná alebo nevyhovujúca odpoveď");
}
// Surový JSON zostáva dostupný v message.content
console.log(`Surový JSON: ${message.content}`);
// parsed má typ unknown: BookSchema.parse() vráti typovaný Book
return BookSchema.parse(message.parsed);
}
// 5. Použitie
async function main() {
const book = await extractBook(
"Miloval som '1984' od Georgea Orwella, vydané v roku 1949. Dystopická klasika."
);
console.log(`Názov: ${book.title}`);
console.log(`Autori: ${book.authors.join(", ")}`);
console.log(`Rok: ${book.year}`);
console.log(`Žáner: ${book.genre}`);
}
main();
Popis polí pomocou .describe()
V Zode plní .describe() rovnakú úlohu ako Field(description=...) v Pydantic: hovorí modelu, čo má pole obsahovať, najmä keď názov sám o sebe nie je jednoznačný. score bez popisu môže skončiť na stupnici 0–100; s explicitným uvedením rozsahu sa bude držať tvojej konvencie.
const SentimentSchema = z.object({
sentiment: z.enum(["positive", "negative", "neutral"]).describe(
"Celkový sentiment textu"
),
score: z.number().describe(
"Skóre istoty medzi 0,0 a 1,0"
),
keywords: z.array(z.string()).describe(
"3–5 hlavných kľúčových slov"
),
summary: z.string().describe(
"Zhrnutie maximálne v jednej vete"
),
});
Ošetrenie chýb
Vzor opakovania (retry) nasleduje rovnakú logiku ako v Pythone, s generickým podpisom, ktorý ho robí opakovane použiteľným pre ľubovoľnú schému. Nie je potrebné zachytávať ZodError: chat.parse() ho nevyhadzuje, necháva parsed prázdne. Tento prípad, spolu so sieťovými alebo HTTP chybami, spustí opakovanie. Obmedzenie z.ZodType<T> prepojuje schému odovzdanú ako argument s návratovým typom: schema.parse() vráti T, takže volajúci dostane správne typovaný objekt bez ďalších anotácií.
// Pokračovanie toho istého súboru: client, z a BookSchema sú už definované
async function safeExtract<T>(
text: string,
schema: z.ZodType<T>,
maxRetries = 2
): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
const response = await client.chat.parse({
model: "mistral-large-latest",
messages: [
{ role: "system", content: "Extrahuj požadované informácie." },
{ role: "user", content: text },
],
responseFormat: schema,
temperature: 0,
});
const parsed = response.choices?.[0]?.message?.parsed;
if (!parsed) {
throw new Error("Chýbajúca alebo nevyhovujúca odpoveď");
}
return schema.parse(parsed); // obnoví typ T
} catch (error) {
console.error(`Pokús ${attempt + 1} zlyhal:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Neočakávané zlyhanie");
}
// Použitie
try {
const book = await safeExtract("Môj text tu", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extrakcia zlyhala:", error);
}
Kľúčové poznatky
- Zod je ekvivalent Pydantic pre vlastné štruktúrované výstupy v TypeScripte
z.infer<typeof Schema>automaticky generuje typ TypeScriptu.describe()pridáva inštrukcie pre jednotlivé polia, podobne akoField(description=...)v Pythone- Mistral TypeScript SDK používa
responseFormat(camelCase) namiestoresponse_format - Nevyhovujúca odpoveď nechá
parsedakoundefined(žiadna výnimka): otestuj to a v prípade potreby opakuj