Zod sheme u TypeScriptu
Na ovoj stranici
Ažurirano 3. studenoga 2026. nakon kompajliranja sa SDK-om
@mistralai/mistralaiverzije 3.5.0, Zodom 4.6 i TypeScriptom 7.0.2. Izvorni je primjer prema zadanim postavkama uvozioMistral, no SDK nudi samo imenovani izvoz. Također je čitao varijabluresponseunutarmain()koja je postojala samo unutarextractBook(). Pristupanjemparsedignoriralo se da suchoicesimessageopcionalni u tipovima SDK-a, aparsedse tretirao kaoBookiako je njegov tip zapravounknown. UvozZodErrorbio je nepotreban:chat.parse()validira putemsafeParsei nikada ne baca iznimku. API ključ više nije hardkodiran. Izvori: Mistral TypeScript SDK · službeni primjerchat.parse.
Zod: TypeScript ekvivalent Pydantica
Ako radiš u TypeScriptu ili JavaScriptu, Zod je biblioteka za validaciju shema koju Mistral SDK koristi za prilagođene strukturirane izlaze. Igra točno istu ulogu kao Pydantic u Pythonu: definira strogu shemu koje se model mora pridržavati. Sve što si naučio o shemama vrijedi i ovdje, uz razlike samo u sintaksi.
Instaliraj i SDK i Zod jednom naredbom:
npm install @mistralai/mistralai zod
Zod radi izvorno s TypeScriptom i pruža automatsko zaključivanje tipova – to je njegova glavna prednost nad ručnim pisanjem sučelja.
Definiranje jednostavne sheme
Izgradi Zod shemu pomoću z.object(), dodjeljujući validator svakom polju. Redak z.infer čini razliku: on izvodi TypeScript tip iz sheme, tako da ne moraš održavati dvije paralelne deklaracije koje bi se mogle razilaziti.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript automatski zaključuje tip
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Tipovi koji će ti trebati
Zod pokriva sve potrebe za strukturiranim izlazima. Shema tiketa u nastavku objedinjuje uobičajene slučajeve: osnovna polja, polje koje može biti null za nedodijeljeni tiket, enumeraciju za prioritet i tipizirane nizove.
import { z } from "zod";
const TicketSchema = z.object({
// Osnovni tipovi
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Opcionalno (može biti null)
assignee: z.string().nullable(),
// Enum (ograničene vrijednosti)
priority: z.enum(["low", "medium", "high", "critical"]),
// Liste
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Jedna nijansa zaslužuje pažnju: dok Python razlikuje int i float, Zod poznaje samo z.number(). Imaj ovo mapiranje na umu kada prenosiš shemu iz jednog jezika u drugi.
| 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([...]) |
Ugniježđene sheme
Kao i kod Pydantica, shema može sadržavati drugu: samo referenciraj konstantu. Kompozicija se tada čita od najunutarnjeg prema najvanjskijem: adresa unutar tvrtke, tvrtka unutar 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>;
Potpuni poziv s Mistral SDK-om
Evo istog izvlačenja podataka o knjizi iz lekcije za Python, prenesenog u TypeScript. Tri točke zahtijevaju pažnju. Parametar je responseFormat u camelCaseu. Moraš testirati parsed prije korištenja: SDK validira odgovor prema shemi pomoću safeParse i, ako je JSON odsječen ili se ne podudara sa shemom, ostavlja parsed kao undefined umjesto da baci iznimku. Konačno, SDK ne prenosi tip tvoje sheme: deklarira parsed kao unknown. Prosljeđivanjem objekta kroz BookSchema.parse() on postaje tipiziran kao Book i pritom se ponovno validira.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definiraj shemu
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. Kreiraj klijenta
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Pozovi 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. Pristupi parsiranom objektu
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Sirovi JSON ostaje dostupan u message.content
console.log(`Raw JSON: ${message.content}`);
// parsed je tipiziran kao unknown: BookSchema.parse() vraća tipizirani Book
return BookSchema.parse(message.parsed);
}
// 5. Upotreba
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();
Opisivanje polja s .describe()
U Zodu, .describe() ima istu ulogu kao Field(description=...) u Pydanticu: govori modelu što polje treba sadržavati, posebno kada je samo ime dvosmisleno. score bez opisa mogao bi završiti na ljestvici 0–100; uz eksplicitno spomenuti raspon, slijedi tvoju konvenciju.
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"
),
});
Rukovanje greškama
Obrazac ponovnog pokušaja slijedi istu logiku kao u Pythonu, s generičkim potpisom koji ga čini ponovno upotrebljivim za bilo koju shemu. Nema potrebe za hvatanjem ZodError: chat.parse() ga ne baca; ostavlja parsed praznim. Taj slučaj, zajedno s mrežnim ili HTTP greškama, pokreće ponovni pokušaj. Ograničenje z.ZodType<T> povezuje shemu proslijeđenu kao argument s povratnim tipom: schema.parse() vraća T, tako da pozivatelj dobiva ispravno tipizirani objekt bez dodatnih anotacija.
// Nastavak iste datoteke: client, z i BookSchema su već definirani
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); // vraća tip T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Upotreba
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Ključne točke
- Zod je TypeScript ekvivalent Pydantica za prilagođene strukturirane izlaze
z.infer<typeof Schema>automatski generira TypeScript tip.describe()dodaje upute po poljima, poputField(description=...)u Pythonu- Mistral TypeScript SDK koristi
responseFormat(camelCase) umjestoresponse_format - Neusklađen odgovor ostavlja
parsedkaoundefined(bez iznimke): testiraj ga, a zatim ponovi pokušaj ako je potrebno