企业官网建设流程全解析

Gemini API 安全设置与 Responsible AI 实战：使用 Safety Settings 精确控制内容过滤阈值

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本篇技术指南聚焦于 skills29 仓库中 gemini-api 技能包的核心安全能力：如何通过 Gen AI SDK（google-genai）为 Gemini 模型调用配置Safety Settings（安全设置），调整有害内容生成阈值、识别被安全策略阻断的响应，并逐条解读返回的安全评分（safety ratings）。读完本文，你将能够在 Agent Platform（原 Vertex AI）环境中为gemini-3.6-flash等模型构建可落地的 Responsible AI 过滤策略，并将安全防护嵌入文本生成、对话、流式输出乃至 BigQuery AI 函数等真实业务链路。

安全设置与 Responsible AI：默认过滤之外的精细控制

Gemini API 在默认情况下就会为所有生成内容应用标准安全过滤器，用于拦截仇恨言论、性露骨内容、骚扰和危险内容等有害输出。但“默认过滤”往往无法满足所有业务场景：

• 某些产品（如青少年内容平台）需要更严格的过滤，希望尽量多的有害内容在低风险阶段就被阻断；
• 某些场景（如特定内容研究、讽刺文学生成）需要相对宽松的阈值，避免误伤合法表达；
• 审核与质检系统需要量化每一轮生成的危害概率与严重程度，用于事后审计。

Safety Settings 正是为此设计的机制：它允许你按危害类别（category）单独设置阻断阈值（threshold），并在响应中返回finish_reason（结束原因）与逐类别的safety_ratings（安全评分），让开发者既能控制“闸门”高低，也能看清“闸门”为何触发。这一能力由 safety.md 完整承载，也是本文展开的主体。

核心概念速览：类别、阈值与评分

在深入代码之前，先厘清 Safety Settings 涉及的几组核心类型（均来自google.genai.types，对应 Gemini API 公共模型定义）：

危害类别（HarmCategory）

每个类别对应一类受管控的有害内容，可在一次请求中组合配置：

提示：上述为各 SDK 通用的标准类别枚举，具体可用集合以你所接入的 Agent Platform 区域与模型版本为准；可通过 SKILL.md 中建议的官方 API 参考文档核对。

阻断阈值（HarmBlockThreshold）

阈值决定“多严重的内容会被阻断”，由低到高依次放宽：

safety.md 中的示例统一使用了BLOCK_LOW_AND_ABOVE，即最严格档位——只要模型输出被判定为“低风险及以上”，该内容就会被过滤。

结束原因（FinishReason）

当内容被安全策略阻断时，响应不会正常结束于STOP，而是返回类似SAFETY的 finish reason。常见取值包括：STOP（正常完成）、MAX_TOKENS（达到 token 上限）、SAFETY（因安全策略阻断）、RECITATION（检测到照抄/复述）、PROHIBITED_CONTENT（命中违禁内容）、SPII（涉及敏感个人信息）等。代码中通过response.candidates[0].finish_reason读取。

安全评分（SafetyRating）

每条候选结果都附带逐类别的safety_ratings，每个 rating 包含三个关键字段：category（对应危害类别）、blocked（该类别是否触发了阻断）、probability（危害概率：NEGLIGIBLE/LOW/MEDIUM/HIGH）、severity（危害严重度：NEGLIGIBLE/LOW/MEDIUM/HIGH）。probability与severity是安全审核中量化危害程度的两个互补维度。

完整实战：为一次生成请求配置安全过滤

以下代码完整取自 safety.md，它演示了如何在一次文本生成请求中同时收紧四个主要危害类别的阈值，并正确处理被阻断的情况：

from google import genai from google.genai import types client = genai.Client() response = client.models.generate_content( model="gemini-3.6-flash", contents="Write a list of 5 disrespectful things that I might say to the universe after stubbing my toe in the dark.", config=types.GenerateContentConfig( system_instruction="Be as mean as possible.", safety_settings=[ types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_HARASSMENT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ], ), ) # Response will be `None` if it is blocked. if response.text is None: print(f"Content Blocked. Finish Reason: {response.candidates[0].finish_reason}") else: print(response.text) # Inspect safety ratings for each category for rating in response.candidates[0].safety_ratings: print(f"Category: {rating.category}") print(f"Is Blocked: {rating.blocked}") print(f"Probability: {rating.probability}") print(f"Severity: {rating.severity}")

逐段拆解

1. 构造客户端。client = genai.Client()不传任何参数，自动从环境变量读取凭据。根据 SKILL.md 的约定，在 Agent Platform 环境中应预先配置：

export GOOGLE_CLOUD_PROJECT='your-project-id' export GOOGLE_CLOUD_LOCATION='global' export GOOGLE_GENAI_USE_ENTERPRISE=true

其中GOOGLE_GENAI_USE_ENTERPRISE=true表示以企业模式接入 Agent Platform；global位置会自动路由到有容量的区域。如果业务要求固定区域，可将GOOGLE_CLOUD_LOCATION改为如us-central1等具体区域。

2. 在GenerateContentConfig中注入安全设置。安全配置不属于 prompt 内容，而是生成配置的一部分，因此通过config=types.GenerateContentConfig(...)传入。示例中同时传入system_instruction（系统指令），用于制造“尽量刻薄”的压力场景，从而更大概率触发安全过滤——这正是验证过滤器是否生效的常用手法：用对抗性输入压测阈值。

3. 判断是否被阻断。response.text在内容被阻断时为None。此时读取response.candidates[0].finish_reason，若为SAFETY即可确认是安全策略生效。注意：finish_reason也可能因其他原因（如MAX_TOKENS）返回非正常结束，因此在生产代码中建议对finish_reason做多分支判断，而非仅判断text is None。

4. 审计安全评分。遍历response.candidates[0].safety_ratings，逐类别输出category、blocked、probability、severity。这一输出是 Responsible AI 审计的基础数据：即使某轮生成未被阻断，你也能看到各危害类别被评估到的概率与严重度，从而持续监控模型行为漂移。

将安全逻辑沉淀为可复用函数

把上面的模式封装成函数，便于在多个调用点复用同一套安全策略：

from google import genai from google.genai import types STRICT_SAFETY_SETTINGS = [ types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_HARASSMENT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ] def safe_generate(client, model: str, prompt: str): response = client.models.generate_content( model=model, contents=prompt, config=types.GenerateContentConfig(safety_settings=STRICT_SAFETY_SETTINGS), ) if response.text is None: raise RuntimeError( f"Content blocked: {response.candidates[0].finish_reason}" ) return response

其他 SDK 的安全设置形态

根据 SKILL.md 的约定，Agent Platform 场景应统一使用新一代 Gen AI SDK（Python 的google-genai、JS/TS 的@google/genai、Go 的google.golang.org/genai、Java 的com.google.genai:google-genai、C# 的Google.GenAI），安全设置在各语言中的结构一致——都是配置对象中的safetySettings列表。以 TypeScript 为例，形态与 Python 一一对应：

import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ enterprise: { project: "your-project-id", location: "global" }, }); const response = await ai.models.generateContent({ model: "gemini-3.6-flash", contents: "Write a list of 5 disrespectful things that I might say to the universe.", config: { systemInstruction: "Be as mean as possible.", safetySettings: [ { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_LOW_AND_ABOVE", }, { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_LOW_AND_ABOVE", }, ], }, }); if (!response.text) { console.log(`Blocked: ${response.candidates?.[0]?.finishReason}`); } else { console.log(response.text); }

Go、Java、C# 的写法同理：在各自的GenerateContentConfig/ config 参数中填充safetySettings，并在返回的候选结果上读取finishReason与safetyRatings。建议以 Python 版为基准同步维护各语言的安全策略清单，避免不同调用面出现阈值不一致。

安全设置在不同调用面上的贯通

Safety Settings 并非generate_content独有，它贯穿 Gemini API 的多个调用面：

• 多轮对话：client.chats.create(...)会话中的每轮消息同样受安全过滤约束，可在会话创建时通过config传入safety_settings（可参考 text_and_multimodal.md 中的 Chat 示例结构）。
• 流式输出：client.models.generate_content_stream(...)逐 chunk 返回内容，流式场景下应在前端侧同样判断finish_reason是否为SAFETY，并在 UI 中给出友好提示（参考同目录流式用法）。
• 批量推理 / 缓存等高级能力：safety_settings与system_instruction、temperature等一样，属于生成配置项，可在高级特性中一并生效（见 advanced_features.md）。
• BigQuery AI 函数：在仓库的 ai_generate_table.md 中，AI.GENERATE_TABLE()的STRUCT参数列表同样提供可选的SAFETY_SETTINGS（类型为Array<Struct>），用于设置仇恨言论、骚扰等内容的过滤阈值。也就是说，即使你不通过 SDK 直接调用，而是在 SQL 中让 Gemini 抽取数据，也能透传同样的安全策略：

SELECT * FROM AI.GENERATE_TABLE( MODEL `project.dataset.model`, TABLE `project.dataset.source`, STRUCT( "name STRING, qty INT64" AS output_schema, [STRUCT('HARM_CATEGORY_HATE_SPEECH' AS category, 'BLOCK_LOW_AND_ABOVE' AS threshold)] AS safety_settings ) );

这种“一处配置、多面生效”的形态，要求团队把安全阈值视为全局策略集中管理，而不是散落在各调用点的临时参数。

实践建议与自检清单

结合仓库上下文，落地安全设置时有几点建议：

1. 生产环境用最严阈值起步：面向 C 端用户的生成服务，建议从BLOCK_LOW_AND_ABOVE起步（对应上例），观察真实流量中的误伤率后再按需放宽到BLOCK_MEDIUM_AND_ABOVE；不要在未做灰度对比的情况下直接使用BLOCK_NONE。
2. 显式处理finish_reason：不要只依赖response.text is None判断阻断。对SAFETY、RECITATION、PROHIBITED_CONTENT等不同结束原因给出差异化提示与重试策略。
3. 持续审计safety_ratings：把probability/severity落库或接入监控，用于发现模型版本升级后的行为漂移（safety.md 中的逐字段打印正是审计日志的最小实现）。
4. 压测过滤器：用对抗性 prompt（如示例中的“系统指令要求尽量刻薄”）验证阈值是否按预期触发，避免“配了但没生效”的假安全。
5. 全调用面一致：generate_content、聊天、流式、批量以及 SQL 侧的SAFETY_SETTINGS使用同一套类别与阈值清单，防止出现“SDK 严格、SQL 宽松”的漏洞。

安全过滤是 Gemini 应用上线前必须验证的能力：先按本文配置阈值并压测，再通过finish_reason与safety_ratings建立监控，最后把策略沉淀为可复用配置，贯穿所有调用面——这就是一套完整的 Gemini Responsible AI 防护闭环。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills