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 的功能,请将 googleCloud 插件添加到 Genkit 配置中:

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 等)运行 flow,系统会自动设置项目 ID 和凭据。

应用默认凭据

如需在其他环境中运行,需要将 GCLOUD_PROJECT 环境变量设置为您的 Google Cloud 项目,并使用 gcloud 工具进行身份验证:

gcloud auth application-default login

如需了解详情,请参阅应用默认凭据文档。

服务账号凭据

如果您使用的是服务账号,并且在 Google Cloud 环境之外运行,则可以将凭据设置为环境变量。按照此处的说明设置 Google Cloud 服务账号密钥

下载密钥文件后,您可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量在文件位置采用两种方式指定凭据,也可以直接将 json 文件的内容复制到环境变量 GCLOUD_SERVICE_ACCOUNT_CREDS 中。

文件路径:

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

直接复制:

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"
}'

插件配置

googleCloud() 插件可接受可选的配置对象:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

此选项允许明确指定 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,
  },
});

forceDevExport

选择此选项后,Genkit 在 dev 环境(例如本地)中运行时会导出遥测数据和日志数据。

采样器

如果导出所有轨迹不切实际,OpenTelemetry 允许对轨迹进行采样

有四种预配置的采样器:

autoInstrumentation 和autoInstrumentationConfig

启用自动插桩后,OpenTelemetry 便可从第三方库捕获遥测数据,而无需修改代码。

MetricsExportInterval

此字段指定指标导出间隔(以毫秒为单位)。

测试您的集成

配置该插件时,请使用 forceDevExport: true 为本地运行启用遥测数据导出。这是快速发送您的第一个事件以便在 Google Cloud 中进行监控的方法。

通过 Google Cloud 的运维套件监控生产环境

部署 flow 后,请前往 Google Cloud 的运维套件,然后选择您的项目。

日志和跟踪记录

在侧边菜单中,找到“Logging“,然后点击“Logs Explorer”。

您会看到与已部署的 flow 关联的所有日志,包括 console.log()。任何带有前缀 [genkit] 的日志都是 Genkit 内部日志,其中包含一些可能对调试有用的信息。例如,格式为 Config[...] 的 Genkit 日志包含用于特定 LLM 推理的温度和 topK 值等元数据。格式为 Output[...] 的日志包含 LLM 回答,而 Input[...] 日志包含提示。Cloud Logging 具有强大的 ACL,可对敏感日志进行精细控制。

对于特定日志行,您可以点击展开的菜单 图标并选择“View in trace details”,以找到其各自的跟踪记录。

系统会打开一个跟踪记录预览窗格,您可在其中快速浏览跟踪记录的详细信息。如需查看完整详情,请点击窗格右上角的“在 Trace 中查看”链接。

Cloud Trace 中最突出的导航元素是跟踪记录散点图。该散点图包含在给定时间范围内收集的所有跟踪记录。

点击每个数据点会在散点图下方显示详细信息。

详细视图包含 flow 形状(包括所有步骤)和重要时间信息。Cloud Trace 能够在此视图中交织与给定跟踪记录关联的所有日志。在“日志和事件”下拉菜单中,选择“显示展开的内容”选项。

在生成的视图中,您可以详细检查跟踪记录的上下文中的日志,包括提示和 LLM 回答。

指标

如需查看 Genkit 导出的所有指标,请从侧边菜单中选择“Logging”,然后点击“指标管理”。

指标管理控制台包含一个表格视图,其中包含所有收集的指标,包括与 Cloud Run 及其周围环境相关的指标。点击“工作负载”选项会显示一个包含 Genkit 收集的指标的列表。任何带有前缀 genkit 的指标都是内部 Genkit 指标。

Genkit 会收集多种类别的指标,包括 flow 级指标、操作级指标和生成级指标。每个指标都有几个实用的维度,以便实现强大的过滤和分组功能。

常见的维度包括:

  • flow_name - flow 的顶级名称。
  • flow_path - span 及其父级 span 链,直到根 span。
  • error_code - 如果出现错误,则为相应的错误代码。
  • error_message - 如果出现错误,则为相应的错误消息。
  • model - 模型的名称。
  • temperature - 推理温度
  • topK - 推理 topK
  • topP - 推理 topP

Flow 级指标

名称 维度
genkit/flow/requests flow_name、error_code、error_message
genkit/flow/latency flow_name

操作级指标

名称 维度
genkit/action/requests flow_name、error_code、error_message
genkit/action/latency flow_name

生成级指标

名称 维度
genkit/ai/generate flow_path、model、temperature、topK、topP、error_code、error_message
genkit/ai/generate/input_tokens flow_path、model、temperature、topK、topP
genkit/ai/generate/output_tokens flow_path、model、temperature、topK、topP
genkit/ai/generate/input_characters flow_path、model、temperature、topK、topP
genkit/ai/generate/output_characters flow_path、model、temperature、topK、topP
genkit/ai/generate/input_images flow_path、model、temperature、topK、topP
genkit/ai/generate/output_images flow_path、model、temperature、topK、topP
genkit/ai/generate/latency flow_path、model、temperature、topK、topP、error_code、error_message

您可以通过 Metrics Explorer 直观呈现指标。使用侧边菜单,选择“Logging”,然后点击“Metrics Explorer”

点击“选择指标”下拉菜单,选择“通用节点”“Genkit”和一个指标,以选择指标。

指标的直观呈现取决于其类型(计数器、直方图等)。Metrics Explorer 提供了强大的汇总和查询功能,可帮助您按各种维度绘制指标图表。

遥测数据延迟

Flow 的特定执行的遥测数据可能略有延迟才会显示在 Cloud 的运维套件中。在大多数情况下,此延迟不到 1 分钟。

配额和限制

请务必注意以下几个配额:

费用

Cloud Logging、Cloud Trace 和 Cloud Monitoring 提供宽裕的免费层级。如需查看具体价格,请访问以下链接: