Przejdź do głównej treści
Polski— Wybierz język
Menu

Schematy Zod w TypeScript

Lekcja 9 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zod: TypeScriptowy odpowiednik Pydantic
  2. Definiowanie prostego schematu
  3. Typy, których będziesz potrzebować
  4. Schematy zagnieżdżone
  5. Pełne wywołanie z SDK Mistral
  6. Opisywanie pól za pomocą .describe()
  7. Obsługa błędów
  8. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 po kompilacji z SDK @mistralai/mistralai w wersji 3.5.0, Zod 4.6 oraz TypeScript 7.0.2. Oryginalny przykład domyślnie importował Mistral, ale SDK udostępnia jedynie eksport nazwany. Odwoływał się też do zmiennej response w funkcji main(), która istniała tylko wewnątrz extractBook(). Dostęp do parsed ignorował fakt, że choices i message są opcjonalne w typach SDK, i traktował parsed jako Book, podczas gdy jego typ to w rzeczywistości unknown. Import ZodError był zbędny: chat.parse() waliduje dane za pomocą safeParse i nigdy nie rzuca wyjątkiem. Klucz API nie jest już zakodowany na sztywno. Źródła: Mistral TypeScript SDK · oficjalny przykład chat.parse.

Zod: TypeScriptowy odpowiednik Pydantic

Jeśli pracujesz w TypeScript lub JavaScript, Zod jest biblioteką do walidacji schematów używaną przez SDK Mistral do niestandardowych wyjść strukturalnych. Pełni dokładnie taką samą rolę jak Pydantic w Pythonie: definiuje ścisły schemat, którego model musi przestrzegać. Wszystko, czego nauczyłeś się o schematach, ma tu zastosowanie – różnią się jedynie składnią.

Zainstaluj zarówno SDK, jak i Zod jedną komendą:

npm install @mistralai/mistralai zod

Zod działa natywnie z TypeScript i zapewnia automatyczne wnioskowanie typów – to jego główna przewaga nad ręcznym pisaniem interfejsów.

Definiowanie prostego schematu

Budujesz schemat Zod za pomocą z.object(), przypisując walidator do każdego pola. Linia z z.infer robi różnicę: wyprowadza typ TypeScript ze schematu, więc nie musisz utrzymywać dwóch równoległych deklaracji, które mogłyby się ze sobą rozmijać.

import { z } from "zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  phone: z.string(),
  company: z.string(),
});

// TypeScript automatycznie wnioskuję typ
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Typy, których będziesz potrzebować

Zod pokrywa każde zapotrzebowanie na wyjścia strukturalne. Poniższy schemat zgłoszenia łączy typowe przypadki: pola podstawowe, pole nullable dla nieprzypisanego zgłoszenia, enum dla priorytetu oraz typowane tablice.

import { z } from "zod";

const TicketSchema = z.object({
  // Typy podstawowe
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Opcjonalne (może być null)
  assignee: z.string().nullable(),

  // Enum (ograniczone wartości)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Listy
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Jeden niuans zasługuje na uwagę: tam gdzie Python rozróżnia int i float, Zod zna tylko z.number(). Miej to odwzorowanie na uwadze, przenosząc schemat z jednego języka na drugi.

Pydantic (Python)Zod (TypeScript)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.enum([...])

Schematy zagnieżdżone

Tak jak w Pydantic, schemat może zawierać inny: wystarczy odwołać się do stałej. Kompozycja czyta się wtedy od wnętrza na zewnątrz: adres wewnątrz firmy, firma wewnątrz 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>;

Pełne wywołanie z SDK Mistral

Oto to samo wydobycie informacji o książce z lekcji Pythonowej, przeniesione do TypeScript. Trzy punkty wymagają uwagi. Parametr to responseFormat w camelCase. Musisz przetestować parsed przed użyciem: SDK waliduje odpowiedź względem schematu za pomocą safeParse i, jeśli JSON jest ucięty lub nie zgadza się ze schematem, pozostawia parsed jako undefined, zamiast rzucać wyjątkiem. Na koniec SDK nie przenosi typu twojego schematu: deklaruje parsed jako unknown. Przepuszczenie obiektu przez BookSchema.parse() typuje go jako Book i przy okazji ponownie go waliduje.

import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

// 1. Zdefiniuj schemat
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. Utwórz klienta
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Wywołaj 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. Uzyskaj dostęp do sparsowanego obiektu
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Surowy JSON pozostaje dostępny w message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed ma typ unknown: BookSchema.parse() zwraca typowane Book
  return BookSchema.parse(message.parsed);
}

// 5. Użycie
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();

Opisywanie pól za pomocą .describe()

W Zod .describe() pełni tę samą rolę co Field(description=...) w Pydantic: mówi modelowi, co powinno zawierać pole, zwłaszcza gdy sama nazwa jest niejednoznaczna. score bez opisu może trafić na skalę 0–100; z jawnie wspomnianym zakresem, podąża za twoją konwencją.

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"
  ),
});

Obsługa błędów

Wzorzec ponawiania prób podąża za tą samą logiką co w Pythonie, z generyczną sygnaturą, która czyni go wielokrotnego użytku dla dowolnego schematu. Nie ma potrzeby łapania ZodError: chat.parse() go nie rzuca; pozostawia parsed puste. Ten przypadek, wraz z błędami sieciowymi lub HTTP, uruchamia ponowną próbę. Ograniczenie z.ZodType<T> łączy schemat przekazany jako argument z typem zwracanym: schema.parse() zwraca T, więc wywołujący otrzymuje poprawnie typowany obiekt bez dodatkowych adnotacji.

// Kontynuacja tego samego pliku: client, z i BookSchema są już zdefiniowane

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); // przywraca typ T
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error);
      if (attempt === maxRetries) throw error;
    }
  }
  throw new Error("Unexpected failure");
}

// Użycie
try {
  const book = await safeExtract("My text here", BookSchema);
  console.log(book.title);
} catch (error) {
  console.error("Extraction failed:", error);
}

Kluczowe wnioski

  • Zod to TypeScriptowy odpowiednik Pydantic dla niestandardowych wyjść strukturalnych
  • z.infer<typeof Schema> automatycznie generuje typ TypeScript
  • .describe() dodaje instrukcje dla każdego pola, jak Field(description=...) w Pythonie
  • TypeScriptowe SDK Mistral używa responseFormat (camelCase) zamiast response_format
  • Odpowiedź niezgodna ze schematem pozostawia parsed jako undefined (brak wyjątku): sprawdź to, a następnie w razie potrzeby ponów próbę