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 等）运行数据流，系统会自动设置项目 ID 和凭据。在其他环境中运行需要将 GCLOUD_PROJECT 环境变量设置为您的 Google Cloud 项目，并使用 gcloud 工具进行身份验证：

gcloud auth application-default login

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

插件配置

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

{
    projectId?: string,
    forceDevExport?: boolean,
    telemetryConfig?: TelemetryConfig
}

projectId

使用此选项时，您可以明确指定 Google Cloud 项目 ID。在大多数情况下，这是没有必要的。

forceDevExport

此选项会强制 Genkit 在 dev 环境（例如本地）中运行时导出遥测数据和日志数据。

遥测配置

此选项会配置 OpenTelemetry NodeSDK 实例。

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

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

采样器

对于无法导出所有跟踪记录的情况，OpenTelemetry 允许对跟踪记录进行采样。

有四个预配置的采样器：

autoInstrumentation 和 autoInstrumentationConfig

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

metricExportInterval

此字段用于指定指标导出时间间隔（以毫秒为单位）。

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

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

日志和跟踪记录

在侧边菜单中，找到“Logging”并点击“日志浏览器”。

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

对于特定的日志行，通过点击扩展菜单 图标并选择“View in trace details”，可以导航到其各自的跟踪记录。

系统将打开一个轨迹预览窗格，可让您快速浏览轨迹详情。如需获取完整详细信息，请点击窗格右上角的“View in Trace”链接。

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

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

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

结果视图让您可以在跟踪记录的上下文中详细检查日志，包括提示和 LLM 响应。

指标

从侧边菜单中选择“日志记录”，然后点击“指标管理”，即可查看 Genkit 导出的所有指标。

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

Genkit 会收集几类指标，包括流级、操作级和生成级指标。每个指标都有几个有助于进行强大过滤和分组的实用维度。

常见维度包括：

  • flow_name - 流的顶级名称。
  • flow_path - span 及其父级 span 链，一直到根 span。
  • error_code - 如果出现错误，对应的错误代码。
  • error_message - 如果出现错误，对应的错误消息。
  • model - 模型的名称。
  • temperature - 推断温度值。
  • topK - 推断 TopK 值。
  • topP - 推断的 TopP 值。

流级别的指标

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

操作级指标

名称 维度
genkit/操作/请求 flow_name、error_code、error_message
genkit/操作/延迟时间 流名称

生成级指标

名称 维度
genkit/ai/generate flow_path、model、 temperature、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/generate/latency flow_path、model、 temperature、topK、topP、error_code、error_message

您可以通过 Metrics Explorer 来直观呈现指标。在侧边菜单中，选择“Logging”，然后点击“Metrics Explorer”

点击“选择指标”下拉菜单，然后选择“通用节点”“Genkit”和指标，即可选择指标。

指标的可视化效果取决于其类型（计数器、直方图等）。Metrics Explorer 提供了强大的汇总和查询工具，可帮助您按各个维度绘制指标图表。

遥测延迟

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

配额和限制

有几个配额需要注意：

费用

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