Премини към основното съдържание
Български— Изберете език
Меню

Zod с JavaScript

Урок 7 от 12 Обновен 30 юли 2026 г. Програмист
На тази страница
  1. Структурирани изходи в JavaScript
  2. Инсталация
  3. Конфигурация на клиента
  4. Дефиниране на схема със Zod
  5. Съпоставка на типовете
  6. Пълен пример
  7. Вложени схеми
  8. Незадължителни полета с nullable
  9. Валидиране на страната на клиента
  10. Ключови изводи

Структурирани изходи в JavaScript

Ако разработвате с JavaScript или TypeScript, Zod е еквивалентът на Pydantic. Тази библиотека за валидиране на схеми се интегрира безпроблемно с Grok API, за да генерира типизирани структурирани изходи.

Инсталация

npm install zod openai

OpenAI SDK за JavaScript работи директно с Grok API – просто трябва да го насочите към правилния крайна точка (endpoint).

Конфигурация на клиента

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-xai-key",
  baseURL: "https://api.x.ai/v1"
});

Дефиниране на схема със Zod

Zod използва fluent API за дефиниране на схеми. Всеки метод съответства на JSON тип:

import { z } from "zod";

const MovieReview = z.object({
  title: z.string(),
  rating: z.number(),
  summary: z.string(),
  recommend: z.boolean()
});

Съпоставка на типовете

ZodJSON SchemaPydantic (Python)
z.string()"type": "string"str
z.number()"type": "number"float
z.boolean()"type": "boolean"bool
z.array(z.string())array от низовеlist[str]
z.object({...})"type": "object"BaseModel
z.enum([...])enumLiteral[...]
z.union([...])anyOfUnion типове
z.nullable()anyOf с nullstr | None

Пълен пример

import OpenAI from "openai";
import { z } from "zod";

const client = new OpenAI({
  apiKey: "your-xai-key",
  baseURL: "https://api.x.ai/v1"
});

const Analyse = z.object({
  titre: z.string(),
  resume: z.string(),
  sentiment: z.enum(["positif", "negatif", "neutre"]),
  score: z.number(),
  mots_cles: z.array(z.string()),
  recommandation: z.boolean()
});

const response = await client.chat.completions.create({
  model: "grok-4.20-0309-reasoning",
  messages: [{
    role: "user",
    content: "Analyze the following text: Sales increased by 25% this quarter."
  }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "analyse",
      schema: Analyse
    }
  }
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data.sentiment);  // "positive"
console.log(data.score);      // 0.92

Вложени схеми

Подобно на Pydantic, Zod обработва влагането естествено:

const Adresse = z.object({
  rue: z.string(),
  ville: z.string(),
  code_postal: z.string(),
  pays: z.string()
});

const Contact = z.object({
  nom: z.string(),
  email: z.string(),
  telephone: z.string().nullable(),
  adresse: Adresse,
  tags: z.array(z.string())
});

Незадължителни полета с nullable

За да направите едно поле незадължително (способно да бъде null), използвайте .nullable():

const Produit = z.object({
  nom: z.string(),
  prix: z.number(),
  description: z.string().nullable(),
  promotion: z.number().nullable()
});

Валидиране на страната на клиента

Едно предимство на Zod е, че можете да валидирате данни на страната на клиента, използвайки същата схема:

const rawData = JSON.parse(response.choices[0].message.content);

// Валидиране със Zod
const result = Analyse.safeParse(rawData);

if (result.success) {
  console.log(result.data.titre);
} else {
  console.error("Validation error:", result.error);
}

На практика валидирането винаги ще успее, тъй като API гарантира съответствие със схемата. Въпреки това, този допълнителен слой е полезен за осигуряване на надеждност в производствена среда.

Ключови изводи

  • Zod е JavaScript/TypeScript еквивалентът на Pydantic
  • Синтаксисът е fluent: z.string(), z.number(), z.object({...})
  • .nullable() прави полето незадължително (може да бъде null)
  • Предавайте Zod схеми в response_format.json_schema.schema
  • safeParse() позволява защитно валидиране на страната на клиента
  • OpenAI SDK за JavaScript работи директно с Grok API