@genkit-ai/google-cloud

中文文档
1.44.0发布于 2026/11/04Apache-2.0TypeScriptESM + CJS近 30 天下载 92.7万

Genkit AI framework plugin for Google Cloud Platform including Firestore trace/state store and deployment helpers for Cloud Functions for Firebase.

原始使用文档
文档目录10 节
  1. Features
  2. Installation
  3. Google Cloud Observability
  4. Model Armor
  5. Usage
  6. Configuration Options
  7. Firestore Session Store (Beta)
  8. Usage
  9. Options
  10. Reference

Google Cloud Plugin for Genkit

The Google Cloud plugin provides integrations with Google Cloud Platform services for Genkit.

Building with a coding agent? Install the Genkit JS skill first.

npx skills add genkit-ai/skills --skill developing-genkit-js

It teaches your agent the current Genkit JS APIs and common gotchas. Source, manual install and skills for other languages: genkit-ai/skills.

Features

  • Google Cloud Observability: Exports telemetry (traces, metrics) and logs to Google Cloud's operations suite.
  • Model Armor: Middleware for sanitizing user prompts and model responses using Google Cloud Model Armor.
  • Firestore Session Store (Beta): Persists agent session snapshots in Firestore, sharded and scalable to arbitrarily long sessions.

Installation

npm install @genkit-ai/google-cloud

Google Cloud Observability

The plugin allows you to export telemetry data to Google Cloud. This is useful for monitoring your Genkit flows and models in production.

To enable it, use enableGoogleCloudTelemetry:

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

enableGoogleCloudTelemetry({
  // Optional configuration
  // projectId: 'your-project-id',
  // forceDevMode: false, // Set to true to enable export in dev environment
});

This will configure Genkit to send OpenTelemetry traces and metrics to Cloud Trace and Cloud Monitoring, and logs to Cloud Logging.

Model Armor

Google Cloud Model Armor helps you mitigate risks when using Large Language Models (LLMs) by providing a layer of protection that sanitizes both user prompts and model responses.

Usage

You can use the modelArmor middleware in your generation requests:

import { modelArmor } from '@genkit-ai/google-cloud/model-armor';
import { googleAI } from '@genkit-ai/google-genai';
import { genkit } from 'genkit';

const ai = genkit({
  plugins: [googleAI()],
});

const response = await ai.generate({
  model: googleAI.model('gemini-flash-latest'),
  prompt: 'your prompt here',
  use: [
    modelArmor({
      templateName: 'projects/your-project/locations/your-location/templates/your-template',
      // Optional configuration
      filters: ['pi_and_jailbreak', 'malicious_uris'], // Specific filters to enforce
      strictSdpEnforcement: true, // Block if sensitive data is found even if masked
      protectionTarget: 'all', // 'all', 'userPrompt', or 'modelResponse'
      clientOptions: {
        apiEndpoint: 'modelarmor.us-central1.rep.googleapis.com',
      },
    }),
  ],
});

Configuration Options

  • templateName (Required): The resource name of your Model Armor template (e.g., projects/.../locations/.../templates/...).
  • filters (Optional): A list of filters to enforce (e.g., rai, pi_and_jailbreak, malicious_uris, csam, sdp). If not specified, all filters enabled in the template are enforced.
  • strictSdpEnforcement (Optional): If true, blocks execution if Sensitive Data Protection (SDP) detects sensitive info, even if it was successfully de-identified. Defaults to false.
  • protectionTarget (Optional): specificies what to sanitize. Options: 'all' (default), 'userPrompt', 'modelResponse'.
  • clientOptions (Optional): Additional options for the underlying Model Armor client.

Firestore Session Store (Beta)

FirestoreSessionStore is a Firestore-backed SessionStore for persisting agent session snapshots. Unlike a naive single-document store, it persists each turn as an incremental JSON Patch diff anchored to periodic, sharded full-state checkpoints, so:

  • No single document approaches Firestore's 1 MiB limit (state is sharded across documents).
  • The number of documents read/written per turn is bounded by checkpointInterval rather than total session length, so it scales to arbitrarily long sessions (e.g. long-lived chatbots, coding agents).
  • Reconstruction uses only document-ID lookups inside a read-only transaction, so it needs no secondary indexes and is strongly consistent.

If you are running on Firebase, the @genkit-ai/firebase package re-exports this store with Firebase app setup (a firebaseApp option). See its README.

Usage

Import it from @genkit-ai/google-cloud/beta and pass it as the store when defining an agent:

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

const ai = genkit({
  plugins: [
    // ...
  ],
});

const myAgent = ai.defineAgent({
  name: 'myAgent',
  system: 'You are a helpful assistant.',
  // Defaults to a new Firestore() instance using Application Default
  // Credentials; pass `db` to provide your own.
  store: new FirestoreSessionStore(),
});

Options

  • db: An explicit Firestore instance. Defaults to a new Firestore() instance (which picks up Application Default Credentials and the FIRESTORE_EMULATOR_HOST environment variable).
  • collection: The collection where snapshot documents are stored. Defaults to "genkit-sessions". Two companion collections are derived from it: "<collection>-pointers" (one pointer document per session) and "<collection>-shards" (the sharded checkpoint state).
  • checkpointInterval: Number of turns between full-state checkpoints. Defaults to 25. Lower it (e.g. 10) for small-state, read-heavy sessions; raise it (e.g. 50-100) for large per-turn state retained for a long time.
  • shardSize: Maximum size in bytes of a single shard / diff document. Defaults to 512 KiB. Any diff exceeding this is promoted to a sharded checkpoint so no document approaches the 1 MiB limit.

Reference

Visit the official Genkit documentation for more information.

The sources for this package are in the main Genkit repo. Please file issues and pull requests against that repo.

License: Apache 2.0

版本与发布记录

@genkit-ai/google-cloud 共发布 167 个版本,首次发布于 2024/04/05;过去 12 个月发布了 40 个版本。

版本发布日期距今
1.44.0latest2026/11/0412 天前
1.43.02026/10/2225 天前
1.43.0-rc.3next2026/10/2225 天前
1.43.0-rc.22026/10/2126 天前
1.43.0-rc.12026/10/091 个月前
1.43.0-rc.02026/10/091 个月前

关于 @genkit-ai/google-cloud 的常见问题

@genkit-ai/google-cloud 是什么?

Genkit AI framework plugin for Google Cloud Platform including Firestore trace/state store and deployment helpers for Cloud Functions for Firebase.

如何安装 @genkit-ai/google-cloud?

在项目目录运行 npm install @genkit-ai/google-cloud,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:genkit(^1.44.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@genkit-ai/google-cloud 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genkit-ai/google-cloud 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@genkit-ai/google-cloud 可以商用吗?

@genkit-ai/google-cloud 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genkit-ai/google-cloud 的下载量有多少?

根据 npm 官方下载统计,@genkit-ai/google-cloud 在 2026/10/16 – 2026/11/14 这 30 天内被下载 927,022 次,日均约 30,901 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genkit-ai/google-cloud 还在维护吗?

最新版本 1.44.0 发布于 2026/11/04(12 天前);至今共发布 167 个版本,其中过去 12 个月发布了 40 个;首次发布于 2024/04/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。