TypeScript Zod + AI SDK 结构化输出教程：让 AI 返回的数据可以直接用

我第一次用 AI 做项目时，遇到了一个头疼的问题：AI 返回的内容是自由文本，我想提取里面的邮箱、日期、金额，结果要写一堆正则表达式，还动不动就解析失败。后来我学会了 Zod + AI SDK 的结构化输出，就像给 AI 装上了一个"数据模板"，它只返回我想要的数据格式，再也不用担心解析问题了。今天我就手把手教大家，从零开始实现这个功能。

什么是结构化输出？为什么重要？

普通 AI 输出是这样的：

根据您提供的信息，用户张三的邮箱是 [email protected]，注册日期是 2024年1月15日。

结构化输出是这样的：

{
  "name": "张三",
  "email": "[email protected]",
  "registeredDate": "2024-01-15"
}

结构化输出的好处显而易见：可以直接用、不会解析错误、代码更简洁。对于需要从 AI 获取数据的应用来说，这简直是救星。

准备工作：注册 HolySheep AI 获取 API Key

首先你需要一个 API Key。我推荐使用 HolySheep AI，它有三个明显优势：

• 汇率 ¥1=$1 无损（比官方 ¥7.3=$1 节省 85%+）
• 国内直连，延迟 <50ms
• 注册送免费额度，微信/支付宝直接充值

点击注册后，进入控制台 → API Keys → 创建新 Key，复制备用。

项目初始化

（图文提示：打开终端，执行以下命令）

mkdir ai-structured-output
cd ai-structured-output
npm init -y
npm install typescript @types/node ts-node ai @ai-sdk/zod zod

初始化 TypeScript 配置：

npx tsc --init

创建 .env 文件存放你的 API Key：

HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY

写代码：从 Zod schema 开始

我第一次看到 schema 这个词时完全懵了，其实你可以把它理解为"数据模板"。我定义了这个模板，AI 就按这个格式返回数据。

import { z } from 'zod';

// 定义一个用户信息模板
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(), // 必须是邮箱格式
  age: z.number().optional(), // 可选字段
  tags: z.array(z.string())
});

type User = z.infer;

现在用 AI SDK 生成符合这个模板的数据：

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import 'dotenv/config';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().optional(),
  tags: z.array(z.string())
});

async function main() {
  const { object } = await generateText({
    model: openai('gpt-4o'),
    baseURL: 'https://api.holysheep.ai/v1',
    apiKey: process.env.HOLYSHEEP_API_KEY,
    prompt: '生成一个用户信息示例',
    schema: UserSchema,
  });

  console.log('用户数据：', object);
  console.log('姓名：', object.name);
  console.log('邮箱：', object.email);
}

main();

运行后，你会在控制台看到完美结构化的数据，可以直接使用 object.name、object.email，完全不用解析文本。

实战案例：提取简历关键信息

这是我工作中真实用到的场景：从简历文本中提取结构化数据。

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import 'dotenv/config';

// 定义简历解析模板
const ResumeSchema = z.object({
  personalInfo: z.object({
    name: z.string(),
    phone: z.string(),
    email: z.string().email(),
  }),
  education: z.array(z.object({
    school: z.string(),
    degree: z.string(),
    graduationYear: z.number(),
  })),
  skills: z.array(z.string()),
  workExperience: z.array(z.object({
    company: z.string(),
    position: z.string(),
    duration: z.string(),
  })),
  expectedSalary: z.number().optional(),
});

async function extractResume(text: string) {
  const { object } = await generateText({
    model: openai('gpt-4o'),
    baseURL: 'https://api.holysheep.ai/v1',
    apiKey: process.env.HOLYSHEEP_API_KEY,
    prompt: 从以下简历文本中提取结构化信息：\n\n${text},
    schema: ResumeSchema,
  });

  return object;
}

// 使用示例
const resumeText = `
张三，男，28岁，电话13800138000，邮箱[email protected]
毕业于清华大学，计算机科学硕士，2020年毕业
技能：Python、TypeScript、机器学习、React
工作经历：
1. 字节跳动，后端工程师，2020-2023
2. 腾讯，高级工程师，2023至今
期望薪资：50000元/月
`;

extractResume(resumeText).then(result => {
  console.log('姓名：', result.personalInfo.name);
  console.log('邮箱：', result.personalInfo.email);
  console.log('技能列表：', result.skills);
  console.log('工作经历数：', result.workExperience.length);
});

常见报错排查

我刚开始用的时候踩过不少坑，分享给大家：

错误1：No API Key provided

错误信息：Error: No API Key provided. Set HOLYSHEEP_API_KEY in environment.

解决方法：确保 .env 文件存在且包含正确的 Key：

HOLYSHEEP_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

然后在代码开头导入：

import 'dotenv/config';

错误2：Invalid API Key

错误信息：Error: Invalid API key provided

解决方法：这个 Key 不是 HolySheep 的，请确认你使用的是 HolySheep AI 控制台生成的 Key，而不是 OpenAI 或其他平台的。

错误3：Zod validation failed

错误信息：Error: Zod validation failed

解决方法：检查 schema 定义是否合理，特别是字段类型和必填/可选设置：

// 可能的问题：要求邮箱格式但 AI 返回了普通字符串
const UserSchema = z.object({
  email: z.string().email(), // 如果 AI 返回 "zhangsan#email.com" 就会报错
});

// 解决方案：改用宽松模式或让字段可选
const UserSchema = z.object({
  email: z.string(), // 先不要求格式
  age: z.number().optional(), // 可选字段
});

错误4：Request timeout

错误信息：Error: Request timeout

解决方法：网络问题导致，使用 HolySheep AI 国内节点可解决：

const { text } = await generateText({
  model: openai('gpt-4o'),
  baseURL: 'https://api.holysheep.ai/v1', // 国内直连，延迟 <50ms
  apiKey: process.env.HOLYSHEEP_API_KEY,
  prompt: '你的问题',
  maxRetries: 3, // 增加重试次数
  timeout: 60000, // 60秒超时
});

价格对比：为什么用 HolySheep

我做项目时特别关注成本，对比一下主流模型在 HolySheep AI 的 output 价格（$/百万Token）：

• GPT-4.1：$8.00
• Claude Sonnet 4.5：$15.00
• Gemini 2.5 Flash：$2.50
• DeepSeek V3.2：$0.42

如果你用 DeepSeek V3.2 做结构化输出，成本只有 Claude 的 1/36。而且 HolySheep 的汇率 ¥1=$1，比官方 ¥7.3=$1 便宜 85%+。

我的实战经验总结

用了半年结构化输出，我的心得是：

• schema 设计要"刚刚好"，字段太多 AI 容易出错，太少又不够用
• 可选字段尽量用 optional()，避免 AI 因为某个字段"编造"数据
• 复杂结构可以嵌套，但建议不超过 3 层
• 调试时先用简单 schema，成功后再逐步加字段

下一步：流式输出 + 结构化

如果你想实现打字机效果的同时保持结构化，可以用 streamText：

import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-4o'),
  baseURL: 'https://api.holysheep.ai/v1',
  apiKey: process.env.HOLYSHEEP_API_KEY,
  prompt: '生成一个产品信息',
  schema: ProductSchema,
});

// 流式处理每个部分
for await (const part of result.fullStream) {
  console.log(part);
}

结束语

Zod + AI SDK 的结构化输出，是让 AI 应用走向生产级别的关键技术。它让 AI 返回的数据"所见即所得"，再也不用担心解析问题。

建议大家从今天的简单例子开始练习，然后尝试提取简历、分析评论、分类商品等实际场景。

👉 免费注册 HolySheep AI，获取首月赠额度，国内直连低延迟，微信支付宝充值方便，非常适合快速验证你的 AI 想法。