Schematy Zod w TypeScript
Na tej stronie
Zaktualizowano 3 listopada 2026 po kompilacji z SDK
@mistralai/mistralaiw wersji 3.5.0, Zod 4.6 oraz TypeScript 7.0.2. Oryginalny przykład domyślnie importowałMistral, ale SDK udostępnia jedynie eksport nazwany. Odwoływał się też do zmiennejresponsew funkcjimain(), która istniała tylko wewnątrzextractBook(). Dostęp doparsedignorował fakt, żechoicesimessagesą opcjonalne w typach SDK, i traktowałparsedjakoBook, podczas gdy jego typ to w rzeczywistościunknown. ImportZodErrorbył zbędny:chat.parse()waliduje dane za pomocąsafeParsei nigdy nie rzuca wyjątkiem. Klucz API nie jest już zakodowany na sztywno. Źródła: Mistral TypeScript SDK · oficjalny przykładchat.parse.
Zod: TypeScriptowy odpowiednik Pydantic
Jeśli pracujesz w TypeScript lub JavaScript, Zod jest biblioteką do walidacji schematów używaną przez SDK Mistral do niestandardowych wyjść strukturalnych. Pełni dokładnie taką samą rolę jak Pydantic w Pythonie: definiuje ścisły schemat, którego model musi przestrzegać. Wszystko, czego nauczyłeś się o schematach, ma tu zastosowanie – różnią się jedynie składnią.
Zainstaluj zarówno SDK, jak i Zod jedną komendą:
npm install @mistralai/mistralai zod
Zod działa natywnie z TypeScript i zapewnia automatyczne wnioskowanie typów – to jego główna przewaga nad ręcznym pisaniem interfejsów.
Definiowanie prostego schematu
Budujesz schemat Zod za pomocą z.object(), przypisując walidator do każdego pola. Linia z z.infer robi różnicę: wyprowadza typ TypeScript ze schematu, więc nie musisz utrzymywać dwóch równoległych deklaracji, które mogłyby się ze sobą rozmijać.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript automatycznie wnioskuję typ
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Typy, których będziesz potrzebować
Zod pokrywa każde zapotrzebowanie na wyjścia strukturalne. Poniższy schemat zgłoszenia łączy typowe przypadki: pola podstawowe, pole nullable dla nieprzypisanego zgłoszenia, enum dla priorytetu oraz typowane tablice.
import { z } from "zod";
const TicketSchema = z.object({
// Typy podstawowe
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Opcjonalne (może być null)
assignee: z.string().nullable(),
// Enum (ograniczone wartości)
priority: z.enum(["low", "medium", "high", "critical"]),
// Listy
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Jeden niuans zasługuje na uwagę: tam gdzie Python rozróżnia int i float, Zod zna tylko z.number(). Miej to odwzorowanie na uwadze, przenosząc schemat z jednego języka na drugi.
| 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([...]) |
Schematy zagnieżdżone
Tak jak w Pydantic, schemat może zawierać inny: wystarczy odwołać się do stałej. Kompozycja czyta się wtedy od wnętrza na zewnątrz: adres wewnątrz firmy, firma wewnątrz osoby.
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>;
Pełne wywołanie z SDK Mistral
Oto to samo wydobycie informacji o książce z lekcji Pythonowej, przeniesione do TypeScript. Trzy punkty wymagają uwagi. Parametr to responseFormat w camelCase. Musisz przetestować parsed przed użyciem: SDK waliduje odpowiedź względem schematu za pomocą safeParse i, jeśli JSON jest ucięty lub nie zgadza się ze schematem, pozostawia parsed jako undefined, zamiast rzucać wyjątkiem. Na koniec SDK nie przenosi typu twojego schematu: deklaruje parsed jako unknown. Przepuszczenie obiektu przez BookSchema.parse() typuje go jako Book i przy okazji ponownie go waliduje.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Zdefiniuj schemat
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. Utwórz klienta
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Wywołaj 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. Uzyskaj dostęp do sparsowanego obiektu
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Surowy JSON pozostaje dostępny w message.content
console.log(`Raw JSON: ${message.content}`);
// parsed ma typ unknown: BookSchema.parse() zwraca typowane Book
return BookSchema.parse(message.parsed);
}
// 5. Użycie
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();
Opisywanie pól za pomocą .describe()
W Zod .describe() pełni tę samą rolę co Field(description=...) w Pydantic: mówi modelowi, co powinno zawierać pole, zwłaszcza gdy sama nazwa jest niejednoznaczna. score bez opisu może trafić na skalę 0–100; z jawnie wspomnianym zakresem, podąża za twoją konwencją.
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"
),
});
Obsługa błędów
Wzorzec ponawiania prób podąża za tą samą logiką co w Pythonie, z generyczną sygnaturą, która czyni go wielokrotnego użytku dla dowolnego schematu. Nie ma potrzeby łapania ZodError: chat.parse() go nie rzuca; pozostawia parsed puste. Ten przypadek, wraz z błędami sieciowymi lub HTTP, uruchamia ponowną próbę. Ograniczenie z.ZodType<T> łączy schemat przekazany jako argument z typem zwracanym: schema.parse() zwraca T, więc wywołujący otrzymuje poprawnie typowany obiekt bez dodatkowych adnotacji.
// Kontynuacja tego samego pliku: client, z i BookSchema są już zdefiniowane
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); // przywraca typ T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Użycie
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Kluczowe wnioski
- Zod to TypeScriptowy odpowiednik Pydantic dla niestandardowych wyjść strukturalnych
z.infer<typeof Schema>automatycznie generuje typ TypeScript.describe()dodaje instrukcje dla każdego pola, jakField(description=...)w Pythonie- TypeScriptowe SDK Mistral używa
responseFormat(camelCase) zamiastresponse_format - Odpowiedź niezgodna ze schematem pozostawia
parsedjakoundefined(brak wyjątku): sprawdź to, a następnie w razie potrzeby ponów próbę