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 提供宽裕的免费层级。如需查看具体价格，请访问以下链接：