Google Cloud 外掛程式

Google Cloud 外掛程式會將 Firebase Genkit 遙測和記錄資料匯出至 Cloud Observability 套件，以便支援 Firebase AI Monitoring 資訊主頁。

安裝

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

在本機執行含有此外掛程式的 Genkit 程式碼時，您也需要安裝 Google Cloud CLI 工具。

設定 Google Cloud 帳戶

這個外掛程式需要 Google Cloud 帳戶/專案。根據預設，所有 Firebase 專案都會包含一個 (GCP 主控台)，您也可以前往 https://cloud.google.com 註冊。

在新增外掛程式之前，請確認已為 GCP 專案啟用下列 API：

這些 API 應列在專案的 API 資訊主頁中。

如要進一步瞭解如何啟用及停用 API，請按這裡。

Genkit 設定

如要啟用 Cloud Tracing、Logging 和 Monitoring (指標)，只要呼叫 enableGoogleCloudTelemetry() 即可：

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

enableGoogleCloudTelemetry();

在實際環境中執行時，系統會自動匯出遙測資料。

驗證及授權

外掛程式需要 Google Cloud 專案 ID 和應用程式憑證。

Google Cloud

如果您將程式碼部署至 Google Cloud 環境 (Cloud Functions、Cloud Run 等)，系統會透過應用程式預設憑證自動偵測專案 ID 和憑證。

您必須透過 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,
});

設定物件可精細控管下列所述的遙測資料匯出作業的各個層面。

憑證

允許使用 Google 授權程式庫中的 JWTInput 直接指定憑證。

取樣器

如果無法匯出所有追蹤記錄，OpenTelemetry 允許追蹤取樣。

四種預先設定的取樣器如下：

autoInstrumentation 和 autoInstrumentationConfig

啟用自動檢測功能後，OpenTelemetry 就能擷取第三方程式庫的遙測資料，而無須修改程式碼。

metricExportIntervalMillis

這個欄位會以毫秒為單位指定指標匯出間隔。

metricExportTimeoutMillis

這個欄位會以毫秒為單位，指定指標匯出作業的逾時時間。

disableMetrics

提供覆寫值，可在匯出記錄和記錄的同時停用指標匯出功能。

disableTraces

提供覆寫值，可在匯出指標和記錄的同時，停用匯出追蹤記錄的功能。

disableLoggingIO

提供覆寫值，停用輸入和輸出記錄收集功能。

forceDevExport

這個選項會在 dev 環境 (例如本機) 中執行時，強制 Genkit 匯出遙測資料和記錄資料。

測試整合

設定外掛程式時，請使用 forceDevExport: true 啟用本機執行的遙測資料匯出功能。前往 Google Cloud 記錄、Metrics 或 Trace Explorer，查看遙測資料。

Google Cloud Observability 套件

程式碼 (例如流程) 部署完成後，請前往 Cloud Monitoring 資訊主頁並選取專案。您可以輕鬆瀏覽「記錄」、「指標」和「追蹤」探索器，用於實際工作環境監控。

記錄和追蹤記錄

在左側選單中，按一下「探索」標題下方的「記錄瀏覽器」。

您會在這裡看到與已部署的 Genkit 程式碼相關的所有記錄，包括 console.log()。任何前置字串為 [genkit] 的記錄都是 Genkit 內部記錄，其中包含可能對偵錯有用的資訊。舉例來說，格式為 Config[...] 的 Genkit 記錄包含中繼資料，例如特定 LLM 推論的溫度和 topK 值。格式為 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 直方圖 執行延遲時間 (以毫秒為單位)

每項功能指標都包含下列維度：

名稱 說明
名稱 功能名稱。在大多數情況下，這是頂層 Genkit 流程
狀態 視功能要求是否成功而定，傳回「成功」或「失敗」
錯誤 只有在 status=failure 時才會設定。包含導致失敗的錯誤類型
來源 Genkit 原文語言。例如：'ts'
sourceVersion Genkit 架構版本

動作指標

動作代表 Genkit 中的一般執行步驟。系統會追蹤下列指標：

名稱 類型 說明
genkit/action/requests 計數器 這項動作的執行次數
genkit/action/latency 直方圖 執行延遲時間 (以毫秒為單位)

每項行動指標都包含下列維度：

名稱 說明
名稱 動作名稱
featureName 正在執行的父項功能名稱
路徑 從功能根目錄到此動作的執行路徑，例如'/myFeature/parentAction/thisAction'
狀態 視動作是否成功而定，傳回「成功」或「失敗」
錯誤 只有在 status=failure 時才會設定。包含導致失敗的錯誤類型
來源 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 模型的回應時間
狀態 視功能要求是否成功而定，傳回「成功」或「失敗」
錯誤 只有在 status=failure 時才會設定。包含導致失敗的錯誤類型
來源 Genkit 原文語言。例如：'ts'
sourceVersion Genkit 架構版本

您可以透過 Metrics Explorer 視覺化指標。使用左側選單，按一下「探索」標題下方的「Metrics Explorer」。

按一下「選取指標」下拉式選單，選取「Generic Node」、「Genkit」和指標，即可選取指標。

指標的視覺化呈現方式取決於指標類型 (計數器、直方圖等)。Metrics Explorer 提供強大的匯總和查詢工具，可根據各種維度繪製指標圖表。

遙測延遲

在 Cloud 的作業套件中顯示特定執行作業的遙測資料前，可能會稍微延遲。在大多數情況下，這項延遲時間會低於 1 分鐘。

配額與限制

請注意以下幾項重要的配額：

費用

Cloud Logging、Cloud Trace 和 Cloud Monitoring 提供豐富的免費方案。如要瞭解具體價格，請點選下列連結：