Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Skemi Zod f'TypeScript

Lezzjoni 9 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Zod: L-Ekwivalenti ta’ Pydantic f’TypeScript
  2. Iddefinixxi Skema Sempliċi
  3. Tipi li Se Jkollok Bżonn
  4. Skemi Mbejjna (Nested)
  5. Sejħa Sħiħa bl-SDK ta’ Mistral
  6. Iddeskrivi l-Kampijiet b’.describe()
  7. Ġestjoni tal-Iżbalji
  8. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026 wara l-kompilazzjoni bl-SDK @mistralai/mistralai 3.5.0, Zod 4.6, u TypeScript 7.0.2. L-eżempju oriġinali kien jimporta Mistral b’mod default, iżda l-SDK joffri biss esportazzjoni msemmija. Kien jaqra wkoll varjabbli response f’main() li kien jeżisti biss ġewwa extractBook(). L-aċċess għal parsed injora li choices u message huma opzjonali fit-tipi tal-SDK, u ttratta parsed bħala Book meta t-tip tiegħu huwa attwalment unknown. L-importazzjoni ta’ ZodError ma kinitx meħtieġa: chat.parse() jivvalida b’safeParse u qatt ma jarmi eċċezzjoni. Iċ-ċavetta tal-API m’għadhiex imwaħħla fil-kodiċi. Sorsi: Mistral TypeScript SDK · eżempju uffiċjali ta’ chat.parse.

Zod: L-Ekwivalenti ta’ Pydantic f’TypeScript

Jekk taħdem b’TypeScript jew JavaScript, Zod hija l-librerija ta’ validazzjoni tal-iskemi użata mill-SDK ta’ Mistral għal Outputs Strutturati Personalizzati. Twettaq eżattament l-istess rwol bħal Pydantic f’Python: tiddefinixxi skema stretta li l-mudell irid isegwi. Kollox li tgħallimt dwar l-iskemi japplika hawnhekk, b’differenzi biss fis-sintassi.

Installa kemm l-SDK kif ukoll Zod f’kmand wieħed:

npm install @mistralai/mistralai zod

Zod jaħdem nativament ma’ TypeScript u jipprovdi inferenza awtomatika tat-tipi—dan huwa l-vantaġġ ewlieni tiegħu meta tikteb interfaċċji bl-idejn.

Iddefinixxi Skema Sempliċi

Ibni skema Zod b’z.object(), u assenja validatur għal kull kamp. Il-linja z.infer tagħmel id-differenza: tiddeduċi t-tip ta’ TypeScript mill-iskema, hekk ma jkollokx bżonn iżżomm żewġ dikjarazzjonijiet paralleli li jistgħu jiddiverġu.

import { z } from "zod";

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

// TypeScript jinferixxi t-tip awtomatikament
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tipi li Se Jkollok Bżonn

Zod ikopri kull ħtieġa għal outputs strutturati. L-iskema tat-ticket hawn taħt tiġbor flimkien każijiet komuni: kampijiet bażiċi, kamp nullable għal ticket mhux assenjat, enum għall-prijorità, u arrays ittajpjati.

import { z } from "zod";

const TicketSchema = z.object({
  // Tipi bażiċi
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Opzjonali (jista' jkun null)
  assignee: z.string().nullable(),

  // Enum (valuri ristretti)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Listi
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Nuansa waħda tiġbed l-attenzjoni: fejn Python jagħmel distinzjoni bejn int u float, Zod jaf biss z.number(). Żomm din il-mappatura f’moħħok meta ttrasporta skema minn lingwa għall-oħra.

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

Skemi Mbejjna (Nested)

Bħal ma’ Pydantic, skema tista’ fiha oħra: sempliċiment irreferenzja l-kostanti. Il-kompożizzjoni mbagħad taqra mill-aktar interna għall-aktar esterna: l-indirizz ġewwa l-kumpanija, il-kumpanija ġewwa l-persuna.

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

Sejħa Sħiħa bl-SDK ta’ Mistral

Hawnhekk hemm l-istess estrazzjoni tal-ktieb mil-lezzjoni tal-Python, ittrasportata għal TypeScript. Tliet punti jeħtieġu attenzjoni. Il-parametru huwa responseFormat f’camelCase. Trid tittestja parsed qabel ma tużah: l-SDK jivvalida r-risposta kontra l-iskema b’safeParse u, jekk il-JSON ikun imqatta’ jew ma jaqbilx mal-iskema, iħalli parsed bħala undefined minflok ma jarmi eċċezzjoni. Fl-aħħar nett, l-SDK ma jġorrx it-tip tal-iskema tiegħek: jiddikjara parsed bħala unknown. Li tgħaddi l-oġġett permezz ta’ BookSchema.parse() jagħmlu ittajpjat bħala Book u jerġa’ jivvalidah fil-proċess.

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

// 1. Iddefinixxi l-iskema
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. Oħloq il-klijent
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Sejjaħ 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. Aċċessa l-oġġett ipparzjat
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Il-JSON raw jibqa' disponibbli f'message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed huwa ttajpjat bħala unknown: BookSchema.parse() jirritorna Book ittajpjat
  return BookSchema.parse(message.parsed);
}

// 5. Użu
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();

Iddeskrivi l-Kampijiet b’.describe()

F’Zod, .describe() iwettaq l-istess rwol bħal Field(description=...) f’Pydantic: jgħid lill-mudell x’għandu jkun fih il-kamp, speċjalment meta l-isem waħdu jkun ambigwu. score mingħajr deskrizzjoni jista’ jaqa’ fuq skala ta’ 0–100; b’firxa espliċita msemmija, isegwi l-konvenzjoni tiegħek.

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

Ġestjoni tal-Iżbalji

Il-mudell ta’ retry isegwi l-istess loġika bħal f’Python, b’firma ġenerika li tagħmlu riutilizzabbli għal kwalunkwe skema. M’hemmx bżonn taqbbed ZodError: chat.parse() ma jarmihx; iħalli parsed vojt. Dak il-każ, flimkien ma’ żbalji tan-network jew HTTP, jipprovoka retry. Il-vincolu z.ZodType<T> jgħaqqad l-iskema mgħoddija bħala argument mat-tip tar-ritorn: schema.parse() jirritorna T, hekk is-sejjaħ jikseb oġġett ittajpjat sew mingħajr annotazzjonijiet extra.

// Komplement tal-istess fajl: client, z, u BookSchema huma diġà definiti

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

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

Punti Ewlenin

  • Zod huwa l-ekwivalenti ta’ Pydantic f’TypeScript għal Outputs Strutturati Personalizzati
  • z.infer<typeof Schema> jiġġenera awtomatikament it-tip ta’ TypeScript
  • .describe() iżid istruzzjonijiet għal kull kamp, bħal Field(description=...) f’Python
  • L-SDK ta’ Mistral għal TypeScript juża responseFormat (camelCase) minflok response_format
  • Risposta li ma tikkonformax tħalli parsed bħala undefined (l-ebda eċċezzjoni): ittestjah, imbagħad ipprova mill-ġdid jekk ikun meħtieġ