Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Schémy Zod v TypeScripte

Lekcia 9 z 12 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Zod: Ekvivalent Pydantic pre TypeScript
  2. Definovanie jednoduchej schémy
  3. Typy, ktoré budeš potrebovať
  4. Vnorené schémy
  5. Kompletné volanie s Mistral SDK
  6. Popis polí pomocou .describe()
  7. Ošetrenie chýb
  8. Kľúčové poznatky

Aktualizované 3. novembra 2026 po kompilácii so SDK @mistralai/mistralai verzie 3.5.0, Zod 4.6 a TypeScript 7.0.2. Pôvodný príklad importoval Mistral ako predvolený export, no SDK ponúka iba pomenovaný export. Tiež čítal premennú response vo funkcii main(), ktorá existovala len vnútri extractBook(). Prístup k parsed ignoroval fakt, že choices a message sú v typoch SDK voliteľné, a zaobchádzal s parsed ako s Book, hoci jeho typ je v skutočnosti unknown. Import ZodError bol zbytočný: chat.parse() validuje pomocou safeParse a nikdy nevyhadzuje výnimku. API kľúč už nie je natvrdo zakódovaný. Zdroje: Mistral TypeScript SDK · oficiálny príklad chat.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)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.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 ako Field(description=...) v Pythone
  • Mistral TypeScript SDK používa responseFormat (camelCase) namiesto response_format
  • Nevyhovujúca odpoveď nechá parsed ako undefined (žiadna výnimka): otestuj to a v prípade potreby opakuj