Entender e definir as configurações de segurança

Os modelos do Gemini foram criados para priorizar a segurança. No entanto, eles ainda podem gerar respostas prejudiciais, especialmente quando são explicitamente solicitados. Para aumentar ainda mais a segurança e minimizar o uso indevido, você pode configurar filtros de segurança para bloquear respostas potencialmente perigosas.

Há duas camadas de proteção:

  • Proteções principais integradas:

    • Todos os modelos do Gemini têm proteções integradas contra danos graves, como exploração infantil, ataques cibernéticos e armas perigosas.
    • Essas proteções estão sempre ativas, são aplicadas automaticamente a todos os comandos e respostas e não podem ser modificadas ou desativadas.
  • Filtros de segurança configuráveis:

    • O Gemini API oferece filtros de segurança configuráveis adicionais, que você define usando as configurações de segurança no app.
    • Com essas configurações, você controla o limite em que o conteúdo é bloqueado em quatro categorias de danos principais: assédio, discurso de ódio, conteúdo sexualmente explícito e conteúdo perigoso.

Ir para exemplos de código

Conceitos de segurança importantes

Ao trabalhar com segurança para modelos do Gemini, é importante entender alguns conceitos:

  • Configurações de segurança: a configuração definida no código do app que especifica quais categorias de conteúdo nocivo monitorar e em qual limite bloquear o conteúdo.

  • Filtros de segurança: os classificadores do lado do servidor que avaliam os comandos e as respostas do modelo em relação às dimensões de segurança do Google. Os filtros bloqueiam conteúdo com base nas configurações de segurança definidas.

  • Classificações de segurança: os metadados de avaliação retornados pelo modelo no objeto de resposta. As classificações indicam a probabilidade e a gravidade do dano potencial detectado para cada categoria.

Modelos compatíveis

  • gemini-4-argon
  • gemini-3.8-flash (e as versões mais antigas gemini-3.7-flash, gemini-3.6-flash e gemini-3.5-flash)
  • gemini-3.5-flash-lite (e o gemini-3.1-flash-lite mais antigo)
  • gemini-nano-banana-2.1 (Nano Banana 2.1)
  • gemini-3.1-flash-image (Nano Banana 2)
  • gemini-3.1-flash-lite-image (Nano Banana 2 Lite)
  • gemini-3-pro-image (Nano Banana Pro)

O modelo gemini-3.1-pro-preview, bem como os modelos Gemini 2.5 de uso geral e de geração de imagens (que foram descontinuados), também são compatíveis com esse recurso.



Definir as configurações de segurança no app

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

As configurações de segurança são definidas como parte da inicialização de uma instância GenerativeModel. A configuração é mantida durante o ciclo de vida dessa instância de modelo.

Saiba mais sobre as categorias de danos disponíveis e os limites que podem ser definidos para cada categoria mais adiante nesta página.

Swift

Configure SafetySetting ao criar uma instância do GenerativeModel:


import FirebaseAILogic

let safetySettings = [
  SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh),
  SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)
]

// Specify the safety settings as part of creating the `GenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .googleAI()).generativeModel(
  modelName: "GEMINI_MODEL_NAME",
  safetySettings: safetySettings
)

// ...

Kotlin

Configure SafetySetting ao criar uma instância de GenerativeModel:


// ...

val safetySettings = listOf(
    SafetySetting(HarmCategory.HARASSMENT, HarmBlockThreshold.ONLY_HIGH),
    SafetySetting(HarmCategory.HATE_SPEECH, HarmBlockThreshold.MEDIUM_AND_ABOVE)
)

// Specify the safety settings as part of creating the `GenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    safetySettings = safetySettings
)

// ...

Java

Configure SafetySetting ao criar uma instância de GenerativeModel:


// ...

List safetySettings = List.of(
    new SafetySetting(HarmCategory.HARASSMENT, HarmBlockThreshold.ONLY_HIGH),
    new SafetySetting(HarmCategory.HATE_SPEECH, HarmBlockThreshold.MEDIUM_AND_ABOVE)
);

// Specify the safety settings as part of creating the `GenerativeModel` instance.
GenerativeModelFutures model = GenerativeModelFutures.from(
    FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel(
            /* modelName */ "GEMINI_MODEL_NAME",
            /* generationConfig is optional */ null,
            safetySettings
        )
);

// ...

Web

Configure SafetySetting ao criar uma instância de GenerativeModel:


import { HarmBlockThreshold, HarmCategory, getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// ...

const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

// Specify the safety settings as part of creating the `GenerativeModel` instance.
const model = getGenerativeModel(ai, {
  model: "GEMINI_MODEL_NAME",
  safetySettings,
});

// ...

Dart

Configure SafetySetting ao criar uma instância de GenerativeModel:


import 'package:firebase_ai/firebase_ai.dart';

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.medium),
];

// Specify the safety settings as part of creating the `GenerativeModel` instance.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  safetySettings: safetySettings,
);

// ...

Unity

Configure SafetySetting ao criar uma instância de GenerativeModel:


// ...

var safetySettings = new SafetySetting[] {
  new SafetySetting(HarmCategory.Harassment, SafetySetting.HarmBlockThreshold.OnlyHigh),
  new SafetySetting(HarmCategory.HateSpeech, SafetySetting.HarmBlockThreshold.MediumAndAbove)
};

// Specify the safety settings as part of creating the `GenerativeModel` instance.
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  safetySettings: safetySettings
);

// ...



Categorias de dano disponíveis

Os filtros de segurança avaliam os comandos e as respostas do modelo em relação às seguintes categorias de danos configuráveis:

Categoria de dano Descrição
HARM_CATEGORY_HARASSMENT Comentários negativos, ameaçadores, intimidadores, abusivos ou de bullying direcionados a uma pessoa ou identidade.
HARM_CATEGORY_HATE_SPEECH Conteúdo que ataque, menospreze, promova o ódio ou incite a violência contra indivíduos ou grupos com base em atributos protegidos (como raça, origem étnica, religião, deficiência, idade, nacionalidade, status de veterano, orientação sexual ou identidade de gênero).
HARM_CATEGORY_SEXUALLY_EXPLICIT Contém referências a atos sexuais, pornografia ou outro conteúdo obsceno e erótico.
HARM_CATEGORY_DANGEROUS_CONTENT Promove, facilita, incentiva ou fornece instruções para atos prejudiciais, produtos e serviços ilegais, armas, automutilação ou atividades perigosas.
HARM_CATEGORY_CIVIC_INTEGRITY Conteúdo que possa ser usado para enganar eleitores ou prejudicar processos cívicos e eleitorais. (Disponível em alguns modelos e regiões).

Filtros de segurança não configuráveis

Além das categorias configuráveis, todas as solicitações passam por filtros no nível do sistema que não podem ser ajustados:

  • Material de abuso sexual infantil (CSAM, na sigla em inglês) / Conteúdo proibido: comandos ou respostas sinalizados por conteúdo proibido são bloqueados imediatamente (PROHIBITED_CONTENT).

  • Informações sensíveis de identificação pessoal (SPII): as respostas que correm o risco de expor dados pessoais sensíveis (como números de contas financeiras ou documentos de identificação nacional) são bloqueadas (SPII).



Definir limites

Para cada categoria de dano que você quer controlar no app, é necessário definir um limite. Se o conteúdo avaliado atingir ou exceder esse limite, ele será bloqueado.

Como funciona a avaliação de segurança: probabilidade x gravidade

Os filtros de segurança avaliam o conteúdo em duas dimensões distintas:

  • Probabilidade: a confiança do modelo de que o conteúdo se enquadra em uma determinada categoria de dano.

  • Gravidade: a magnitude ou o grau de dano potencial se o conteúdo for prejudicial.

Cada dimensão recebe um destes níveis: NEGLIGIBLE, LOW, MEDIUM ou HIGH.

O conteúdo pode ter uma alta probabilidade com baixo nível de gravidade (por exemplo, brincadeiras leves ou insultos amigáveis) ou baixa probabilidade com alto nível de gravidade (por exemplo, discussões médicas ou históricas que mencionam violência).

Limites de bloqueio de conteúdo nocivo disponíveis

É possível definir qualquer um dos seguintes limites para as categorias de conteúdo nocivo que você quer controlar no app:

Limite Descrição Níveis permitidos
BLOCK_LOW_AND_ABOVE Mais restritiva.
Bloqueia o conteúdo quando a probabilidade (ou gravidade) é LOW, MEDIUM ou HIGH.
Permite apenas NEGLIGIBLE
BLOCK_MEDIUM_AND_ABOVE Restrição moderada.
Bloqueia o conteúdo quando a probabilidade (ou gravidade) é MEDIUM ou HIGH.
Permite NEGLIGIBLE e LOW
BLOCK_ONLY_HIGH Filtro ativo menos restritivo.
Bloqueia o conteúdo somente quando a probabilidade (ou gravidade) é HIGH.
Permite NEGLIGIBLE, LOW e MEDIUM
BLOCK_NONE O bloqueio de respostas automáticas está desativado para esta categoria. Os metadados de classificações de segurança ainda são calculados e retornados com a resposta para que seu app possa realizar uma moderação personalizada. Todo o conteúdo é permitido
OFF Desativa totalmente o filtro de segurança para essa categoria. Nenhum bloqueio automatizado ocorre e nenhum metadado de classificação de segurança é retornado. Todo o conteúdo é permitido



Inspecionar classificações de segurança e lidar com conteúdo bloqueado

O conteúdo pode ser bloqueado em dois estágios durante uma solicitação:

  1. Comando bloqueado (PromptFeedback): o comando de entrada violou os filtros de segurança antes que o modelo gerasse qualquer saída. Nenhuma resposta candidata é retornada.

  2. Resposta candidata bloqueada (finishReason == SAFETY): o modelo avaliou ou gerou uma resposta candidata que excedeu o limite configurado. O texto candidato gerado é apagado ou editado.

O objeto SafetyRating

Cada comando ou resposta candidata avaliada contém uma matriz de objetos SafetyRating. Cada classificação fornece o seguinte:

  • Propriedades disponíveis com Gemini Developer API e Agent Platform Gemini API (formerly Vertex AI):

    • category: o HarmCategory avaliado.

    • probability: uma classificação discreta (NEGLIGIBLE, LOW, MEDIUM ou HIGH).

    • blocked: true se essa classificação específica fez com que o conteúdo fosse bloqueado.

  • Outras propriedades disponíveis com o Agent Platform Gemini API (formerly Vertex AI):

    • probabilityScore: uma pontuação de confiança de usar pontos flutuantes de 0.0 a 1.0.

    • severity: um nível de gravidade discreto (NEGLIGIBLE, LOW, MEDIUM ou HIGH).

    • severityScore: uma pontuação de gravidade de usar pontos flutuantes de 0.0 a 1.0.

Exemplo de objeto SafetyRating

O exemplo a seguir ilustra o payload de resposta JSON bruto quando um candidato é bloqueado por filtros de segurança:

{
  "candidates": [
    {
      "finishReason": "SAFETY",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "HIGH",
          "blocked": true
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "totalTokenCount": 24
  }
}

Detectar erros de segurança no código

Quando o conteúdo é bloqueado, os SDKs do cliente mostram o bloqueio como uma exceção ou um código do erro para que o app possa lidar com isso de forma adequada.

Swift

É possível capturar GenerateContentError.promptBlocked ou GenerateContentError.responseStoppedEarly:

do {
  let response = try await model.generateContent("Your prompt here")
  print(response.text ?? "No text generated.")
} catch GenerateContentError.promptBlocked(let response) {
  // The input prompt was blocked
  if let feedback = response.promptFeedback {
    let reason = feedback.blockReason?.rawValue ?? "unknown"
    print("Prompt blocked for reason: \(reason)")
    for rating in feedback.safetyRatings {
      let cat = rating.category.rawValue
      let prob = rating.probability.rawValue
      print("Category: \(cat), probability: \(prob)")
    }
  }
} catch GenerateContentError.responseStoppedEarly(let reason, let response) {
  // Candidate response was blocked or stopped early
  if reason == .safety {
    print("Response blocked due to safety.")
    if let candidate = response.candidates.first {
      for rating in candidate.safetyRatings where rating.blocked {
        print("Blocked by category: \(rating.category.rawValue)")
      }
    }
  }
} catch {
  print("Unexpected error: \(error)")
}

Kotlin

É possível capturar PromptBlockedException ou inspecionar candidate.finishReason:

try {
  val response = model.generateContent("Your prompt here")
  val candidate = response.candidates.firstOrNull()

  if (candidate?.finishReason == FinishReason.SAFETY) {
    val blockedRating =
      candidate.safetyRatings.firstOrNull { it.blocked }
    println("Response blocked by category: ${blockedRating?.category}")
  } else {
    println(response.text)
  }
} catch (e: PromptBlockedException) {
  val reason = e.response?.promptFeedback?.blockReason
  println("Prompt was blocked: $reason")
} catch (e: Exception) {
  println("Error generating content: ${e.message}")
}

Java

É possível capturar PromptBlockedException ou inspecionar candidate.getFinishReason():

try {
  GenerateContentResponse response = model.generateContent("Your prompt here").get();
  Candidate candidate = response.getCandidates().isEmpty() ? null : response.getCandidates().get(0);

  if (candidate != null && candidate.getFinishReason() == FinishReason.SAFETY) {
    SafetyRating blockedRating = null;
    for (SafetyRating rating : candidate.getSafetyRatings()) {
      if (Boolean.TRUE.equals(rating.getBlocked())) {
        blockedRating = rating;
        break;
      }
    }
    System.out.println("Response blocked by category: " +
        (blockedRating != null ? blockedRating.getCategory() : "unknown"));
  } else {
    System.out.println(response.getText());
  }
} catch (ExecutionException e) {
  if (e.getCause() instanceof PromptBlockedException) {
    PromptBlockedException pbe = (PromptBlockedException) e.getCause();
    GenerateContentResponse blockedResponse = pbe.getResponse();
    String reason = (blockedResponse != null && blockedResponse.getPromptFeedback() != null)
        ? String.valueOf(blockedResponse.getPromptFeedback().getBlockReason())
        : "unknown";
    System.out.println("Prompt was blocked: " + reason);
  } else {
    System.out.println("Error generating content: " + e.getMessage());
  }
} catch (InterruptedException e) {
  System.out.println("Generation was interrupted: " + e.getMessage());
}

Web

É possível inspecionar promptFeedback e candidate.finishReason:

try {
  const response = await model.generateContent("Your prompt here");

  // Check if the prompt was blocked
  if (response.promptFeedback?.blockReason) {
    console.warn(`Prompt blocked: ${response.promptFeedback.blockReason}`);
    return;
  }

  const candidate = response.candidates?.[0];
  if (candidate?.finishReason === "SAFETY") {
    const blockedRating = candidate.safetyRatings?.find((r) => r.blocked);
    console.warn(`Response blocked by category: ${blockedRating?.category}`);
  } else {
    console.log(response.text);
  }
} catch (error) {
  console.error("Error generating content:", error);
}

Dart

É possível inspecionar promptFeedback e candidate.finishReason:

try {
  final response = await model.generateContent([Content.text('Your prompt here')]);

  // Check if the prompt was blocked
  if (response.promptFeedback?.blockReason != null) {
    print('Prompt blocked: ${response.promptFeedback?.blockReason}');
    return;
  }

  final candidate = response.candidates.firstOrNull;
  if (candidate?.finishReason == FinishReason.safety) {
    final blockedRating =
        candidate?.safetyRatings?.where((r) => r.isBlocked == true).firstOrNull;
    print('Response blocked by category: ${blockedRating?.category.name}');
  } else {
    print(response.text);
  }
} catch (e) {
  print('Error generating content: $e');
}

Unity

É possível inspecionar PromptFeedback e candidate.FinishReason:

try {
  var response = await model.GenerateContentAsync("Your prompt here");

  // Check if the prompt was blocked
  if (response.PromptFeedback?.BlockReason != null) {
    Debug.LogWarning($"Prompt blocked: {response.PromptFeedback.BlockReason}");
    return;
  }

  var candidate = response.Candidates.FirstOrDefault();
  if (candidate?.FinishReason == FinishReason.Safety) {
    var blockedRating = candidate.SafetyRatings?.FirstOrDefault(r => r.Blocked);
    Debug.LogWarning($"Response blocked by category: {blockedRating?.Category}");
  } else {
    Debug.Log(response.Text);
  }
} catch (Exception ex) {
  Debug.LogError($"Error generating content: {ex.Message}");
}



Práticas recomendadas para design responsável de apps

  • Defesa em profundidade: os filtros de segurança são uma proteção, não uma instrução. Combine as configurações de segurança com instruções do sistema explícitas e design de comandos direcionado para orientar o tom e o escopo.

  • Feedback do usuário: nunca falhe ou mostre uma tela em branco quando o conteúdo estiver bloqueado. Detecte finishReason == SAFETY ou PromptBlockedException e mostre uma mensagem amigável informando ao usuário que a solicitação não pôde ser atendida de acordo com suas diretrizes de conteúdo.

  • Use BLOCK_NONE para moderação personalizada: se você já tiver seu próprio pipeline de moderação do lado do cliente ou do lado do servidor, defina limites como BLOCK_NONE para receber o safetyRatings do modelo sem bloqueio automático, permitindo que seu app aplique políticas de moderação personalizadas.

  • Revise os Termos de Serviço: se você usar configurações menos restritivas (BLOCK_ONLY_HIGH ou BLOCK_NONE), verifique se o app continua em conformidade com a Política de uso proibido do Google.

Outras opções para controlar a geração de conteúdo

  • Saiba mais sobre o design de comandos para influenciar o modelo a gerar saídas específicas para suas necessidades.
  • Configure os parâmetros do modelo para controlar como o modelo gera uma resposta, como o máximo de tokens de saída, a probabilidade de tokens de saída repetidos etc.
  • Defina instruções do sistema para orientar o comportamento do modelo. Esse recurso é como um preâmbulo que você adiciona antes que o modelo seja exposto a outras instruções do usuário final.
  • Transmita um esquema de resposta com o comando para especificar um esquema de saída específico. Esse recurso é usado com frequência ao gerar saída JSON, mas também pode ser usado para tarefas de classificação, como quando você quer que o modelo use rótulos ou tags específicos.