Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Sheme Zod v TypeScriptu

Lekcija 9 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Zod: Ekvivalent Pydantic za TypeScript
  2. Definicija preproste sheme
  3. Tipi, ki jih boš potreboval
  4. Gnezdenje shem
  5. Popoln klic z Mistral SDK
  6. Opisovanje polj z .describe()
  7. Obravnava napak
  8. Ključne ugotovitve

Posodobljeno 3. novembra 2026 po kompilaciji s SDK-jem @mistralai/mistralai različice 3.5.0, Zod 4.6 in TypeScript 7.0.2. Prvotni primer je privzeto uvažal Mistral, vendar SDK ponuja le poimenovani izvoz. Prav tako je v funkciji main() bral spremenljivko response, ki je obstajala le znotraj extractBook(). Dostop do parsed je ignoriral dejstvo, da sta choices in message v tipih SDK opcijska, ter obravnaval parsed kot Book, čeprav je njegov dejanski tip unknown. Uvoz ZodError je bil nepotreben: chat.parse() validira s safeParse in nikoli ne vrže napake. Ključ API ni več trdo kodiran. Viri: Mistral TypeScript SDK · uradni primer chat.parse.

Zod: Ekvivalent Pydantic za TypeScript

Če delaš v TypeScriptu ali JavaScriptu, je Zod knjižnica za validacijo shem, ki jo SDK Mistral uporablja za prilagojene strukturirane izhode. Igra popolnoma enako vlogo kot Pydantic v Pythonu: definira strogo shemo, ki se ji mora model podrediti. Vse, kar si se naučil o shemah, velja tudi tukaj, razlikujejo se le sintaksa.

Namesti oba paketa, SDK in Zod, z enim ukazom:

npm install @mistralai/mistralai zod

Zod deluje avtohtono s TypeScriptom in ponuja samodejno sklepanje tipov – to je njegova glavna prednost pred ročnim pisanjem vmesnikov.

Definicija preproste sheme

Shemo Zod gradiš z z.object(), kjer vsakemu polju dodeliš validator. Vrstica z.infer naredi ključno razliko: iz sheme izpelje tip TypeScript, zato ti ni treba vzdrževati dveh vzporednih deklaracij, ki bi se lahko razšli.

import { z } from "zod";

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

// TypeScript samodejno sklepa tip
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tipi, ki jih boš potreboval

Zod pokriva vse potrebe za strukturirane izhode. Spodnja shema za vstopnico združuje pogoste primere: osnovna polja, polje, ki je lahko ničelno (za nedodeljeno vstopnico), naštevanje za prioriteto in tipizirana polja.

import { z } from "zod";

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

  // Opcijsko (lahko je null)
  assignee: z.string().nullable(),

  // Enum (omejene vrednosti)
  priority: z.enum(["low", "medium", "high", "critical"]),

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

type Ticket = z.infer<typeof TicketSchema>;

Ena podrobnost si zasluži pozornost: medtem ko Python razlikuje med int in float, Zod pozna le z.number(). To preslikavo imej v mislih, ko prenašaš shemo iz enega jezika v drugega.

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

Gnezdenje shem

Kot pri Pydanticu lahko shema vsebuje drugo shemo: preprosto se sklicuj na konstanto. Sestava se nato bere od notranjega k zunanjemu: naslov znotraj podjetja, podjetje znotraj osebe.

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

Popoln klic z Mistral SDK

Tukaj je ista ekstrakcija knjige iz lekcije za Python, prenesena v TypeScript. Pozoren bodi na tri točke. Parameter se imenuje responseFormat (camelCase). Pred uporabo moraš testirati parsed: SDK validira odgovor glede na shemo s safeParse in, če je JSON okrnjen ali se ne ujema s shemo, pusti parsed kot undefined, namesto da bi vrgel napako. Končno, SDK ne ohranja tipa tvoje sheme: parsed deklarira kot unknown. Če objekt prepustiš skozi BookSchema.parse(), postane tipiziran kot Book in se s tem ponovno validira.

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

// 1. Definiraj shemo
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. Ustvari odjemalca
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Pokliči 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. Dostop do razčlenjenega objekta
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Surovi JSON ostane na voljo v message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed je tipiziran kot unknown: BookSchema.parse() vrne tipiziran Book
  return BookSchema.parse(message.parsed);
}

// 5. Uporaba
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();

Opisovanje polj z .describe()

V Zod .describe() opravlja enako vlogo kot Field(description=...) v Pydanticu: modelu pove, kaj naj polje vsebuje, še posebej, ko je samo ime dvoumno. score brez opisa bi lahko pristal na lestvici 0–100; z izrecno navedenim obsegom pa sledi tvoji konvenciji.

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

Obravnava napak

Vzorec ponovnega poskusa sledi isti logiki kot v Pythonu, z generičnim podpisom, ki ga naredi ponovno uporabnega za katero koli shemo. Ni treba loviti ZodError: chat.parse() ga ne vrže; pusti parsed prazno. Ta primer, skupaj z omrežnimi ali HTTP napakami, sproži ponovni poskus. Omejitev z.ZodType<T> poveže shemo, podano kot argument, s povratnim tipom: schema.parse() vrne T, tako da klicatelj dobi pravilno tipiziran objekt brez dodatnih anotacij.

// Nadaljevanje iste datoteke: client, z in BookSchema so že definirani

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

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

Ključne ugotovitve

  • Zod je ekvivalent Pydantic za TypeScript pri prilagojenih strukturiranih izhodih.
  • z.infer<typeof Schema> samodejno generira tip TypeScript.
  • .describe() doda navodila za posamezno polje, podobno kot Field(description=...) v Pythonu.
  • Mistral TypeScript SDK uporablja responseFormat (camelCase) namesto response_format.
  • Neustrezen odgovor pusti parsed kot undefined (brez izjeme): preveri ga in po potrebi poskusi znova.