Schemele Zod în TypeScript
Pe această pagină
Actualizat la 3 noiembrie 2026 după compilare cu SDK-ul
@mistralai/mistralai3.5.0, Zod 4.6 și TypeScript 7.0.2. Exemplul original importaMistralimplicit, dar SDK-ul oferă doar un export numit. De asemenea, citea o variabilăresponseînmain()care exista doar în interiorul funcțieiextractBook(). Accesarea luiparsedignora faptul căchoicesșimessagesunt opționale în tipurile SDK și îl trata peparsedca fiind unBook, când tipul său real esteunknown. ImportulZodErrorera inutil:chat.parse()validează cusafeParseși nu aruncă niciodată erori. Cheia API nu mai este codificată direct. Surse: Mistral TypeScript SDK · exemplul oficialchat.parse.
Zod: Echivalentul TypeScript al lui Pydantic
Dacă lucrați în TypeScript sau JavaScript, Zod este biblioteca de validare a schemelor utilizată de SDK-ul Mistral pentru ieșiri structurate personalizate. Acesta joacă exact același rol ca Pydantic în Python: definirea unei scheme stricte pe care modelul trebuie să o respecte. Tot ce ați învățat despre scheme se aplică și aici, cu diferențe doar de sintaxă.
Instalați atât SDK-ul, cât și Zod într-o singură comandă:
npm install @mistralai/mistralai zod
Zod funcționează nativ cu TypeScript și oferă inferență automată a tipurilor – acesta fiind principalul său avantaj față de scrierea manuală a interfețelor.
Definirea unei scheme simple
Construiți o schemă Zod cu z.object(), asignând un validator fiecărui câmp. Linia z.infer face diferența: aceasta deduce tipul TypeScript din schemă, astfel încât nu trebuie să mențineți două declarații paralele care ar putea diverge.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript inferă automat tipul
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Tipuri de care veți avea nevoie
Zod acoperă toate nevoile pentru ieșiri structurate. Schema de tichet de mai jos reunește cazuri comune: câmpuri de bază, un câmp nulabil pentru un tichet nealocat, o enumerare pentru prioritate și tablouri tipate.
import { z } from "zod";
const TicketSchema = z.object({
// Tipuri de bază
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Opțional (poate fi null)
assignee: z.string().nullable(),
// Enum (valori constrânse)
priority: z.enum(["low", "medium", "high", "critical"]),
// Liste
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
O nuanță merită atenție: acolo unde Python distinge între int și float, Zod cunoaște doar z.number(). Aveți în vedere această corespondență atunci când portati o schemă dintr-un limbaj în altul.
| 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([...]) |
Scheme imbricate
Ca și în cazul Pydantic, o schemă poate conține o altă schemă: este suficient să faceți referire la constantă. Compoziția se citește apoi de la interior spre exterior: adresa în cadrul companiei, compania în cadrul persoanei.
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>;
Un apel complet cu SDK-ul Mistral
Iată aceeași extragere de carte din lecția Python, portată în TypeScript. Trei puncte necesită atenție. Parametrul este responseFormat în camelCase. Trebuie să testați parsed înainte de a-l utiliza: SDK-ul validează răspunsul față de schemă cu safeParse și, dacă JSON-ul este trunchiat sau nu corespunde schemei, lasă parsed ca undefined în loc să arunce o eroare. În final, SDK-ul nu păstrează tipul schemei dumneavoastră: declară parsed ca fiind unknown. Trecerea obiectului prin BookSchema.parse() îl tipizează ca Book și îl revalidează în proces.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definirea schemei
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. Crearea clientului
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Apelarea 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. Accesarea obiectului parsat
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// JSON-ul brut rămâne disponibil în message.content
console.log(`Raw JSON: ${message.content}`);
// parsed este tipat ca unknown: BookSchema.parse() returnează un Book tipat
return BookSchema.parse(message.parsed);
}
// 5. Utilizare
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();
Descrierea câmpurilor cu .describe()
În Zod, .describe() îndeplinește același rol ca Field(description=...) în Pydantic: indică modelului ce ar trebui să conțină câmpul, mai ales când numele singur este ambiguu. Un score fără descriere ar putea ajunge pe o scală de la 0 la 100; cu un interval explicit menționat, acesta va urma convenția dumneavoastră.
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"
),
});
Gestionarea erorilor
Modelul de reîncercare urmează aceeași logică ca în Python, cu o semnătură generică care îl face reutilizabil pentru orice schemă. Nu este nevoie să prindeți o ZodError: chat.parse() nu aruncă una; lasă parsed gol. Acest caz, împreună cu erorile de rețea sau HTTP, declanșează o reîncercare. Constrângerea z.ZodType<T> leagă schema transmisă ca argument de tipul de returnare: schema.parse() returnează un T, astfel încât apelantul primește un obiect corect tipat fără adnotări suplimentare.
// Continuarea aceluiași fișier: client, z și BookSchema sunt deja definite
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); // restabilește tipul T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Utilizare
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Puncte cheie
- Zod este echivalentul TypeScript al lui Pydantic pentru ieșiri structurate personalizate
z.infer<typeof Schema>generează automat tipul TypeScript.describe()adaugă instrucțiuni per-câmp, la fel caField(description=...)în Python- SDK-ul Mistral TypeScript folosește
responseFormat(camelCase) în loc deresponse_format - Un răspuns neconform lasă
parsedcaundefined(fără excepție): testați-l, apoi reîncercați dacă este necesar