✨ ZodGPT

从 OpenAI 和 Anthropic 模型获取结构化、完全类型化的验证过的 JSON 输出。

在底层，zod-gpt 使用函数来强制模型始终以函数调用的形式响应。通过自我反思提高可靠性，并使用 zod 进行解析和类型检查。

• 简介
• 使用方法
  • 安装
  • 请求
  • 自动修复
  • 文本切分
• 调试
• API 参考

👋 简介

ZodGPT 是一个用于以下功能的库：

• 接收具有完整类型安全性的结构化模型输出。所有响应都经过完全验证和类型化，可与 zod（作为 peer dep）一起使用。
• 定义模式、序列化/解析，以及自动要求模型纠正输出。
• 通过 llm-api 尽可能优雅地处理速率限制和其他 API 错误（例如，针对速率限制的指数退避策略）。

使用 zod-gpt，您可以像这样简单地查询 OpenAI 的 ChatGPT 模型：

import { OpenAIChatApi } from 'llm-api';
import { completion } from 'zod-gpt';

const openai = new OpenAIChatApi({ apiKey: 'YOUR_OPENAI_KEY' });

const response = await completion(openai, '生成一个创业想法', {
  schema: z.object({
    name: z.string().describe('创业公司的名称'),
    description: z.string().describe('这家公司是做什么的？'),
  }),
});

// data 将被类型化为 { name: string; description: string }
console.log(response.data);

Anthropic 也可以通过 llm-api 支持：

import { AnthropicChatApi } from 'llm-api';
import { completion } from 'zod-gpt';

const client = new AnthropicChatApi({ apiKey: 'YOUR_ANTHROPIC_KEY' });
const response = await completion(client, ...);

🔨 使用方法

安装

此包托管在 npm 上：

npm i zod-gpt

yarn add zod-gpt

要在您的代码库中设置，请通过 llm-api peer dep 初始化您想要使用的模型的新实例。请注意，zod-gpt 旨在与任何实现 CompletionApi 接口的模型一起工作，因此您也可以导入自己的 API 包装器。

import { OpenAIChatApi } from 'llm-api';

const openai = new OpenAIChatApi(
  { apiKey: 'YOUR_OPENAI_KEY' },
  { model: 'gpt-4-0613' },
);

请求

要使用给定的模型发送标准完成请求，只需调用 completion 方法。

const response = await completion(openai, 'hello');

// data 将被类型化为 string
console.log(response.data);

要添加模式解析和类型化，只需在选项参数中添加 schema 键。请务必通过 describe 方法为每个键添加描述。 这些描述将被输入到模型中，以确保它准确理解每个键所需的数据。尽量多加描述，以确保模型能够完全理解。

const response = await completion(
  openai,
  '生成一个关于如何举办黑客马拉松的分步计划',
  {
    schema: z.object({
      plan: z.array(
        z.object({
          reason: z.string().describe('这一步的理由'),
          id: z.string().describe('唯一的步骤 ID'),
          task: z
            .string()
            .describe('这一步需要完成的任务是什么？'),
        }),
      ),
    }),
  },
);

// data 将被类型化为 { plan: { reason: string; id: string; task: string }[] }
console.info('响应:', response.data);

注意：schema 键仅接受对象类型的模式——这是 functions API 的限制。如果您需要生成数组或其他类型的响应，只需像上述示例一样将其包装在对象中。

🧑‍⚕️ 自动修复

默认情况下，zod-gpt 具有通过自我反思自动检测和修复任何模式错误的逻辑（例如，如果函数 API 使用不正确，如果模式存在解析错误等）。这意味着每当发生这些类型的错误时，zod-gpt 都会发送一条新消息，重新要求模型纠正其自身输出，并附上从解析中收集到的所有错误信息。

这种逻辑简单但非常强大，为模型输出增加了一层可靠性。建议将此标志保持为 true（默认设置），除非令牌使用量或响应时间成为真正的问题。

📃 文本切分

处理令牌限制问题的一种常见方法是分割内容。zod-gpt 提供了 autoSlice 选项，当检测到来自 llm-api 的令牌溢出错误时，会自动分割您的文本。它足够智能，只有在确定文本超过令牌限制时才会进行分割，并会尽可能保留原始文本的内容。

const openai = new OpenAIChatApi(
  { apiKey: 'YOUR_OPENAI_KEY' },
  // 确保设置 contextSize 以启用 TokenErrors 抛出
  { model: 'gpt-4-0613', contextSize: 8129 },
);

const response = await completion(
  openai,
  'hello world, 测试溢出逻辑',
  { autoSlice: true },
);

🤓 调试

zod-gpt 使用 debug 模块进行日志记录和错误消息输出。要在调试模式下运行，请设置 DEBUG 环境变量：

DEBUG=zod-gpt:* yarn playground

您还可以通过以下方式指定不同的日志记录类型：

DEBUG=zod-gpt:error yarn playground DEBUG=zod-gpt:log yarn playground

✅ API 参考

大模型提供商支持

zod-gpt 当前使用 llm-api 库来支持多个大模型提供商。请查阅 llm-api 的文档，了解如何配置模型参数。

补全请求

要向模型发送补全请求，可以这样做：

const res: Response = await completion(model, prompt, options: RequestOptions);

options 您可以通过此参数覆盖默认的请求选项。RequestOptions 对象扩展了 llm-api 中定义的请求选项。

type RequestOptions = {
  // 设置 Zod 模式以启用 JSON 输出
  schema?: T;

  // 启用自动按 token 溢出切分 prompt 的功能。prompt 将从最后一个字符开始切分
  // 默认：false
  autoSlice?: boolean;

  // 尝试通过自省机制自动修复输出
  // 默认：true
  autoHeal?: boolean;

  // 设置消息历史，如果您想继续现有的对话，这将非常有用
  messageHistory?: ChatRequestMessage[];

  // 因限流或可恢复的 API 错误而重试此请求的次数
  // 默认：3
  retries?: number;
  // 默认：30 秒
  retryInterval?: number;
  // 默认：60 秒
  timeout?: number;

  // 为响应分配的最小 token 数量。如果预测请求所需的 token 不足，将自动抛出 'TokenError' 而不会发送请求。
  // 默认：200
  minimumResponseTokens?: number;
};

响应

补全响应扩展了 llm-api 中的模型响应，特别添加了一个 data 字段，用于存储已解析的 JSON 数据，并根据传入的 Zod 模式自动进行类型推断和转换。

interface Response<T extends z.ZodType> {
  // 从模型中解析并类型转换后的数据
  data: z.infer<T>;

  // 来自补全 API 的原始响应
  content?: string;
  name?: string;
  arguments?: JsonValue;
  usage?: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
}

其他

文本分割

如果您需要在调用大模型之前将长文本拆分为多个块，text-spitter.ts 中也导出了几种文本分割器。除非有特殊原因，否则建议优先使用 RecursiveTextSplitter，因为它是最常用的文本分割器。

ZodGPT 快速上手指南

ZodGPT 是一个用于从 OpenAI 和 Anthropic 等大模型获取结构化、完全类型化且经过验证的 JSON 输出的 TypeScript 库。它利用 Zod 进行模式定义与解析，并具备自动修复输出错误的能力。

环境准备

• 运行时环境: Node.js (推荐 v16+)
• 包管理器: npm, yarn 或 pnpm
• 前置依赖:
  • zod: 用于定义数据模式（作为 peer dependency）。
  • llm-api: 用于连接不同的 LLM 提供商（如 OpenAI, Anthropic）。
• API Key: 需要准备好 OpenAI 或 Anthropic 的 API Key。

国内开发者提示：如果访问 npm 官方源较慢，建议使用国内镜像源加速安装。

# 临时使用淘宝镜像
npm config set registry https://registry.npmmirror.com

安装步骤

在项目目录中执行以下命令安装核心库及依赖：

npm i zod-gpt zod llm-api

或使用 yarn：

yarn add zod-gpt zod llm-api

基本使用

1. 初始化客户端

首先，通过 llm-api 初始化你的模型客户端。

import { OpenAIChatApi } from 'llm-api';
import { completion } from 'zod-gpt';
import { z } from 'zod';

const openai = new OpenAIChatApi(
  { apiKey: 'YOUR_OPENAI_KEY' },
  { model: 'gpt-4-0613' },
);

2. 发送带模式的请求

定义一个 Zod schema 来指定期望的输出结构。注意：务必使用 .describe() 为每个字段添加详细描述，这将帮助模型准确理解所需数据。

const response = await completion(
  openai,
  'Generate a step by step plan on how to run a hackathon',
  {
    schema: z.object({
      plan: z.array(
        z.object({
          reason: z.string().describe('Name the reasoning for this step'),
          id: z.string().describe('Unique step id'),
          task: z
            .string()
            .describe('What is the task to be done for this step?'),
        }),
      ),
    }),
  },
);

// response.data 已被自动推断类型：{ plan: { reason: string; id: string; task: string }[] }
console.info('Response:', response.data);

3. 核心特性说明

• 自动修复 (Auto Healing): 默认开启 (autoHeal: true)。如果模型返回的数据不符合 Schema，ZodGPT 会自动将错误信息反馈给模型并要求其重新生成，无需手动干预。
• 文本切片 (Text Slicing): 若输入内容过长导致 Token 溢出，可设置 autoSlice: true 自动分割文本。需确保初始化 OpenAIChatApi 时设置了 contextSize。
• 类型安全: 返回的 response.data 会根据你定义的 Zod schema 自动获得完整的 TypeScript 类型支持。

注意: schema 选项仅接受对象类型 (z.object)。如果需要返回数组或其他类型，请将其包裹在一个对象中（如上例所示）。