instructor-js

基于 TypeScript 的结构化提取，由大语言模型驱动，旨在实现简单、透明和可控。

---

深入了解基于 TypeScript 的结构化提取，借助 OpenAI 的函数调用 API 和 Zod，以 TypeScript 优先的模式进行类型验证并支持静态类型推断。Instructor 因其简单性、透明性和以用户为中心的设计而脱颖而出。无论您是经验丰富的开发者还是刚刚入门，都会发现 Instructor 的方法直观且易于掌控。

安装

bun add @instructor-ai/instructor zod openai

npm i @instructor-ai/instructor zod openai

pnpm add @instructor-ai/instructor zod openai

基本用法

要了解提示和提取数据的所有技巧与窍门，请查看文档。

import Instructor from "@instructor-ai/instructor";
import OpenAI from "openai"
import { z } from "zod"

const oai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY ?? undefined,
  organization: process.env.OPENAI_ORG_ID ?? undefined
})

const client = Instructor({
  client: oai,
  mode: "TOOLS"
})

const UserSchema = z.object({
  // 描述将用于提示中
  age: z.number().describe("用户的年龄"), 
  name: z.string()
})


// 用户将属于 z.infer<typeof UserSchema> 类型
const user = await client.chat.completions.create({
  messages: [{ role: "user", content: "Jason Liu 是 30 岁" }],
  model: "gpt-3.5-turbo",
  response_model: { 
    schema: UserSchema, 
    name: "User"
  }
})

console.log(user)
// { age: 30, name: "Jason Liu" }

API 参考

Instructor 类

创建 Instructor 客户端的主要类。

createInstructor

function createInstructor<C extends GenericClient | OpenAI>(args: {
  client: OpenAILikeClient<C>;
  mode: Mode;
  debug?: boolean;
}): InstructorClient<C>

创建 Instructor 类的实例。

• client: 类似 OpenAI 的客户端。
• mode: 运行模式。
• debug: 是否记录调试信息。

返回扩展后的 OpenAI 类似客户端。

chat.completions.create

chat.completions.create<
        T extends z.AnyZodObject,
        P extends T extends z.AnyZodObject ? ChatCompletionCreateParamsWithModel<T>
        : ClientTypeChatCompletionParams<OpenAILikeClient<C>> & { response_model: never }
      >(
        params: P
      ): Promise<ReturnTypeBasedOnParams<typeof this.client, P>>

当 params 中存在 response_model 时，根据提供的模式生成结构化提取的聊天完成；否则将代理回提供的客户端。

• params: 包括响应模式模式的聊天完成参数。
• 返回一个解析为根据模式提取的数据的 Promise。

模式

Instructor 支持不同的模式来定义语言模型响应的结构和格式。这些模式在 zod-stream 包中定义，具体如下：

• FUNCTIONS（已弃用）：使用 OpenAI 的函数调用 API 生成响应。它映射到函数调用 API 所需的参数，包括 function_call 和 functions 属性。

• TOOLS：使用 OpenAI 的工具规范生成响应。它构建了工具规范所需的参数，包括 tool_choice 和 tools 属性。

• JSON：将 response_format 设置为 json_object，并在系统消息中包含 JSON 模式以指导响应生成。（Together & Anyscale）

• MD_JSON：生成嵌入在 Markdown 代码块中的 JSON 格式响应。它在系统消息中包含 JSON 模式，并期望响应是一个有效的 JSON 对象，包裹在 Markdown 代码块中。

• JSON_SCHEMA：使用“JSON 模式”生成符合所提供 JSON 模式的响应。它将 response_format 设置为 json_object 并包含所提供的模式，同时在系统消息中包含模式描述。

示例

流式完成

Instructor 支持部分流式完成，允许您在模型生成响应时实时接收提取的数据。这有助于提供更富交互性的用户体验，或以增量方式处理大量数据。

import Instructor from "@instructor-ai/instructor"
import OpenAI from "openai"
import { z } from "zod"

const textBlock = `
  在我们最近的线上会议中，来自不同背景的参会者齐聚一堂，共同探讨即将召开的技术大会。 
  参会者的姓名和联系方式如下：

  - 姓名：John Doe，邮箱：johndoe@email.com，Twitter：@TechGuru44
  - 姓名：Jane Smith，邮箱：janesmith@email.com，Twitter：@DigitalDiva88
  - 姓名：Alex Johnson，邮箱：alexj@email.com，Twitter：@CodeMaster2023

  会议期间，我们达成了若干关键共识。大会将于2024年3月15日在位于创新大道4521号的盛大科技竞技场举行。著名人工智能研究员艾米丽·约翰逊博士将担任我们的主旨演讲嘉宾。本次活动的预算定为5万美元，涵盖场地费用、演讲嘉宾酬金及推广活动等开支。

  每位参会者需在2月20日前向大会博客提交一篇文章。后续会议定于1月25日下午3点（GMT）召开，以敲定会议议程并确认演讲嘉宾名单。
`

async function extractData() {
  const ExtractionSchema = z.object({
    users: z.array(
      z.object({
        name: z.string(),
        handle: z.string(),
        twitter: z.string()
      })
    ).min(3),
    location: z.string(),
    budget: z.number()
  })

  const oai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY ?? undefined,
    organization: process.env.OPENAI_ORG_ID ?? undefined
  })

  const client = Instructor({
    client: oai,
    mode: "TOOLS"
  })

  const extractionStream = await client.chat.completions.create({
    messages: [{ role: "user", content: textBlock }],
    model: "gpt-3.5-turbo",
    response_model: {
      schema: ExtractionSchema,
      name: "Extraction"
    },
    max_retries: 3,
    stream: true
  })

  let extractedData = {}
  for await (const result of extractionStream) {
    extractedData = result
    console.log("部分提取结果:", result)
  }
  
  console.log("最终提取结果:", extractedData)
}

extractData()

在本示例中，我们使用 Zod 定义了一个 ExtractionSchema，用于指定我们要提取的数据结构。然后，我们创建了一个启用了流式处理的 Instructor 客户端，并将该模式传递给 response_model 参数。

extractionStream 变量保存了一个异步生成器，当部分提取结果可用时，它会逐个返回这些结果。我们通过 for await...of 循环遍历这个流，每次获取一个部分结果后更新 extractedData 对象，并将其打印到控制台。

最后，当流处理完毕后，我们打印出完整的提取数据。

通过代理使用不同提供商

Instructor 支持多种符合 OpenAI API 规范的提供商。您只需配置相应的客户端，并指定所需的模型和模式，即可轻松切换不同的提供商。

Anyscale

import Instructor from "@instructor-ai/instructor"
import OpenAI from "openai"
import { z } from "zod"

const UserSchema = z.object({
  age: z.number(),
  name: z.string().refine(name => name.includes(" "), {
    message: "姓名必须包含空格"
  })
})

async function extractUser() {
  const client = new OpenAI({
    baseURL: "https://api.endpoints.anyscale.com/v1",
    apiKey: process.env.ANYSCALE_API_KEY
  })

  const instructor = Instructor({
    client: client,
    mode: "TOOLS"
  })

  const user = await instructor.chat.completions.create({
    messages: [{ role: "user", content: "Jason Liu 是30岁" }],
    model: "mistralai/Mixtral-8x7B-Instruct-v0.1",
    response_model: {
      schema: UserSchema,
      name: "User"
    },
    max_retries: 4
  })

  return user
}

const anyscaleUser = await extractUser()
console.log("Anyscale 用户:", anyscaleUser)

Together

import Instructor from "@instructor-ai/instructor"
import OpenAI from "openai"
import { z } from "zod"

const UserSchema = z.object({
  age: z.number(),
  name: z.string().refine(name => name.includes(" "), {
    message: "姓名必须包含空格"
  })
})

async function extractUser() {
  const client = new OpenAI({
    baseURL: "https://api.together.xyz/v1",
    apiKey: process.env.TOGETHER_API_KEY
  })

  const instructor = Instructor({
    client: client,
    mode: "TOOLS"
  })

  const user = await instructor.chat.completions.create({
    messages: [{ role: "user", content: "Jason Liu 是30岁" }],
    model: "mistralai/Mixtral-8x7B-Instruct-v0.1",
    response_model: {
      schema: UserSchema,
      name: "User"
    },
    max_retries: 4
  })

  return user
}

const togetherUser = await extractUser()
console.log("Together 用户:", togetherUser)

在这些示例中，我们指定了 Anyscale 和 Together 的特定基础 URL 和 API 密钥。

extractUser 函数接受模型、模式和提供商作为参数。它会获取对应的提供商配置，创建 OpenAI 客户端，并用指定模式初始化 Instructor 实例。

随后，我们调用 instructor.chat.completions.create 方法，传入所需的模型、响应模式及其他参数，以提取用户信息。

通过在调用 extractUser 时改变提供商、模型和模式参数，您可以轻松地在不同提供商和配置之间切换。

使用 llm-polyglot 与非 OpenAI 提供商

Instructor 支持通过 @dimitrikennedy 维护的 llm-polyglot 库，与不遵循 OpenAI SDK 的提供商集成，例如 Anthropic、Azure 和 Cohere。该库提供了一个统一的接口，用于与不同提供商的各种语言模型交互。

import { createLLMClient } from "llm-polyglot"
import Instructor from "@instructor-ai/instructor"
import { z } from "zod"

const anthropicClient = createLLMClient({
  provider: "anthropic",
  apiKey: process.env.ANTHROPIC_API_KEY
})

const UserSchema = z.object({
  age: z.number(),
  name: z.string()
})

const instructor = Instructor<typeof anthropicClient>({
  client: anthropicClient,
  mode: "TOOLS"
})

async function extractUser() {
  const user = await instructor.chat.completions.create({
    model: "claude-3-opus-20240229",
    max_tokens: 1000,
    messages: [
      {
        role: "user",
        content: "我的名字是迪米特里·肯尼迪。"
      }
    ],
    response_model: {
      name: "extract_name",
      schema: UserSchema
    }
  })

  return user
}

// 示例用法
const extractedUser = await extractUser()
console.log("提取的用户:", extractedUser)

在本示例中，我们使用 llm-polyglot 库中的 createLLMClient 函数为 Anthropic 提供商创建了一个客户端。我们将提供商名称（“anthropic”）和相应的 API 密钥传递给该函数。

接下来，我们使用 Zod 定义了 UserSchema，以指定我们要提取的用户数据的结构。

我们通过将 Anthropic 客户端和所需模式传递给 Instructor 函数来创建一个 Instructor 实例。请注意，我们使用 Instructor 显式指定客户端类型。

extractUser 函数展示了如何使用 Instructor 实例从给定输入中提取用户信息。我们调用 instructor.chat.completions.create，传入适当的模型（本例中为 “claude-3-opus-20240229”）、参数以及包含我们 UserSchema 的 response_model。

最后，我们记录提取的用户信息。

借助 llm-polyglot 库，Instructor 能够无缝集成多种提供商，而不仅限于那些遵循 OpenAI SDK 的提供商。这使您能够充分利用不同提供商提供的独特功能和模型，同时仍受益于 Instructor 的结构化提取和验证功能。

如需更多支持以及有关使用其他提供商与 llm-polyglot 的信息，请参阅该库的文档和示例。

更多示例

如果您想了解更多，请查看我们的食谱。

安装 Instructor 非常简单。

基于 Island AI 构建

Instructor 基于 Island AI 工具包中的多个强大软件包构建，这些软件包由 Dimitri Kennedy 开发并维护。这些软件包提供了处理结构化数据和使用大型语言模型进行流式处理的关键功能。

zod-stream

zod-stream 是一个直接与 LLM 流对接的客户端模块。它利用 Schema-Stream 进行高效解析，并配备了处理 OpenAI 原始响应的工具，按模式（函数、工具、JSON 等）对响应进行分类，同时确保正确的错误处理和流转换。它非常适合用于交付结构化 LLM 响应流的 API 集成。

schema-stream

schema-stream 是一个 JSON 流式解析器，它根据 Zod 模式逐步构建和更新响应模型。它专为实时数据处理和增量模型填充而设计。

llm-polyglot

llm-polyglot 是一个库，提供了一个统一的接口，用于与不同提供商的各种语言模型交互，例如 OpenAI、Anthropic、Azure 和 Cohere。它简化了与多个 LLM 提供商合作的过程，并实现了与 Instructor 的无缝集成。

Instructor 利用了这些 Island AI 软件包的强大功能，为使用 LLM 进行结构化数据提取和流式处理提供了无缝且高效的体验。Dimitri Kennedy（Island AI 的创建者）与 Jason Liu（原始 Instructor Python 包的作者）的合作促成了 Instructor 的 TypeScript 版本的开发，该版本引入了来自 LLM 的部分 JSON 流的概念。

如需了解有关 Island AI 及其软件包的更多信息，请参阅 Island AI 仓库。

为什么使用 Instructor？

使用 Instructor 的问题本质上就是为什么使用 Zod 的问题。

1. 兼容 OpenAI SDK — Instructor 遵循 OpenAI 的 API。这意味着您可以在支持 OpenAI API 的多个提供商之间，对提示和提取使用相同的 API。

2. 可定制性 — Zod 具有高度可定制性。您可以定义自己的验证器、自定义错误消息等。

3. 生态系统 Zod 是 Typescript 中使用最广泛的数据验证库。

4. 久经考验 — Zod 每月下载量超过 2400 万次，并拥有庞大的贡献者社区支持。

贡献

如果您想帮忙，请查看标记为 good-first-issue 或 help-wanted 的一些问题。这些问题位于 这里。它们可以是代码改进、客座博客文章或新的食谱。

请查看贡献指南，了解如何设置环境、测试、变更集和相关规范。

ℹ️ 提示： 支持其他语言

请查看以下其他语言的移植版本：

- [Python](https://www.github.com/jxnl/instructor)
- [Elixir](https://github.com/thmsmlr/instructor_ex/)

如果您想将 Instructor 移植到另一种语言，请在 [Twitter](https://twitter.com/jxnlco) 上联系我们，我们很乐意帮助您入门！

许可证

本项目采用 MIT 许可证条款授权。

instructor-js 中文快速上手指南

环境准备

• 系统要求：Node.js 16+（推荐 18+）
• 前置依赖：
  • OpenAI API 密钥（可从 platform.openai.com 获取）
  • 可选：支持 OpenAI API 的国内代理（如 https://api.openai.com.cn）用于加速访问

安装步骤

使用任意包管理器安装依赖：

bun add @instructor-ai/instructor zod openai

npm i @instructor-ai/instructor zod openai

pnpm add @instructor-ai/instructor zod openai

✅ 推荐使用 pnpm 或 bun 以获得更快的安装速度和更小的 node_modules。

基本使用

import Instructor from "@instructor-ai/instructor";
import OpenAI from "openai";
import { z } from "zod";

const oai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY ?? undefined,
  organization: process.env.OPENAI_ORG_ID ?? undefined
});

const client = Instructor({
  client: oai,
  mode: "TOOLS"
});

const UserSchema = z.object({
  age: z.number().describe("用户年龄"),
  name: z.string()
});

const user = await client.chat.completions.create({
  messages: [{ role: "user", content: "张三今年 28 岁" }],
  model: "gpt-3.5-turbo",
  response_model: { 
    schema: UserSchema, 
    name: "User"
  }
});

console.log(user);
// 输出：{ age: 28, name: "张三" }