用OpenAI轻松打造一致的结构化投票输出✨

你是否曾经希望只需输入提示词，AI就能为你的团队快速生成一个有趣的投票？系紧安全带！在这篇文章中，我们将深入探讨——结构化输出与OpenAI的领域，并将以独特的方式构建一个投票创建器。

在Kollabe，我们已经集成了这项功能，以帮助团队快速创建吸引人的投票。最棒的是，它的实现比我们预期的要简单得多，接下来我会向大家展示我们是如何实现的。

当你使用AI时，你可能习惯于看到长段落的文字。但如果你需要机器可读的、一致的json数据——比如说，不会让你疑惑“选项A”是不是等于“是”或者“肯定，是”，这时，出现了结构化输出。

这个功能是一项变革，因为它确保了AI的回应将符合你指定的格式。再也不用担心AI会正确格式化内容或编写复杂的解析逻辑——你定义一个格式，OpenAI确保输出完全符合你定义的格式。这不仅简化了后续处理流程，还允许你使用诸如Zod这样的库进行验证和强制执行输出格式。

如果你已经熟悉了如何使用JSON数据与OpenAI合作，你可能在想：“结构化输出格式与OpenAI的JSON模式功能之间有什么区别？”

“结构化输出”是 JSON 模式的演变。虽然两者都确保生成有效的 JSON 数据，但只有“结构化输出”确保遵循模式。

在撰写本文时（2025年2月），以下OpenAI提供的模型提供了结构化数据输出：

• o3-mini-2025年1月31日及以上版本
• o1-2024年12月17日及以上版本
• gpt-4o-mini-2024年7月18日及以上版本
• gpt-4o-2024年8月6日及以上版本

请查阅 OpenAI 的文档获取最新的支持模型列表，因为 OpenAI 会定期更新并添加新的模型。同时确保你能访问这些模型。OpenAI 提供不同的开发者权限等级。

无论你是从团队收集反馈，运行社区调查，还是仅仅为了决定午饭去哪儿吃，一份精心设计的投票问卷都能起到很大的作用。我们的目标很简单：用户提供一个提示（比如“我们每周团队同步的最佳时间是？”），然后AI会提供一个包含清晰简洁问题和吸引人选项的投票。

在有了结构化输出结果之前，实现依赖于希望AI能够正确格式化内容或使用复杂的提示工程。现在，通过结构化输出，我们可以更简洁地编写代码，并让OpenAI处理繁重的事务，同时确保输出完全符合我们的预期结果。

如下是我们的投票生成器使用结构化输出方式的干净、现代且完全使用 TypeScript 的代码。请注意我们是如何定义投票的 JSON 模式来、使用 Zod 来验证响应，然后通过带有 response_format 参数的方式调用 OpenAI API 的。

    import type OpenAI from "openai";
    import type { ChatCompletionCreateParamsBase } from "openai/resources/chat/completions";
    import { z } from "zod";

    import { languageMap, openai } from "@/lib/openai/index";

    /**

* 定义使用 OpenAI 结构化输出格式的投票 JSON 模式。

* 此模式告诉 AI 我们期望的内容——一个问题和一个选项数组。
     */
    const pollSchema: OpenAI.ResponseFormatJSONSchema["json_schema"] = {
      name: "CreateAIPoll",
      description:
        "创建一个高质量的投票，以吸引参与者并激发有意义的讨论。",
      schema: {
        type: "object",
        properties: {
          question: {
            type: "string",
            description:
              "一个清晰简洁的问题，可以通过选择提供的选项之一来回答。",
          },
          options: {
            type: "array",
            description:
              "投票的可能答案列表。每个选项都应独特且涵盖可能的回答范围。可以为每个选项前添加表情符号，以增加趣味性。",
            items: {
              type: "string",
              description:
                "投票问题的一个可能答案。确保每个选项简明且清晰。",
            },
          },
        },
        required: ["question", "options"],
        additionalProperties: false,
      },
      strict: true,
    };

    /**

* 使用 Zod 创建一个模式来验证 API 响应。
     */
    const aiPoll = z.object({
      question: z.string(),
      options: z.array(z.string()),
    });

    export type AIPoll = z.infer<typeof aiPoll>;

    /**

* getAIPoll 使用结构化输出调用 OpenAI 的聊天完成 API。

* 

* @param prompt - 用户提供的引导投票创建的提示。

* @param languageCode - 生成投票的语言代码。

* @param params - OpenAI API 的附加参数。

* @returns 解析并验证后的投票对象 Promise。
     */
    export const getAIPoll = async (
      prompt: string,
      languageCode: string,
      params: Partial<ChatCompletionCreateParamsBase> = {}
    ): Promise<AIPoll> => {
      const resp = await openai.beta.chat.completions.parse({
        ...params,
        stream: false,
        model: "gpt-4o-2024-11-20",
        messages: [
          {
            role: "system",
            content:
              "您是一个投票生成 AI。您的任务是生成能吸引参与者并激发有意义讨论的投票。根据用户的提示调整语气和风格。",
          },
          {
            role: "user",
            content: `投票的提示是：${prompt}。 请生成 ${languageMap[languageCode]} (${languageCode}) 的答案。`,
          },
        ],
        response_format: {
          type: "json_schema",
          json_schema: pollSchema,
        },
      });

      // 使用 Zod 解析并验证响应内容
      return aiPoll.parse(resp.choices[0]?.message.parsed);
    };

进入全屏 退出全屏

代码走读 🧑‍💻

1. 定义架构：

• 我们首先声明一个 JSON 架构 (pollSchema)，该架构精确地描述了我们的投票应该包含的内容。该架构指定了两个属性：

• question ：表示投票问题的字符串

• options ：一个字符串的数组，每个字符串代表一个可能的答案
• additionalProperties: false 标志确保我们的响应中不会混入任何额外的数据
• 最重要的是，OpenAI 保证 响应将完全匹配此架构，没有任何偏差

• 当使用 json_schema 时，必须包含 strict、required 和 additionalProperties

• 接下来，我们创建一个 Zod schema（aiPoll）来验证 AI 的响应。
• 这样就相当于一个安全网——如果响应与我们的 Zod schema 不匹配（这种情况在结构化输出中通常不会发生），我们的代码就会抛出错误而不是处理这些无效数据。
• 它还通过类型推断为我们提供了良好的 TypeScript 类型支持。

1. 调用 API：

• 在 getAIPoll 函数中，我们调用 openai.beta.chat.completions.parse，并用我们的提示和结构化的 response_format 参数传递给它

• messages 数组包含两个角色：

• 系统：设置 AI 作为投票生成助手的行为

• 用户：传递具体的提示和需求的语言

• response_format 参数告诉 OpenAI 严格遵循我们的结构

  1. 验证与返回：
• 最后，我们使用Zod模式来解析返回的消息
• 由于OpenAI确保了格式的一致性，这个验证步骤主要关注的是TypeScript类型安全，而不是运行时检查，

使用OpenAI的结构化输出有以下几个主要好处：

1. 保证格式: AI的输出保证遵循您的格式。再也不会出现“期望数组，却得到字符串”的错误
2. 类型安全: 结合Zod，从AI的响应到您的应用程序代码，保证全程类型安全
3. 简化处理: 不再需要复杂的解析或错误处理——数据返回完全符合您的预期
4. 多语言支持: 同一结构适用于任何语言，便于为全球团队创建投票
5. 干净集成: 代码可与任何现代TypeScript/JavaScript应用程序无缝集成

在 Kollabe，这种方法让我们能够专注于创造出色的用户体验，而不是把精力放在解析 AI 回应上。我们的用户几秒钟内就能生成投票，知道他们总是能得到结构清晰、实用的结果。

结构化输出的应用远不止简单的民意调查。这里有一些组织利用这项技术的方式：

const 提示 = "关于最近的项目启动，您想讨论哪些方面？";
const 调查 = await getAIPoll(提示, "en");

console.log(调查);
// 输出如下：
// {
//   question: "在最近的项目启动中，哪个方面最有利于我们的成功？",
//   options: [
//     "🚀 项目启动前的准备工作和规划",
//     "👥 团队协作与沟通",
//     "🛠️ 技术执行与问题解决",
//     "🎯 营销策略和客户互动",
//     "📈 启动后的支持与改进"
//   ]
// }

进入全屏 退出全屏

本文讲述了如何利用OpenAI的结构化结果来构建一个既实用、又有趣的投票工具。我们介绍了关键要素：

• 定义一个 JSON 架构，明确告诉 AI 所期望的输出
• 使用 Zod 对输出进行验证，以发现任何不一致之处
• 使用一组清晰的指令来调用 OpenAI API
• 最重要的是，每次都能确保得到结构化的回复

如果你对这个方法感兴趣，可以试试看Kollabe。我们实现了与此完全相同的方法，帮助团队快速创建有趣的投票，并对此效果感到非常惊讶。

无论你是自己搭建实现还是寻找现成解决方案，结构化结果改变了游戏规则。它们将有时难以预料的AI响应变成你可以信任的结果，让你可以专注于构建优秀的功能，而不是解析响应。

投票开心！