ปลั๊กอิน Google Cloud

ปลั๊กอิน Google Cloud จะส่งออกข้อมูลการวัดและการบันทึกของ Firebase Genkit ไปยังชุดเครื่องมือตรวจสอบ Cloud ซึ่งขับเคลื่อนแดชบอร์ดการตรวจสอบ AI ของ Firebase

การติดตั้ง

npm i --save @genkit-ai/google-cloud

เมื่อเรียกใช้โค้ด Genkit ในเครื่องซึ่งมีปลั๊กอินนี้ คุณจะต้องติดตั้งเครื่องมือ CLI ของ Google Cloud ด้วย

ตั้งค่าบัญชี Google Cloud

ปลั๊กอินนี้ต้องใช้บัญชี/โปรเจ็กต์ Google Cloud โปรเจ็กต์ Firebase ทั้งหมดจะมีคอนโซลนี้โดยค่าเริ่มต้น (คอนโซล GCP) หรือคุณจะลงชื่อสมัครใช้ที่ https://cloud.google.com ก็ได้

ก่อนเพิ่มปลั๊กอิน ให้ตรวจสอบว่าได้เปิดใช้ API ต่อไปนี้สําหรับโปรเจ็กต์ GCP แล้ว

API เหล่านี้ควรแสดงอยู่ในหน้าแดชบอร์ด API ของโปรเจ็กต์

คลิกที่นี่เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการเปิดและปิดใช้ API

การกําหนดค่า Genkit

หากต้องการเปิดใช้การติดตาม การบันทึก และการตรวจสอบ (เมตริก) ของ Cloud ให้เรียกใช้ enableGoogleCloudTelemetry()

import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';

enableGoogleCloudTelemetry();

เมื่อทํางานในเวอร์ชันที่ใช้งานจริง ระบบจะส่งออกข้อมูลการวัดผลโดยอัตโนมัติ

การตรวจสอบสิทธิ์และการให้สิทธิ์

ปลั๊กอินต้องใช้รหัสโปรเจ็กต์ Google Cloud และข้อมูลเข้าสู่ระบบแอปพลิเคชัน

Google Cloud

หากทำให้โค้ดใช้งานได้ในสภาพแวดล้อม Google Cloud (Cloud Functions, Cloud Run ฯลฯ) ระบบจะค้นหารหัสโปรเจ็กต์และข้อมูลเข้าสู่ระบบโดยอัตโนมัติผ่านข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน

คุณจะต้องกำหนดบทบาทต่อไปนี้ให้กับบัญชีบริการที่เรียกใช้โค้ด (เช่น "บัญชีบริการที่แนบมา") ผ่านคอนโซล IAM

  • roles/monitoring.metricWriter
  • roles/cloudtrace.agent
  • roles/logging.logWriter

การพัฒนาในพื้นที่

เมื่อทําการพัฒนาในเครื่อง คุณจะต้องทําตามขั้นตอนเพิ่มเติมเพื่อให้ข้อมูลเข้าสู่ระบบของผู้ใช้พร้อมใช้งานสําหรับปลั๊กอิน

  1. ตั้งค่าตัวแปรสภาพแวดล้อม GCLOUD_PROJECT เป็นโปรเจ็กต์ Google Cloud

  2. ตรวจสอบสิทธิ์โดยใช้ gcloud CLI

    gcloud auth application-default login

สภาพแวดล้อมเวอร์ชันที่ใช้งานจริงนอก Google Cloud

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

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

  1. ทำตามวิธีการเพื่อตั้งค่าคีย์บัญชีบริการ

  2. ตรวจสอบว่าบัญชีบริการมีบทบาทต่อไปนี้

    • roles/monitoring.metricWriter
    • roles/cloudtrace.agent
    • roles/logging.logWriter

  3. ติดตั้งใช้งานไฟล์ข้อมูลเข้าสู่ระบบในเวอร์ชันที่ใช้งานจริง (อย่าตรวจสอบในซอร์สโค้ด)

  4. ตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เป็นเส้นทางไปยังไฟล์ข้อมูลเข้าสู่ระบบ

    GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

ในสภาพแวดล้อมแบบเซิร์ฟเวอร์เสมือนบางสภาพแวดล้อม คุณอาจไม่สามารถทำให้ไฟล์ข้อมูลเข้าสู่ระบบใช้งานได้ ในกรณีนี้ คุณสามารถตั้งค่าตัวแปรสภาพแวดล้อม GCLOUD_SERVICE_ACCOUNT_CREDS ด้วยเนื้อหาของไฟล์ข้อมูลเข้าสู่ระบบแทนขั้นตอนที่ 3 และ 4 ด้านบน ดังนี้

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

การกำหนดค่าปลั๊กอิน

ฟังก์ชัน enableGoogleCloudTelemetry() จะรับออบเจ็กต์การกําหนดค่าที่ไม่บังคับซึ่งกําหนดค่าอินสแตนซ์ OpenTelemetry NodeSDK

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

enableGoogleCloudTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
  sampler: new AlwaysOnSampler(),
  autoInstrumentation: true,
  autoInstrumentationConfig: {
    '@opentelemetry/instrumentation-fs': { enabled: false },
    '@opentelemetry/instrumentation-dns': { enabled: false },
    '@opentelemetry/instrumentation-net': { enabled: false },
  },
  metricExportIntervalMillis: 5_000,
});

ออบเจ็กต์การกําหนดค่าช่วยให้ควบคุมแง่มุมต่างๆ ของการส่งออกข้อมูลการวัดและส่งข้อมูลทางไกลที่ระบุไว้ด้านล่างได้

ข้อมูลเข้าสู่ระบบ

อนุญาตให้ระบุข้อมูลเข้าสู่ระบบโดยตรงโดยใช้ JWTInput จากไลบรารี google-auth

แซมเพลอร์

สําหรับกรณีที่การส่งออกร่องรอยทั้งหมดไม่เหมาะสําหรับการใช้งาน OpenTelemetry อนุญาตให้สุ่มตัวอย่างร่องรอย

เครื่องมือสุ่มตัวอย่างที่กำหนดค่าไว้ล่วงหน้ามี 4 รายการดังนี้

  • AlwaysOnSampler - บันทึกตัวอย่างร่องรอยทั้งหมด
  • AlwaysOffSampler - ไม่สุ่มตัวอย่างร่องรอย
  • ParentBased - ตัวอย่างตามช่วงของรายการหลัก
  • TraceIdRatioBased - สุ่มตัวอย่างการติดตามตามเปอร์เซ็นต์ที่กำหนดค่าได้

autoInstrumentation และ autoInstrumentationConfig

การเปิดใช้เครื่องมือวัดอัตโนมัติช่วยให้ OpenTelemetry สามารถบันทึกข้อมูลการวัดจากไลบรารีของบุคคลที่สามได้โดยไม่ต้องแก้ไขโค้ด

metricExportIntervalMillis

ช่องนี้จะระบุช่วงเวลาการส่งออกเมตริกเป็นมิลลิวินาที

metricExportTimeoutMillis

ช่องนี้จะระบุการหมดเวลาสําหรับการส่งออกเมตริกเป็นมิลลิวินาที

disableMetrics

ระบุการลบล้างที่ปิดใช้การส่งออกเมตริกขณะที่ยังคงส่งออกร่องรอยและบันทึก

disableTraces

ให้การลบล้างที่ปิดใช้การส่งออกร่องรอยขณะที่ยังคงส่งออกเมตริกและบันทึก

disableLoggingIO

ให้การลบล้างที่ปิดใช้การเก็บรวบรวมบันทึกอินพุตและเอาต์พุต

forceDevExport

ตัวเลือกนี้จะบังคับให้ Genkit ส่งออกข้อมูลการวัดและการบันทึกเมื่อทํางานในสภาพแวดล้อม dev (เช่น ในพื้นที่)

ทดสอบการผสานรวม

เมื่อกําหนดค่าปลั๊กอิน ให้ใช้ forceDevExport: true เพื่อเปิดใช้การส่งออกข้อมูลการวัดผลสําหรับการเรียกใช้ในเครื่อง ไปที่เครื่องมือสำรวจบันทึก เมตริก หรือการติดตามของ Google Cloud เพื่อดูการวัดผล

ชุดเครื่องมือความสามารถในการสังเกตของ Google Cloud

เมื่อทําให้การเผยแพร่โค้ด (เช่น เวิร์กโฟลว์) แล้ว ให้ไปที่แดชบอร์ด Cloud Monitoring แล้วเลือกโปรเจ็กต์ จากตรงนี้ คุณสามารถไปยังส่วนต่างๆ ของเครื่องมือสำรวจบันทึก เครื่องมือสำรวจเมตริก และเครื่องมือสำรวจการติดตามสําหรับการตรวจสอบเวอร์ชันที่ใช้งานจริงได้อย่างง่ายดาย

บันทึกและการติดตาม

จากเมนูด้านซ้ายมือ ให้คลิก "เครื่องมือสำรวจบันทึก" ในส่วนหัว "สํารวจ"

คุณจะเห็นบันทึกทั้งหมดที่เชื่อมโยงกับโค้ด Genkit ที่ติดตั้งใช้งาน รวมถึง console.log() บันทึกที่มีคำนำหน้า [genkit] คือบันทึกภายในของ Genkit ที่มีข้อมูลที่อาจเป็นประโยชน์สำหรับการแก้ไขข้อบกพร่อง ตัวอย่างเช่น บันทึกของ Genkit ในรูปแบบ Config[...] จะมีข้อมูลเมตา เช่น ค่าอุณหภูมิและ topK สำหรับการอนุมาน LLM ที่เฉพาะเจาะจง บันทึกในรูปแบบ Output[...] จะมีคําตอบ LLM ส่วนบันทึก Input[...] จะมีพรอมต์ Cloud Logging มี ACL ที่มีประสิทธิภาพซึ่งช่วยให้ควบคุมการเข้าถึงบันทึกที่มีความละเอียดอ่อนได้อย่างละเอียด

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

องค์ประกอบการนําทางที่โดดเด่นที่สุดใน Cloud Trace คือผังกระจายของร่องรอย ซึ่งประกอบด้วยร่องรอยที่รวบรวมทั้งหมดในระยะเวลาที่ระบุ

การคลิกจุดข้อมูลแต่ละจุดจะแสดงรายละเอียดด้านล่างผังกระจาย

มุมมองแบบละเอียดจะมีรูปร่างของขั้นตอน ซึ่งรวมถึงขั้นตอนทั้งหมดและข้อมูลการกําหนดเวลาที่สําคัญ Cloud Trace สามารถแทรกบันทึกทั้งหมดที่เชื่อมโยงกับการติดตามหนึ่งๆ ภายในมุมมองนี้ได้ เลือกตัวเลือก "แสดงแบบขยาย" ในเมนูแบบเลื่อนลง "บันทึกและเหตุการณ์"

มุมมองที่ได้จะช่วยให้ตรวจสอบบันทึกโดยละเอียดในบริบทของการติดตาม รวมถึงพรอมต์และการตอบกลับของ LLM

เมตริก

คุณดูเมตริกทั้งหมดที่ Genkit ส่งออกได้โดยคลิก "การจัดการเมตริก" ในส่วนหัว "กําหนดค่า" ในเมนูด้านซ้ายมือ

คอนโซลการจัดการเมตริกมีมุมมองตารางของเมตริกที่รวบรวมทั้งหมด รวมถึงเมตริกที่เกี่ยวข้องกับ Cloud Run และสภาพแวดล้อมรอบข้าง การคลิกตัวเลือก "เวิร์กโหลด" จะแสดงรายการที่มีเมตริกที่ Genkit รวบรวม เมตริกที่มีคำนำหน้า genkit จะเป็นเมตริก Genkit ภายใน

Genkit จะรวบรวมเมตริกหลายหมวดหมู่ ซึ่งรวมถึงฟีเจอร์ การดําเนินการ และการสร้าง เมตริกแต่ละรายการมีมิติข้อมูลที่มีประโยชน์หลายรายการที่ช่วยให้กรองและจัดกลุ่มได้อย่างมีประสิทธิภาพ

มิติข้อมูลที่พบได้ทั่วไปมีดังนี้

  • flow_name - ชื่อระดับบนสุดของโฟลว์
  • flow_path - ช่วงที่เชื่อมโยงกับช่วงระดับบนสุดไปจนถึงช่วงรูท
  • error_code - ในกรณีที่เกิดข้อผิดพลาด ให้ระบุรหัสข้อผิดพลาดที่เกี่ยวข้อง
  • error_message - ในกรณีที่เกิดข้อผิดพลาด ข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง
  • model - ชื่อของโมเดล

เมตริกฟีเจอร์

ฟีเจอร์คือจุดแรกเข้าระดับบนสุดของโค้ด Genkit ในกรณีส่วนใหญ่ การดำเนินการนี้จะเป็นแบบโฟลว์ มิฉะนั้น จะเป็นสแปนที่อยู่บนสุดในการติดตาม

ชื่อ ประเภท คำอธิบาย
genkit/feature/requests ตัวนับ จำนวนคำขอ
genkit/feature/latency ฮิสโตแกรม เวลาในการตอบสนองของการดำเนินการเป็นมิลลิวินาที

เมตริกฟีเจอร์แต่ละรายการประกอบด้วยมิติข้อมูลต่อไปนี้

ชื่อ คำอธิบาย
name ชื่อของฟีเจอร์ ในกรณีส่วนใหญ่ นี่เป็นเวิร์กโฟลว์ Genkit ระดับบนสุด
สถานะ "success" หรือ "failure" โดยขึ้นอยู่กับว่าคำขอฟีเจอร์สำเร็จหรือไม่
ข้อผิดพลาด ตั้งค่าเฉพาะเมื่อ status=failure มีประเภทข้อผิดพลาดที่ทําให้ดำเนินการไม่สําเร็จ
source ภาษาต้นฉบับของ Genkit เช่น 'ts'
sourceVersion เวอร์ชันเฟรมเวิร์ก Genkit

เมตริกการกระทํา

การดําเนินการแสดงถึงขั้นตอนทั่วไปของการดำเนินการภายใน Genkit ขั้นตอนแต่ละขั้นตอนเหล่านี้จะมีการติดตามเมตริกต่อไปนี้

ชื่อ ประเภท คำอธิบาย
genkit/action/requests ตัวนับ จํานวนครั้งที่ดําเนินการนี้
genkit/action/latency ฮิสโตแกรม เวลาในการตอบสนองของการดำเนินการเป็นมิลลิวินาที

เมตริกการกระทําแต่ละรายการประกอบด้วยมิติข้อมูลต่อไปนี้

ชื่อ คำอธิบาย
name ชื่อการดำเนินการ
featureName ชื่อของฟีเจอร์หลักที่ใช้งานอยู่
เส้นทาง เส้นทางการเรียกใช้จากรูทฟีเจอร์ไปยังการดำเนินการนี้ เช่น '/myFeature/parentAction/thisAction'
สถานะ "สำเร็จ" หรือ "ไม่สำเร็จ" โดยขึ้นอยู่กับว่าการดำเนินการสำเร็จหรือไม่
ข้อผิดพลาด ตั้งค่าเฉพาะเมื่อ status=failure มีประเภทข้อผิดพลาดที่ทําให้ดำเนินการไม่สําเร็จ
source ภาษาต้นฉบับของ Genkit เช่น 'ts'
sourceVersion เวอร์ชันเฟรมเวิร์ก Genkit

สร้างเมตริก

เมตริกเหล่านี้คือเมตริกการกระทําพิเศษที่เกี่ยวข้องกับการกระทําที่โต้ตอบกับโมเดล นอกจากคำขอและเวลาในการตอบสนองแล้ว ระบบยังติดตามอินพุตและเอาต์พุตด้วย โดยมีมิติข้อมูลเฉพาะโมเดลที่ทําให้การแก้ไขข้อบกพร่องและการปรับการกําหนดค่าง่ายขึ้น

ชื่อ ประเภท คำอธิบาย
genkit/ai/generate/requests ตัวนับ จํานวนครั้งที่มีการเรียกใช้รูปแบบนี้
genkit/ai/generate/latency ฮิสโตแกรม เวลาในการตอบสนองของการดำเนินการเป็นมิลลิวินาที
genkit/ai/generate/input/tokens ตัวนับ โทเค็นอินพุต
genkit/ai/generate/output/tokens ตัวนับ โทเค็นเอาต์พุต
genkit/ai/generate/input/characters ตัวนับ ป้อนอักขระ
genkit/ai/generate/output/characters ตัวนับ อักขระเอาต์พุต
genkit/ai/generate/input/images ตัวนับ รูปภาพอินพุต
genkit/ai/generate/output/images ตัวนับ รูปภาพเอาต์พุต
genkit/ai/generate/input/audio ตัวนับ ป้อนไฟล์เสียง
genkit/ai/generate/output/audio ตัวนับ ไฟล์เสียงเอาต์พุต

เมตริกที่สร้างขึ้นแต่ละรายการจะมีมิติข้อมูลต่อไปนี้

ชื่อ คำอธิบาย
modelName ชื่อของโมเดล
featureName ชื่อของฟีเจอร์หลักที่ใช้งานอยู่
เส้นทาง เส้นทางการเรียกใช้จากรูทฟีเจอร์ไปยังการดำเนินการนี้ เช่น '/myFeature/parentAction/thisAction'
latencyMs เวลาที่โมเดลใช้ในการตอบกลับ
สถานะ "success" หรือ "failure" โดยขึ้นอยู่กับว่าคำขอฟีเจอร์สำเร็จหรือไม่
ข้อผิดพลาด ตั้งค่าเฉพาะเมื่อ status=failure มีประเภทข้อผิดพลาดที่ทําให้ดำเนินการไม่สําเร็จ
source ภาษาต้นฉบับของ Genkit เช่น 'ts'
sourceVersion เวอร์ชันเฟรมเวิร์ก Genkit

การแสดงภาพเมตริกทำได้ผ่านเครื่องมือสํารวจเมตริก ใช้เมนูด้านซ้ายมือเพื่อคลิก "เครื่องมือสํารวจเมตริก" ในส่วนหัว "สํารวจ"

เลือกเมตริกโดยคลิกเมนูแบบเลื่อนลง "เลือกเมตริก" แล้วเลือก 'โหนดทั่วไป', 'Genkit' และเมตริก

ภาพเมตริกจะขึ้นอยู่กับประเภทของเมตริก (ตัวนับ ฮิสโตแกรม ฯลฯ) เครื่องมือสํารวจเมตริกมีเครื่องมือรวบรวมและค้นหาที่มีประสิทธิภาพเพื่อช่วยสร้างกราฟเมตริกตามมิติข้อมูลต่างๆ

ความล่าช้าของข้อมูลที่ได้รับจากทางไกล

ระบบอาจใช้เวลาสักครู่ก่อนที่การวัดผลสําหรับการดําเนินการของฟิวเมนต์หนึ่งๆ จะแสดงในชุดโปรแกรมสําหรับการดําเนินการของ Cloud ในกรณีส่วนใหญ่ ความล่าช้านี้ไม่เกิน 1 นาที

โควต้าและขีดจำกัด

โควต้าที่สำคัญที่ควรทราบมีดังนี้

ค่าใช้จ่าย

Cloud Logging, Cloud Trace และ Cloud Monitoring มีระดับการใช้งานแบบไม่มีค่าใช้จ่ายที่คุ้มค่า ดูราคาที่เจาะจงได้ที่ลิงก์ต่อไปนี้