Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Zod-skemaer i TypeScript

Lektion 9 af 12 Opdateret 3. november 2026 Udvikler
På denne side
  1. Zod: TypeScript-modstykket til Pydantic
  2. Definition af et simpelt skema
  3. Typer, du får brug for
  4. Næstede skemaer
  5. Et komplet kald med Mistral SDK’et
  6. Beskrivelse af felter med .describe()
  7. Fejlhåndtering
  8. Vigtige pointer

Opdateret 3. november 2026 efter kompilering med @mistralai/mistralai SDK 3.5.0, Zod 4.6 og TypeScript 7.0.2. Det oprindelige eksempel importerede Mistral som standard, men SDK’et tilbyder kun en navngiven eksport. Det læste også en response-variabel i main(), som kun eksisterede inde i extractBook(). Adgang til parsed ignorerede, at choices og message er valgfrie i SDK-typerne, og det behandlede parsed som en Book, når dens type faktisk er unknown. Importen af ZodError var unødvendig: chat.parse() validerer med safeParse og kaster aldrig en fejl. API-nøglen er ikke længere hardcodet. Kilder: Mistral TypeScript SDK · officielt chat.parse-eksempel.

Zod: TypeScript-modstykket til Pydantic

Hvis du arbejder med TypeScript eller JavaScript, er Zod det skemavalideringsbibliotek, som Mistral SDK’et bruger til brugerdefinerede strukturerede output. Det spiller præcis samme rolle som Pydantic i Python: at definere et strengt skema, som modellen skal overholde. Alt, hvad du har lært om skemaer, gælder også her; kun syntaksen er anderledes.

Installér både SDK’et og Zod med én enkelt kommando:

npm install @mistralai/mistralai zod

Zod fungerer nativt med TypeScript og giver automatisk typeudledning – det er dets største fordel frem for at skrive interfaces i hånden.

Definition af et simpelt skema

Byg et Zod-skema med z.object(), og tildel en validator til hvert felt. Linjen med z.infer gør forskellen: den udleder TypeScript-typen direkte fra skemaet, så du slipper for at vedligeholde to parallelle deklarationer, der kunne komme ud af sync.

import { z } from "zod";

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

// TypeScript udleder typen automatisk
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Typer, du får brug for

Zod dækker alle behov for strukturerede output. Skemaet til sagsbehandling nedenfor samler常见的 tilfælde: basale felter, et nullable felt til en ikke-tildelt sag, en enum til prioritet og typede arrays.

import { z } from "zod";

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

  // Valgfrit (kan være null)
  assignee: z.string().nullable(),

  // Enum (begrænsede værdier)
  priority: z.enum(["low", "medium", "high", "critical"]),

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

type Ticket = z.infer<typeof TicketSchema>;

Én nuance fortjener opmærksomhed: Hvor Python skelner mellem int og float, kender Zod kun z.number(). Husk denne mapping, når du porterer et skema fra det ene sprog til det andet.

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

Næstede skemaer

Ligesom med Pydantic kan et skema indeholde et andet: du refererer blot til konstanten. Sammensætningen læses derefter indefra og ud: adressen inde i virksomheden, virksomheden inde i personen.

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

Et komplet kald med Mistral SDK’et

Her er den samme bogudtrækning fra Python-lektionen, porteret til TypeScript. Tre punkter kræver opmærksomhed. Parameteren hedder responseFormat i camelCase. Du skal teste parsed, før du bruger den: SDK’et validerer svaret mod skemaet med safeParse, og hvis JSON’en er trunkeret eller ikke matcher skemaet, efterlades parsed som undefined i stedet for at kaste en fejl. Endelig bærer SDK’et ikke din skemas type med sig: det deklarerer parsed som unknown. Ved at sende objektet gennem BookSchema.parse() får det typen Book, og det bliver samtidig genvalideret.

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

// 1. Definer skemaet
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. Opret klienten
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Kald 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. Tilgå det parsede objekt
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Rå JSON er stadig tilgængelig i message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed er typet som unknown: BookSchema.parse() returnerer en typet Book
  return BookSchema.parse(message.parsed);
}

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

Beskrivelse af felter med .describe()

I Zod udfylder .describe() samme rolle som Field(description=...) i Pydantic: det fortæller modellen, hvad feltet skal indeholde, især når navnet alene er tvetydigt. En score uden beskrivelse kunne ende på en skala fra 0–100; med en eksplicit nævnt rækkefølge følger den din konvention.

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

Fejlhåndtering

Retry-mønsteret følger den samme logik som i Python, med en generisk signatur, der gør det genanvendeligt for ethvert skema. Der er ikke behov for at fange en ZodError: chat.parse() kaster ikke en sådan; den efterlader blot parsed tom. Det tilfælde, sammen med netværks- eller HTTP-fejl, udløser et nyt forsøg. Begrænsningen z.ZodType<T> linker skemaet, der sendes som argument, til returtypen: schema.parse() returnerer en T, så kalderen får et korrekt typet objekt uden ekstra annotationer.

// Fortsættelse af samme fil: client, z og BookSchema er allerede defineret

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

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

Vigtige pointer

  • Zod er TypeScript-modstykket til Pydantic for brugerdefinerede strukturerede output
  • z.infer<typeof Schema> genererer automatisk TypeScript-typen
  • .describe() tilføjer instruktioner pr. felt, ligesom Field(description=...) i Python
  • Mistral TypeScript SDK’et bruger responseFormat (camelCase) i stedet for response_format
  • Et svar, der ikke overholder skemaet, efterlader parsed som undefined (ingen undtagelse): test for det, og gentag forsøget om nødvendigt