Zod-skeemat TypeScriptissä
Tällä sivulla
Päivitetty 3. marraskuuta 2026 kääntämisen jälkeen käyttäen
@mistralai/mistralaiSDK:ta 3.5.0, Zodia 4.6 ja TypeScriptiä 7.0.2. Alkuperäinen esimerkki toiMistral-luokan oletusarvoisesti, mutta SDK tarjoaa vain nimetyn viennin. Se luki myösresponse-muuttujaa funktiossamain(), vaikka se oli olemassa vainextractBook()-funktion sisällä.parsed-muuttujan käyttö ei ottanut huomioon, ettächoicesjamessageovat valinnaisia SDK-tyypeissä, ja se käsitteliparsed-muuttujaa tyyppinäBook, vaikka sen todellinen tyyppi onunknown.ZodError-tuonti oli tarpeeton:chat.parse()validoi käyttämälläsafeParse-metodia eikä heitä poikkeuksia. API-avainta ei enää kovakoodata. Lähteet: Mistral TypeScript SDK · virallinenchat.parse-esimerkki.
Zod: TypeScriptin vastine Pydanticille
Jos työskentelet TypeScriptillä tai JavaScriptillä, Zod on skeemien validointikirjasto, jota Mistral SDK käyttää mukautettuihin jäsenneltyihin tulosteisiin. Sillä on täsmälleen sama rooli kuin Pydanticilla Pythonissa: määritellään tiukka skeema, jota mallin on noudatettava. Kaikki skeemoista oppimasi pätee myös tähän, eroavaisuudet ovat vain syntaksissa.
Asenna sekä SDK että Zod yhdellä komennolla:
npm install @mistralai/mistralai zod
Zod toimii natiivisti TypeScriptin kanssa ja tarjoaa automaattisen tyypinpäätelyn – tämä on sen suurin etu verrattuna rajapintojen kirjoittamiseen käsin.
Yksinkertaisen skeeman määrittäminen
Rakenna Zod-skeema käyttämällä z.object()-funktiota ja määritä validaattori jokaiselle kentälle. z.infer-rivi tekee eron: se päättelee TypeScript-tyypin suoraan skeemasta, joten sinun ei tarvitse ylläpitää kahta rinnakkaista määrittelyä, jotka voivat ajautua erilleen.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript päättelee tyypin automaattisesti
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Tarvitsemasi tyypit
Zod kattaa kaikki jäsenneltyjen tulosteiden tarpeet. Alla oleva tukilippuskeema yhdistää yleisiä tapauksia: peruskentät, null-arvon salliva kenttä varaamattomalle lipulle, arvojoukko prioriteetille ja tyypitetyt taulukot.
import { z } from "zod";
const TicketSchema = z.object({
// Perustyypit
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Valinnainen (voi olla null)
assignee: z.string().nullable(),
// Enum (rajoitetut arvot)
priority: z.enum(["low", "medium", "high", "critical"]),
// Listat
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Yksi vivahde ansaitsee huomiota: kun Python erottaa toisistaan int ja float, Zod tuntee vain z.number()-tyypin. Pidä tämä vastaavuus mielessäsi, kun siirrät skeemaa kielestä toiseen.
| 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([...]) |
Sisäkkäiset skeemat
Kuten Pydanticissa, skeema voi sisältää toisen skeeman: viittaa vain vakioon. Koostaminen etenee sisimmästä uloimpaan: osoite yrityksen sisällä, yritys henkilön sisällä.
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>;
Täydellinen kutsu Mistral SDK:lla
Tässä on sama kirjan tietojen poiminta kuin Python-tunnilla, mutta portattuna TypeScriptiin. Kolme kohtaa vaatii huomiota. Parametrin nimi on responseFormat camelCase-muodossa. Sinun on testattava parsed-muuttuja ennen käyttöä: SDK validoi vastauksen skeemaa vasten käyttämällä safeParse-metodia, ja jos JSON on typistynyt tai ei täytä skeemaa, parsed jää arvoksi undefined poikkeuksen heittämisen sijaan. Lopuksi SDK ei säilytä skeemasi tyyppiä: se määrittelee parsed-muuttujan tyypiksi unknown. Objektin välittäminen BookSchema.parse()-funktion kautta tyypittää sen Book-tyypiksi ja samalla validoi sen uudelleen.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Määritä skeema
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. Luo asiakas
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Kutsu 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. Käsittele jäsennetty objekti
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Raaka JSON on edelleen saatavilla muodossa message.content
console.log(`Raw JSON: ${message.content}`);
// parsed on tyypiltään unknown: BookSchema.parse() palauttaa tyypitetyn Book-objektin
return BookSchema.parse(message.parsed);
}
// 5. Käyttö
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();
Kenttien kuvaaminen .describe()-metodilla
Zodissa .describe() täyttää saman roolin kuin Field(description=...) Pydanticissa: se kertoo mallille, mitä kentän tulisi sisältää, erityisesti kun nimi yksinään on epäselvä. score ilman kuvausta saattaa päätyä 0–100-asteikolle; jos mainitset eksplisiittisen alueen, malli noudattaa sopimaasi käytäntöä.
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"
),
});
Virheenkäsittely
Yritysmalli seuraa samaa logiikkaa kuin Pythonissa, ja yleinen allekirjoitus tekee siitä uudelleenkäytettävän mille tahansa skeemalle. ZodError-poikkeusta ei tarvitse siepata: chat.parse() ei heitä sellaista, vaan jättää parsed-muuttujan tyhjäksi. Tämä tilanne sekä verkko- tai HTTP-virheet käynnistävät uudelleenyrityksen. Rajoite z.ZodType<T> yhdistää argumenttina annetun skeeman palautustyyppiin: schema.parse() palauttaa tyypin T, joten kutsuja saa oikein tyypitetyn objektin ilman lisämerkintöjä.
// Sama tiedosto jatkuu: client, z ja BookSchema on jo määritelty
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); // palauttaa tyypin T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Käyttö
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Keskeiset asiat
- Zod on TypeScriptin vastine Pydanticille mukautetuissa jäsennellyissä tulosteissa
z.infer<typeof Schema>generoi TypeScript-tyypin automaattisesti.describe()lisää kenttäkohtaisia ohjeita, kutenField(description=...)Pythonissa- Mistral TypeScript SDK käyttää
responseFormat(camelCase) eikäresponse_format - Skeeman vastainen vastaus jättää
parsed-muuttujan arvoksiundefined(ei poikkeusta): testaa se ja yritä uudelleen tarvittaessa