Google Cloud 外掛程式

Google Cloud 外掛程式會將 Firebase Genkit 的遙測和記錄資料匯出至 Google Cloud 作業套件。

安裝項目

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

如果想在本機執行使用這個外掛程式的流程，您也需要安裝 Google Cloud CLI 工具。

設定 Google Cloud 帳戶

您必須具備 Google Cloud 帳戶 (如果您還沒有帳戶，請先註冊) 和 Google Cloud 專案，才能使用這個外掛程式。

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

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

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

Genkit 設定

如要啟用匯出至 Google Cloud Tracing、Logging 和 Monitoring 的功能，請在 Genkit 設定中新增 googleCloud 外掛程式：

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

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

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

外掛程式需要 Google Cloud 專案 ID 和 Google Cloud 專案憑證。如果您是從 Google Cloud 環境 (Cloud Functions、Cloud Run 等) 執行流程，系統會自動設定專案 ID 和憑證。如要在其他環境中執行作業，你必須將 GCLOUD_PROJECT 環境變數設為 Google Cloud 專案，並使用 gcloud 工具進行驗證：

gcloud auth application-default login

如需詳細資訊，請參閱「應用程式預設憑證」說明文件。

外掛程式設定

googleCloud() 外掛程式會採用選用的設定物件：

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

專案 ID

這個選項可讓您明確指定 Google Cloud 專案 ID。在大部分的情況下，此步驟並非必要。

遙測設定

這個選項會設定 OpenTelemetry NodeSDK 執行個體，

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

googleCloud({
  telemetryConfig: {
    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,
  },
});

強制開發匯出

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

取樣器

如果匯出所有追蹤記錄並不可行，OpenTelemetry 允許對追蹤記錄取樣。

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

檢測與 autoInstrumentation 設定

啟用自動檢測功能，可讓 OpenTelemetry 從第三方程式庫擷取遙測資料，無需修改程式碼。

指標匯出間隔

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

測試整合功能

設定外掛程式時，請使用 forceDevExport: true 啟用本機執行的遙測匯出功能。這種做法能快速傳送第一項事件來進行 Google Cloud 監控。

透過 Google Cloud 作業套件監控正式環境

部署流程後，請前往 Google Cloud 作業套件，然後選取所需專案。

記錄檔和追蹤記錄

在側邊選單中找到「記錄」，然後按一下「記錄檔探索工具」。

畫面會顯示與已部署流程相關聯的所有記錄，包括 console.log()。任何前置字串為 [genkit] 的記錄都是 Genkit-internal 記錄，當中包含可能用於偵錯的資訊。舉例來說，採用 Config[...] 格式的 Genkit 記錄含有特定 LLM 推論的中繼資料，例如溫度和 TopK 值。Output[...] 格式的記錄含有 LLM 回應，Input[...] 記錄則含有提示。Cloud Logging 擁有完善的 ACL，可讓您精細控管機密記錄檔。

如需查看特定記錄行，可以按一下擴充選單 圖示並選取「在追蹤記錄詳細資料中查看」，前往個別追蹤記錄。

系統隨即顯示追蹤記錄預覽窗格，方便您快速查看追蹤記錄的詳細資料。如要查看完整詳細資料，請按一下窗格右上方的「在追蹤記錄中查看」連結。

Cloud Trace 中最醒目的導覽元素是追蹤記錄散佈圖。其中包含指定時間範圍內收集的所有追蹤記錄。

按一下各個資料點，即可在散佈圖下方顯示詳細資料。

詳細資料檢視畫面會包含流程形狀，包括所有步驟和重要時間資訊。Cloud Trace 可以在這個檢視畫面中交錯與特定追蹤記錄相關的所有記錄，在「記錄和事件」下拉式選單中選取「顯示已展開」選項。

產生結果檢視畫面可讓您詳細檢查追蹤記錄中的記錄檔，包括提示和 LLM 回覆。

指標

如要查看 Genkit 匯出項目的所有指標，請從側邊選單中選取「記錄」，然後按一下「指標管理」。

指標管理主控台提供所有收集到的指標表格，包括 Cloud Run 及其周遭環境的相關指標。按一下「Workload」(工作負載) 選項，系統就會顯示包含 Genkit 收集指標的清單。前置字串為 genkit 的任何指標都會構成內部 Genkit 指標。

Genkit 會收集多種指標，包括流程層級、動作層級和產生層級指標。每項指標都有幾個實用維度，有助於發揮強大的篩選和分組功能。

常見維度包括：

  • flow_name - 資料流的頂層名稱。
  • flow_path - 跨距及其父項時距鏈結至根時距。
  • error_code：如果發生錯誤，則為對應的錯誤代碼。
  • error_message：如果發生錯誤，則為對應的錯誤訊息。
  • model：模型的名稱。
  • temperature - 推論溫度 value。
  • topK - 推論的 TopK 值。
  • topP - 推論的 TopP 值。

流程層級指標

名稱 維度
genkit/流程/要求 流程名稱、error_code、error_message
genkit/流程/延遲 流程名稱

動作層級指標

名稱 維度
genkit/行動/要求 流程名稱、error_code、error_message
genkit/動作/延遲 流程名稱

產生層級指標

名稱 維度
genkit/AI/生成 流量路徑、模型、隨機性參數、topK、topP、error_code、error_message
genkit/ai/generate/input_tokens 流量路徑、模型、溫度、TopK、TopP
genkit/ai/generate/output_tokens 流量路徑、模型、溫度、TopK、TopP
genkit/ai/generate/input_characters 流量路徑、模型、溫度、TopK、TopP
genkit/ai/generate/output_characters 流量路徑、模型、溫度、TopK、TopP
genkit/ai/generate/input_images 流量路徑、模型、溫度、TopK、TopP
genkit/ai/generate/output_images 流量路徑、模型、溫度、TopK、TopP
genkit/ai/生成/延遲 流量路徑、模型、隨機性參數、topK、topP、error_code、error_message

您可以透過 Metrics Explorer 以視覺化方式呈現指標。在側邊選單中選擇「記錄」，然後按一下「Metrics Explorer」

按一下「選取指標」下拉式選單，選取「一般節點」、「Genkit」和指標，即可選取指標。

指標的視覺化呈現取決於其類型 (計數器、直方圖等)。Metrics Explorer 提供強大的匯總和查詢功能，協助依各種維度繪製指標圖表。

遙測延遲

在 Cloud 作業套件中，特定流程的遙測執行前，可能會有略微的延遲。在大多數情況下，這類延遲不會超過 1 分鐘。

配額與限制

請留意以下幾項配額：

費用

Cloud Logging、Cloud Trace 和 Cloud Monitoring 提供免費方案。如需具體定價資訊，請點選下列連結：