Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Schémata Zod v TypeScriptu

Lekce 9 z 12 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Zod: Ekvivalent Pydantic pro TypeScript
  2. Definice jednoduchého schématu
  3. Typy, které budeš potřebovat
  4. Vnořená schémata
  5. Kompletní volání s Mistral SDK
  6. Popis polí pomocí .describe()
  7. Zpracování chyb
  8. Klíčové poznatky

Aktualizováno 3. listopadu 2026 po kompilaci s SDK @mistralai/mistralai verze 3.5.0, Zod 4.6 a TypeScript 7.0.2. Původní příklad implicitně importoval Mistral, ale SDK nabízí pouze pojmenovaný export. Také četl proměnnou response ve funkci main(), která existovala pouze uvnitř extractBook(). Přístup k parsed ignoroval fakt, že choices a message jsou v typech SDK volitelné, a zacházel s parsed jako s Book, přestože jeho typ je ve skutečnosti unknown. Import ZodError byl zbytečný: chat.parse() validuje pomocí safeParse a nikdy nevyhazuje výjimku. Klíč API již není natvrdo zakódován. Zdroje: Mistral TypeScript SDK · oficiální příklad chat.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)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.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ě jako Field(description=...) v Pythonu
  • Mistral TypeScript SDK používá responseFormat (camelCase) místo response_format
  • Nevyhovující odpověď nechá parsed jako undefined (žádná výjimka): otestuj to a v případě potřeby opakuj