使用 Cloud Run 部署数据流

您可以使用 Cloud Run 将 Genkit flow 部署为 HTTPS 端点。Cloud Run 提供了多种部署选项，包括基于容器的部署；本页将介绍如何直接通过代码部署数据流。

准备工作

  • 安装 Google Cloud CLI。
  • 您应该熟悉 Genkit 的流程概念以及如何编写流程。本页面假定您已经有要部署的工作流。
  • 如果您之前使用过 Google Cloud 和 Cloud Run，将会很有帮助，但不是必需的。

1. 设置 Google Cloud 项目

如果您尚未设置 Google Cloud 项目，请按照以下步骤操作：

  1. 使用 Cloud 控制台创建新的 Google Cloud 项目，或选择现有 Google Cloud 项目。

  2. 将项目关联到结算账号（这是 Cloud Run 的必需条件）。

  3. 配置 Google Cloud CLI 以使用您的项目：

    gcloud init

2. 准备 Node 项目以进行部署

为了能够部署流程，您需要对项目代码进行一些细微更改：

将启动和构建脚本添加到 package.json

将 Node.js 项目部署到 Cloud Run 时，部署工具需要您的项目包含 start 脚本，并且可以包含 build 脚本。对于典型的 TypeScript 项目，以下脚本通常就足够了：

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

添加代码以配置和启动流服务器

在由 start 脚本运行的文件中，添加对 startFlowServer 的调用。此方法会启动一个 Express 服务器，该服务器会将您的流程作为 Web 端点进行传送。

在进行调用时，指定要投放的广告系列：

ai.startFlowServer({
  flows: [menuSuggestionFlow],
});

您还可以指定一些可选参数：

  • port：要监听的网络端口。如果未指定，服务器会监听 PORT 环境变量中定义的端口；如果未设置 PORT，则默认为 3400。
  • cors：流服务器的 CORS 政策。如果您将通过 Web 应用访问这些端点，则可能需要指定这一点。
  • pathPrefix：要在流程端点之前添加的可选路径前缀。
  • jsonParserOptions：要传递给 Express 的 JSON 正文解析器的选项

可选：定义授权政策

所有已部署的流程都应需要某种形式的授权；否则，任何人都可以调用您的可能需要高昂费用的生成式 AI 流程。

使用 Cloud Run 部署流程时，您有两种授权选项：

  • 基于 Cloud IAM 的授权：使用 Google Cloud 的原生访问权限管理设施来控制对端点的访问权限。如需了解如何提供这些凭据，请参阅 Cloud Run 文档中的身份验证部分。

  • 在代码中定义的授权政策：使用 Genkit 流程的授权政策功能，通过自定义代码验证授权信息。这通常（但不一定）是基于令牌的授权。

如果您想在代码中定义授权政策，请在流程定义中使用 authPolicy 参数：

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

授权政策的 auth 参数来自请求对象的 auth 属性。通常，您可以使用 Express 中间件设置此属性。请参阅授权和完整性。

向已部署的流程提供 API 凭据

部署后，您的流程需要通过某种方式与其依赖的任何远程服务进行身份验证。大多数流程至少需要凭据才能访问其使用的模型 API 服务。

对于此示例，请根据您选择的模型提供方，执行以下操作之一：

Gemini (Google AI)

  1. 确保您所在的区域提供 Google AI。

  2. 使用 Google AI Studio 为 Gemini API 生成 API 密钥。

  3. 在 Cloud Run 环境中提供 API 密钥：

    1. 在 Cloud 控制台中，启用 Secret Manager API。
    2. 在 Secret Manager 页面上，创建一个包含 API 密钥的新 Secret。
    3. 创建 Secret 后，在同一页面上，通过 Secret Manager Secret Accessor 角色为默认计算服务账号授予对 Secret 的访问权限。（您可以在 IAM 页面上查找默认计算服务账号的名称。）

    在后面的步骤中，当您部署服务时，需要引用此 Secret 的名称。

Gemini (Vertex AI)

  1. 在 Cloud 控制台中，为您的项目启用 Vertex AI API。

  2. 在 IAM 页面上，确保为默认计算服务账号授予 Vertex AI User 角色。

在本教程中，您只需要为模型提供方设置 Secret，但一般来说，您必须为流程使用的每项服务执行类似的操作。

3. 将数据流部署到 Cloud Run

准备好要部署的项目后，您可以使用 gcloud 工具进行部署。

Gemini (Google AI)

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

Gemini (Vertex AI)

gcloud run deploy

部署工具会提示您提供所需的任何信息。

当系统询问您是否要允许进行未经身份验证的调用时，请执行以下操作：

  • 如果您未使用 IAM，而是在代码中定义了授权政策，请回答 Y。
  • 回答 N 可将您的服务配置为需要 IAM 凭据。

可选：试用已部署的流程

部署完成后，该工具会输出服务网址。您可以使用 curl 进行测试：

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'