Güvenlik ayarlarını anlama ve yapılandırma

Gemini modelleri, güvenliğe öncelik verecek şekilde tasarlanmıştır. Ancak özellikle açıkça istendiğinde zararlı yanıtlar üretmeye devam edebilirler. Güvenliği daha da artırmak ve kötüye kullanımı en aza indirmek için güvenlik filtrelerini yapılandırarak zararlı olabilecek yanıtları engelleyebilirsiniz.

İki güvenlik koruması katmanı sağlanır:

  • Yerleşik temel korumalar:

    • Tüm Gemini modellerinde ciddi zararlara (ör. çocuk istismarı, siber saldırılar ve tehlikeli silahlar) karşı yerleşik koruma özellikleri bulunur.
    • Bu korumalar her zaman etkindir, tüm istemlere ve yanıtlara otomatik olarak uygulanır ve değiştirilemez veya devre dışı bırakılamaz.
  • Ayarlanabilir güvenlik filtreleri:

    • Gemini API, uygulamanızdaki güvenlik ayarlarını kullanarak tanımladığınız ek yapılandırılabilir güvenlik filtreleri sunar.
    • Bu ayarlar, dört ana zarar kategorisinde (Taciz, Nefret söylemi, Müstehcen içerik ve Tehlikeli içerik) içeriğin engelleneceği eşik değerini kontrol etmenizi sağlar.

Kod örneklerine git

Önemli güvenlik kavramları

Gemini modellerinde güvenlikle ilgili çalışırken anlamanız gereken bazı önemli kavramlar şunlardır:

  • Güvenlik ayarları: Uygulama kodunuzda tanımladığınız yapılandırma. Bu yapılandırma, hangi zarar kategorilerinin izleneceğini ve içeriğin hangi eşikte engelleneceğini belirtir.

  • Güvenlik filtreleri: İstemleri ve model yanıtlarını Google'ın güvenlik boyutlarına göre değerlendiren sunucu tarafı sınıflandırıcılar. Filtreler, yapılandırdığınız güvenlik ayarlarına göre içerikleri engeller.

  • Güvenlik derecelendirmeleri: Model tarafından yanıt nesnesinde döndürülen değerlendirme meta verileri. Derecelendirmeler, her bir zarar kategorisi için tespit edilen potansiyel zararın olasılığını ve önem derecesini gösterir.

Desteklenen modeller

  • gemini-4-argon
  • gemini-3.8-flash (ve daha eski gemini-3.7-flash, gemini-3.6-flash ve gemini-3.5-flash)
  • gemini-3.5-flash-lite (ve daha eski gemini-3.1-flash-lite)
  • 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)

gemini-3.1-pro-preview modelinin yanı sıra genel kullanıma yönelik ve görüntü üreten Gemini 2.5 modelleri de (desteği sonlandırılmıştır) bu özelliği destekler.



Uygulamanızda güvenlik ayarlarını yapılandırma

Bu sayfada sağlayıcıya özel içerik ve kodları görüntülemek için Gemini API sağlayıcınızı tıklayın.

Güvenlik ayarlarını, bir GenerativeModel örneğini başlatma işleminin parçası olarak yapılandırırsınız. Yapılandırma, ilgili model örneğinin kullanım ömrü boyunca korunur.

Kullanılabilir zarar kategorileri ve her kategori için ayarlayabileceğiniz eşikler hakkında daha fazla bilgiyi bu sayfanın ilerleyen bölümlerinde bulabilirsiniz.

Swift

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


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

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


// ...

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

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


// ...

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

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


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

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


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

GenerativeModel örneği oluştururken SafetySetting yapılandırın:


// ...

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
);

// ...



Mevcut zarar kategorileri

Güvenlik filtreleri, istemleri ve model yanıtlarını aşağıdaki yapılandırılabilir zarar kategorilerine göre değerlendirir:

Zarar kategorisi Açıklama
HARM_CATEGORY_HARASSMENT Bir kişiyi veya kimliği hedef alan olumsuz, tehdit edici, korkutucu, zorbalık içeren ya da kötüye kullanım amaçlı yorumlar
HARM_CATEGORY_HATE_SPEECH Korunan özelliklere (ör. ırk, etnik köken, din, engellilik, yaş, milliyet, gazilik durumu, cinsel yönelim veya cinsiyet kimliği) dayalı olarak bireylere ya da gruplara saldıran, onları aşağılayan, onlara karşı nefreti teşvik eden veya şiddeti kışkırtan içerikler.
HARM_CATEGORY_SEXUALLY_EXPLICIT Cinsel eylemlere, pornografiye veya diğer müstehcen ve erotik içeriklere referanslar içeriyor.
HARM_CATEGORY_DANGEROUS_CONTENT Zararlı eylemleri, yasa dışı ürün ve hizmetleri, silahları, kendine zarar vermeyi veya tehlikeli faaliyetleri teşvik eden, kolaylaştıran, destekleyen ya da bunlarla ilgili talimatlar veren içerikler
HARM_CATEGORY_CIVIC_INTEGRITY Seçmenleri yanıltmak veya sivil ve seçim süreçlerini baltalamak için kullanılabilecek içerikler. (Belirli modellerde ve bölgelerde desteklenir).

Yapılandırılamayan güvenlik filtreleri

Yapılandırılabilir kategorilere ek olarak tüm istekler, ayarlanamayan sistem düzeyindeki filtrelerden geçer:

  • Çocukların cinsel istismarı nitelikli materyal (CSAM) / Yasaklanmış içerik: Yasaklanmış içerik olarak işaretlenen istemler veya yanıtlar hemen engellenir (PROHIBITED_CONTENT).

  • Hassas Kişisel Veriler (SPII): Hassas kişisel verilerin (ör. finansal hesap numaraları veya ulusal kimlikler) ifşa edilme riski taşıyan yanıtlar engellenir (SPII).



Eşik belirleme

Uygulamanızda kontrol etmek istediğiniz her zarar kategorisi için bir eşik belirlemeniz gerekir. Değerlendirilen içerik bu eşiği karşılıyor veya aşıyorsa içerik engellenir.

Güvenlik değerlendirmesinin işleyiş şekli: Olasılık ve önem derecesi

Güvenlik filtreleri, içeriği iki farklı boyutta değerlendirir:

  • Olasılık: Modelin, içeriğin belirli bir zarar kategorisine girdiğine dair güveni.

  • Önem derecesi: İçeriğin zararlı olması durumunda ortaya çıkabilecek potansiyel zararın büyüklüğü veya derecesi.

Her boyuta şu seviyelerden biri atanır: NEGLIGIBLE, LOW, MEDIUM veya HIGH.

İçerik, düşük önem düzeyinde yüksek olasılığa (ör. hafif komedi şakaları veya arkadaşça hakaretler) ya da yüksek önem düzeyinde düşük olasılığa (ör. şiddetten bahseden tıbbi veya tarihi tartışmalar) sahip olabilir.

Kullanılabilir zararlı içerik engelleme eşikleri

Uygulamanızda kontrol etmek istediğiniz zarar kategorileri için aşağıdaki eşiklerden herhangi birini ayarlayabilirsiniz:

Eşik Açıklama İzin verilen seviyeler
BLOCK_LOW_AND_ABOVE En kısıtlayıcı.
Olasılık (veya önem derecesi) LOW, MEDIUM veya HIGH olduğunda içeriği engeller.
Yalnızca NEGLIGIBLE için izin verir.
BLOCK_MEDIUM_AND_ABOVE Orta düzeyde kısıtlama.
Olasılık (veya önem derecesi) MEDIUM ya da HIGH olduğunda içeriği engeller.
NEGLIGIBLE ve LOW için izin verir
BLOCK_ONLY_HIGH En az kısıtlayıcı etkin filtre.
İçeriği yalnızca olasılık (veya önem derecesi) HIGH olduğunda engeller.
NEGLIGIBLE, LOW ve MEDIUM uygulamalarına izin verir.
BLOCK_NONE Otomatik yanıt engelleme bu kategori için devre dışı bırakıldı. Güvenlik derecelendirmesi meta verileri hesaplanmaya ve yanıtla birlikte döndürülmeye devam eder. Böylece uygulamanız özel moderasyon gerçekleştirebilir. Tüm içeriklere izin verilir.
OFF Bu kategori için güvenlik filtresini tamamen devre dışı bırakır. Otomatik engelleme yapılmaz ve güvenlik derecelendirmesi meta verileri döndürülmez. Tüm içeriklere izin verilir.



Güvenlik puanlarını inceleme ve engellenen içerikleri yönetme

İçerik, istek sırasında iki aşamada engellenebilir:

  1. İstem engellendi (PromptFeedback): Giriş istemi, model herhangi bir çıkış oluşturmadan önce güvenlik filtrelerini ihlal etti. Yanıt adayı döndürülmez.

  2. Yanıt adayı engellendi (finishReason == SAFETY): Model, yapılandırılmış eşiğinizi aşan bir yanıt adayını değerlendirdi veya oluşturdu. Oluşturulan aday metin temizlenir veya çıkartılır.

SafetyRating nesnesi

Değerlendirilen her istem veya yanıt adayı, bir SafetyRating nesnesi dizisi içerir. Her derecelendirme aşağıdaki bilgileri sağlar:

  • Hem Gemini Developer API hem de Agent Platform Gemini API (formerly Vertex AI) ile kullanılabilen mülkler:

    • category: Değerlendirilen HarmCategory.

    • probability: Ayrık bir derecelendirme (NEGLIGIBLE, LOW, MEDIUM veya HIGH).

    • blocked: Bu derecelendirme, içeriğin engellenmesine neden olduysa true.

  • Agent Platform Gemini API (formerly Vertex AI) ile kullanılabilen ek özellikler:

    • probabilityScore: 0.0 ile 1.0 arasında kayan noktalı bir güven puanı.

    • severity: Farklı bir önem düzeyi (NEGLIGIBLE, LOW, MEDIUM veya HIGH).

    • severityScore: 0.0 ile 1.0 arasında kayan nokta önem puanı.

Örnek SafetyRating nesnesi

Aşağıdaki örnekte, bir aday güvenlik filtreleri tarafından engellendiğinde ham JSON yanıt yükü gösterilmektedir:

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

Kodlardaki güvenlik hatalarını yakalama

İçerik engellendiğinde istemci SDK'ları, engellemeyi bir istisna veya hata kodu olarak gösterir. Böylece uygulamanız bu durumu sorunsuz bir şekilde yönetebilir.

Swift

GenerateContentError.promptBlocked veya GenerateContentError.responseStoppedEarly yakalayabilirsiniz:

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

PromptBlockedException hatasını yakalayabilir veya candidate.finishReason nesnesini inceleyebilirsiniz:

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

PromptBlockedException hatasını yakalayabilir veya candidate.getFinishReason() nesnesini inceleyebilirsiniz:

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

promptFeedback ve candidate.finishReason öğelerini inceleyebilirsiniz:

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

promptFeedback ve candidate.finishReason öğelerini inceleyebilirsiniz:

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

PromptFeedback ve candidate.FinishReason öğelerini inceleyebilirsiniz:

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}");
}



Sorumlu uygulama tasarımı için en iyi uygulamalar

  • Derinlemesine savunma: Güvenlik filtreleri bir talimat değil, önlemdir. Üslubu ve kapsamı yönlendirmek için güvenlik ayarlarını açık sistem talimatları ve hedeflenen istem tasarımıyla birleştirin.

  • Kullanıcıya uygun şekilde geri bildirim verme: İçerik engellendiğinde hiçbir zaman kilitlenmeyin veya boş ekran göstermeyin. finishReason == SAFETY veya PromptBlockedException tespit edin ve kullanıcıya, isteğin içerik yönergeleriniz kapsamında yerine getirilemediğini bildiren samimi bir mesaj gösterin.

  • Özel denetim için BLOCK_NONE kullanın: Kendi istemci tarafı veya sunucu tarafı denetim hattınız varsa eşikleri BLOCK_NONE olarak ayarlayarak modelin safetyRatings değerini otomatik engelleme olmadan alabilir ve uygulamanızın özel denetim politikalarını uygulamasını sağlayabilirsiniz.

  • Hizmet Şartları'nı inceleyin: Daha az kısıtlayıcı ayarlar (BLOCK_ONLY_HIGH veya BLOCK_NONE) kullanıyorsanız uygulamanızın Google'ın Yasaklanan Kullanım Politikası'na uymaya devam ettiğinden emin olun.

İçerik üretimini kontrol etmek için diğer seçenekler

  • Modeli, ihtiyaçlarınıza özel çıktılar üretecek şekilde etkilemek için istem tasarımı hakkında daha fazla bilgi edinin.
  • Modelin nasıl yanıt üreteceğini kontrol etmek için model parametrelerini yapılandırın (ör. maksimum çıkış jetonu sayısı, tekrarlanan çıkış jetonlarının olasılığı vb.).
  • Modelin davranışını yönlendirmek için sistem talimatları belirleyin. Bu özellik, model son kullanıcıdan başka talimatlar almadan önce eklediğiniz bir ön talimat gibidir.
  • Belirli bir çıkış şeması belirtmek için istemle birlikte bir yanıt şeması iletin. Bu özellik en yaygın olarak JSON çıkışı oluştururken kullanılır ancak sınıflandırma görevleri için de kullanılabilir (ör. modelin belirli etiketleri kullanmasını istediğinizde).