使用 Cloud Run 部署流程

您可以使用 Cloud Run 將 Genkit 流程部署為 HTTPS 端點。Cloud Run 提供多種部署選項，包括容器型部署；本頁將說明如何直接透過程式碼部署流程。

事前準備

  • 安裝 Google Cloud CLI。
  • 您應該熟悉 Genkit 的流程概念，以及如何編寫流程。本頁假設您已擁有要部署的流程。
  • 您可以先前使用過 Google Cloud 和 Cloud Run，但這並非必要條件。

1. 設定 Google Cloud 專案

如果您尚未設定 Google Cloud 專案，請按照下列步驟操作：

  1. 使用 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 伺服器，並將流程設為網路端點。

在呼叫時，請指定要放送的流程：

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

您也可以指定一些選用參數：

  • port：要監聽的網路通訊埠。如果未指定，伺服器會監聽 PORT 環境變數中定義的通訊埠，如果未設定 PORT，則預設為 3400。
  • cors：流程伺服器的 CORS 政策。如果您要從網頁應用程式存取這些端點，可能需要指定這項資訊。
  • 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 金鑰的新密鑰。
    3. 建立 Secret 後，請在同一個頁面上，授予預設運算服務帳戶 Secret Manager Secret Accessor 角色，以便存取 Secret。(您可以在 IAM 頁面上查詢預設運算服務帳戶的名稱)。

    在後續步驟中，當您部署服務時，需要參照此密鑰的名稱。

Gemini (Vertex AI)

  1. 在 Cloud 控制台中，為專案啟用 Vertex AI API。

  2. 在「IAM」頁面上，確認「預設運算服務帳戶」已獲授「Vertex AI 使用者」角色。

您只需要為本教學課程的模型供應商設定一個機密，但一般來說，您必須為流程使用的每項服務執行類似的操作。

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