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


Uygulamanızın Firebase AI Logic üzerinden Gemini API'a gönderdiği her istekten önce ve sonra kendi özel sunucu tarafı komut dosyalarınızı çalıştırabilirsiniz. İstemci kodunuzu değiştirmeniz gerekmez. Bu komut dosyalarını, Cloud Functions for Firebase'a dağıtılan geri çağırma stili işlevler olarak uygularsınız.

Bu özellik sayesinde istemleri denetleme, jeton kullanımını sınırlama, analiz için oluşturulan içerikleri kaydetme veya yanıt içeriğini düzeltme gibi işlemler yapabilirsiniz.

İki etkinlik türü vardır:

  • beforeGenerateContent: İstek Gemini API'e 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 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'da işlev olarak dağıtıldıktan sonra Firebase AI Logic tetikleyicileri olarak kaydedilir. Bu nedenle, projenizdeki her generateContent isteği için Firebase AI Logic üzerinden Gemini API'ye (sunucu istemi şablonlarıyla yapılan istekler dahil) çalıştırılır.

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

Ön koşullar

  • KurulumFirebase AI Logic: Henüz yapmadıysanız Firebase AI LogicBaşlangıç Kılavuzu'nu tamamlayın. Bu kılavuzda Firebase projenizi nasıl ayarlayacağınız, uygulamanızı Firebase'e nasıl bağlayacağınız, SDK'yı nasıl ekleyeceğiniz, seçtiğiniz Gemini API sağlayıcısı için arka uç hizmetini nasıl başlatacağınız ve nasıl GenerativeModel örneği oluşturacağınız açıklanmaktadır.

  • Gerekli izinler: �Cloud Functions for Firebase

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

Firebase projenizde hiç Cloud Functions for Firebase 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 kullanmak için gereklidir).

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

  3. Varsayılan Compute hizmet hesabına, işlevinizi oluşturmak için gereken Cloud Build Hizmet Hesabı rolünü (roles/cloudbuild.builds.builder) verin. Aşağıdaki gcloud CLI komutu ç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'ı 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. functions/package.json'nizdeki firebase-functions'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

Ön istek işlevi yazma (beforeGenerateContent) İstek sonrası işlevi yazma (afterGenerateContent)

Ön istek işlevi yazma (beforeGenerateContent)

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

İşlevinizi yazmadan önce aşağıdaki bilgileri incelediğinizden emin olun:

Örnek

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

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

  • İstemde engellenen konuları inceler ve hata vererek isteği reddeder.

  • Metin oluşturma modelleri için maksimum çıkış jetonlarını sınırlar.

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ıyı 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 (örneğin, sırasıyla geminiV1Beta veya vertexV1Beta1 ile karşılaştırın) değerini kontrol etmeniz gerekir.

  • Hata verme işlemi isteği engelliyor: HttpsError hata verirseniz istek reddedilir.

  • İsteğin tamamını döndürün: İşleviniz isteği değiştiriyorsa değiştirilmiş istek nesnesinin tamamını döndürmeniz gerekir. Hiçbir şey döndürmemek (veya undefined) isteği değiştirmeden bırakır.

  • Gecikme testi: İşlevinizin ne yaptığına bağlı olarak gecikme ekleyebilir ve kullanıcı deneyimini etkileyebilir.

İstek sonrası işlev yazma (afterGenerateContent)

afterGenerateContent etkinlik türünde, Firebase AI Logic proxy'si generateContent isteğinden yanıt aldığında işlev tetiklenir. İşlev, yanıt istemci uygulamasına döndürülmeden önce yanıta göre ç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 incelediğinizden emin olun:

Örnek

Aşağıda, jeton kullanımını ve bitirme nedenini kaydeden bir örnek 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ıyı belirtin: event.data.response, Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI) için olabilir. İsteği güvenli bir şekilde yayınlamak ve istek nesnesiyle çalışmak için event.data.api (örneğin, sırasıyla geminiV1Beta veya vertexV1Beta1 ile karşılaştırın) kontrol etmeniz gerekir.

  • Gecikme testi: İşlevinizin ne yaptığına bağlı olarak gecikme ekleyebilir ve kullanıcı deneyimini etkileyebilir.

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

İşlevlerinizi Firebase'e dağıtmak, Firebase AI Logic hizmet aracısına bu işlevleri çağırma izni verir ve her işlevi Firebase AI Logic tetikleyici olarak kaydeder.

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

    firebase deploy --only functions

  2. Dağıtım işleminden 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 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 tetikleyici olarak kaydının silinmesi gerekir. Bu işlemi, aşağıdaki seçeneklerden biriyle Firebase KSA'yı kullanarak yapabilirsiniz:

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

    1. İşlevi proje dizininizin kod tabanından 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 dizininizin kod tabanından 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, istek hakkında bağlam ve meta veriler içeren bir AIBlockingEvent nesnesi alır.

Üst düzey istek meta verileri (AIBlockingEvent)

En üst düzeydeki AIBlockingEvent nesne, arayan ve tetikleme 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: Arayan uygulamanın paket adı veya paket kimliği (sırasıyla Android veya Apple platformları için geçerlidir).
  • event.data: Ön istek ve istek sonrası işlevler arasında farklılık gösteren etkinlik yükü:

İstek öncesi etkinlik verileri (beforeGenerateContent)

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

  • event.data.api: Gemini API sağlayıcı: geminiV1Beta (Gemini Developer API) veya vertexV1Beta1 (Agent Platform Gemini API (formerly Vertex AI)).
  • event.data.model: Modelin tam kaynak yolu (örneğin, projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.8-flash).
  • event.data.template: Kullanılan sunucu istemi şablonuyla ilgili meta veriler (PromptTemplateInfo), varsa.
  • 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, AfterGenerateContentData nesnesiyle doldurulur. Bu nesne, BeforeGenerateContentData'yı 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'e yapılan generateContent istekleriyle tetiklenebilir.

    Aşağıdaki durumlarda bu işlevler tetiklenmez ve işlevler bu istek için sessizce atlanır:

    • generateContentStream istekleri bu işlevleri tetiklemez.

    • Gemini Live API ile ilgili istekler bu işlevleri tetiklemez.

  • İstemci tarafında kod değişikliği gerekmez: Bu işlevleri çalıştırmak istediğinizde generateContent isteklerini kullandığınızdan emin olmanız dışında, istemci tarafındaki 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 proxy'nin istekleri ve yanıtları sunucu tarafında yakalayabilmesi için Firebase AI Logic tetikleyicileri olarak kaydedilir.

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

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