如何从大型语言模型中获取可靠的结构化数据

function findSemanticProblems(resume: Resume): string[] {
  const problems: string[] = [];
  const currentMonth = new Date().toISOString().slice(0, 7);

  for (const role of resume.roles) {
    if (rolestartDate > currentMonth) {
      problems.push(`${role.company}: 开始日期在将来`);
    }
    if (role endDate && role.endDate < role startDate) {
      problems.push(${role.company}: 结束日期早于开始日期`);
    }
  }

  const currentRoles = resume.roles.filter((r) => rendDate === null);
  if (currentRoles.length > 1) {
    problems.push("有多个职位被标记为当前职位");
  }

  return problems;
}

这些代码并没有什么高明的之处，而这恰恰就是其意义所在。它们只是普通的业务逻辑，只不过用来检查模型是否正确工作而已，并非用于验证用户的输入信息。在发现错误时再编写这样的代码吧，把每次新的检查都视为对模型之前所犯错误的永久性回归测试。

这里存在一种有用的不对称性：对于语义上的错误来说，直接将它们呈现给用户通常比重新运行模型来得更有效，因为模型利用现有信息往往无法得到更好的结果。如果一份文档确实列出了两个当前职位，那么这就是文档所显示的内容，再次让模型进行判断也不会改变这一结果。

构建一个不会消耗令牌的重试循环

当验证失败时，人们通常会想用相同的输入再次调用模型，期望得到不同的结果。这种做法在很多情况下确实有效，但也会造成资源的浪费——因为对于那些已经成功完成大部分处理的请求来说，用户仍然需要支付全部的输入成本。

做出两个小小的调整就能产生巨大的效果。

首先，在花费任何资源之前，应该先尝试进行本地修复。很多错误其实只是表面上的问题，通过简单的字符串处理就可以解决：

function salvage(raw: string): string {
  let text = raw.trim();

  // 删除模型添加的Markdown标记。
  const fenced = text.match/^```(?:json)?\s*([\s\S]*?)\s*$$$/);
  if (fenced) text = fenced[1];

  // 删除文档开头或结尾的冗余文本。
  const start = text.indexOf("{");
  const end = text.lastIndexOf("}");
  if (start !== -1 && end > start) text = text.slice(start, end + 1);

  return text;
}

其次，当确实需要再次调用模型时，应该发送修复请求而不是重新开始整个处理流程。在请求中应包含原始的输入内容、失败的输出结果以及具体的验证错误信息。模型已经完成了大部分的数据提取工作，现在只需要它来解决那些具体存在的问题而已。这样修复操作会更快完成，产生的输出也会更短，因此所需的资源也会更少。

async function requestRepair(
  originalPrompt: string,
  badOutput: string,
  error: z.ZodError,
): Promise {
  const issues = error.issues
    .map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
    .join("\n");

  const response = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 4096,
    messages: [
      { role: "user", content: originalPrompt },
      { role: "assistant", content: badOutput },
      {
        role: "user",
        content:
          `该输出因以下问题未能通过验证:\n${issues}\n\n` +
          `请仅返回修正后的JSON格式内容，保留所有已经正确的部分。",
      },
    ],
  });

  return response.content[0].type === "text" ? response.content[0].text : "";
}

综合来看，这个循环机制的作用是区分不同的失败类型，并限制尝试次数：

type Outcome =
  | { ok: true; value: T; attempts: number }
  | { ok: false; error: string; attempts: number };

async function extract( 
  schema: z.ZodType, 
  prompt: string, 
  maxAttempts = 3 
): Promise> { 
  let lastRaw = ""; 
  let lastError: z.ZodError | null = null;

  for (let attempt = 1; attempt <= max Attempts; attempt++) {
    lastRaw =
      attempt === 1
        ? await callModel(prompt)
        : await requestRepair(prompt, lastRaw, lastError!);

    let candidate: unknown;
    try {
      candidate = JSON.parse(salvage(lastRaw));
    } catch {
      continue; // 如果解析失败，直接跳过本次尝试。
    }

    const result = schema.safeParse(candidate);
    if (result.success) {
      return { ok: true, value: result.data, attempts: attempt };
    }
    lastError = result.error;
  }

  return {
    ok: false,
    error: lastError?.message ?? "输出数据无法被解析",
    attempts: maxAttempts,
  };
}

关于这个循环机制，有两点设计意图是显而易见的。首先，它会返回尝试次数，这个数据值得被记录下来，因为每次成功所需的尝试次数是评估提取流程效率的重要指标。其次，它将尝试次数限制在三次以内——如果三次尝试都没有得到有效的结果，再进行第四次尝试往往也无济于事，此时选择优雅地退出程序反而比继续浪费资源更好。

还需要注意的一点是：速率限制错误与模式验证错误属于不同的失败类型，因此不应该采用相同的重试策略。对于速率限制错误，应该采用指数级退避算法，因为问题出在时间控制上；而对于模式验证错误，则需要立即发送修复请求，因为问题出在数据内容本身，等待并不会改变任何情况。

流式结构化输出

流式输出与结构化输出之间存在矛盾。流式输出的设计目的是让用户能够在响应完成之前就看到处理进度，但只有当所有的闭合括号都被解析出来后，才能真正生成一个有效的JSON对象。如果提取数据需要12秒钟的时间，那么最好的处理方式就是让用户等待这12秒钟，或者想办法以流式格式展示一些有意义的信息。

目前有两种合理的处理方法。

第一种方法是使用部分JSON解析器，这种解析器会接收不完整的字符串，并尝试从中提取出最有效的结构，同时会补全缺失的闭合括号并忽略那些不完整的数据。像best-effort-json-parser这样的库就采用了这种方法。当输出数据确实是一个大的对象时，这种方法是可行的；但它的缺点是，中间状态可能会产生误导，因为某些字段可能会以被截断的形式出现，从而看起来像是完整的。

第二种方法更适合当输出数据是一组列表时的情况。这时可以将输出格式改为每行包含一个对象，这样就可以实现流式输出了。由于每一行的数据都可以独立进行解析，因此可以在数据解析完成的瞬间就对其进行验证并展示出来。

const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  messages: [{ role: "user", content: prompt }],
});

let buffer = "";

for await (const event of stream) {
  if (event.type !== "content_block_delta") continue;
  buffer += event.delta.text ?? "";

  const lines = buffer.split("\n");
  buffer = lines.pop() ?? ""; // 保留未完成的部分，以便处理下一块数据。

  for (const line of lines) {
    if (!line.trim()) continue;

    try {
      const parsed = Role.safeParse(JSON.parse(line));
      if (parsed.success) onRole(parsed.data);
    } catch {
      // 如果遇到格式错误的行，就直接忽略它，而不会导致整个解析过程失败。
    }
  }
}

在处理数据缓冲区时，很多人会犯错。网络传输过来的数据块与行界并不一致，因此某个数据块往往会在某个对象的中途结束。将最后一个元素重新添加到缓冲区中，并继续进行处理，这样才能确保程序能够正确地处理剩余的数据。

这种处理方式可以让你对每一条数据进行单独的验证，这比直接解析一个大型数据对象要有优势得多。因为如果其中有一条数据有错误，也不会影响其他数据的解析结果。

那些无法通过重试来解决的故障

到目前为止，我们所讨论的所有情况都假设：只要你的请求方式正确，模型就能产生正确的结果。但有些故障并不是这样，如果将这些故障视为可以重试的情况，不仅会浪费资源，还会得到错误的数据。

其中最常见的一种故障就是从源数据中提取那些根本不存在的信息。例如，如果一份简历中确实没有电子邮件地址，而你的数据结构却要求必须包含这一字段，那么模型就会生成一些看似合理但实际上错误的值。

即使重新尝试，也会得到不同的“看似合理”的结果。对于这种故障，如果采用强制解码的方式，情况只会变得更糟，因为语法规定某个应该为空的字段必须包含某种格式正确的数据。解决这个问题的方法是在数据结构层面进行修改，因此在我的数据提取方案中，几乎所有的字段都被设置为可为空。

源数据中的歧义也是导致类似问题出现的另一个原因。当一份文档中同时列出了两个不同的职位名称以及相应的日期范围时，实际上并没有正确的提取方式，只能进行猜测。重新尝试虽然会得到不同的猜测结果，但置信度仍然是一样的。对于这类情况，数据结构中应该包含表示置信度的信息，用户界面中也应该提供审核机制，而不是再通过一次API调用来解决这个问题。

还有一种情况是数据被无声地截断了。如果响应数据在某个对象的中途就达到了输出字符数的限制，那么就会得到格式错误的JSON数据。如果使用简单的重试机制，程序会再次尝试解析，但同样的问题仍然会再次出现。因此，在尝试重试之前，一定要检查响应数据中显示的停止原因。如果模型是因为字符数不足而停止工作的，那么不增加字符数限制或不对输入数据进行分割，重新尝试肯定还会失败。

一般来说，在决定是否应该重试之前，首先需要判断这种故障属于哪种类型，这样才能确定重试是否真的有助于解决问题。

这实际上会带来哪些代价

每一层处理都对应一定的成本，因此对其进行量化测量是必要的，而不能仅凭猜测来决定。

需要重点关注的关键指标是每次成功提取所需尝试的次数。请在每次请求时记录这一数据，并重点观察其p95分位数而非平均值，因为平均值会掩盖那些真正产生成本的部分。当数据库模式发生变化导致质量下降时，这个数值会比其他指标更早出现变化。

在这里，提示信息的缓存效果比在大多数工作负载中都要重要得多。提取提示信息非常适合进行缓存处理，因为在每次请求时，系统提示、数据库模式以及少量的示例数据都是完全相同的，只有输入文档会发生变化。

在一个处理流程中，如果数据库模式和指令涉及的字符数量达到数千个，那么将相关数据放入缓存机制中，将会大幅降低输入处理成本。而且，每次重试时都会再次利用这些缓存数据，因此这种节省效果会更加明显。

为什么修复请求的成本会比重新尝试的成本更低呢？原因在于：虽然输入数据的量会增加——因为需要发送原始提示信息、失败的输出结果以及错误列表——但输出数据的量实际上会大大减少，因为模型只需要修改其中少数几个字段，而不需要重新生成整个文档。在大多数服务提供商那里，生成输出数据才是成本较高的环节，因此这种处理方式通常来说是划算的。

还有两件事从一开始就值得进行监控：一是验证错误出现的分布情况，这一数据能准确指出是哪些数据库字段导致了问题，其参考价值远高于整体失败率；二是本地修复机制的成功率。如果salvage()函数能够修复大部分错误结果，那就说明提示信息本身存在问题，这时只需解决一次这个问题即可，而不需要反复进行修复操作。

当你不需要这些功能时

这些技术只在特定的使用场景下才具有价值，在其他情况下则属于过度设计。

如果模型的输出结果会直接由人类阅读，而且人们会将其视为普通文本来理解，那么你根本不需要结构化输出格式。聊天界面、摘要或电子邮件草稿等工具本身就已经有人类来进行验证了，再添加数据库模式只会给模型带来额外的限制，而并不会带来任何实际好处。

如果你只需要提取一两个字段的数据，而不是整个文档的内容，那么使用针对性强的提示信息、适当的safeParse安全处理机制以及一次重试就足够了。只有当处理量非常大或者数据库模式非常复杂时，才需要使用重试循环、语义验证层和流式解析器这些功能。