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 SDKgoogle-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每个类别对应一类受管控的有害内容可在一次请求中组合配置类别常量管控内容HARM_CATEGORY_HARASSMENT骚扰类内容欺凌、威胁、贬损性言论HARM_CATEGORY_HATE_SPEECH仇恨言论针对群体身份的歧视与煽动HARM_CATEGORY_SEXUALLY_EXPLICIT性露骨内容HARM_CATEGORY_DANGEROUS_CONTENT危险内容暴力、自残、违法操作指导等HARM_CATEGORY_CIVIC_INTEGRITY公民诚信类内容选举与民主进程相关的误导信息HARM_CATEGORY_UNSPECIFIED未指定类别通常表示沿用默认行为提示上述为各 SDK 通用的标准类别枚举具体可用集合以你所接入的 Agent Platform 区域与模型版本为准可通过 SKILL.md 中建议的官方 API 参考文档核对。阻断阈值HarmBlockThreshold阈值决定“多严重的内容会被阻断”由低到高依次放宽阈值常量含义BLOCK_LOW_AND_ABOVE低及以上概率/严重度即阻断最严格BLOCK_MEDIUM_AND_ABOVE中等及以上概率/严重度才阻断BLOCK_ONLY_HIGH仅在高概率/高严重度时阻断最宽松BLOCK_NONE不阻断一般不建议在生产环境使用HARM_BLOCK_THRESHOLD_UNSPECIFIED未指定沿用服务端默认值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( modelgemini-3.6-flash, contentsWrite a list of 5 disrespectful things that I might say to the universe after stubbing my toe in the dark., configtypes.GenerateContentConfig( system_instructionBe as mean as possible., safety_settings[ types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_HARASSMENT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_HATE_SPEECH, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ], ), ) # Response will be None if it is blocked. if response.text is None: print(fContent 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(fCategory: {rating.category}) print(fIs Blocked: {rating.blocked}) print(fProbability: {rating.probability}) print(fSeverity: {rating.severity})逐段拆解1. 构造客户端。client genai.Client()不传任何参数自动从环境变量读取凭据。根据 SKILL.md 的约定在 Agent Platform 环境中应预先配置export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISEtrue其中GOOGLE_GENAI_USE_ENTERPRISEtrue表示以企业模式接入 Agent Platformglobal位置会自动路由到有容量的区域。如果业务要求固定区域可将GOOGLE_CLOUD_LOCATION改为如us-central1等具体区域。2. 在GenerateContentConfig中注入安全设置。安全配置不属于 prompt 内容而是生成配置的一部分因此通过configtypes.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( categorytypes.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_HARASSMENT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_HATE_SPEECH, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), types.SafetySetting( categorytypes.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, thresholdtypes.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ] def safe_generate(client, model: str, prompt: str): response client.models.generate_content( modelmodel, contentsprompt, configtypes.GenerateContentConfig(safety_settingsSTRICT_SAFETY_SETTINGS), ) if response.text is None: raise RuntimeError( fContent blocked: {response.candidates[0].finish_reason} ) return response其他 SDK 的安全设置形态根据 SKILL.md 的约定Agent Platform 场景应统一使用新一代 Gen AI SDKPython 的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类型为ArrayStruct用于设置仇恨言论、骚扰等内容的过滤阈值。也就是说即使你不通过 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 ) );这种“一处配置、多面生效”的形态要求团队把安全阈值视为全局策略集中管理而不是散落在各调用点的临时参数。实践建议与自检清单结合仓库上下文落地安全设置时有几点建议生产环境用最严阈值起步面向 C 端用户的生成服务建议从BLOCK_LOW_AND_ABOVE起步对应上例观察真实流量中的误伤率后再按需放宽到BLOCK_MEDIUM_AND_ABOVE不要在未做灰度对比的情况下直接使用BLOCK_NONE。显式处理finish_reason不要只依赖response.text is None判断阻断。对SAFETY、RECITATION、PROHIBITED_CONTENT等不同结束原因给出差异化提示与重试策略。持续审计safety_ratings把probability/severity落库或接入监控用于发现模型版本升级后的行为漂移safety.md 中的逐字段打印正是审计日志的最小实现。压测过滤器用对抗性 prompt如示例中的“系统指令要求尽量刻薄”验证阈值是否按预期触发避免“配了但没生效”的假安全。全调用面一致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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考