เรียกใช้สคริปต์ฝั่งเซิร์ฟเวอร์ที่กำหนดเองก่อนและหลังคำขอ

ฟังก์ชันเหล่านี้จะไม่ทริกเกอร์โดยคำขอที่ส่งไปยัง Gemini API ซึ่งไม่ได้ผ่าน Firebase AI Logic

ข้อกำหนดเบื้องต้น

• ตั้งค่า Firebase AI Logic: หากยังไม่ได้ดำเนินการ โปรดอ่านคู่มือเริ่มต้นใช้งาน Firebase AI Logic ซึ่งอธิบายวิธีตั้งค่าโปรเจ็กต์ Firebase, เชื่อมต่อแอปกับ Firebase, เพิ่ม SDK, เริ่มต้นบริการแบ็กเอนด์สำหรับผู้ให้บริการ Gemini API ที่เลือก และสร้างอินสแตนซ์ GenerativeModel

• สิทธิ์ที่จำเป็น: ตรวจสอบว่าคุณมีสิทธิ์ IAM ที่จำเป็นสำหรับการทำให้ใช้งานได้ใน Cloud Functions for Firebase

ขั้นตอนที่ 1: ตั้งค่าโปรเจ็กต์สำหรับ Cloud Functions for Firebase

หากคุณไม่เคยใช้ Cloud Functions for Firebase ในโปรเจ็กต์ Firebase ให้ตั้งค่าต่อไปนี้ให้เสร็จสมบูรณ์

1. ตรวจสอบว่าโปรเจ็กต์ Firebase ใช้แพ็กเกจราคา Blaze แบบจ่ายเมื่อใช้ (จำเป็นสำหรับการใช้ Cloud Functions for Firebase)

2. ติดตั้งอินเทอร์เฟซบรรทัดคำสั่ง (CLI) gcloud CLI และ Firebase CLI

3. มอบบทบาทบัญชีบริการ Cloud Build (roles/cloudbuild.builds.builder) ให้กับบัญชีบริการ Compute เริ่มต้น ซึ่งเป็นบทบาทที่จำเป็นในการสร้างฟังก์ชัน เรียกใช้คำสั่ง gcloud CLI ต่อไปนี้

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

4. เริ่มต้น Cloud Functions for Firebase ในโปรเจ็กต์ Firebase โดยทำดังนี้

   1. เรียกใช้คำสั่ง Firebase CLI ต่อไปนี้

      firebase init functions
      

   2. เมื่อได้รับข้อความแจ้ง ให้เลือก TypeScript

   3. ตรวจสอบว่า firebase-functions ใน functions/package.json เป็นเวอร์ชัน 6.3.0 ขึ้นไป วิธีตรวจสอบเวอร์ชันมีดังนี้

      npm --prefix functions list firebase-functions
      

ขั้นตอนที่ 2: เขียนฟังก์ชัน

arrow_downward เขียนฟังก์ชันก่อนส่งคำขอ (beforeGenerateContent) arrow_downward เขียนฟังก์ชันหลังส่งคำขอ (afterGenerateContent)

เขียนฟังก์ชันก่อนส่งคำขอ (beforeGenerateContent)

เมื่อใช้ประเภทเหตุการณ์ beforeGenerateContent ฟังก์ชันจะทริกเกอร์เมื่อพร็อกซี Firebase AI Logic ได้รับคำขอ generateContent ฟังก์ชันจะทำงานกับคำขอก่อนที่จะส่งคำขอไปยัง Gemini API ฟังก์ชันนี้สามารถแก้ไขคำขอหรือบล็อกคำขอโดยสมบูรณ์ได้

โปรดอ่านข้อมูลต่อไปนี้ก่อนเขียนฟังก์ชัน

• ข้อมูลเหตุการณ์ที่คุณใช้ในฟังก์ชันได้
• ข้อควรพิจารณาที่สำคัญสำหรับฟังก์ชันก่อนส่งคำขอ
• ข้อจำกัดและลักษณะการทำงานของฟังก์ชัน

ตัวอย่าง

ต่อไปนี้เป็นตัวอย่างฟังก์ชัน pre-request ที่ทำสิ่งต่อไปนี้

• ระบุว่าฟังก์ชันควรทำงานเมื่อคำขอมีไว้สำหรับผู้ให้บริการ Gemini API ที่เฉพาะเจาะจงเท่านั้น

• ตรวจสอบพรอมต์เพื่อหาหัวข้อที่ถูกบล็อกและปฏิเสธคำขอโดยแสดงข้อผิดพลาด

• จำกัดโทเค็นเอาต์พุตสูงสุดสำหรับโมเดลการสร้างข้อความ

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

ข้อควรพิจารณาที่สำคัญสำหรับฟังก์ชันก่อนส่งคำขอ

• ระบุผู้ให้บริการ Gemini API: event.data.request อาจเป็นGemini Developer APIหรือAgent Platform Gemini API (formerly Vertex AI)ก็ได้ ออบเจ็กต์คำขอสำหรับ API ต่างๆ เหล่านี้มีรูปแบบที่แตกต่างกัน หากต้องการทำงานกับออบเจ็กต์คำขออย่างปลอดภัย คุณต้องตรวจสอบ event.data.api (เช่น เปรียบเทียบกับ geminiV1Beta หรือ vertexV1Beta1 ตามลำดับ)

• การส่งข้อผิดพลาดจะบล็อกคำขอ: หากคุณส่ง HttpsError คำขอจะถูกปฏิเสธ

• แสดงผลคำขอทั้งหมด: หากฟังก์ชันแก้ไขคำขอ คุณต้องแสดงผลออบเจ็กต์คำขอที่แก้ไขแล้วทั้งหมด การไม่แสดงผลลัพธ์ (หรือ undefined) จะทำให้คำขอไม่มีการเปลี่ยนแปลง

• ทดสอบเวลาในการตอบสนอง: ฟังก์ชันอาจเพิ่มเวลาในการตอบสนองและส่งผลต่อประสบการณ์ของผู้ใช้ ทั้งนี้ขึ้นอยู่กับสิ่งที่ฟังก์ชันทำ

เขียนฟังก์ชันคำขอ POST (afterGenerateContent)

เมื่อใช้ประเภทเหตุการณ์ afterGenerateContent ฟังก์ชันจะทริกเกอร์เมื่อพร็อกซี Firebase AI Logic ได้รับการตอบกลับจากคำขอ generateContent ฟังก์ชันจะทำงานกับคำตอบก่อนที่จะส่งคำตอบกลับไปยังแอปไคลเอ็นต์ ฟังก์ชันสามารถบันทึกการใช้งาน แก้ไขคำตอบ หรือบล็อกคำตอบทั้งหมดได้

โปรดอ่านข้อมูลต่อไปนี้ก่อนเขียนฟังก์ชัน

• ข้อมูลเหตุการณ์ที่คุณใช้ในฟังก์ชันได้
• ข้อควรพิจารณาที่สำคัญสำหรับฟังก์ชันหลังคำขอ
• ข้อจำกัดและลักษณะการทำงานของฟังก์ชัน

ตัวอย่าง

ต่อไปนี้คือตัวอย่างฟังก์ชันคำขอ POST ที่บันทึกการใช้งานโทเค็นและเหตุผลที่เสร็จสิ้น

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

ข้อควรพิจารณาที่สำคัญสำหรับฟังก์ชันหลังคำขอ

• ระบุผู้ให้บริการ Gemini API: event.data.response อาจเป็น Gemini Developer API หรือ Agent Platform Gemini API (formerly Vertex AI) ก็ได้ หากต้องการแคสต์และทำงานกับออบเจ็กต์คำขออย่างปลอดภัย คุณต้องตรวจสอบ event.data.api (เช่น เปรียบเทียบกับ geminiV1Beta หรือ vertexV1Beta1 ตามลำดับ)

• ทดสอบเวลาในการตอบสนอง: ฟังก์ชันอาจเพิ่มเวลาในการตอบสนองและส่งผลต่อประสบการณ์ของผู้ใช้ ทั้งนี้ขึ้นอยู่กับสิ่งที่ฟังก์ชันทำ

ขั้นตอนที่ 3: ติดตั้งใช้งานฟังก์ชัน

การทำให้ฟังก์ชันใช้งานได้ใน Firebase จะให้สิทธิ์แก่ตัวแทนบริการ Firebase AI Logic ในการเรียกใช้ฟังก์ชันเหล่านี้ และลงทะเบียนแต่ละฟังก์ชันเป็นทริกเกอร์ Firebase AI Logic

1. ทำให้ฟังก์ชันใช้งานได้โดยใช้ Firebase CLI โดยทำดังนี้

   firebase deploy --only functions
   

2. หลังจากทำให้ใช้งานได้แล้ว ให้ยืนยันว่าได้ทำให้ฟังก์ชันใช้งานได้ใน Firebase แล้ว โดยทำดังนี้

   firebase functions:list
   

3. หากต้องการทำซ้ำในฟังก์ชัน ให้ทำดังนี้

   อัปเดตฟังก์ชันในไดเรกทอรีโปรเจ็กต์ แล้วเรียกใช้ firebase deploy --only functions อีกครั้ง

หยุดการทำงานของฟังก์ชัน

หากต้องการหยุดการทำงานของฟังก์ชันใดฟังก์ชันหนึ่ง คุณต้องลบฟังก์ชันนั้นออกจากเซิร์ฟเวอร์ของเราและยกเลิกการลงทะเบียนเป็นทริกเกอร์ Firebase AI Logic ซึ่งทำได้โดยใช้ Firebase CLI ด้วยตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้

• ตัวเลือกที่ 1: ลบฟังก์ชันโดยนัย

  1. นำฟังก์ชันออกจากฐานของโค้ดในไดเรกทอรีโปรเจ็กต์

  2. เรียกใช้คำสั่ง Firebase CLI ต่อไปนี้

     firebase deploy --only functions
     

• ตัวเลือกที่ 2: ลบฟังก์ชันอย่างชัดแจ้ง

  1. นำฟังก์ชันออกจากฐานของโค้ดในไดเรกทอรีโปรเจ็กต์

  2. เรียกใช้คำสั่ง Firebase CLI ต่อไปนี้

     firebase functions:delete FUNCTION_NAME
     

ข้อมูลอ้างอิงของข้อมูลเหตุการณ์

ทั้ง beforeGenerateContent และ afterGenerateContent จะได้รับออบเจ็กต์ AIBlockingEvent ที่มีบริบทและข้อมูลเมตาเกี่ยวกับคำขอ

ข้อมูลเมตาของคำขอระดับบนสุด (AIBlockingEvent)

ออบเจ็กต์ AIBlockingEvent ระดับบนสุดจะให้ข้อมูลเกี่ยวกับผู้เรียกและสภาพแวดล้อมที่ทริกเกอร์ ดังนี้

• event.authType: สถานะการตรวจสอบสิทธิ์ของผู้โทร: "app_user", "unauthenticated" หรือ "unknown"
• event.authId: UID การตรวจสอบสิทธิ์ Firebase ของผู้โทร หากลงชื่อเข้าใช้
• event.authClaims: การอ้างสิทธิ์การตรวจสอบสิทธิ์ที่กำหนดเองของผู้โทร (หากมี)
• event.appId: รหัสแอป Firebase ที่ส่งคำขอ
• event.androidPackageName / event.iosBundleId: ชื่อแพ็กเกจหรือรหัสชุดของแอปการโทร (ใช้ได้กับแพลตฟอร์ม Android หรือ Apple ตามลำดับ)
• event.data: เพย์โหลดของเหตุการณ์ ซึ่งแตกต่างกันระหว่างฟังก์ชันก่อนส่งคำขอและหลังส่งคำขอ ดังนี้
  • สำหรับ beforeGenerateContent จะเป็นออบเจ็กต์ BeforeGenerateContentData
  • สำหรับ afterGenerateContent นี่คือออบเจ็กต์ AfterGenerateContentData

ข้อมูลเหตุการณ์ก่อนส่งคำขอ (beforeGenerateContent)

ในฟังก์ชัน beforeGenerateContent ระบบจะป้อนข้อมูล event.data ด้วยออบเจ็กต์ BeforeGenerateContentData ดังนี้

• event.data.api: ผู้ให้บริการ Gemini API: geminiV1Beta (Gemini Developer API) หรือ vertexV1Beta1 (Agent Platform Gemini API (formerly Vertex AI))
• event.data.model: เส้นทางทรัพยากรโมเดลแบบเต็ม (เช่น projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.8-flash)
• event.data.template: ข้อมูลเมตาเกี่ยวกับเทมเพลตพรอมต์ของเซิร์ฟเวอร์ที่ใช้ (PromptTemplateInfo) หากมี
• event.data.request: เพย์โหลดคำขอขาออก ประเภทและพร็อพเพอร์ตี้ของออบเจ็กต์จะขึ้นอยู่กับผู้ให้บริการ Gemini API ดังนี้
  • Gemini Developer API (geminiV1Beta): GeminiV1BetaGenerateContentRequest
  • Agent Platform Gemini API (formerly Vertex AI) (vertexV1Beta1): VertexV1Beta1GenerateContentRequest

ข้อมูลเหตุการณ์หลังคำขอ (afterGenerateContent)

ในฟังก์ชัน afterGenerateContent ระบบจะป้อนข้อมูล event.data ด้วยออบเจ็กต์ AfterGenerateContentData ออบเจ็กต์นี้ขยาย BeforeGenerateContentData (ซึ่งให้ api, model, template และ request) และเพิ่มการตอบกลับของโมเดล ดังนี้

• event.data.response: เพย์โหลดการตอบกลับของโมเดล ประเภทออบเจ็กต์และพร็อพเพอร์ตี้จะขึ้นอยู่กับผู้ให้บริการ Gemini API ดังนี้
  • Gemini Developer API (geminiV1Beta): GeminiV1BetaGenerateContentResponse
  • Agent Platform Gemini API (formerly Vertex AI) (vertexV1Beta1): VertexV1Beta1GenerateContentResponse

ข้อจำกัดและลักษณะการทำงาน

เมื่อใช้ฟังก์ชันเหล่านี้ โปรดคำนึงถึงลักษณะการทำงานและข้อจำกัดต่อไปนี้

• คำขอ generateContent เท่านั้น: ฟังก์ชันเหล่านี้จะทริกเกอร์ได้โดยคำขอ generateContent ไปยัง Gemini API ผ่าน Firebase AI Logic เท่านั้น

  การดำเนินการต่อไปนี้จะไม่ทริกเกอร์ฟังก์ชันเหล่านี้ และระบบจะข้ามฟังก์ชันดังกล่าวโดยไม่มีการแจ้งเตือนสำหรับคำขอนั้น

  • คำขอที่ส่งไปยัง generateContentStream จะไม่เรียกใช้ฟังก์ชันเหล่านี้

  • คำขอไปยัง Gemini Live API จะไม่ทริกเกอร์ฟังก์ชันเหล่านี้

• ไม่มีการเปลี่ยนแปลงโค้ดฝั่งไคลเอ็นต์: นอกเหนือจากการตรวจสอบว่าคุณใช้คำขอ generateContent เมื่อต้องการเรียกใช้ฟังก์ชันเหล่านี้ คุณไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ ในฐานของโค้ดฝั่งไคลเอ็นต์

  ระบบจะติดตั้งใช้งานฟังก์ชันเหล่านี้ในเซิร์ฟเวอร์ของเรา และลงทะเบียนเป็นทริกเกอร์ Firebase AI Logic เพื่อให้พร็อกซี Firebase AI Logic สามารถสกัดกั้นคำขอและการตอบกลับฝั่งเซิร์ฟเวอร์ได้

• ขอบเขตระดับโปรเจ็กต์: คุณสามารถติดตั้งใช้งานฟังก์ชัน beforeGenerateContent ได้สูงสุด 1 รายการและฟังก์ชัน afterGenerateContent ได้สูงสุด 1 รายการต่อโปรเจ็กต์ Firebase

• ตำแหน่งเริ่มต้น: ระบบจะติดตั้งใช้งานฟังก์ชันเหล่านี้ใน us-central1 โดยค่าเริ่มต้น (ดูข้อมูลเกี่ยวกับตำแหน่งสำหรับฟังก์ชัน) อย่างไรก็ตาม ระบบจะลงทะเบียนฟังก์ชันเป็นทริกเกอร์ Firebase AI Logic ในภูมิภาค global ไม่ว่าคุณจะติดตั้งใช้งานฟังก์ชันที่ใดก็ตาม