Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Zod sémák TypeScriptben

9. lecke 12 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Zod: A Pydantic TypeScript megfelelője
  2. Egyszerű séma definiálása
  3. Szükséges típusok
  4. Beágyazott sémák
  5. Teljes hívás a Mistral SDK-val
  6. Mezők leírása a .describe() segítségével
  7. Hibakezelés
  8. Főbb megállapítások

Frissítve: 2026. november 3. A @mistralai/mistralai SDK 3.5.0, a Zod 4.6 és a TypeScript 7.0.2 verzióval történő fordítás után. Az eredeti példa alapértelmezetten importálta a Mistral-t, de az SDK csak név szerinti exportot kínál. Emellett a main() függvény egy olyan response változót olvasott be, amely csak az extractBook() függvényen belül létezett. A parsed elérése figyelmen kívül hagyta, hogy a choices és a message opcionális az SDK típusaiban, valamint úgy kezelte a parsed-et, mint egy Book típust, holott a típusa valójában unknown. A ZodError importálása felesleges volt: a chat.parse() a safeParse segítségével validál, és soha nem dob kivételt. Az API-kulcs már nincs hardkódolva. Források: Mistral TypeScript SDK · hivatalos chat.parse példa.

Zod: A Pydantic TypeScript megfelelője

Ha TypeScriptben vagy JavaScriptben dolgozol, a Zod az a sémavalidáló könyvtár, amelyet a Mistral SDK az egyéni strukturált kimenetekhez használ. Ugyanazt a szerepet tölti be, mint a Pydantic Pythonban: egy szigorú séma definiálását, amelyet a modellnek követnie kell. Minden, amit a sémákról tanultál, itt is érvényes, csupán a szintaxis különbözik.

Telepítsd az SDK-t és a Zodot egyetlen paranccsal:

npm install @mistralai/mistralai zod

A Zod natívan működik TypeScriptkel, és automatikus típuskövetkeztetést biztosít – ez a fő előnye a kézzel írt interfészekkel szemben.

Egyszerű séma definiálása

Hozz létre egy Zod sémát a z.object() segítségével, és rendelj validátort minden mezőhöz. A z.infer sor teszi a különbséget: ez a sémából következteti ki a TypeScript típust, így nem kell két párhuzamos deklarációt karbantartanod, amelyek eltérhetnek egymástól.

import { z } from "zod";

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

// A TypeScript automatikusan kikövetkezteti a típust
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Szükséges típusok

A Zod minden igényt kielégít a strukturált kimenetek terén. Az alábbi jegyséma összegyűjti a gyakori eseteket: alapvető mezők, egy nullázható mező a hozzá nem rendelt jegyekhez, egy enumeráció a prioritáshoz és típusozott tömbök.

import { z } from "zod";

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

  // Opcionális (lehet null)
  assignee: z.string().nullable(),

  // Enum (korlátozott értékek)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Listák
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Egy apróságra érdemes figyelni: míg a Python különbséget tesz az int és a float között, a Zod csak a z.number()-t ismeri. Tartsd észben ezt a leképezést, amikor sémát portsz egyik nyelvről a másikra.

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

Beágyazott sémák

Akárcsak a Pydantic esetében, egy séma tartalmazhat egy másikat is: egyszerűen hivatkozz a konstansra. A kompozíció ezután belülről kifelé olvasható: a cím a vállalaton belül, a vállalat a személyen belül.

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>;

Teljes hívás a Mistral SDK-val

Íme ugyanaz a könyv-kinyerés, mint a Python leckében, most TypeScriptre portolva. Három pontra kell figyelned. A paraméter neve responseFormat (camelCase-ben). Használat előtt tesztelned kell a parsed változót: az SDK a safeParse segítségével validálja a választ a sémához képest, és ha a JSON csonka vagy nem felel meg a sémának, a parsed értéke undefined lesz kivétel dobása helyett. Végül az SDK nem őrzi meg a sémád típusát: a parsed-et unknown-ként deklarálja. Ha az objektumot átvezeted a BookSchema.parse() függvényen, az Book típussá válik, és közben újra is validálódik.

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

// 1. A séma definiálása
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. A kliens létrehozása
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. A chat.parse() hívása
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. A parsolt objektum elérése
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // A nyers JSON továbbra is elérhető a message.content-ben
  console.log(`Raw JSON: ${message.content}`);
  // A parsed típusa unknown: a BookSchema.parse() egy típusozott Book-ot ad vissza
  return BookSchema.parse(message.parsed);
}

// 5. Használat
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();

Mezők leírása a .describe() segítségével

A Zodban a .describe() ugyanazt a szerepet tölti be, mint a Field(description=...) a Pydanticban: megmondja a modellnek, mit kell tartalmaznia a mezőnek, különösen akkor, ha a név önmagában nem egyértelmű. Egy score leírás nélkül lehet 0–100 skálán; egy explicit tartomány említésével azonban követi a te konvenciódat.

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

Hibakezelés

Az újrapróbálkozási minta ugyanazt a logikát követi, mint Pythonban, egy általános szignatúrával, amely bármely sémához újrahasználhatóvá teszi. Nincs szükség ZodError elkapására: a chat.parse() nem dob ilyet; ehelyett üresen hagyja a parsed mezőt. Ez az eset, valamint a hálózati vagy HTTP hibák váltanak ki újrapróbálkozást. A z.ZodType<T> kényszer összeköti az argumentumként átadott sémát a visszatérési típussal: a schema.parse() egy T típust ad vissza, így a hívó fél megfelelően típusozott objektumot kap extra annotációk nélkül.

// Ugyanannak a fájlnak a folytatása: a client, z és BookSchema már definiálva van

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); // visszaállítja a T típust
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error);
      if (attempt === maxRetries) throw error;
    }
  }
  throw new Error("Unexpected failure");
}

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

Főbb megállapítások

  • A Zod a Pydantic TypeScript megfelelője az egyéni strukturált kimenetekhez
  • A z.infer<typeof Schema> automatikusan generálja a TypeScript típust
  • A .describe() mezőszintű utasításokat ad hozzá, hasonlóan a Python Field(description=...) függvényéhez
  • A Mistral TypeScript SDK a responseFormat (camelCase) paramétert használja a response_format helyett
  • A nem compliant válasz esetén a parsed értéke undefined lesz (kivétel nélkül): teszteld ezt, majd szükség esetén próbáld újra