Schémata Zod v TypeScriptu
Na této stránce
Aktualizováno 3. listopadu 2026 po kompilaci s SDK
@mistralai/mistralaiverze 3.5.0, Zod 4.6 a TypeScript 7.0.2. Původní příklad implicitně importovalMistral, ale SDK nabízí pouze pojmenovaný export. Také četl proměnnouresponseve funkcimain(), která existovala pouze uvnitřextractBook(). Přístup kparsedignoroval fakt, žechoicesamessagejsou v typech SDK volitelné, a zacházel sparsedjako sBook, přestože jeho typ je ve skutečnostiunknown. ImportZodErrorbyl zbytečný:chat.parse()validuje pomocísafeParsea nikdy nevyhazuje výjimku. Klíč API již není natvrdo zakódován. Zdroje: Mistral TypeScript SDK · oficiální příkladchat.parse.
Zod: Ekvivalent Pydantic pro TypeScript
Pokud pracuješ v TypeScriptu nebo JavaScriptu, je Zod knihovna pro validaci schémat, kterou SDK Mistral používá pro vlastní strukturované výstupy. Hraje přesně stejnou roli jako Pydantic v Pythonu: definuje přísné schéma, kterému se model musí podřídit. Všechno, co jsi se naučil o schématech, platí i zde, liší se pouze syntaxe.
Nainstaluj si SDK i Zod jedním příkazem:
npm install @mistralai/mistralai zod
Zod funguje nativně s TypeScriptem a poskytuje automatickou inferenci typů – to je jeho hlavní výhoda oproti ručnímu psaní rozhraní.
Definice jednoduchého schématu
Schéma Zod vytvoříš pomocí z.object(), kde každému poli přiřadíš validátor. Řádek s z.infer dělá rozdíl: odvozuje typ TypeScriptu přímo ze schématu, takže nemusíš udržovat dvě paralelní deklarace, které by se mohly rozcházet.
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, které budeš potřebovat
Zod pokrývá všechny potřeby pro strukturované výstupy. Následující schéma lístku (ticket) spojuje běžné případy: základní pole, nullable pole pro nepřidělený lístek, enum pro prioritu a typovaná pole.
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(),
// Volitelné (může být null)
assignee: z.string().nullable(),
// Enum (omezené hodnoty)
priority: z.enum(["low", "medium", "high", "critical"]),
// Seznamy
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Jeden detail si zaslouží pozornost: zatímco Python rozlišuje int a float, Zod zná pouze z.number(). Měj toto mapování na paměti, když přenášíš schéma z jednoho 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([...]) |
Vnořená schémata
Stejně jako u Pydantic může schéma obsahovat jiné schéma: stačí odkázat na konstantu. Kompozice pak probíhá od nejvnitřnějšího k nejvnějšímu: adresa uvnitř firmy, firma uvnitř osoby.
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í volání s Mistral SDK
Zde je stejná extrakce knihy z lekce o Pythonu, převedená do TypeScriptu. Tři body vyžadují pozornost. Parametr se jmenuje responseFormat (camelCase). Před použitím musíš otestovat parsed: SDK validuje odpověď proti schématu pomocí safeParse a pokud je JSON neúplný nebo neodpovídá schématu, nechá parsed jako undefined místo vyhození chyby. Nakonec, SDK nenesou typ tvého schématu: deklarují parsed jako unknown. Předáním objektu přes BookSchema.parse() získáš typ Book a zároveň proběhne opětovná validace.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definice schématu
const BookSchema = z.object({
title: z.string().describe("Book title"),
authors: z.array(z.string()).describe("List of authors"),
year: z.number().nullable().describe("Publication year"),
genre: z.string().describe("Main literary genre"),
summary: z.string().describe("Summary in 2-3 sentences"),
});
type Book = z.infer<typeof BookSchema>;
// 2. Vytvoření klienta
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Volání chat.parse()
async function extractBook(text: string): Promise<Book> {
const response = await client.chat.parse({
model: "mistral-large-latest",
messages: [
{
role: "system",
content: "You are an expert librarian. Extract book information.",
},
{ role: "user", content: text },
],
responseFormat: BookSchema,
temperature: 0,
});
// 4. Přístup k parsovanému objektu
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Surové JSON zůstává dostupné v message.content
console.log(`Raw JSON: ${message.content}`);
// parsed je typován jako unknown: BookSchema.parse() vrací typovaný Book
return BookSchema.parse(message.parsed);
}
// 5. Použití
async function main() {
const book = await extractBook(
"I loved '1984' by George Orwell, published in 1949. A dystopian classic."
);
console.log(`Title: ${book.title}`);
console.log(`Authors: ${book.authors.join(", ")}`);
console.log(`Year: ${book.year}`);
console.log(`Genre: ${book.genre}`);
}
main();
Popis polí pomocí .describe()
V Zod plní .describe() stejnou roli jako Field(description=...) v Pydantic: říká modelu, co by pole mělo obsahovat, zejména když samotný název není dostatečně jednoznačný. score bez popisu může skončit na stupnici 0–100; s explicitním uvedením rozsahu se bude řídit tvou konvencí.
const SentimentSchema = z.object({
sentiment: z.enum(["positive", "negative", "neutral"]).describe(
"Overall sentiment of the text"
),
score: z.number().describe(
"Confidence score between 0.0 and 1.0"
),
keywords: z.array(z.string()).describe(
"The 3–5 main keywords"
),
summary: z.string().describe(
"Summary in one sentence maximum"
),
});
Zpracování chyb
Vzor pro opakování (retry) sleduje stejnou logiku jako v Pythonu, s obecnou signaturou, která jej činí znovu použitelným pro jakékoli schéma. Není třeba zachytávat ZodError: chat.parse() jej nevyhazuje; místo toho nechá parsed prázdné. Tento případ, spolu se síťovými nebo HTTP chybami, spustí opakování. Omezení z.ZodType<T> propojuje schéma předané jako argument s návratovým typem: schema.parse() vrací T, takže volající získá správně typovaný objekt bez dalších anotací.
// Pokračování stejného souboru: client, z a BookSchema jsou již definovány
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: "Extract the requested information." },
{ role: "user", content: text },
],
responseFormat: schema,
temperature: 0,
});
const parsed = response.choices?.[0]?.message?.parsed;
if (!parsed) {
throw new Error("Response missing or non-compliant with schema");
}
return schema.parse(parsed); // obnoví typ T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Použití
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Klíčové poznatky
- Zod je ekvivalent Pydantic pro vlastní strukturované výstupy v TypeScriptu
z.infer<typeof Schema>automaticky generuje typ TypeScriptu.describe()přidává instrukce pro jednotlivá pole, stejně jakoField(description=...)v Pythonu- Mistral TypeScript SDK používá
responseFormat(camelCase) místoresponse_format - Nevyhovující odpověď nechá
parsedjakoundefined(žádná výjimka): otestuj to a v případě potřeby opakuj