如何利用Gemini构建人工智能功能：面向开发者的提示工程实用指南

关键在于要具备这样一种思维模式：把模型生成的回答视为可疑的“编辑内容”，而不是满意的“开发成果”。在做出任何修改后，人们的第一反应往往是检查这些修改是否有效，但更有意义的做法是去找出这些修改仍然存在的问题所在。

优雅地应对失败

模型API出现故障的情况比你想象的要频繁得多，而且故障类型也多种多样。速率限制、超时问题、安全机制的触发、空白的回复内容，以及传输过程中出现的格式错误，这些都可能出现在等待用户接收的回答中。

使用备用模型进行重试

该应用程序会最多尝试三次重试，每次尝试之间的间隔时间会呈指数级递增。如果第一次尝试失败，系统就会切换到性能较低的备用模型来继续处理请求：

while (attempts < maxAttempts && !success && !isAborted) {
  try {
    if (attempts > 0) {
      currentModelName = AI_CONFIG.FALLBACK_MODEL;
      console.warn(`[AI_LOG] 主模型失败，正在切换到 ${AI_CONFIG.FALLBACKMODEL}。`);
    }
    // ... 发送回复内容
    success = true;
  } catch (streamError) {
    if (isAborted) break;

    console.error(`[AI_LOG> 使用 ${currentModelName} 为用户 ${userId} 进行第 ${attempts} 次尝试，但失败了：${streamError.message}`);
    
    if (attempts >= maxAttempts) {
      throw new Error("当前系统负荷过高，请稍后再试。");
    }

    const backoffMs = Math.pow(2, attempts - 1) * 500;
    await new Promise(resolve => setTimeout(resolve, backoffMs));
  }
}

尝试 1 ──► 主模式 gemini-2.0-flash
                   │ 失败
                   ▼ 等待 500毫秒
尝试 2 ──► 备用模式 gemini-2.0-flash-lite
                   │ 失败
                   ▼ 等待 1秒
尝试 3 ──► 备用模式 gemini-2.0-flash-lite
                   │ 失败
                   ▼
        抛出错误：“当前系统负载过高……”
        真实错误信息 ──► 被记录到日志中（包括状态码、使用的模型名称以及用户ID）
        显示给用户的消息 ──► 由程序生成的简短提示语

如果有任何一次尝试成功，就会将处理结果发送给客户端。

需要注意的是，是第一次失败才会触发模型切换到备用模式，而不是最后一次失败。因此，第二次和第三次尝试都会使用较轻量的模型来处理请求。

之所以要设置备用模式，是因为当主模式出现故障时，问题通常与系统容量不足有关；继续使用同一个已经超负荷的模型去处理请求，几乎不可能解决问题。相比之下，即使响应速度稍慢一些，总比没有响应要好——用户虽然无法分辨到底是哪个模型在为他们提供服务，但至少可以知道是否收到了任何反馈信息。

延迟策略被设置得相当严格。Math.pow(2, attempts - 1) * 500这个计算公式决定了等待时间：前两次尝试分别需要等待500毫秒和1秒，而第三次尝试则会直接抛出错误而不是继续等待。这样一来，三次请求总共会带来1.5秒的延迟——这对于那些原本就存在较高延迟的系统来说，已经接近了系统的处理极限了。

通常人们认为延迟策略是免费的，但实际上当用户看到页面上出现旋转图标、提示信息在不断闪烁时，这些等待时间其实是在消耗用户的耐心。如果你将一个默认设置为等待1秒/2秒/4秒的重试机制直接应用到用户界面中，那么就会导致用户需要等待长达10秒钟才能得到响应。

在边界处处理错误

需要注意的是，程序抛出的错误信息其实是面向用户的提示语，而不是底层的异常详细信息。真正的错误数据（如状态码、使用的模型名称、用户ID）会被记录到日志中。用户看到的只是“当前系统负载过高”这样的提示信息。

绝对不能让服务器出现的错误直接显示在用户界面上。因为这些错误信息会泄露系统的实现细节，有时甚至会包含请求的内容，而对于阅读这些信息的人来说，它们根本没有任何意义。应该将真实的错误数据记录到日志中，而向用户展示的则应该是简洁明了的提示语。

将安全过滤机制产生的结果视为普通内容而非错误

被安全过滤机制阻止的响应并不属于异常情况，它只是意味着数据流被暂时中断了。因此，需要专门针对这种情况进行处理：

if (candidate.finishReason === 'SAFETY') {
  const safetyMsg = "\n\n[我无法继续进行这次对话。我们可以在其他地方继续讨论。];
  fullResponse += safetyMsg;
  res.write(`data: ${JSON.stringify({ type: 'content', delta: safetyMsg })}\n\n`);
  break;
}

这种提示信息会被添加到数据流中，因此用户看到的会是已经处理完成的部分内容以及相应的解释说明，而不会是那些在中间突然中断的文本。

对于数据流中的各个部分，也需要进行特别的保护——因为即使其中有一部分数据有问题，也不应该导致整个数据流无法正常传输：

try {
  const chunkText = chunk.text();
  if (chunkText) { /* ... */ }
} catch (textErr) {
  console.warn(`[AI_LOG] 无法从该数据块中提取文本：${textErr.message}`);
}

在不应调用模型时切勿调用它

最重要的错误处理机制其实与模型毫无关系。在任何API调用之前，系统会先检查传入的消息是否符合危机模式：

if (CRISIS_RE.test(userMessage)) {
  return res.json({ success: true, replyText: CRISIS_REPLY });
}

虽然个性化提示系统中存在危机处理机制，而且这种机制确实有效，但对于处于危险中的人来说，“通常有效”显然不是足够的标准。正则表达式和固定的响应方式具有确定性，反应速度也非常快，而且无法通过特殊的表述来改变这些规则。当某种错误处理方式真的会带来危害时，应该在模型之前设置确定的检查机制，而不是依赖提示系统。

{quota Reached && !isSynthesizing && (

每日语音使用量已达到上限。明天再试吧。

或者，您也可以录制自己的声音。

)} {synthError && !quota Reached && !isSynthesizing && (

无法生成音频。

再试一次

)}

当出现使用量上限问题时，系统会显示警告信息，并提供替代方案（例如让用户录制自己的声音，而这个过程完全不需要API）。而对于临时性的错误，系统会显示红色提示，并允许用户重新尝试，同时会先清除缓存数据。

总的来说：任何人工智能系统的错误处理机制都应该用通俗的语言向用户说明发生了什么，并告诉他们下一步该做什么。无论是让用户重新尝试、提供替代方案，还是建议他们明天再来操作，这些都是必要的。如果系统在出现错误后只是显示红色提示而没有任何提示信息，那就算错误处理技术在理论上没有问题，这也仍然是一个漏洞。

从第一天起就保存错误的输出结果

对我来说，最好的提示素材就是那些实际发生的错误案例。那个“虚构的遗憾”例子最终被既用于提示系统的设计中，也用于质量检查清单的编写。我是通过回忆和截图才找回这些例子的。

如果在出现问题时立即创建一个名为`bad-outputs.md`的文件，那么每次迭代的工作效率都会大大提高。这是这份清单上最简单易行的建议，也是我会首先采纳的措施。

早先在提示中出现的这些问题

关于长度与表达方式之间的冲突，其实是由于在同一个文本中同时包含了语音、长度以及推理内容所导致的。如果事先明确规定每个组成部分只对应一个具体的维度，那么这类问题本来是可以避免的。

记录更多数据

我目前只有延迟相关的指标，而没有质量评估指标。我知道响应来得有多快，但却不清楚这些响应的质量如何。即使只是简单地使用点赞/点踩的方式来记录反馈，或者记录那些会触发警报的响应，也能帮助我们将质量评估从偶尔进行的检查转变为能够持续跟踪的趋势分析。

目前，当模型版本发生变化时，其性能逐渐下降这一现象是很难被我察觉到的，除非有用户提出来。

不要将编写较长的提示作为默认解决方案

直接的提示往往很长——甚至可以说太长了。每一个出现的错误都会引发新的规则生成，而这些规则会不断累积起来。其中一些规则现在肯定已经变得多余了，或者彼此之间存在矛盾。

面对不良的输出结果，添加文本通常是人们最先想到的解决办法，但这种做法往往并不可取。更好的做法是修复具体的示例，而不是新增规则，因为示例中的每个词条都蕴含着更多的信息。我目前还没有一个有效的优化流程，应该尽快建立这样一个流程。

我会保留哪些内容

确实有一些有用的东西是我会保留的，比如那些包含备用模型的配置文件、仅在服务器端生效的关键边界设置、具有容错功能的解析机制，以及模型运行前的确定性检查流程。从那以后，这些措施都没有引发过任何问题。

总结

以下是五条值得借鉴的经验：

1. 除非输入数据是无限制的，且输出结果需要人为判断，否则不要使用人工智能。

必须确保这两个条件都得到满足。否则，直接编写代码会更快、更便宜，也更容易进行调试。一个在大多数情况下都能正确工作的正则表达式，往往比那些偶尔才能正确运行的模型调用更有效率，因为前者不会带来延迟问题，也不会增加开发成本，更不会引发新的故障类型。

2. 如果模型的输出结果是通用的、缺乏针对性的，那么很可能它只是在回答你输入内容的平均版本而已。

在调整语言风格之前，首先要检查模型是否添加了用户从未提供过的额外信息。只要纠正了这种过度解读的问题，语言风格往往也会随之得到改善。如果只调整语言风格，那么得到的结果往往只是些听起来自信但实际上并不准确的虚假内容。

3>首先禁止使用某些特定的短语，然后再解决过度纠正的问题。

“直接表达”这个要求本身并没有明确的意义，但列出哪些表达是禁止使用的，就能起到明确指导的作用。而且，当你禁止某种行为时，同时也要禁止它的相反行为——因为模型在处理这类问题时，往往会走向另一个极端。

4. 对于边界设定应使用规则，而对于语音处理则应借助示例，因为这两者的失败机制是不同的。

仅依靠规则，你得到的结果虽然正确，但却缺乏生命力；而只使用示例进行训练，虽然模型能够根据这些示例做出反应，但其行为却具有不可预测性。因此，你需要为相同的输入提供两种不同的、有效的输出结果，这样模型才能真正学会如何处理各种情况，而不会只是机械地重复某个特定的示例。

5. 编写一份手动质量检查清单，其中应列出“预期的结果范围”，而非实际出现的输出结果。

对于那些具有非确定性特征的文本，你无法做出明确的判断，但你可以指定特定的检测范围，并列举出可能出现的错误情况。这些评估标准应该主要以负面条件为主，每一条错误案例都应当基于真实的回归测试结果来制定；同时，为六个月后的版本准备一份“症状与原因对照表”，以便随时查看问题产生的根源。

而所有这些方法的核心在于：你的功能质量高低，其实取决于你能否准确识别出那些出现的错误。这里提到的各种技术手段——比如禁止使用的列表、反例、质量检查案例以及警示信号——实际上都是人们为了记录那些不良输出结果而特意整理出来的。而这个提示系统，只不过是这些记录的载体罢了。