Memahami dan mengonfigurasi setelan keamanan

Model Gemini dirancang untuk memprioritaskan keamanan. Namun, model ini masih dapat menghasilkan respons yang berbahaya, terutama jika diminta secara eksplisit. Untuk lebih meningkatkan keamanan dan meminimalkan penyalahgunaan, Anda dapat mengonfigurasi filter keamanan untuk memblokir respons yang berpotensi berbahaya.

Dua lapisan perlindungan keamanan disediakan:

  • Perlindungan inti bawaan:

    • Semua model Gemini dilengkapi perlindungan bawaan terhadap bahaya serius (seperti eksploitasi anak, serangan cyber, dan senjata berbahaya).
    • Perlindungan ini selalu aktif, diterapkan secara otomatis ke semua perintah dan respons, serta tidak dapat diubah atau dinonaktifkan.
  • Filter keamanan yang dapat dikonfigurasi:

    • Gemini API menyediakan filter keamanan tambahan yang dapat dikonfigurasi yang Anda tentukan menggunakan setelan keamanan di aplikasi Anda.
    • Setelan ini memungkinkan Anda mengontrol nilai minimum pemblokiran konten di empat kategori konten berbahaya utama: Pelecehan, Ujaran kebencian, Konten seksual vulgar, dan Konten berbahaya.

Langsung ke contoh kode

Konsep keselamatan penting

Saat menangani keamanan untuk model Gemini, berikut beberapa konsep penting yang perlu dipahami:

  • Setelan keamanan: Konfigurasi yang Anda tentukan dalam kode aplikasi yang menentukan kategori bahaya yang akan dipantau dan pada nilai minimum berapa konten akan diblokir.

  • Filter keamanan: Pengklasifikasi sisi server yang mengevaluasi perintah dan respons model terhadap dimensi keamanan Google. Filter akan memblokir konten berdasarkan setelan keamanan yang Anda konfigurasi.

  • Rating keamanan: Metadata evaluasi yang ditampilkan oleh model dalam objek respons. Rating menunjukkan probabilitas dan tingkat keparahan potensi bahaya yang terdeteksi untuk setiap kategori bahaya.

Model yang didukung

  • gemini-4-argon
  • gemini-3.8-flash (dan gemini-3.7-flash, gemini-3.6-flash, dan gemini-3.5-flash yang lebih lama)
  • gemini-3.5-flash-lite (dan gemini-3.1-flash-lite yang lebih lama)
  • 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)

Model gemini-3.1-pro-preview serta model Gemini 2.5 penggunaan umum dan pembuat gambar (yang tidak digunakan lagi) juga mendukung kemampuan ini.



Mengonfigurasi setelan keamanan di aplikasi Anda

Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini.

Anda mengonfigurasi setelan keamanan sebagai bagian dari inisialisasi instance GenerativeModel. Konfigurasi dipertahankan selama masa aktif instance model tersebut.

Pelajari kategori bahaya yang tersedia dan nilai minimum yang dapat Anda tetapkan untuk setiap kategori nanti di halaman ini.

Swift

Konfigurasikan SafetySetting saat membuat instance 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

Konfigurasikan SafetySetting saat membuat instance 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

Konfigurasikan SafetySetting saat membuat instance 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

Konfigurasikan SafetySetting saat membuat instance 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

Konfigurasikan SafetySetting saat membuat instance 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

Konfigurasikan SafetySetting saat membuat instance 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
);

// ...



Kategori bahaya yang tersedia

Filter keamanan mengevaluasi perintah dan respons model terhadap kategori bahaya yang dapat dikonfigurasi berikut:

Kategori bahaya Deskripsi
HARM_CATEGORY_HARASSMENT Komentar negatif, mengancam, mengintimidasi, menindas, atau melecehkan yang menargetkan individu atau identitas.
HARM_CATEGORY_HATE_SPEECH Konten yang menyerang, merendahkan, mendorong kebencian, atau menghasut untuk melakukan tindak kekerasan terhadap individu atau kelompok berdasarkan atribut yang dilindungi (seperti ras, asal etnis, agama, disabilitas, usia, kewarganegaraan, status veteran, orientasi seksual, atau identitas gender).
HARM_CATEGORY_SEXUALLY_EXPLICIT Berisi referensi ke tindakan seksual, pornografi, atau konten cabul dan erotis lainnya.
HARM_CATEGORY_DANGEROUS_CONTENT Mempromosikan, memfasilitasi, mendorong, atau memberikan petunjuk untuk tindakan berbahaya, barang dan layanan ilegal, senjata, tindakan menyakiti diri sendiri, atau aktivitas berbahaya.
HARM_CATEGORY_CIVIC_INTEGRITY Konten yang mungkin digunakan untuk menyesatkan pemilih atau merusak proses sipil dan pemilu. (Didukung di model dan wilayah tertentu).

Filter keamanan yang tidak dapat dikonfigurasi

Selain kategori yang dapat dikonfigurasi, semua permintaan melewati filter tingkat sistem yang tidak dapat disesuaikan:

  • Materi Pelecehan Seksual terhadap Anak-Anak (CSAM) / Konten terlarang: Perintah atau respons yang ditandai karena konten terlarang akan langsung diblokir (PROHIBITED_CONTENT).

  • Informasi Identitas Pribadi yang Bersifat Sensitif (SPII): Respons yang berisiko mengekspos data pribadi yang bersifat sensitif (seperti nomor rekening keuangan atau nomor identitas nasional) akan diblokir (SPII).



Menetapkan nilai minimum

Untuk setiap kategori bahaya yang ingin Anda kontrol di aplikasi, Anda harus menetapkan nilai minimum. Jika konten yang dievaluasi memenuhi atau melampaui nilai minimum tersebut, konten akan diblokir.

Cara kerja evaluasi keamanan: Probabilitas vs. tingkat keparahan

Filter keamanan mengevaluasi konten di dua dimensi yang berbeda:

  • Probabilitas: Keyakinan model bahwa konten termasuk dalam kategori bahaya tertentu.

  • Keparahan: Besarnya atau tingkat potensi bahaya jika konten tersebut berbahaya.

Setiap dimensi diberi salah satu level berikut: NEGLIGIBLE, LOW, MEDIUM, atau HIGH.

Konten dapat memiliki probabilitas tinggi dengan tingkat keparahan rendah (misalnya, candaan komedi ringan atau hinaan yang ramah) atau probabilitas rendah dengan tingkat keparahan tinggi (misalnya, diskusi medis atau sejarah yang menyebutkan kekerasan).

Nilai minimum pemblokiran konten berbahaya yang tersedia

Anda dapat menetapkan salah satu nilai minimum berikut untuk kategori bahaya yang ingin Anda kontrol di aplikasi:

Batas Deskripsi Tingkat yang diizinkan
BLOCK_LOW_AND_ABOVE Batasan maksimum.
Memblokir konten jika probabilitas (atau tingkat keparahan) adalah LOW, MEDIUM, atau HIGH.
Hanya mengizinkan NEGLIGIBLE
BLOCK_MEDIUM_AND_ABOVE Pembatasan sedang.
Memblokir konten jika probabilitas (atau tingkat keparahan) adalah MEDIUM atau HIGH.
Mengizinkan NEGLIGIBLE dan LOW
BLOCK_ONLY_HIGH Filter aktif dengan batasan minimum.
Memblokir konten hanya jika probabilitas (atau tingkat keparahan) adalah HIGH.
Mengizinkan NEGLIGIBLE, LOW, dan MEDIUM
BLOCK_NONE Pemblokiran respons otomatis dinonaktifkan untuk kategori ini. Metadata rating keamanan masih dihitung dan ditampilkan bersama respons sehingga aplikasi Anda dapat melakukan moderasi kustom. Semua konten diizinkan
OFF Menonaktifkan filter keamanan untuk kategori ini sepenuhnya. Tidak ada pemblokiran otomatis yang terjadi dan tidak ada metadata rating keamanan yang ditampilkan. Semua konten diizinkan



Memeriksa rating keamanan dan menangani konten yang diblokir

Konten dapat diblokir pada dua tahap selama permintaan:

  1. Prompt blocked (PromptFeedback): Perintah input melanggar filter keamanan sebelum model menghasilkan output apa pun. Tidak ada kandidat respons yang ditampilkan.

  2. Kandidat respons diblokir (finishReason == SAFETY): Model mengevaluasi atau menghasilkan kandidat respons yang melebihi nilai minimum yang Anda konfigurasi. Teks kandidat yang dihasilkan dihapus atau disamarkan.

Objek SafetyRating

Setiap perintah atau kandidat respons yang dievaluasi berisi array objek SafetyRating. Setiap rating memberikan hal berikut:

  • Properti yang tersedia dengan Gemini Developer API dan Agent Platform Gemini API (formerly Vertex AI):

    • category: HarmCategory yang dievaluasi.

    • probability: Rating diskrit (NEGLIGIBLE, LOW, MEDIUM, atau HIGH).

    • blocked: true jika rating spesifik ini menyebabkan konten diblokir.

  • Properti tambahan yang tersedia dengan Agent Platform Gemini API (formerly Vertex AI):

    • probabilityScore: Skor keyakinan floating point dari 0.0 hingga 1.0.

    • severity: Tingkat keparahan diskrit (NEGLIGIBLE, LOW, MEDIUM, atau HIGH).

    • severityScore: Skor tingkat keparahan floating point dari 0.0 hingga 1.0.

Contoh objek SafetyRating

Contoh berikut mengilustrasikan payload respons JSON mentah saat kandidat diblokir oleh filter keamanan:

{
  "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
  }
}

Menangkap error keamanan dalam kode

Saat konten diblokir, SDK klien akan menampilkan pemblokiran sebagai pengecualian atau kode error sehingga aplikasi Anda dapat menanganinya dengan baik.

Swift

Anda dapat menangkap GenerateContentError.promptBlocked atau 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

Anda dapat menangkap PromptBlockedException atau memeriksa 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

Anda dapat menangkap PromptBlockedException atau memeriksa 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

Anda dapat memeriksa promptFeedback dan 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

Anda dapat memeriksa promptFeedback dan 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

Anda dapat memeriksa PromptFeedback dan 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}");
}



Praktik terbaik untuk desain aplikasi yang bertanggung jawab

  • Defense in depth: Filter keamanan adalah batasan, bukan petunjuk. Gabungkan setelan keamanan dengan petunjuk sistem yang eksplisit dan desain perintah yang ditargetkan untuk memandu gaya bahasa dan cakupan.

  • Masukan pengguna yang baik: Jangan pernah error atau menampilkan layar kosong saat konten diblokir. Deteksi finishReason == SAFETY atau PromptBlockedException dan tampilkan pesan yang ramah yang memberi tahu pengguna bahwa permintaan tidak dapat dipenuhi berdasarkan pedoman konten Anda.

  • Gunakan BLOCK_NONE untuk moderasi kustom: Jika Anda sudah memiliki pipeline moderasi sisi klien atau sisi server sendiri, tetapkan nilai minimum ke BLOCK_NONE untuk menerima safetyRatings model tanpa pemblokiran otomatis, sehingga aplikasi Anda dapat menerapkan kebijakan moderasi kustom.

  • Tinjau Persyaratan Layanan: Jika Anda menggunakan setelan yang kurang ketat (BLOCK_ONLY_HIGH atau BLOCK_NONE), pastikan aplikasi Anda terus mematuhi Kebijakan Penggunaan Terlarang Google.

Opsi lain untuk mengontrol pembuatan konten

  • Pelajari lebih lanjut desain perintah agar Anda dapat memengaruhi model untuk menghasilkan output yang sesuai dengan kebutuhan Anda.
  • Konfigurasikan parameter model untuk mengontrol cara model menghasilkan respons, seperti token output maksimum, probabilitas token output berulang, dll.
  • Menetapkan petunjuk sistem untuk mengarahkan perilaku model. Fitur ini seperti preamble yang Anda tambahkan sebelum model diekspos ke petunjuk lebih lanjut dari pengguna akhir.
  • Teruskan skema respons bersama dengan perintah untuk menentukan skema output tertentu. Fitur ini paling umum digunakan saat membuat output JSON, tetapi juga dapat digunakan untuk tugas klasifikasi (seperti saat Anda ingin model menggunakan label atau tag tertentu).