Премини към основното съдържание
Български— Изберете език
Меню

Схеми на Zod в TypeScript

Урок 9 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Zod: TypeScript еквивалентът на Pydantic
  2. Дефиниране на проста схема
  3. Типове, от които ще се нуждаете
  4. Вложени схеми
  5. Пълен вызов с Mistral SDK
  6. Описване на полета с .describe()
  7. Обработка на грешки
  8. Ключови изводи

Обновено на 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)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.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 (без изключение): тествайте за това и след това повторете опита, ако е необходимо