Zod-skemaer i TypeScript
På denne side
Opdateret 3. november 2026 efter kompilering med
@mistralai/mistralaiSDK 3.5.0, Zod 4.6 og TypeScript 7.0.2. Det oprindelige eksempel importeredeMistralsom standard, men SDK’et tilbyder kun en navngiven eksport. Det læste også enresponse-variabel imain(), som kun eksisterede inde iextractBook(). Adgang tilparsedignorerede, atchoicesogmessageer valgfrie i SDK-typerne, og det behandledeparsedsom enBook, når dens type faktisk erunknown. Importen afZodErrorvar unødvendig:chat.parse()validerer medsafeParseog kaster aldrig en fejl. API-nøglen er ikke længere hardcodet. Kilder: Mistral TypeScript SDK · officieltchat.parse-eksempel.
Zod: TypeScript-modstykket til Pydantic
Hvis du arbejder med TypeScript eller JavaScript, er Zod det skemavalideringsbibliotek, som Mistral SDK’et bruger til brugerdefinerede strukturerede output. Det spiller præcis samme rolle som Pydantic i Python: at definere et strengt skema, som modellen skal overholde. Alt, hvad du har lært om skemaer, gælder også her; kun syntaksen er anderledes.
Installér både SDK’et og Zod med én enkelt kommando:
npm install @mistralai/mistralai zod
Zod fungerer nativt med TypeScript og giver automatisk typeudledning – det er dets største fordel frem for at skrive interfaces i hånden.
Definition af et simpelt skema
Byg et Zod-skema med z.object(), og tildel en validator til hvert felt. Linjen med z.infer gør forskellen: den udleder TypeScript-typen direkte fra skemaet, så du slipper for at vedligeholde to parallelle deklarationer, der kunne komme ud af sync.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript udleder typen automatisk
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Typer, du får brug for
Zod dækker alle behov for strukturerede output. Skemaet til sagsbehandling nedenfor samler常见的 tilfælde: basale felter, et nullable felt til en ikke-tildelt sag, en enum til prioritet og typede arrays.
import { z } from "zod";
const TicketSchema = z.object({
// Basistyper
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Valgfrit (kan være null)
assignee: z.string().nullable(),
// Enum (begrænsede værdier)
priority: z.enum(["low", "medium", "high", "critical"]),
// Lister
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Én nuance fortjener opmærksomhed: Hvor Python skelner mellem int og float, kender Zod kun z.number(). Husk denne mapping, når du porterer et skema fra det ene sprog til det andet.
| 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([...]) |
Næstede skemaer
Ligesom med Pydantic kan et skema indeholde et andet: du refererer blot til konstanten. Sammensætningen læses derefter indefra og ud: adressen inde i virksomheden, virksomheden inde i personen.
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>;
Et komplet kald med Mistral SDK’et
Her er den samme bogudtrækning fra Python-lektionen, porteret til TypeScript. Tre punkter kræver opmærksomhed. Parameteren hedder responseFormat i camelCase. Du skal teste parsed, før du bruger den: SDK’et validerer svaret mod skemaet med safeParse, og hvis JSON’en er trunkeret eller ikke matcher skemaet, efterlades parsed som undefined i stedet for at kaste en fejl. Endelig bærer SDK’et ikke din skemas type med sig: det deklarerer parsed som unknown. Ved at sende objektet gennem BookSchema.parse() får det typen Book, og det bliver samtidig genvalideret.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Definer skemaet
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. Opret klienten
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Kald 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. Tilgå det parsede objekt
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Rå JSON er stadig tilgængelig i message.content
console.log(`Raw JSON: ${message.content}`);
// parsed er typet som unknown: BookSchema.parse() returnerer en typet Book
return BookSchema.parse(message.parsed);
}
// 5. Brug
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();
Beskrivelse af felter med .describe()
I Zod udfylder .describe() samme rolle som Field(description=...) i Pydantic: det fortæller modellen, hvad feltet skal indeholde, især når navnet alene er tvetydigt. En score uden beskrivelse kunne ende på en skala fra 0–100; med en eksplicit nævnt rækkefølge følger den din konvention.
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"
),
});
Fejlhåndtering
Retry-mønsteret følger den samme logik som i Python, med en generisk signatur, der gør det genanvendeligt for ethvert skema. Der er ikke behov for at fange en ZodError: chat.parse() kaster ikke en sådan; den efterlader blot parsed tom. Det tilfælde, sammen med netværks- eller HTTP-fejl, udløser et nyt forsøg. Begrænsningen z.ZodType<T> linker skemaet, der sendes som argument, til returtypen: schema.parse() returnerer en T, så kalderen får et korrekt typet objekt uden ekstra annotationer.
// Fortsættelse af samme fil: client, z og BookSchema er allerede defineret
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); // genopretter type T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Brug
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Vigtige pointer
- Zod er TypeScript-modstykket til Pydantic for brugerdefinerede strukturerede output
z.infer<typeof Schema>genererer automatisk TypeScript-typen.describe()tilføjer instruktioner pr. felt, ligesomField(description=...)i Python- Mistral TypeScript SDK’et bruger
responseFormat(camelCase) i stedet forresponse_format - Et svar, der ikke overholder skemaet, efterlader
parsedsomundefined(ingen undtagelse): test for det, og gentag forsøget om nødvendigt