Схеми на Zod в TypeScript
На тази страница
Обновено на 3 ноември 2026 г. след компилация със SDK
@mistralai/mistralaiверсия 3.5.0, Zod 4.6 и TypeScript 7.0.2. Първоначалният пример импортирашеMistralпо подразбиране, но SDK предлага само именован експорт. Също така четеше променливаresponseвъв функциятаmain(), която съществуваше само вътре вextractBook(). Достъпът доparsedигнорираше факта, чеchoicesиmessageса опционални в типовете на SDK, и третирашеparsedкатоBook, въпреки че реалният му тип еunknown. Импортирането наZodErrorбеше излишно:chat.parse()валидира чрезsafeParseи никога не хвърля грешка. API ключът вече не е вграден в кода. Източници: Mistral TypeScript SDK · официален пример заchat.parse.
Zod: TypeScript еквивалентът на Pydantic
Ако работите с TypeScript или JavaScript, Zod е библиотеката за валидиране на схеми, използвана от Mistral SDK за персонализирани структурирани изходи. Тя играе абсолютно същата роля като Pydantic в Python: дефиниране на строга схема, която моделът трябва да следва. Всичко, което научихте за схемите, важи и тук, като единствената разлика е в синтаксиса.
Инсталирайте както SDK, така и Zod с една команда:
npm install @mistralai/mistralai zod
Zod работи нативно с TypeScript и осигурява автоматично извеждане на типове – това е основното му предимство пред ръчното писане на интерфейси.
Дефиниране на проста схема
Изградете схема на Zod с z.object(), присвоявайки валидатор на всяко поле. Редът с z.infer прави разликата: той извежда TypeScript типа от схемата, така че не е необходимо да поддържате две паралелни декларации, които могат да се разминат с времето.
import { z } from "zod";
const ContactSchema = z.object({
name: z.string(),
email: z.string(),
phone: z.string(),
company: z.string(),
});
// TypeScript автоматично извежда типа
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }
Типове, от които ще се нуждаете
Zod покрива всяка нужда за структурирани изходи. Схемата за билет по-долу обединява често срещани случаи: основни полета, nullable поле за неназначен билет, enum за приоритет и типизирани масиви.
import { z } from "zod";
const TicketSchema = z.object({
// Основни типове
title: z.string(),
description: z.string(),
ticketId: z.number(),
confidence: z.number(),
isUrgent: z.boolean(),
// Опционално (може да бъде null)
assignee: z.string().nullable(),
// Enum (ограничени стойности)
priority: z.enum(["low", "medium", "high", "critical"]),
// Списъци
tags: z.array(z.string()),
relatedIds: z.array(z.number()),
});
type Ticket = z.infer<typeof TicketSchema>;
Един нюанс заслужава внимание: докато Python прави разлика между int и float, Zod познава само z.number(). Имайте предвид това съответствие, когато пренасяте схема от един език на друг.
| 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([...]) |
Вложени схеми
Както при Pydantic, една схема може да съдържа друга: просто направете препратка към константата. Композицията след това се чете от вътрешното към външното: адресът вътре в компанията, компанията вътре в лицето.
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>;
Пълен вызов с Mistral SDK
Ето същото извличане на информация за книга от урока за Python, пренесено в TypeScript. Три точки изискват внимание. Параметърът е responseFormat в camelCase. Трябва да тествате parsed, преди да го използвате: SDK валидира отговора спрямо схемата с safeParse и, ако JSON е отрязан или не съвпада със схемата, оставя parsed като undefined, вместо да хвърли грешка. Накрая, SDK не носи типа на вашата схема: той декларира parsed като unknown. Преминаването на обекта през BookSchema.parse() го прави типизиран като Book и го ревалидира в процеса.
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";
// 1. Дефиниране на схемата
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. Създаване на клиента
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
// 3. Извикване на 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. Достъп до парсирания обект
const message = response.choices?.[0]?.message;
if (!message?.parsed) {
throw new Error("Response missing, truncated, or non-compliant with schema");
}
// Суровият JSON остава наличен в message.content
console.log(`Raw JSON: ${message.content}`);
// parsed е типизиран като unknown: BookSchema.parse() връща типизиран Book
return BookSchema.parse(message.parsed);
}
// 5. Използване
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();
Описване на полета с .describe()
В Zod, .describe() изпълнява същата роля като Field(description=...) в Pydantic: казва на модела какво трябва да съдържа полето, особено когато самото име е двусмислено. score без описание може да попадне в скала 0–100; с изрично споменат диапазон, то следва вашата конвенция.
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"
),
});
Обработка на грешки
Моделът за повторни опити следва същата логика като в Python, с обща сигнатура, която го прави многократно използваем за всяка схема. Няма нужда да прихващате ZodError: chat.parse() не хвърля такава; то оставя parsed празно. Този случай, заедно с мрежови или HTTP грешки, задейства повторен опит. Ограничението z.ZodType<T> свързва схемата, предадена като аргумент, с връщания тип: schema.parse() връща T, така че caller получава правилно типизиран обект без допълнителни анотации.
// Продължение на същия файл: client, z и BookSchema са вече дефинирани
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); // възстановява тип T
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxRetries) throw error;
}
}
throw new Error("Unexpected failure");
}
// Използване
try {
const book = await safeExtract("My text here", BookSchema);
console.log(book.title);
} catch (error) {
console.error("Extraction failed:", error);
}
Ключови изводи
- Zod е TypeScript еквивалентът на Pydantic за персонализирани структурирани изходи
z.infer<typeof Schema>автоматично генерира TypeScript типа.describe()добавя инструкции за всяко поле, подобно наField(description=...)в Python- Mistral TypeScript SDK използва
responseFormat(camelCase) вместоresponse_format - Несъответстващ отговор оставя
parsedкатоundefined(без изключение): тествайте за това и след това повторете опита, ако е необходимо