Σχήματα Zod σε TypeScript
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026 μετά από compilation με το SDK
@mistralai/mistralai3.5.0, Zod 4.6 και TypeScript 7.0.2. Το αρχικό παράδειγμα εισήγαγε τοMistralως προεπιλογή, αλλά το SDK προσφέρει μόνο μια ονομαζόμενη εξαγωγή (named export). Επίσης, διάβαζε μια μεταβλητήresponseστηνmain()που υπήρχε μόνο μέσα στηνextractBook(). Η πρόσβαση στοparsedαγνοούσε το γεγονός ότι ταchoicesκαιmessageείναι προαιρετικά στους τύπους του SDK, και αντιμετώπιζε τοparsedωςBookόταν ο τύπος του είναι στην πραγματικότηταunknown. Η εισαγωγή τουZodErrorήταν περιττή: τοchat.parse()επικυρώνει μεsafeParseκαι δεν ρίχνει ποτέ σφάλμα. Το κλειδί API δεν είναι πλέον σκληρά κωδικοποιημένο. Πηγές: Mistral TypeScript SDK · επίσημο παράδειγμαchat.parse.
Zod: Το ισοδύναμο του Pydantic σε TypeScript
Αν εργάζεστε σε TypeScript ή JavaScript, το Zod είναι η βιβλιοθήκη επικύρωσης σχημάτων που χρησιμοποιείται από το SDK της Mistral για Προσαρμοσμένες Δομημένες Εξόδους (Custom Structured Outputs). Παίζει ακριβώς τον ίδιο ρόλο με το 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 καλύπτει κάθε ανάγκη για δομημένες εξόδους. Το παρακάτω σχήμα εισιτηρίου (ticket) συνδυάζει κοινές περιπτώσεις: βασικά πεδία, ένα πεδίο που μπορεί να είναι null για ένα μη ανατεθειμένο εισιτήριο, ένα enum για την προτεραιότητα και typed arrays.
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) |
|---|---|
str | z.string() |
int, float | z.number() |
bool | z.boolean() |
list[str] | z.array(z.string()) |
Optional[str] | z.string().nullable() |
Enum | z.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() το κάνει typed ως 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. Δημιουργία του client
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. Πρόσβαση στο parsed αντικείμενο
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 είναι typed ως unknown: το BookSchema.parse() επιστρέφει ένα typed 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"
),
});
Διαχείριση Σφαλμάτων
Το μοτίβο επανάληψης (retry) ακολουθεί την ίδια λογική με την Python, με μια γενική υπογραφή που το καθιστά επαναχρησιμοποιήσιμο για οποιοδήποτε σχήμα. Δεν υπάρχει ανάγκη να πιάσετε ένα ZodError: το chat.parse() δεν ρίχνει ένα τέτοιο σφάλμα· αφήνει το parsed κενό. Αυτή η περίπτωση, μαζί με σφάλματα δικτύου ή HTTP, ενεργοποιεί μια επανάληψη. Ο περιορισμός z.ZodType<T> συνδέει το σχήμα που περνιέται ως όρισμα με τον τύπο επιστροφής: το schema.parse() επιστρέφει ένα T, οπότε ο καλών λαμβάνει ένα σωστά typed αντικείμενο χωρίς επιπλέον σημειώσεις.
// Συνέχεια του ίδιου αρχείου: τα 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 είναι το ισοδύναμο του Pydantic σε TypeScript για Προσαρμοσμένες Δομημένες Εξόδους
- Το
z.infer<typeof Schema>δημιουργεί αυτόματα τον τύπο TypeScript - Το
.describe()προσθέτει οδηγίες ανά πεδίο, όπως τοField(description=...)στην Python - Το Mistral TypeScript SDK χρησιμοποιεί το
responseFormat(camelCase) αντί γιαresponse_format - Μια μη συμμορφούμενη απόκριση αφήνει το
parsedωςundefined(χωρίς εξαίρεση): ελέγξτε το και κάντε επανάληψη αν χρειάζεται