Zod sémák TypeScriptben
Ezen az oldalon
Frissítve: 2026. november 3. A
@mistralai/mistralaiSDK 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 aMistral-t, de az SDK csak név szerinti exportot kínál. Emellett amain()függvény egy olyanresponseváltozót olvasott be, amely csak azextractBook()függvényen belül létezett. Aparsedelérése figyelmen kívül hagyta, hogy achoicesés amessageopcionális az SDK típusaiban, valamint úgy kezelte aparsed-et, mint egyBooktípust, holott a típusa valójábanunknown. AZodErrorimportálása felesleges volt: achat.parse()asafeParsesegítségével validál, és soha nem dob kivételt. Az API-kulcs már nincs hardkódolva. Források: Mistral TypeScript SDK · hivataloschat.parsepé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) |
|---|---|
str | z.string() |
int, float | z.number() |
bool | z.boolean() |
list[str] | z.array(z.string()) |
Optional[str] | z.string().nullable() |
Enum | z.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 PythonField(description=...)függvényéhez - A Mistral TypeScript SDK a
responseFormat(camelCase) paramétert használja aresponse_formathelyett - A nem compliant válasz esetén a
parsedértékeundefinedlesz (kivétel nélkül): teszteld ezt, majd szükség esetén próbáld újra