Scéamaí Zod i TypeScript
Ar an leathanach seo
Nuashonraithe an 3 Samhain, 2026 tar éis tiomsú le SDK
@mistralai/mistralai3.5.0, Zod 4.6, agus TypeScript 7.0.2. D’iompórtáil an sampla bunaidhMistralgo réamhshocraithe, ach ní thairgeann an SDK ach onnmhairiú ainmnithe. Léigh sé athrógresponseimain()nach raibh ann ach laistigh deextractBook(). Rinne rochtain arparsedneamhaird ar an bhfíric go bhfuilchoicesagusmessageroghnach i gcineálacha an SDK, agus thug sé arparsedmarBooknuair is éunknowna chineál i ndáiríre. Ní raibh gá le hiompórtáilZodError: déanannchat.parse()bailíochtú lesafeParseagus ní chaitheann sé eisceacht riamh. Níl an eochair API crua-chódaithe a thuilleadh. Foinse: Mistral TypeScript SDK · sampla oifigiúilchat.parse.
Zod: An Coibhéis TypeScript do Pydantic
Má oibríonn tú i TypeScript nó JavaScript, is é Zod an leabharlann bailíochtaithe scéama a úsáideann an Mistral SDK d’Aschuir Struchtúrtha Saincheaptha. Imríonn sé an ról céanna go díreach agus a imríonn Pydantic i bPython: scéama dian a shainiú ar cheart don mhúnla cloí leis. Baineann gach rud a d’fhoghlaim tú faoi scéamaí anseo, gan ach difríochtaí comhréire.
Suiteáil an SDK agus Zod araon in ordú amháin:
npm install @mistralai/mistralai zod
Oibríonn Zod go dúchasach le TypeScript agus soláthraíonn sé tuiscint chineáil uathoibríoch—sin é a phríomhbhuntáiste thar chomhéadain a scríobh de láimh.
Scéama Simplí a Shainiú
Tóg scéama Zod le z.object(), agus sann bailíochtóir do gach réimse. Is é an líne z.infer a dhéanann an difríocht: díorthaíonn sé an cineál TypeScript ón scéama, ionas nach gcaithfidh tú dhá dhearadh chomhthreomhara a chothabháil a d’fhéadfadh imeacht ó chéile.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// Tuigeann TypeScript an cineál go huathoibríoch
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Cineálacha a Bheidh Ag Teastáil Uait
Clúdaíonn Zod gach riachtanas d’aschuir struchtúrtha. Tugann an scéama ticéid thíos le chéile cásanna coitianta: réimsí bunúsacha, réimse inbhainte do thicéad gan sannadh, áireamh do thosaíocht, agus eagair chineálaithe.
import { z } from "zod";
const TicketSchema = z.object({
// Cineálacha bunúsacha
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Roghnach (féadfaidh sé a bheith null)
assignee: z.string().nullable(),
// Áireamh (luachanna srianta)
priority: z.enum(["low", "medium", "high", "critical"]),
// Liostaí
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Tá nuansa amháin ar chóir aird a thabhairt air: cé go ndéanann Python idirdhealú idir int agus float, níl a fhios ag Zod ach z.number(). Coinnigh an mapáil seo i gcuimhne agus tú ag portáil scéama ó theanga amháin go teanga eile.
| 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([...]) |
Scéamaí Neadaigh
Mar atá le Pydantic, is féidir le scéama ceann eile a bheith ann: ní gá ach tagairt a dhéanamh don tairiseach. Ansin léann an comhdhéanamh ón gceann is faide isteach go dtí an ceann is faide amuigh: an seoladh laistigh den chuideachta, an chuideachta laistigh den duine.
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>;
Glao Iomlán leis an Mistral SDK
Seo an t-aistriúchán leabhair céanna ón gceacht Python, portáilte go TypeScript. Tá trí phointe ar chóir aird a thabhairt orthu. Is é responseFormat an paraiméadar i camelCase. Caithfidh tú parsed a thástáil sula n-úsáideann tú é: déanann an SDK bailíochtú ar an bhfreagra i gcoinne an scéama le safeParse agus, má tá an JSON gearrtha nó mura meaitseálann sé an scéama, fágann sé parsed mar undefined in ionad eisceacht a chaitheamh. Ar deireadh, ní iompraíonn an SDK cineál do scéama: dearbhann sé parsed mar unknown. Má chuireann tú an oibiacht trí BookSchema.parse(), déantar é a chineálú mar Book agus déantar é a athbhailíochtú sa phróiseas.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Sainigh an scéama
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. Cruthaigh an cliant
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Glaoigh ar 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. Faigh rochtain ar an oibiacht pharsáilte
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Tá an JSON amh ar fáil fós i message.content
console.log(`Raw JSON: ${message.content}`);
// Tá parsed cineálaithe mar unknown: filleann BookSchema.parse() Book cineálaithe
return BookSchema.parse(message.parsed);
}
// 5. Úsáid
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();
Réimsí a Chur Síos le .describe()
I Zod, líonann .describe() an ról céanna agus a líonann Field(description=...) i bPython: insíonn sé don mhúnla cad ba chóir a bheith sa réimse, go háirithe nuair atá an t-ainm féin débhríoch. D’fhéadfadh score gan cur síos titim ar scála 0–100; le raon sainráite luaite, leanfaidh sé do choinbhinsiún.
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"
),
});
Láimhseáil Earráidí
Leanann an patrún athiarrtha an loighic chéanna agus atá i bPython, le síniú ginearálta a dhéanann in-athúsáidte é do gach scéama. Níl aon ghá le ZodError a ghabháil: ní chaitheann chat.parse() ceann ar bith; fágann sé parsed folamh. Spreagann an cás sin, mar aon le hearráidí líonra nó HTTP, athiarracht. Nascann an srian z.ZodType<T> an scéama a tharchuirtear mar argóint leis an gcineál fillte: filleann schema.parse() T, mar sin faigheann an glaoiteoir oibiacht chineálaithe i gceart gan nótaí breise.
// Leanúint den chomhad céanna: tá client, z, agus BookSchema sainithe cheana
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); // athchuireann sé cineál T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Úsáid
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Príomhphointí
- Is é Zod an coibhéis TypeScript do Pydantic d’Aschuir Struchtúrtha Saincheaptha
- Gineann
z.infer<typeof Schema>an cineál TypeScript go huathoibríoch - Cuireann
.describe()treoracha in aghaidh an réimse leis, cosúil leField(description=...)i bPython - Úsáideann an Mistral TypeScript SDK
responseFormat(camelCase) in ionadresponse_format - Fágann freagra nach bhfuil comhlíontach
parsedmarundefined(gan eisceacht): déan tástáil air, agus déan athiarracht más gá