Salt la conținutul principal
Română— Alege o limbă
Meniu

Schemele Zod în TypeScript

Lecția 9 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Zod: Echivalentul TypeScript al lui Pydantic
  2. Definirea unei scheme simple
  3. Tipuri de care veți avea nevoie
  4. Scheme imbricate
  5. Un apel complet cu SDK-ul Mistral
  6. Descrierea câmpurilor cu .describe()
  7. Gestionarea erorilor
  8. Puncte cheie

Actualizat la 3 noiembrie 2026 după compilare cu SDK-ul @mistralai/mistralai 3.5.0, Zod 4.6 și TypeScript 7.0.2. Exemplul original importa Mistral implicit, dar SDK-ul oferă doar un export numit. De asemenea, citea o variabilă response în main() care exista doar în interiorul funcției extractBook(). Accesarea lui parsed ignora faptul că choices și message sunt opționale în tipurile SDK și îl trata pe parsed ca fiind un Book, când tipul său real este unknown. Importul ZodError era inutil: chat.parse() validează cu safeParse și nu aruncă niciodată erori. Cheia API nu mai este codificată direct. Surse: Mistral TypeScript SDK · exemplul oficial chat.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)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.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 ca Field(description=...) în Python
  • SDK-ul Mistral TypeScript folosește responseFormat (camelCase) în loc de response_format
  • Un răspuns neconform lasă parsed ca undefined (fără excepție): testați-l, apoi reîncercați dacă este necesar