Gemini接口finish_reason SAFETY排查与降级兜底实践

半夜三点，监控告警群里弹出一条日志：finish_reason: SAFETY。接口返回 200，HTTP 层面一切正常，但candidates[0].content是空的，或者只有半段话戛然而止。如果你正在用 Gemini 系列接口做产品，这个字段一定会遇到——它既不是网络故障，也不是密钥问题，更不是限流，而是模型侧的内容安全机制在生成过程中把输出掐断了。这篇文章就把这件事讲透：finish_reason: "SAFETY"到底代表什么，它和输入侧被拒有什么区别，拦截链路是怎么判定的，遇到之后应该按什么顺序排查、怎么改 prompt、怎么写兜底代码，以及哪些“看起来很聪明”的做法其实是坑。适合正在接入大模型接口的后端、全栈、算法同学，也适合产品同学理解为什么有些请求会“莫名其妙”失败。读完你至少能做到两件事：一是在日志里一眼分清是哪一层的拦截，二是有一套可以直接抄的降级与可观测方案。

1. 先把现象拆开：finish_reason 到底在说什么

1.1 响应结构里那几个字段的分工

很多人第一次看到这个报错，会以为是请求根本没发出去，其实恰恰相反——请求发出去了，模型也开始生成了，中途被安全分类器判定为高风险，于是生成被强制中止。要理解这件事，得先把响应体里几个容易混淆的字段分清楚。以常见的 Gemini 接口返回为例，一次调用的结果大致包含这几块：candidates数组、prompt_feedback对象、usage_metadata用量信息。三者各管一段，职责完全不重叠。

candidates[0].finish_reason描述的是这条候选输出的结束原因。它是“生成侧”的状态码，告诉你在解码循环里是怎么停下来的。candidates[0].finish_message通常会给一句人类可读的补充说明，但不要依赖它做逻辑判断，字段值可能为空。

candidates[0].safety_ratings是打分表，逐类给出概率等级（通常是 NEGLIGIBLE / LOW / MEDIUM / HIGH）以及一个blocked布尔值。这里有个特别容易被忽略的点：即使 finish_reason 是正常的 STOP，safety_ratings 里也可能出现 MEDIUM 甚至 HIGH 的评分。也就是说，这段内容“擦边但没被拦”。如果你只判断 finish_reason，就会漏掉一批潜在风险内容，后面做内容审核时会很被动。

prompt_feedback则是输入侧的反馈。只有你的 prompt 在进入模型之前就被拦了，这里才会出现block_reason。它和 finish_reason 是两条独立的链路，一个管输入、一个管输出，混为一谈是排查时最常见的第一个错误。

usage_metadata值得单独说一句：当输出被安全机制中止时，已经生成的那部分 token 通常是会计费的。也就是说，你付了钱，但拿到的是一段残缺文本。在高并发场景下，这个成本不能不算。

1.2 一张表看懂各种结束原因

finish_reason不是一个只有“成功/失败”的二元状态，它是一组枚举。不同版本的接口枚举值可能有增删，但核心几类是稳定的。下面这张表是我在实际项目里整理的对照，按处理优先级从高到低排：

把这张表贴在代码里比贴在文档里管用。我见过不止一个项目把所有非 STOP 的原因统一走同一条重试分支，结果SAFETY的请求被反复重试了五次，延迟翻了三倍，费用也翻了三倍，最后还是失败。

1.3 输入侧拦截和输出侧拦截长得完全不一样

这两种情况的表象差异非常大，但错误信息往往都很含糊，所以必须靠字段结构来区分。

输入侧被拦（prompt_feedback.block_reason有值）时，candidates通常是空数组，或者只有一个空的候选对象。这种请求的特点是响应极快——因为模型根本没开始解码，几百毫秒就返回了。如果你在监控里看到某类请求的 P50 延迟突然掉到很低，同时失败率上升，基本可以判断是输入侧被批量拦截。

输出侧被拦（finish_reason = SAFETY）时，响应时间明显更长，因为模型已经跑了一段解码。而且candidates[0].content里往往有部分文本——可能是开头几句正常内容，然后突然断在半句话上。这个“半句话”是最有价值的排查线索，它往往直接指向触发点。

还有一种更隐蔽的中间态：输入侧有一部分被拦截，prompt_feedback里没有 block_reason，但某些 segment 被标记了；模型仍然生成，但输出质量明显下降。这种情况在长上下文、多轮对话里出现得不少，需要通过对比实验才能确认。

注意：不要用“有没有报错”来判断是否被拦截。安全拦截在 HTTP 层是 200，在业务层是“成功返回了一段不完整内容”，绝大多数 SDK 不会抛异常。如果你的代码只 catch 异常，这类失败会静默穿透到用户侧。

2. 为什么会触发：拦截链路到底怎么判定的

2.1 分类器不是关键词黑名单

这是理解整件事的关键前提。很多同学的第一反应是“我明明没写敏感词，为什么被拦”，潜台词是把它当成了关键词过滤。实际上背后的判定通常是一个多类别、带上下文语义的概率分类器，它对整段文本（输入 + 已生成的输出）做打分，超过阈值就触发拦截。

这个机制带来几个直接后果。第一，同一个词在不同上下文里结果完全不同。写“如何在家处理轻微烫伤”可能没事，写“如何让某人不留痕迹地受伤”就会被拦。第二，改写措辞有效，改关键词无效。把某个词换成同义词，语义没变，分类器的判断基本不会变。第三，分类器有误判率。正常的技术讨论、医学描述、安全研究、法律条文解读，都是误判高发区，因为它们天然包含高风险的词汇组合，但意图是良性的。

我在一个客服摘要项目里遇到过典型误判：用户投诉里说“你们的服务让我想砸了手机”，摘要把这句原样保留，结果整段输出被中止。从语义上讲这是情绪表达，不是暴力威胁，但分类器在短文本、缺少上下文的情况下很难区分。后来我们改成让模型输出“用户表达了强烈不满情绪”这种归一化描述，问题消失。

2.2 最容易踩雷的六类场景

按我自己的经验，触发 SAFETY 的请求高度集中在下面几类。这里用虚构的场景举例，只讲结构，不讲具体内容：

第一类是医疗健康。剂量、药物相互作用、症状自查、急救处置，这些话题的专业表述和“危险行为描述”在语义空间里距离很近。缓解方式通常是加明确的场景限定（“用于科普说明”“用于给医生的沟通材料”）并去掉操作性细节。

第二类是安全测试与攻防演练。做安全方向的同学写 prompt 描述漏洞原理时，很容易被判为提供攻击方法。这类需求更适合把描述抽象化、聚焦防御视角，或者走企业内部审核过的专用通道。

第三类是隐私信息。当上下文里混入了手机号、住址、证件号片段，输出侧可能直接命中 SPII 类拦截。这类问题应该在进入模型之前就做脱敏，而不是等它被拦了再处理。

第四类是版权复述。要求“逐字复述某段歌词/某本书的章节”，很容易触发 RECITATION 或 SAFETY。改成“用自己的话概括要点”通常就没事。

第五类是情绪激烈文本。做心理陪伴、舆情分析类产品时，用户输入里高频出现极端情绪表达，模型的输出如果顺着情绪走，很可能被拦。正确做法是让模型的输出走中性、支持性、引导求助的方向。

第六类是未成年人相关。任何涉及未成年人的内容，阈值都会更严格，这个没有太多技巧可言，只能从产品设计上规避。

2.3 阈值参数能调，但别指望它是万能开关

Gemini 系列接口提供了safety_settings，可以按类别设置拦截阈值。常见类别包括骚扰、仇恨言论、色情、危险内容等，每个类别可以设成不同的档位。档位大致从宽到严分为几级：完全关闭拦截、只在极高概率时拦截、中高概率拦截、低概率就拦截。

# 结构示意，不同 SDK 版本字段名略有差异 safety_settings = [ {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"}, {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_ONLY_HIGH"}, {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}, ]

放宽容忍度确实能降低误杀，但有三条硬约束必须知道。第一，有些类别无法关闭，某些明确禁止的内容类型即使设成最宽松也会拦。第二，放宽阈值意味着产品侧要承接更多风险内容，你得有后置审核兜底，否则是把风险从前端挪到了用户眼前。第三，阈值设置会随模型版本变化，同一份配置在不同模型版本上的实际效果可能不一致，升级模型后必须回归验证。

提示：与其把阈值调到最宽，不如先用默认阈值跑一批真实流量，统计各类别的probability分布，再决定放宽哪一类。盲目全开通常只会把误杀换成了漏杀。

3. 实操：从日志到定位的四步排查法

3.1 第一步：把完整响应结构打出来

大部分 SDK 的封装层会把finish_reason抹掉，只返回文本。所以排查的第一步永远是打印原始响应。下面这段是我常用的诊断函数，直接抄就行：

def diagnose(response) -> dict: info = { "candidates_count": len(response.candidates or []), "prompt_block_reason": None, "finish_reason": None, "finish_message": None, "safety_ratings": [], "text_len": 0, "tokens": None, } pf = getattr(response, "prompt_feedback", None) if pf is not None: info["prompt_block_reason"] = getattr(pf, "block_reason", None) if response.candidates: c = response.candidates[0] info["finish_reason"] = str(getattr(c, "finish_reason", None)) info["finish_message"] = getattr(c, "finish_message", None) for r in (getattr(c, "safety_ratings", None) or []): info["safety_ratings"].append({ "category": str(getattr(r, "category", None)), "probability": str(getattr(r, "probability", None)), "blocked": bool(getattr(r, "blocked", False)), }) content = getattr(c, "content", None) if content and getattr(content, "parts", None): info["text_len"] = sum( len(getattr(p, "text", "") or "") for p in content.parts ) um = getattr(response, "usage_metadata", None) if um is not None: info["tokens"] = getattr(um, "total_token_count", None) return info

关键点在于：把 safety_ratings 里probability为 MEDIUM 及以上的类别全列出来，哪怕它们没被标记 blocked。这些类别就是“差点被拦”的高危信号，比事后补救有价值得多。我在一个内容生成项目里就是靠这个指标，提前两周发现了某批模板文案会稳定把某个类别推到 MEDIUM，赶在上线前改掉了。

3.2 第二步：二分定位触发点

知道是输出侧被拦之后，下一步是找出到底是哪一段引发的。这里最有效的手段是二分法，而不是盯着 prompt 反复猜。

如果 prompt 很长（比如带了几千字的检索结果），做法是把上下文按段落切成两半，分别加上原始指令单独调用，看哪一半会触发。触发的那一半继续二分，通常三四轮就能缩到一两句话。

如果是多轮对话，先做一次“无历史”的对照调用。多轮历史是最常见的隐形雷区——用户上一轮说了某句话，这一轮虽然问得很干净，但模型在生成时会参考历史，导致输出被带偏然后被拦。我遇到过好几次，单轮测试怎么都复现不了，加上会话历史就稳定复现。

如果输出是流式的，定位方式更直接：把每个 chunk 的文本拼接起来，找到最后一个正常 chunk，看它后面紧接着要说什么。虽然拿不到被截掉的内容，但断点的语义位置通常已经足够提示问题所在。

3.3 第三步：确认是“表述问题”还是“需求问题”

定位到具体片段后，要做一个判断：这是表述方式的问题，还是需求本身就越界了。这个判断决定了后面是改写还是拒绝。

判断方法很简单：把这段需求用最中性、最抽象的方式重述一遍，只保留“要解决什么问题”，去掉所有操作细节和情绪色彩，再调用一次。如果通过了，说明是表述问题，改写即可；如果还是被拦，说明需求本身触碰了硬边界，这时候在 prompt 里怎么折腾都是浪费时间，应该在产品层做拦截提示。

举个虚构的例子：某教育类产品让模型生成“化学实验的危险性说明”，原始写法是让模型描述“如果不当操作会发生什么”。改成“说明该实验的规范操作要点和风险提示”之后，通过了。反过来，如果某个需求抽象到“解释原理”这一层仍然被拦，那就该考虑换一种产品表达。

3.4 第四步：改写 prompt 的五个具体手法

改写不是玄学，有相对固定的套路。我把常用手法按效果排序：

手法一，加角色和用途声明。在系统指令里明确写清“你是一名面向专业人员的科普作者，输出用于内部培训材料，不包含操作性指导”。这个声明本身不保证通过，但它会显著影响分类器对上下文的判断。

手法二，把“怎么做”换成“是什么/为什么”。这个转换的收益最大。分类器对操作步骤类表述的敏感度远高于原理类表述。

手法三，去掉第二人称和祈使句。“你可以先……然后再……”这种写法风险明显高于“该流程通常包括两个阶段”。这听起来有点反直觉，但实测有效，因为它改变了文本的“可执行性”特征。

手法四，拆分长任务。一个 prompt 里塞了五件事，只要其中一件踩线，整段输出就被中止。拆成五次调用，四次成功一次失败，用户体验远好于整体失败。

手法五，把敏感判断交给前置过滤。与其让模型在生成中途被拦，不如在调用前先用一个轻量分类器或规则集过一遍输入，命中高风险就直接走预设回复。这样既省 token，也避免“半句话”这种最差的体验。

注意：改写之后一定要用同一批样本回归。我踩过的坑是改了一版 prompt，主场景通过了，但另一条支线的通过率从 95% 掉到 70%，因为新加的用途声明和那条支线的上下文冲突了。

4. 修复与兜底：代码层面怎么写得稳

4.1 重试策略要分类，不能一刀切

这是最容易写错的地方。SAFETY不应该重试，原因有两个：一是判定基本是确定性的，同样的输入大概率还是同样的结果；二是即使因为采样温度带来一点随机性而偶尔通过，这种“通过”也是不可复现的，等于在生产环境里埋了一个随机炸弹。

真正需要重试的是这些：网络超时、429 限流、5xx 服务端错误，以及MAX_TOKENS（这个其实不算重试，算续写）。下面这个决策函数建议直接放进你的公共层：

RETRYABLE = {"TIMEOUT", "RATE_LIMIT", "SERVER_ERROR", "UNAVAILABLE"} def classify_failure(resp_info: dict) -> str: """返回: ok / retry / rewrite / reject""" if resp_info.get("prompt_block_reason"): return "reject" fr = (resp_info.get("finish_reason") or "").upper() if not fr or "STOP" in fr: # 注意: STOP 也要检查 safety_ratings 是否擦边 risky = any( r["probability"] in ("MEDIUM", "HIGH") for r in resp_info.get("safety_ratings", []) ) return "ok" if not risky else "review" if "MAX_TOKENS" in fr: return "rewrite" # 走续写逻辑，不是简单重试 if "SAFETY" in fr or "PROHIBITED" in fr or "SPII" in fr: return "reject" # 不重试，走降级 if "RECITATION" in fr: return "rewrite" if "MALFORMED_FUNCTION_CALL" in fr: return "retry" # 工具定义问题，修正后可重试 return "retry"

这个函数的价值在于把“失败了”这个笼统概念拆成了四种可执行动作。上线之后你会发现，retry分支的实际占比远低于预期，大部分失败都落在reject和rewrite上——这也说明了为什么无脑重试是错的。

4.2 降级链路要有梯度

被拦之后用户看到什么，直接决定了这个产品的体感。我的建议是三层梯度，逐层降：

第一层是自动改写重试一次。把原始 prompt 做一次轻量改写（加用途声明、去掉祈使句），重新调用。这一层能救回相当一部分误杀，成本是双倍 token。

第二层是退化回答。如果改写后仍失败，不返回错误，而是返回一段基于模板的通用回复，并附上“是否换个角度提问”的引导。对用户来说，这是“答得不够好”，而不是“系统坏了”。

第三层是明确提示 + 人工通道。如果这个请求属于关键业务路径（比如工单提交、合同审阅），必须记录完整上下文，进人工队列，同时给用户一个明确的预期时间。

def call_with_fallback(prompt: str, history: list | None = None): info = handle_once(prompt, history) action = classify_failure(info) if action in ("ok", "review"): return info["text"], None if action == "rewrite": info2 = handle_once(soften(prompt), history) if classify_failure(info2) in ("ok", "review"): return info2["text"], None return FALLBACK_TEXT, "degraded" if action == "retry": for _ in range(2): info3 = handle_once(prompt, history) if classify_failure(info3) in ("ok", "review"): return info3["text"], None return FALLBACK_TEXT, "degraded" # reject return FALLBACK_TEXT, "blocked"

soften()就是那个改写函数，只做安全无害的文本变换：加一句用途声明、去掉感叹号和第二人称、把“你应该”换成“通常建议”。不要在这个函数里做任何对抗性的改写尝试，那是另一个性质的问题，也不会有稳定收益。

4.3 流式场景：断在半句话的体验怎么救

流式输出遇到 SAFETY 最难受，因为前面几个 chunk 已经推到前端了，最后突然断掉，用户看到的是半句话加一个空白。这个问题在技术上不难解，但需要前后端配合。

服务端要做的是：在流式响应里显式下发一个终止事件，带上finish_reason和是否降级的标记。不要指望前端从“连接关闭”推断原因，连接关闭的原因太多了。

前端要做的是：收到终止事件后，如果finish_reason是 SAFETY，在已输出内容后面追加一段样式不同的提示文本，比如“该话题需要更具体的背景说明才能继续”，并提供重新提问的入口。绝对不能让半句话直接停在那里——用户会以为产品崩了。

还有一个细节：流式场景下，已生成内容的清理成本很高。如果产品对内容一致性有要求，可以在服务端做一层缓冲，攒够一定长度或等到结束再一起推，代价是牺牲首字延迟。这个取舍取决于产品类型，对话类产品一般选流式，文档生成类产品可以选缓冲。

提示：流式场景务必记录“最后一个正常 chunk 的位置”到日志里。这个偏移量在复盘误杀时极其有用，很多时候一看断点在哪，问题的原因就出来了。

5. 可观测性：让这类失败变得可统计、可回归

5.1 埋点要埋哪几个维度

安全拦截类的失败如果没有埋点，就永远只能靠用户投诉驱动，这在产品上线后是不可接受的。我建议至少记录六个维度：模型版本、是否输入侧拦截、finish_reason 枚举值、触发类别（safety_ratings 里概率最高的那一项）、输出文本长度、请求耗时与 token 用量。

其中模型版本这个维度尤其重要。同一份 prompt，在不同模型版本上的拦截行为可能完全不同，而你如果不记录版本号，做同比分析时就会看到一堆无法解释的波动。我见过一个团队花了整整两天排查“误杀率突然翻倍”，最后发现是灰度发布时换了模型版本，而日志里没有版本字段。

触发类别这个维度也不能省。只看总数你只知道“失败了变多了”，看不出“是哪一类风险变多了”。按类别拆开之后，通常能立刻定位到是某条业务线、某个模板、或者某批用户输入的问题。

5.2 建一个“曾经被拦”的回归集

这是我认为投入产出比最高的一件事。每次排查出一个触发 SAFETY 的样本，就把它脱敏后存进一个专门的测试集，标记上触发类别和当时的模型版本。每次改 prompt、换模型、调阈值之前，先跑一遍这个回归集，看通过率是升了还是降了。

这件事的价值在于它把“偶发问题”变成了“可度量指标”。没有回归集的时候，优化 prompt 全靠手感，改完之后不知道是变好了还是把别的地方弄坏了。有了之后，你至少能回答两个问题：这次改动救回了多少，弄坏了多少。

回归集的规模不需要很大，几十到一两百条就足够有代表性。关键是覆盖要广：正常请求、擦边请求、真越界请求，三类都要有，否则你优化出来的 prompt 可能是在一味放宽，而不是在提升判断准确度。

5.3 成本侧的真实影响

这一点经常被忽略。输出侧被拦的请求，已经生成的 token 通常照常计费。假设某业务每天十万次调用，3% 被拦，平均每次生成 400 token 后中止，按当时的单价折算下来，一个月是笔不小的数字。更要命的是这些钱花出去，用户什么也没拿到。

所以除了降误杀，还有一个优化方向是尽早失败。把明显高风险的判断前移到调用之前，用规则或轻量模型做一次过滤，能省下不少“生成了半截才被拦”的浪费。这个改造的收益在流量大的场景下非常明显。

6. 常见问题速查与踩过的坑

6.1 问题速查表

6.2 几个我实际踩过的坑

坑一：把所有非 STOP 都当异常。早期我在一个项目里写了个统一的异常分支，只要 finish_reason 不是 STOP 就抛错。结果 MAX_TOKENS 这种完全正常的截断也被当成故障，告警天天响，真正的 SAFETY 反而被淹没在噪音里。后来改成按枚举值分流才清净。

坑二：以为提高温度能绕过。这个想法在逻辑上似乎成立——采样更随机，可能就绕开了。实测下来确实偶尔能过，但通过率没法预测，时好时坏。更要命的是，靠这种方式“通过”的内容质量往往很差，因为它本来就在风险边界附近。最后我们把这套逻辑整个删了，换成确定性的改写和降级。

坑三：只测主路径，漏了系统指令。有一次排查了很久，发现触发点根本不在用户输入里，而在我们写的系统指令中——那段指令为了显得“专业”，用了一些比较强烈的表述，用户输入只是把它激活了。系统指令也会被分类器扫描，这点很容易忘。

坑四：忽略 safety_ratings 这个富矿。前两年我们的监控只看 blocked 字段，直到有一次做内容质量复盘，才发现大量 probability 为 MEDIUM 的输出一直在正常返回。这些内容多半是“擦边但可接受”，但它们是最容易在下一个模型版本里变成拦截的那一批。提前看到这个信号，就能提前调整。

坑五：改写函数写得太“聪明”。一开始我尝试在改写函数里做同义词替换、句式打散，想提高通过率。结果是改写后的 prompt 语义漂移，即使通过了，回答质量也明显下降，还引入了新的不可控因素。后来把改写范围严格限制在“加声明、去人称、拆任务”这三件事上，效果反而更稳定。

6.3 一个容易被忽略的经验

最后分享一个我觉得最实用的做法：给每一类拦截建立一个“人工兜底话术”。不是让模型生成，而是提前写好、经过审核的固定文案，按类别对应。比如隐私类被拦，回“你的描述里可能包含个人信息，建议隐去后再试”；危险内容类被拦，回“这个问题涉及专业操作，建议咨询相关专业人员”。

这样做有三个好处。一是响应稳定，不受模型波动影响；二是文案可控，不会出现“模型自己解释为什么被拦”这种越描越黑的情况；三是速度快，省掉一次额外调用。我现在的习惯是，任何接入生成式接口的项目，第一版代码里就带上这套话术，而不是等出了问题再补。毕竟真正难处理的从来不是那个SAFETY字段本身，而是它背后那个正在等回复的用户。