درک و پیکربندی تنظیمات ایمنی

مدل‌های Gemini به‌گونه‌ای طراحی شده‌اند که ایمنی را در اولویت قرار دهند. بااین‌حال، این مدل‌ها همچنان می‌توانند پاسخ‌های مضر تولید کنند، به‌ویژه زمانی که به‌طور صریح از آن‌ها خواسته شود. برای افزایش بیشتر ایمنی و به‌حداقل رساندن سوءاستفاده، می‌توانید فیلترهای ایمنی را پیکربندی کنید تا پاسخ‌های بالقوه مضر را مسدود کنید.

دو لایه محافظت ایمنی ارائه می‌شود:

  • محافظت‌های اصلی داخلی:

    • همه مدل‌های Gemini دارای محافظت‌های داخلی دربرابر آسیب‌های شدید (مانند بهره‌کشی از کودکان، حملات سایبری، و سلاح‌های خطرناک) هستند.
    • این محافظت‌ها همیشه فعال هستند، به‌طور خودکار برای همه پیام‌واره‌ها و پاسخ‌ها اعمال می‌شوند، و نمی‌توان آن‌ها را تغییر داد یا غیرفعال کرد.
  • فیلترهای ایمنی قابل‌پیکربندی:

    • Gemini API فیلترهای ایمنی قابل‌پیکربندی بیشتری ارائه می‌دهد که بااستفاده از تنظیمات ایمنی در برنامه‌تان تعریف می‌کنید.
    • این تنظیمات به شما امکان می‌دهد آستانه مسدود شدن محتوا را در چهار دسته اصلی آسیب کنترل کنید: آزار، سخنان مشوق عداوت و تنفر، محتوای صریح جنسی، و محتوای خطرناک.

پرش به نمونه‌های کد

مفاهیم ایمنی مهم

هنگام کار با ایمنی برای مدل‌های Gemini، در اینجا چند مفهوم مهم برای درک وجود دارد:

  • تنظیمات ایمنی: پیکربندی‌ای که در کد برنامه‌تان تعریف می‌کنید و مشخص می‌کند کدام دسته‌های آسیب پایش شوند و در چه آستانه‌ای محتوا مسدود شود.

  • فیلترهای ایمنی: طبقه‌بندهای سمت سرور که پیام‌واره‌ها و پاسخ‌های مدل را براساس ابعاد ایمنی Google ارزیابی می‌کنند. فیلترها محتوا را براساس تنظیمات ایمنی پیکربندی‌شده شما مسدود می‌کنند.

  • رده‌بندی‌های ایمنی: فراداده ارزیابی که توسط مدل در شیء پاسخ برگردانده می‌شود. رده‌بندی‌ها نشان‌دهنده احتمال و شدت آسیب احتمالی شناسایی‌شده برای هر دسته آسیب است.

مدل‌های پشتیبانی‌شده

  • gemini-4-hydrogen
  • gemini-4-argon
  • gemini-4-carbon
  • gemini-3.8-flash
  • ‫gemini-3.5-flash-lite (و 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.x Flash با کاربرد عمومی از این قابلیت پشتیبانی می‌کنند، اما به‌دلیل تاریخ‌های تعطیلی آتی و/یا مسیریابی خودکار به مدل‌های جدیدتر، دیگر برای استفاده توصیه نمی‌شوند.



پیکربندی تنظیمات ایمنی در برنامه

روی ارائه‌دهنده Gemini API خود کلیک کنید تا محتوا و کد مختص ارائه‌دهنده را در این صفحه ببینید.

تنظیمات ایمنی را به‌عنوان بخشی از مقداردهی اولیه نمونه GenerativeModel پیکربندی می‌کنید. پیکربندی برای طول عمر آن نمونه مدل حفظ می‌شود.

در ادامه این صفحه، با دسته‌های آسیب موجود و آستانه‌هایی که می‌توانید برای هر دسته تنظیم کنید آشنا شوید.

Swift

هنگام ایجاد نمونه GenerativeModel، SafetySetting را پیکربندی کنید:


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، SafetySetting را پیکربندی کنید:


// ...

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، SafetySetting را پیکربندی کنید:


// ...

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، SafetySetting را پیکربندی کنید:


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، SafetySetting را پیکربندی کنید:


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، SafetySetting را پیکربندی کنید:


// ...

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

// ...



دسته‌های آسیب دردسترس

فیلترهای ایمنی پیام‌واره‌ها و پاسخ‌های مدل را براساس دسته‌های آسیب قابل‌پیکربندی زیر ارزیابی می‌کنند:

دسته آسیب شرح
HARM_CATEGORY_HARASSMENT نظرات منفی، تهدیدآمیز، ارعاب‌کننده، زورگویانه، یا توهین‌آمیز که فرد یا هویتی را هدف قرار می‌دهد.
HARM_CATEGORY_HATE_SPEECH محتوایی که به افراد یا گروه‌ها براساس مشخصه‌های حفاظت‌شده (مانند نژاد، قومیت، دین، ناتوانی جسمی، سن، ملیت، وضعیت سربازی، تمایل جنسی، یا هویت جنسیتی) حمله می‌کند، آن‌ها را تحقیر می‌کند، مروج نفرت علیه آن‌ها است، یا مشوق خشونت علیه آن‌ها است.
HARM_CATEGORY_SEXUALLY_EXPLICIT حاوی ارجاع به اعمال جنسی، هرزه‌نگاری، یا سایر محتواهای شهوانی و شهوت‌انگیز است.
HARM_CATEGORY_DANGEROUS_CONTENT ترویج، تسهیل، تشویق، یا ارائه دستورالعمل برای اعمال مضر، کالاها و خدمات غیرقانونی، سلاح، خودآزاری، یا فعالیت‌های خطرناک.
HARM_CATEGORY_CIVIC_INTEGRITY محتوایی که ممکن است برای گمراه کردن رأی‌دهندگان یا تضعیف فرایندهای مدنی و انتخاباتی استفاده شود. (در مدل‌ها و مناطق منتخب پشتیبانی می‌شود).

فیلترهای ایمنی غیرقابل‌پیکربندی

علاوه‌بر دسته‌های قابل‌پیکربندی، همه درخواست‌ها از فیلترهای سطح سیستم عبور می‌کنند که قابل‌تنظیم نیستند:

  • محتوای کودک‌آزاری جنسی (CSAM) / محتوای ممنوع: پیام‌واره‌ها یا پاسخ‌هایی که به‌دلیل محتوای ممنوع پرچم‌گذاری شده‌اند فوراً مسدود می‌شوند (PROHIBITED_CONTENT).

  • اطلاعات حساس شناساننده شخصی (SPII): پاسخ‌هایی که خطر افشای داده‌های شخصی حساس (مانند شماره حساب‌های مالی یا شناسه‌های ملی) را دارند مسدود می‌شوند (SPII).



تنظیم آستانه‌ها

برای هر دسته آسیب که می‌خواهید در برنامه‌تان کنترل کنید، باید آستانه‌ای تنظیم کنید. اگر محتوای ارزیابی‌شده به آن آستانه برسد یا از آن فراتر رود، محتوا مسدود می‌شود.

نحوه عملکرد ارزیابی ایمنی: احتمال دربرابر شدت

فیلترهای ایمنی محتوا را در دو بعد متمایز ارزیابی می‌کنند:

  • احتمال: اطمینان مدل از اینکه محتوا در دسته آسیب مشخصی قرار می‌گیرد.

  • شدت: میزان یا درجه آسیب احتمالی درصورتی‌که محتوا مضر باشد.

هر بُعد به یکی از این سطوح اختصاص داده می‌شود: NEGLIGIBLE، LOW، MEDIUM، یا HIGH.

محتوا می‌تواند احتمال بالا با سطح شدت پایین داشته باشد (برای مثال، شوخی کمدی ملایم یا توهین‌های دوستانه) یا احتمال پایین با سطح شدت بالا داشته باشد (برای مثال، بحث‌های پزشکی یا تاریخی که به خشونت اشاره می‌کنند).

آستانه‌های مسدود کردن محتوای مضر دردسترس

می‌توانید هرکدام از آستانه‌های زیر را برای دسته‌های آسیب که می‌خواهید در برنامه‌تان کنترل کنید تنظیم کنید:

آستانه شرح سطوح مجاز
BLOCK_LOW_AND_ABOVE بیشترین محدودیت.
وقتی احتمال (یا شدت) LOW، MEDIUM، یا HIGH باشد، محتوا را مسدود می‌کند.
فقط NEGLIGIBLE را مجاز می‌کند
BLOCK_MEDIUM_AND_ABOVE محدودیت متوسط.
محتوا را وقتی احتمال (یا شدت) MEDIUM یا HIGH باشد مسدود می‌کند.
اجازه می‌دهد NEGLIGIBLE و LOW
BLOCK_ONLY_HIGH کمترین فیلتر فعال محدودکننده.
محتوا را فقط زمانی مسدود می‌کند که احتمال (یا شدت) HIGH باشد.
‫NEGLIGIBLE،‏ LOW، و MEDIUM را مجاز می‌کند
BLOCK_NONE مسدود کردن پاسخ خودکار برای این دسته غیرفعال شده است. فراداده رده‌بندی‌های ایمنی همچنان محاسبه می‌شود و با پاسخ برگردانده می‌شود تا برنامه‌تان بتواند تعدیل سفارشی انجام دهد. همه محتوا مجاز است
OFF فیلتر ایمنی را برای این دسته به‌طور کامل خاموش می‌کند. هیچ مسدودسازی خودکاری انجام نمی‌شود و هیچ فراداده‌ای برای رده‌بندی ایمنی برگردانده نمی‌شود. همه محتوا مجاز است



بررسی رده‌بندی‌های ایمنی و رسیدگی به محتوای مسدودشده

محتوا را می‌توان در دو مرحله از درخواست مسدود کرد:

  1. پیام‌واره مسدود شد (PromptFeedback): پیام‌واره ورودی قبل‌از اینکه مدل خروجی‌ای تولید کند، فیلترهای ایمنی را نقض کرد. هیچ پاسخ کاندیدی برگردانده نشده است.

  2. پاسخ نامزد مسدود شد (finishReason == SAFETY): مدل پاسخ نامزدی را ارزیابی یا تولید کرد که از آستانه پیکربندی‌شده شما فراتر رفت. نوشتار نامزد تولیدشده پاک یا ویرایش می‌شود.

شیء SafetyRating

هر پیام‌واره یا پاسخ نامزد ارزیابی‌شده حاوی آرایه‌ای از اشیاء SafetyRating است. هر رده‌بندی موارد زیر را ارائه می‌دهد:

  • ویژگی‌های دردسترس با هر دو Gemini Developer API و Agent Platform Gemini API (formerly Vertex AI):

    • category: HarmCategory ارزیابی‌شده.

    • probability: رده‌بندی گسسته (NEGLIGIBLE، LOW، MEDIUM، یا HIGH).

    • blocked: true اگر این رده‌بندی خاص باعث مسدود شدن محتوا شده است.

  • ویژگی‌های اضافی دردسترس با Agent Platform Gemini API (formerly Vertex AI):

    • ‫probabilityScore: امتیاز اطمینان ممیز شناور از 0.0 تا 1.0.

    • severity: سطح شدت مجزا (NEGLIGIBLE، LOW، MEDIUM، یا HIGH).

    • ‫severityScore: امتیاز شدت ممیز شناور از 0.0 تا 1.0.

نمونه شیء SafetyRating

مثال زیر پایه‌بار پاسخ JSON خام را زمانی نشان می‌دهد که نامزد توسط فیلترهای ایمنی مسدود شده است:

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

شناسایی خطاهای ایمنی در کد

وقتی محتوا مسدود می‌شود، کیت‌های توسعه نرم‌افزار کارخواه، مسدود شدن را به‌عنوان استثنا یا کد خطا نشان می‌دهند تا برنامه‌تان بتواند آن را به‌درستی مدیریت کند.

Swift

می‌توانید GenerateContentError.promptBlocked یا 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

می‌توانید PromptBlockedException را بگیرید یا 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

می‌توانید PromptBlockedException را بگیرید یا 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

می‌توانید promptFeedback و 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

می‌توانید promptFeedback و 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

می‌توانید PromptFeedback و 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}");
}



روال‌های مطلوب برای طراحی مسئولانه برنامه

  • دفاع در عمق: فیلترهای ایمنی یک حفاظ هستند، نه یک دستورالعمل. تنظیمات ایمنی را با دستورالعمل‌های صریح سیستم و طراحی هدفمند پیام‌واره ترکیب کنید تا لحن و دامنه را هدایت کنید.

  • بازخورد کاربر مناسب: هرگز هنگام مسدود شدن محتوا، از کار نیفتید یا صفحه خالی نشان ندهید. finishReason == SAFETY یا PromptBlockedException را شناسایی کنید و پیام دوستانه‌ای نمایش دهید که به کاربر اطلاع دهد درخواستش نمی‌تواند تحت رهنمودهای محتوای شما برآورده شود.

  • استفاده از BLOCK_NONE برای تعدیل سفارشی: اگر ازقبل خط لوله تعدیل سمت کارخواه یا سمت سرور خودتان را دارید، آستانه‌ها را روی BLOCK_NONE تنظیم کنید تا safetyRatings مدل را بدون مسدودسازی خودکار دریافت کنید و به برنامه‌تان اجازه دهید خط‌مشی‌های تعدیل سفارشی را اعمال کند.

  • مرور شرایط خدمات: اگر از تنظیمات با محدودیت کمتر (BLOCK_ONLY_HIGH یا BLOCK_NONE) استفاده می‌کنید، مطمئن شوید که برنامه‌تان همچنان از خط‌مشی کاربردهای غیرمجاز Google پیروی می‌کند.

گزینه‌های دیگر برای کنترل تولید محتوا

  • درباره طراحی پیام‌واره بیشتر بدانید تا بتوانید بر مدل تأثیر بگذارید تا خروجی خاصی را برای نیازهایتان تولید کند.
  • پارامترهای مدل را پیکربندی کنید تا نحوه تولید پاسخ توسط مدل را کنترل کنید، مانند حداکثر داده‌واحدهای خروجی، احتمال تکرار داده‌واحدهای خروجی، و غیره.
  • دستورالعمل‌های سیستم را تنظیم کنید تا رفتار مدل را هدایت کنید. این ویژگی مانند مقدمه‌ای است که قبل‌از اینکه مدل درمعرض دستورالعمل‌های بیشتر ازسوی کاربر نهایی قرار گیرد، اضافه می‌کنید.
  • یک طرح‌واره پاسخ را همراه با پیام‌واره ارسال کنید تا طرح‌واره برونداد خاصی را مشخص کنید. این ویژگی بیشتر زمانی استفاده می‌شود که خروجی JSON تولید می‌شود، اما می‌توان از آن برای تکالیف طبقه‌بندی نیز استفاده کرد (مثلاً وقتی می‌خواهید مدل از برچسب‌ها یا تگ‌های خاصی استفاده کند).