Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Scéamaí Zod i TypeScript

Ceacht 9 as 12 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Zod: An Coibhéis TypeScript do Pydantic
  2. Scéama Simplí a Shainiú
  3. Cineálacha a Bheidh Ag Teastáil Uait
  4. Scéamaí Neadaigh
  5. Glao Iomlán leis an Mistral SDK
  6. Réimsí a Chur Síos le .describe()
  7. Láimhseáil Earráidí
  8. Príomhphointí

Nuashonraithe an 3 Samhain, 2026 tar éis tiomsú le SDK @mistralai/mistralai 3.5.0, Zod 4.6, agus TypeScript 7.0.2. D’iompórtáil an sampla bunaidh Mistral go réamhshocraithe, ach ní thairgeann an SDK ach onnmhairiú ainmnithe. Léigh sé athróg response i main() nach raibh ann ach laistigh de extractBook(). Rinne rochtain ar parsed neamhaird ar an bhfíric go bhfuil choices agus message roghnach i gcineálacha an SDK, agus thug sé ar parsed mar Book nuair is é unknown a chineál i ndáiríre. Ní raibh gá le hiompórtáil ZodError: déanann chat.parse() bailíochtú le safeParse agus ní chaitheann sé eisceacht riamh. Níl an eochair API crua-chódaithe a thuilleadh. Foinse: Mistral TypeScript SDK · sampla oifigiúil chat.parse.

Zod: An Coibhéis TypeScript do Pydantic

Má oibríonn tú i TypeScript nó JavaScript, is é Zod an leabharlann bailíochtaithe scéama a úsáideann an Mistral SDK d’Aschuir Struchtúrtha Saincheaptha. Imríonn sé an ról céanna go díreach agus a imríonn Pydantic i bPython: scéama dian a shainiú ar cheart don mhúnla cloí leis. Baineann gach rud a d’fhoghlaim tú faoi scéamaí anseo, gan ach difríochtaí comhréire.

Suiteáil an SDK agus Zod araon in ordú amháin:

npm install @mistralai/mistralai zod

Oibríonn Zod go dúchasach le TypeScript agus soláthraíonn sé tuiscint chineáil uathoibríoch—sin é a phríomhbhuntáiste thar chomhéadain a scríobh de láimh.

Scéama Simplí a Shainiú

Tóg scéama Zod le z.object(), agus sann bailíochtóir do gach réimse. Is é an líne z.infer a dhéanann an difríocht: díorthaíonn sé an cineál TypeScript ón scéama, ionas nach gcaithfidh tú dhá dhearadh chomhthreomhara a chothabháil a d’fhéadfadh imeacht ó chéile.

import { z } from "zod";

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

// Tuigeann TypeScript an cineál go huathoibríoch
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Cineálacha a Bheidh Ag Teastáil Uait

Clúdaíonn Zod gach riachtanas d’aschuir struchtúrtha. Tugann an scéama ticéid thíos le chéile cásanna coitianta: réimsí bunúsacha, réimse inbhainte do thicéad gan sannadh, áireamh do thosaíocht, agus eagair chineálaithe.

import { z } from "zod";

const TicketSchema = z.object({
  // Cineálacha bunúsacha
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Roghnach (féadfaidh sé a bheith null)
  assignee: z.string().nullable(),

  // Áireamh (luachanna srianta)
  priority: z.enum(["low", "medium", "high", "critical"]),

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

type Ticket = z.infer<typeof TicketSchema>;

Tá nuansa amháin ar chóir aird a thabhairt air: cé go ndéanann Python idirdhealú idir int agus float, níl a fhios ag Zod ach z.number(). Coinnigh an mapáil seo i gcuimhne agus tú ag portáil scéama ó theanga amháin go teanga eile.

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

Scéamaí Neadaigh

Mar atá le Pydantic, is féidir le scéama ceann eile a bheith ann: ní gá ach tagairt a dhéanamh don tairiseach. Ansin léann an comhdhéanamh ón gceann is faide isteach go dtí an ceann is faide amuigh: an seoladh laistigh den chuideachta, an chuideachta laistigh den duine.

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

Glao Iomlán leis an Mistral SDK

Seo an t-aistriúchán leabhair céanna ón gceacht Python, portáilte go TypeScript. Tá trí phointe ar chóir aird a thabhairt orthu. Is é responseFormat an paraiméadar i camelCase. Caithfidh tú parsed a thástáil sula n-úsáideann tú é: déanann an SDK bailíochtú ar an bhfreagra i gcoinne an scéama le safeParse agus, má tá an JSON gearrtha nó mura meaitseálann sé an scéama, fágann sé parsed mar undefined in ionad eisceacht a chaitheamh. Ar deireadh, ní iompraíonn an SDK cineál do scéama: dearbhann sé parsed mar unknown. Má chuireann tú an oibiacht trí BookSchema.parse(), déantar é a chineálú mar Book agus déantar é a athbhailíochtú sa phróiseas.

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

// 1. Sainigh an scéama
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. Cruthaigh an cliant
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Glaoigh ar 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. Faigh rochtain ar an oibiacht pharsáilte
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // Tá an JSON amh ar fáil fós i message.content
  console.log(`Raw JSON: ${message.content}`);
  // Tá parsed cineálaithe mar unknown: filleann BookSchema.parse() Book cineálaithe
  return BookSchema.parse(message.parsed);
}

// 5. Úsáid
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();

Réimsí a Chur Síos le .describe()

I Zod, líonann .describe() an ról céanna agus a líonann Field(description=...) i bPython: insíonn sé don mhúnla cad ba chóir a bheith sa réimse, go háirithe nuair atá an t-ainm féin débhríoch. D’fhéadfadh score gan cur síos titim ar scála 0–100; le raon sainráite luaite, leanfaidh sé do choinbhinsiún.

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

Láimhseáil Earráidí

Leanann an patrún athiarrtha an loighic chéanna agus atá i bPython, le síniú ginearálta a dhéanann in-athúsáidte é do gach scéama. Níl aon ghá le ZodError a ghabháil: ní chaitheann chat.parse() ceann ar bith; fágann sé parsed folamh. Spreagann an cás sin, mar aon le hearráidí líonra nó HTTP, athiarracht. Nascann an srian z.ZodType<T> an scéama a tharchuirtear mar argóint leis an gcineál fillte: filleann schema.parse() T, mar sin faigheann an glaoiteoir oibiacht chineálaithe i gceart gan nótaí breise.

// Leanúint den chomhad céanna: tá client, z, agus BookSchema sainithe cheana

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

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

Príomhphointí

  • Is é Zod an coibhéis TypeScript do Pydantic d’Aschuir Struchtúrtha Saincheaptha
  • Gineann z.infer<typeof Schema> an cineál TypeScript go huathoibríoch
  • Cuireann .describe() treoracha in aghaidh an réimse leis, cosúil le Field(description=...) i bPython
  • Úsáideann an Mistral TypeScript SDK responseFormat (camelCase) in ionad response_format
  • Fágann freagra nach bhfuil comhlíontach parsed mar undefined (gan eisceacht): déan tástáil air, agus déan athiarracht más gá