Shemas Zod TypeScript valodā
Šajā lapā
Atjaunināts 2026. gada 3. novembrī pēc saskaņošanas ar
@mistralai/mistralaiSDK 3.5.0, Zod 4.6 un TypeScript 7.0.2. Sākotnējais piemērs pēc noklusējuma importējaMistral, taču SDK piedāvā tikai nosauktu eksportu. Tas arī lasīja mainīgoresponsefunkcijāmain(), kas eksistēja tikaiextractBook()ietvaros. Pieejotparsed, tika ignorēts fakts, kachoicesunmessageSDK tipos ir opcionāli, unparsedtika uzskatīts parBook, lai gan tā tips faktiski irunknown.ZodErrorimports bija lieks:chat.parse()veic validāciju arsafeParseun nekad neizmet kļūdu. API atslēga vairs nav iekodēta. Avoti: Mistral TypeScript SDK · oficiālschat.parsepiemērs.
Zod: TypeScript ekvivalents Pydantic
Ja strādā ar TypeScript vai JavaScript, Zod ir shēmu validācijas bibliotēka, ko Mistral SDK izmanto pielāgotām strukturētām izvades datnēm. Tai ir tieši tāda pati loma kā Pydantic Python valodā: definēt stingru shēmu, kurai modelim jāseko. Viss, ko esi apguvis par shēmām, attiecas arī šeit; atšķiras tikai sintakse.
Instalē gan SDK, gan Zod ar vienu komandu:
npm install @mistralai/mistralai zod
Zod darbojas dabiski kopā ar TypeScript un nodrošina automātisku tipu secināšanu — tā ir tā galvenā priekšrocība salīdzinājumā ar interfeisu rakstīšanu ar roku.
Vienkāršas shēmas definēšana
Izveido Zod shēmu, izmantojot z.object(), piešķirot validatoru katram laukam. Rinda ar z.infer ir izšķiroša: tā secina TypeScript tipu no shēmas, tāpēc tev nav jāuztur divi paralēli deklarējumi, kas laika gaitā varētu atšķirties.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript automātiski secina tipu
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Tipi, kas tev būs nepieciešami
Zod sedz visas vajadzības strukturētām izvades datnēm. Zemāk redzamā biļešu shēma apvieno biežāk sastopamos gadījumus: pamata laukus, nullable lauku nepiešķirtai biļetei, enumerāciju prioritātei un tipizētus masīvus.
import { z } from "zod";
const TicketSchema = z.object({
// Pamata tipi
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Opcionāls (var būt null)
assignee: z.string().nullable(),
// Enum (ierobežotas vērtības)
priority: z.enum(["low", "medium", "high", "critical"]),
// Saraksti
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Viena nianse ir pelnījusi uzmanību: tur, kur Python nošķir int un float, Zod pazīst tikai z.number(). Paturi šo kartējumu prātā, pārnēsājot shēmu no vienas valodas uz otru.
| 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([...]) |
Ligzdotas shēmas
Tāpat kā Pydantic gadījumā, shēma var saturēt citu shēmu: vienkārši norādi konstanti. Kompozīcija tad lasāma no iekšpuses uz āru: adrese uzņēmumā, uzņēmums personā.
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>;
Pilns izsaukums ar Mistral SDK
Lūk, tas pats grāmatu ekstrakcijas piemērs no Python nodarbības, pārnests uz TypeScript. Ir trīs punkti, kam jāpievērš uzmanība. Parametrs ir responseFormat (camelCase). Pirms parsed izmantošanas tas ir jāpārbauda: SDK validē atbildi pret shēmu, izmantojot safeParse, un, ja JSON ir apgriezts vai neatbilst shēmai, atstāj parsed kā undefined, nevis izmet kļūdu. Visbeidzot, SDK nesaglabā tavas shēmas tipu: tas deklarē parsed kā unknown. Nodevojot objektu caur BookSchema.parse(), tas tiek tipizēts kā Book un vienlaikus tiek atkārtoti validēts.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definē shēmu
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. Izveido klientu
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Izsauc 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. Piekļūst parsētajam objektam
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Neapstrādāts JSON joprojām ir pieejams message.content
console.log(`Raw JSON: ${message.content}`);
// parsed ir tipizēts kā unknown: BookSchema.parse() atgriež tipizētu Book
return BookSchema.parse(message.parsed);
}
// 5. Lietošana
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();
Lauku aprakstīšana ar .describe()
Zod vidē .describe() pilda tādu pašu lomu kā Field(description=...) Pydantic: tas norāda modelim, kam laukam jāsatur, it īpaši, ja nosaukums vien ir neskaidrs. score bez apraksta var nonākt skalā no 0 līdz 100; ar tieši minētu diapazonu tas ievēros tavu 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"
),
});
Kļūdu apstrāde
Atkārtošanas (retry) modelis seko tai pašai loģikai kā Python, ar vispārīgu signatūru, kas padara to atkārtoti izmantojamu jebkurai shēmai. Nav nepieciešams ķert ZodError: chat.parse() to neizmet; tas vienkārši atstāj parsed tukšu. Šis gadījums, kā arī tīkla vai HTTP kļūdas, izraisa atkārtotu mēģinājumu. Ierobežojums z.ZodType<T> saista shēmu, kas padota kā arguments, ar atgriešanas tipu: schema.parse() atgriež T, tāpēc izsaucošais kods saņem pareizi tipizētu objektu bez papildu anotācijām.
// Tā paša faila turpinājums: clients, z un BookSchema jau ir definēti
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); // atjauno tipu T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Lietošana
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Galvenās atziņas
- Zod ir TypeScript ekvivalents Pydantic pielāgotām strukturētām izvades datnēm
z.infer<typeof Schema>automātiski ģenerē TypeScript tipu.describe()pievieno instrukcijas katram laukam, līdzīgi kāField(description=...)Python valodā- Mistral TypeScript SDK izmanto
responseFormat(camelCase) nevisresponse_format - Atbilde, kas neatbilst prasībām, atstāj
parsedkāundefined(bez izņēmuma): pārbaudi to un, ja nepieciešams, atkārto darbību