Cloud Run を使用してフローをデプロイする

Genkit フローは、Cloud Run を使用して 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 でフローをデプロイする場合、認可には次の 2 つのオプションがあります。

  • 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. その API キーを Cloud Run 環境で使用できるようにします。

    1. Cloud コンソールで、Secret Manager API を有効にします。
    2. [Secret Manager] ページで、API キーを含む新しいシークレットを作成します。
    3. シークレットを作成したら、同じページで、デフォルトのコンピューティング サービス アカウントに、Secret Manager 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 認証情報を必要とするようサービスを構成します。

省略可: デプロイされたフローを試す

デプロイが完了すると、ツールによってサービスの URL が出力されます。curl を使用してこれをテストできます。

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