Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Zod-skeemat TypeScriptissä

Oppitunti 9 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Zod: TypeScriptin vastine Pydanticille
  2. Yksinkertaisen skeeman määrittäminen
  3. Tarvitsemasi tyypit
  4. Sisäkkäiset skeemat
  5. Täydellinen kutsu Mistral SDK:lla
  6. Kenttien kuvaaminen .describe()-metodilla
  7. Virheenkäsittely
  8. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 kääntämisen jälkeen käyttäen @mistralai/mistralai SDK:ta 3.5.0, Zodia 4.6 ja TypeScriptiä 7.0.2. Alkuperäinen esimerkki toi Mistral-luokan oletusarvoisesti, mutta SDK tarjoaa vain nimetyn viennin. Se luki myös response-muuttujaa funktiossa main(), vaikka se oli olemassa vain extractBook()-funktion sisällä. parsed-muuttujan käyttö ei ottanut huomioon, että choices ja message ovat valinnaisia SDK-tyypeissä, ja se käsitteli parsed-muuttujaa tyyppinä Book, vaikka sen todellinen tyyppi on unknown. ZodError-tuonti oli tarpeeton: chat.parse() validoi käyttämällä safeParse-metodia eikä heitä poikkeuksia. API-avainta ei enää kovakoodata. Lähteet: Mistral TypeScript SDK · virallinen chat.parse-esimerkki.

Zod: TypeScriptin vastine Pydanticille

Jos työskentelet TypeScriptillä tai JavaScriptillä, Zod on skeemien validointikirjasto, jota Mistral SDK käyttää mukautettuihin jäsenneltyihin tulosteisiin. Sillä on täsmälleen sama rooli kuin Pydanticilla Pythonissa: määritellään tiukka skeema, jota mallin on noudatettava. Kaikki skeemoista oppimasi pätee myös tähän, eroavaisuudet ovat vain syntaksissa.

Asenna sekä SDK että Zod yhdellä komennolla:

npm install @mistralai/mistralai zod

Zod toimii natiivisti TypeScriptin kanssa ja tarjoaa automaattisen tyypinpäätelyn – tämä on sen suurin etu verrattuna rajapintojen kirjoittamiseen käsin.

Yksinkertaisen skeeman määrittäminen

Rakenna Zod-skeema käyttämällä z.object()-funktiota ja määritä validaattori jokaiselle kentälle. z.infer-rivi tekee eron: se päättelee TypeScript-tyypin suoraan skeemasta, joten sinun ei tarvitse ylläpitää kahta rinnakkaista määrittelyä, jotka voivat ajautua erilleen.

import { z } from "zod";

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

// TypeScript päättelee tyypin automaattisesti
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tarvitsemasi tyypit

Zod kattaa kaikki jäsenneltyjen tulosteiden tarpeet. Alla oleva tukilippuskeema yhdistää yleisiä tapauksia: peruskentät, null-arvon salliva kenttä varaamattomalle lipulle, arvojoukko prioriteetille ja tyypitetyt taulukot.

import { z } from "zod";

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

  // Valinnainen (voi olla null)
  assignee: z.string().nullable(),

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

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

type Ticket = z.infer<typeof TicketSchema>;

Yksi vivahde ansaitsee huomiota: kun Python erottaa toisistaan int ja float, Zod tuntee vain z.number()-tyypin. Pidä tämä vastaavuus mielessäsi, kun siirrät skeemaa kielestä toiseen.

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

Sisäkkäiset skeemat

Kuten Pydanticissa, skeema voi sisältää toisen skeeman: viittaa vain vakioon. Koostaminen etenee sisimmästä uloimpaan: osoite yrityksen sisällä, yritys henkilön sisällä.

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

Täydellinen kutsu Mistral SDK:lla

Tässä on sama kirjan tietojen poiminta kuin Python-tunnilla, mutta portattuna TypeScriptiin. Kolme kohtaa vaatii huomiota. Parametrin nimi on responseFormat camelCase-muodossa. Sinun on testattava parsed-muuttuja ennen käyttöä: SDK validoi vastauksen skeemaa vasten käyttämällä safeParse-metodia, ja jos JSON on typistynyt tai ei täytä skeemaa, parsed jää arvoksi undefined poikkeuksen heittämisen sijaan. Lopuksi SDK ei säilytä skeemasi tyyppiä: se määrittelee parsed-muuttujan tyypiksi unknown. Objektin välittäminen BookSchema.parse()-funktion kautta tyypittää sen Book-tyypiksi ja samalla validoi sen uudelleen.

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

// 1. Määritä skeema
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. Luo asiakas
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Kutsu 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. Käsittele jäsennetty objekti
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Raaka JSON on edelleen saatavilla muodossa message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed on tyypiltään unknown: BookSchema.parse() palauttaa tyypitetyn Book-objektin
  return BookSchema.parse(message.parsed);
}

// 5. Käyttö
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();

Kenttien kuvaaminen .describe()-metodilla

Zodissa .describe() täyttää saman roolin kuin Field(description=...) Pydanticissa: se kertoo mallille, mitä kentän tulisi sisältää, erityisesti kun nimi yksinään on epäselvä. score ilman kuvausta saattaa päätyä 0–100-asteikolle; jos mainitset eksplisiittisen alueen, malli noudattaa sopimaasi käytäntöä.

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

Virheenkäsittely

Yritysmalli seuraa samaa logiikkaa kuin Pythonissa, ja yleinen allekirjoitus tekee siitä uudelleenkäytettävän mille tahansa skeemalle. ZodError-poikkeusta ei tarvitse siepata: chat.parse() ei heitä sellaista, vaan jättää parsed-muuttujan tyhjäksi. Tämä tilanne sekä verkko- tai HTTP-virheet käynnistävät uudelleenyrityksen. Rajoite z.ZodType<T> yhdistää argumenttina annetun skeeman palautustyyppiin: schema.parse() palauttaa tyypin T, joten kutsuja saa oikein tyypitetyn objektin ilman lisämerkintöjä.

// Sama tiedosto jatkuu: client, z ja BookSchema on jo määritelty

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

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

Keskeiset asiat

  • Zod on TypeScriptin vastine Pydanticille mukautetuissa jäsennellyissä tulosteissa
  • z.infer<typeof Schema> generoi TypeScript-tyypin automaattisesti
  • .describe() lisää kenttäkohtaisia ohjeita, kuten Field(description=...) Pythonissa
  • Mistral TypeScript SDK käyttää responseFormat (camelCase) eikä response_format
  • Skeeman vastainen vastaus jättää parsed-muuttujan arvoksi undefined (ei poikkeusta): testaa se ja yritä uudelleen tarvittaessa