Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Shemas Zod TypeScript valodā

Nodarbība 9 no 12 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Zod: TypeScript ekvivalents Pydantic
  2. Vienkāršas shēmas definēšana
  3. Tipi, kas tev būs nepieciešami
  4. Ligzdotas shēmas
  5. Pilns izsaukums ar Mistral SDK
  6. Lauku aprakstīšana ar .describe()
  7. Kļūdu apstrāde
  8. Galvenās atziņas

Atjaunināts 2026. gada 3. novembrī pēc saskaņošanas ar @mistralai/mistralai SDK 3.5.0, Zod 4.6 un TypeScript 7.0.2. Sākotnējais piemērs pēc noklusējuma importēja Mistral, taču SDK piedāvā tikai nosauktu eksportu. Tas arī lasīja mainīgo response funkcijā main(), kas eksistēja tikai extractBook() ietvaros. Pieejot parsed, tika ignorēts fakts, ka choices un message SDK tipos ir opcionāli, un parsed tika uzskatīts par Book, lai gan tā tips faktiski ir unknown. ZodError imports bija lieks: chat.parse() veic validāciju ar safeParse un nekad neizmet kļūdu. API atslēga vairs nav iekodēta. Avoti: Mistral TypeScript SDK · oficiāls chat.parse piemērs.

Zod: TypeScript ekvivalents Pydantic

Ja strādā ar TypeScript vai JavaScript, Zod ir shēmu validācijas bibliotēka, ko Mistral SDK izmanto pielāgotām strukturētām izvades datnēm. Tai ir tieši tāda pati loma kā Pydantic Python valodā: definēt stingru shēmu, kurai modelim jāseko. Viss, ko esi apguvis par shēmām, attiecas arī šeit; atšķiras tikai sintakse.

Instalē gan SDK, gan Zod ar vienu komandu:

npm install @mistralai/mistralai zod

Zod darbojas dabiski kopā ar TypeScript un nodrošina automātisku tipu secināšanu — tā ir tā galvenā priekšrocība salīdzinājumā ar interfeisu rakstīšanu ar roku.

Vienkāršas shēmas definēšana

Izveido Zod shēmu, izmantojot z.object(), piešķirot validatoru katram laukam. Rinda ar z.infer ir izšķiroša: tā secina TypeScript tipu no shēmas, tāpēc tev nav jāuztur divi paralēli deklarējumi, kas laika gaitā varētu atšķirties.

import { z } from "zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  phone: z.string(),
  company: z.string(),
});

// TypeScript automātiski secina tipu
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tipi, kas tev būs nepieciešami

Zod sedz visas vajadzības strukturētām izvades datnēm. Zemāk redzamā biļešu shēma apvieno biežāk sastopamos gadījumus: pamata laukus, nullable lauku nepiešķirtai biļetei, enumerāciju prioritātei un tipizētus masīvus.

import { z } from "zod";

const TicketSchema = z.object({
  // Pamata tipi
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Opcionāls (var būt null)
  assignee: z.string().nullable(),

  // Enum (ierobežotas vērtības)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Saraksti
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Viena nianse ir pelnījusi uzmanību: tur, kur Python nošķir int un float, Zod pazīst tikai z.number(). Paturi šo kartējumu prātā, pārnēsājot shēmu no vienas valodas uz otru.

Pydantic (Python)Zod (TypeScript)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.enum([...])

Ligzdotas shēmas

Tāpat kā Pydantic gadījumā, shēma var saturēt citu shēmu: vienkārši norādi konstanti. Kompozīcija tad lasāma no iekšpuses uz āru: adrese uzņēmumā, uzņēmums personā.

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>;

Pilns izsaukums ar Mistral SDK

Lūk, tas pats grāmatu ekstrakcijas piemērs no Python nodarbības, pārnests uz TypeScript. Ir trīs punkti, kam jāpievērš uzmanība. Parametrs ir responseFormat (camelCase). Pirms parsed izmantošanas tas ir jāpārbauda: SDK validē atbildi pret shēmu, izmantojot safeParse, un, ja JSON ir apgriezts vai neatbilst shēmai, atstāj parsed kā undefined, nevis izmet kļūdu. Visbeidzot, SDK nesaglabā tavas shēmas tipu: tas deklarē parsed kā unknown. Nodevojot objektu caur BookSchema.parse(), tas tiek tipizēts kā Book un vienlaikus tiek atkārtoti validēts.

import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

// 1. Definē shēmu
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. Izveido klientu
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Izsauc 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. Piekļūst parsētajam objektam
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Neapstrādāts JSON joprojām ir pieejams message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed ir tipizēts kā unknown: BookSchema.parse() atgriež tipizētu Book
  return BookSchema.parse(message.parsed);
}

// 5. Lietošana
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();

Lauku aprakstīšana ar .describe()

Zod vidē .describe() pilda tādu pašu lomu kā Field(description=...) Pydantic: tas norāda modelim, kam laukam jāsatur, it īpaši, ja nosaukums vien ir neskaidrs. score bez apraksta var nonākt skalā no 0 līdz 100; ar tieši minētu diapazonu tas ievēros tavu konvenciju.

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"
  ),
});

Kļūdu apstrāde

Atkārtošanas (retry) modelis seko tai pašai loģikai kā Python, ar vispārīgu signatūru, kas padara to atkārtoti izmantojamu jebkurai shēmai. Nav nepieciešams ķert ZodError: chat.parse() to neizmet; tas vienkārši atstāj parsed tukšu. Šis gadījums, kā arī tīkla vai HTTP kļūdas, izraisa atkārtotu mēģinājumu. Ierobežojums z.ZodType<T> saista shēmu, kas padota kā arguments, ar atgriešanas tipu: schema.parse() atgriež T, tāpēc izsaucošais kods saņem pareizi tipizētu objektu bez papildu anotācijām.

// Tā paša faila turpinājums: clients, z un BookSchema jau ir definēti

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); // atjauno tipu T
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error);
      if (attempt === maxRetries) throw error;
    }
  }
  throw new Error("Unexpected failure");
}

// Lietošana
try {
  const book = await safeExtract("My text here", BookSchema);
  console.log(book.title);
} catch (error) {
  console.error("Extraction failed:", error);
}

Galvenās atziņas

  • Zod ir TypeScript ekvivalents Pydantic pielāgotām strukturētām izvades datnēm
  • z.infer<typeof Schema> automātiski ģenerē TypeScript tipu
  • .describe() pievieno instrukcijas katram laukam, līdzīgi kā Field(description=...) Python valodā
  • Mistral TypeScript SDK izmanto responseFormat (camelCase) nevis response_format
  • Atbilde, kas neatbilst prasībām, atstāj parsed kā undefined (bez izņēmuma): pārbaudi to un, ja nepieciešams, atkārto darbību