İsteklerden önce ve sonra özel sunucu tarafı komut dosyaları çalıştırma


Uygulamanızın Gemini API hizmetine gönderdiği her istekten önce ve sonra kendi özel sunucu tarafı komut dosyalarınızı Firebase AI Logic aracılığıyla çalıştırabilirsiniz. Bunun için istemci kodunuzu değiştirmeniz gerekmez. Bu komut dosyalarını, Cloud Functions for Firebase'e dağıtılan geri çağırma tarzı işlevler olarak uygularsınız.

Bu özellik sayesinde istemleri denetleyebilir, jeton kullanımını sınırlayabilir, analiz için oluşturma işlemlerini günlüğe kaydedebilir veya yanıt içeriğini çıkartabilirsiniz.

İki etkinlik türü kullanılabilir:

  • beforeGenerateContent: İstek Gemini API hedefine ulaşmadan önce çalışır. İşlev, isteği inceleyebilir veya değiştirebilir ya da hata vererek isteği tamamen engelleyebilir.

  • afterGenerateContent: Yanıt Gemini API tarafından geri gönderildikten sonra ve istemci uygulamasına döndürülmeden önce çalışır. İşlev, yanıtı inceleyebilir veya değiştirebilir, yanıtı tamamen engelleyebilir ya da yalnızca gözlemleyebilir (ör. günlük kaydı veya denetim için).

Komut dosyalarınız Cloud Functions for Firebase için işlev olarak dağıtıldıktan sonra Firebase AI Logic tetikleyicileri olarak kaydedilir. Bu, projenizdeki her generateContent isteği için Firebase AI Logic aracılığıyla Gemini API'e çalıştırılacakları anlamına gelir (sunucu istem şablonları ile yapılan istekler dahil).

Bu işlevler, Firebase AI Logic üzerinden yapılmayan Gemini API istekleri tarafından tetiklenmez.

Ön koşullar

1. adım: Projenizi Cloud Functions for Firebase için ayarlayın.

Firebase projenizde Cloud Functions for Firebase hizmetini daha önce hiç kullanmadıysanız aşağıdaki kurulumu tamamlayın.

  1. Firebase projenizin kullandıkça öde Blaze fiyatlandırma planında olduğundan emin olun (Cloud Functions for Firebase kullanımı için gereklidir).

  2. Komut satırı arayüzlerini (CLI) yükleyin: gcloud CLI ve Firebase CLI

  3. Varsayılan Compute hizmet hesabına, işlevinizi derlemek için gereken Cloud Build Hizmet Hesabı rolünü (roles/cloudbuild.builds.builder) verin. Aşağıdaki gcloud CLI komutunu çalıştırın:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.builder"

  4. Firebase projenizde Cloud Functions for Firebase hizmetini başlatın:

    1. Aşağıdaki Firebase CLI komutunu çalıştırın:

      firebase init functions

    2. İstendiğinde TypeScript'i seçin.

    3. firebase-functions functions/package.json uygulamanızdaki sürümünün 6.3.0 veya sonraki bir sürüm olduğundan emin olun. Sürümünüzü nasıl kontrol edeceğiniz aşağıda açıklanmıştır:

      npm --prefix functions list firebase-functions

2. adım: İşlevlerinizi yazın

İstek öncesi işlevi yazma (beforeGenerateContent) İstek sonrası işlevi yazma (afterGenerateContent)

İstek öncesi işlevi yazma (beforeGenerateContent)

beforeGenerateContent etkinlik türünde, Firebase AI Logic proxy'si bir generateContent isteği aldığında işlev tetiklenir. İşlev, istek Gemini API'e gönderilmeden önce isteğe karşı çalışır. İşlev, isteği değiştirebilir veya tamamen engelleyebilir.

İşlevinizi yazmadan önce aşağıdaki bilgileri inceleyin:

Örnek

Aşağıda, aşağıdakileri yapan örnek bir ön istek işlevi verilmiştir:

  • İşlevin yalnızca istek belirli bir Gemini API sağlayıcı için olduğunda çalışması gerektiğini belirtir.

  • İstemi, engellenen konular açısından inceler ve hata vererek isteği reddeder.

  • Metin üreten modeller için maksimum çıkış jetonu sayısını belirler.

import { logger } from "firebase-functions";
import {
  beforeGenerateContent,
  HttpsError,
  vertexV1Beta1,
  type VertexV1Beta1GenerateContentRequest,
} from "firebase-functions/v2/ai";

const BLOCKED_TOPICS = ["weapon", "explosive", "self-harm"];
const MAX_OUTPUT_TOKENS = 4000;

export const guardPrompts = beforeGenerateContent((event) => {
  // 1. Optional: If you want the function to only run for a specific Gemini API provider, specify it here.
  if (event.data.api !== vertexV1Beta1) return;
  const request = event.data.request as VertexV1Beta1GenerateContentRequest;

  // 2. Read the prompt: contents[] -> parts[] -> text
  const prompt = (request.contents ?? [])
    .flatMap((c) => c.parts ?? [])
    .map((p) => ("text" in p ? p.text : "") ?? "")
    .join(" ")
    .toLowerCase();

  // 3. Throwing rejects the request. The request is never sent to the Gemini API.
  const blocked = BLOCKED_TOPICS.find((t) => prompt.includes(t));
  if (blocked) {
    logger.warn("Blocked a prompt", { topic: blocked });
    throw new HttpsError("invalid-argument", `We don't return content about ${blocked}.`);
  }

  logger.info("Allowing generation", {
    model: event.data.model,
    authType: event.authType,
    authId: event.authId,
    appId: event.appId,
  });

  // 4. The next step truncates the response, but that will break images.
  if (event.data.model.includes("image")) return;

  // 5. Return the WHOLE request, edited. Returning nothing leaves it untouched.
  return {
    ...request,
    generationConfig: {
      ...request.generationConfig,
      maxOutputTokens: Math.min(
        request.generationConfig?.maxOutputTokens ?? MAX_OUTPUT_TOKENS,
        MAX_OUTPUT_TOKENS,
      ),
    },
  };
});

Ön istek işlevleriyle ilgili önemli noktalar

  • Gemini API sağlayıcısını belirtin: event.data.request, Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI) için olabilir. Bu farklı API'lerin istek nesneleri farklı şekillere sahiptir. İstek nesnesiyle güvenli bir şekilde çalışmak için event.data.api değerini kontrol etmeniz gerekir (örneğin, sırasıyla geminiV1Beta veya vertexV1Beta1 ile karşılaştırın).

  • Hata oluşturma, isteği engeller: HttpsError oluşturursanız istek reddedilir.

  • İsteğin tamamını döndürme: İşleviniz isteği değiştiriyorsa değiştirilen istek nesnesinin tamamını döndürmeniz gerekir. Hiçbir şey döndürülmezse (veya undefined döndürülürse) istek değişmeden kalır.

  • Gecikme testi yapın: İşlevinizin ne yaptığına bağlı olarak gecikme süresi artabilir ve kullanıcı deneyimi etkilenebilir.

İstek sonrası işlevi yazma (afterGenerateContent)

afterGenerateContent etkinlik türünde işlev, Firebase AI Logic proxy'si bir generateContent isteğinden yanıt aldığında tetiklenir. İşlev, yanıt istemci uygulamasına döndürülmeden önce yanıta karşı çalışır. İşlev, kullanımı günlüğe kaydedebilir, yanıtı değiştirebilir veya yanıtı tamamen engelleyebilir.

İşlevinizi yazmadan önce aşağıdaki bilgileri inceleyin:

Örnek

Aşağıda, jeton kullanımını ve tamamlanma nedenini günlüğe kaydeden örnek bir istek sonrası işlevi verilmiştir:

import { logger } from "firebase-functions";
import {
  afterGenerateContent,
  vertexV1Beta1,
  type VertexV1Beta1GenerateContentResponse,
} from "firebase-functions/v2/ai";

export const recordGenerationUsage = afterGenerateContent((event) => {
  // Optional: If you want the function to only run for a specific Gemini API provider, specify it here.
  if (event.data.api !== vertexV1Beta1) return;
  const response = event.data.response as VertexV1Beta1GenerateContentResponse;

  logger.info("Generation finished", {
    model: event.data.model,
    promptTokens: response.usageMetadata?.promptTokenCount,
    totalTokens: response.usageMetadata?.totalTokenCount,
    finishReason: response.candidates?.[0]?.finishReason,
  });

  // To leave the response untouched, return nothing.
  // To modify the response, return a modified response object here.
});

İstek sonrası işlevlerle ilgili önemli noktalar

  • Gemini API sağlayıcısını belirtin: event.data.response, Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI) için olabilir. İstek nesnesini güvenli bir şekilde yayınlamak ve bu nesneyle çalışmak için event.data.api değerini kontrol etmeniz gerekir (örneğin, sırasıyla geminiV1Beta veya vertexV1Beta1 ile karşılaştırın).

  • Gecikme testi yapın: İşlevinizin ne yaptığına bağlı olarak gecikme süresi artabilir ve kullanıcı deneyimi etkilenebilir.

3. adım: İşlevlerinizi dağıtın

İşlevlerinizi Firebase'e dağıttığınızda Firebase AI Logic hizmet aracısına bu işlevleri çağırma izni verilir ve her işlev Firebase AI Logic tetikleyicisi olarak kaydedilir.

  1. Firebase KSA'yı kullanarak işlevlerinizi dağıtın:

    firebase deploy --only functions

  2. Dağıtımdan sonra işlevlerinizin Firebase'e dağıtıldığını onaylayın:

    firebase functions:list

  3. İşlevinizi yinelemeniz gerekiyorsa:

    Proje dizininizdeki işlevi güncelleyin ve ardından firebase deploy --only functions komutunu tekrar çalıştırın.

Bir işlevin çalışmasını durdurma

Bu işlevlerden birinin çalışmasını durdurmak için işlevin sunucularımızdan silinmesi ve Firebase AI Logic tetikleyicisi olarak kaydının silinmesi gerekir. Bu işlemi, aşağıdaki seçeneklerden birini kullanarak Firebase CLI ile yapabilirsiniz:

  • 1. seçenek: İşlevi dolaylı olarak silme

    1. İşlevi, proje dizini kod tabanınızdan kaldırın.

    2. Aşağıdaki Firebase CLI komutunu çalıştırın:

      firebase deploy --only functions

  • 2. seçenek: İşlevi açıkça silme

    1. İşlevi proje dizini kod tabanınızdan kaldırın.

    2. Aşağıdaki Firebase CLI komutunu çalıştırın:

      firebase functions:delete FUNCTION_NAME


Etkinlik verileri referansı

Hem beforeGenerateContent hem de afterGenerateContent, istekle ilgili bağlam ve meta verileri içeren bir AIBlockingEvent nesnesi alır.

Üst düzey istek meta verileri (AIBlockingEvent)

Üst düzey AIBlockingEvent nesnesi, arayan ve tetikleyici ortam hakkında bilgi sağlar:

  • event.authType: Arayanın kimlik doğrulama durumu: "app_user", "unauthenticated" veya "unknown".
  • event.authId: Oturum açılmışsa arayanın Firebase Authentication UID'si.
  • event.authClaims: Arayanın özel kimlik doğrulama talepleri (varsa).
  • event.appId: İsteği gönderen Firebase uygulama kimliği.
  • event.androidPackageName / event.iosBundleId: Çağrı yapan uygulamanın paket adı veya paket kimliği (sırasıyla Android veya Apple platformları için geçerlidir).
  • event.data: İstek öncesi ve istek sonrası işlevleri arasında farklılık gösteren etkinlik yükü:

İstek öncesi etkinlik verileri (beforeGenerateContent)

beforeGenerateContent işlevinde event.data, bir BeforeGenerateContentData nesnesiyle doldurulur:

  • event.data.api: Gemini API sağlayıcısı: geminiV1Beta (Gemini Developer API) veya vertexV1Beta1 (Agent Platform Gemini API (formerly Vertex AI)).
  • event.data.model: Tam model kaynak yolu (ör. projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.8-flash).
  • event.data.template: Varsa kullanılan sunucu istem şablonuyla ilgili meta veriler (PromptTemplateInfo).
  • event.data.request: Giden istek yükü. Nesne türü ve özellikleri, Gemini API sağlayıcısına bağlıdır:

İstek sonrası etkinlik verileri (afterGenerateContent)

afterGenerateContent işlevinde event.data, bir AfterGenerateContentData nesnesiyle doldurulur. Bu nesne BeforeGenerateContentData nesnesini genişletir (api, model, template ve request sağlar) ve modelin yanıtını ekler:


Sınırlamalar ve davranışlar

Bu işlevleri uygularken aşağıdaki davranışları ve sınırlamaları göz önünde bulundurun:

  • Yalnızca generateContent istekleri: Bu işlevler yalnızca Firebase AI Logic üzerinden Gemini API için gönderilen generateContent istekleriyle tetiklenebilir.

    Aşağıdakiler bu işlevleri tetiklemez ve işlevler ilgili istek için sessizce atlanır:

    • generateContentStream adresine gönderilen istekler bu işlevleri tetiklemez.

    • Gemini Live API adresine gönderilen istekler bu işlevleri tetiklemez.

  • İstemci tarafı kod değişikliği yok: Bu işlevleri çalıştırmak istediğinizde generateContent isteklerini kullandığınızdan emin olmanın dışında, istemci tarafı kod tabanınızda herhangi bir değişiklik yapmanız gerekmez.

    Bu işlevler sunucularımıza dağıtılır ve Firebase AI Logic tetikleyicileri olarak kaydedilir. Böylece Firebase AI Logic proxy'si, istekleri ve yanıtları sunucu tarafında yakalayabilir.

  • Proje düzeyinde kapsam: Firebase projesi başına en fazla bir beforeGenerateContent işlevi ve bir afterGenerateContent işlevi dağıtabilirsiniz.

  • Varsayılan konumlar: Bu işlevler varsayılan olarak us-central1 konumuna dağıtılır (işlevlerin konumları hakkında bilgi edinin). Ancak işlev, işlevinizi nerede dağıttığınızdan bağımsız olarak global bölgesinde Firebase AI Logic tetikleyicisi olarak kaydedilir.