Tailscaleロゴ

Vertex AIをApertureで使う

サービスアカウントとキーファイルでVertex AIプロバイダーを設定する

最終検証日：
翻訳: 竹洞 陽一郎

Aperture by Tailscaleは、現在ベータ版です。

ApertureにVertex AIプロバイダーを設定すると、チームはApertureを通じてGoogle GeminiおよびAnthropic Claudeのモデルにアクセスできます。
このガイドでは、Google Cloudのサービスアカウントの作成、キーファイルの生成、Apertureの構成へのプロバイダーの追加について、順を追って説明します。

Apertureを使うように設定したLLMクライアントであれば、このプロバイダーが提供するモデルにアクセスできます。
Apertureはモデル名に基づいてリクエストをルーティングするため、Vertex AIのためにクライアントを個別に設定する必要はありません。

Anthropicのサポートが不要で、Geminiモデルだけが必要な場合は、サービスアカウントの代わりにAPIキー認証を使うVertex AI Expressモードを検討してください。

前提条件

始める前に、次のものが必要です。

ステップ1: Google Cloudプロジェクトを設定する

この後の gcloud コマンドで使用するアクティブなプロジェクトを設定します。
<your-project> は、自分のGoogle CloudプロジェクトIDに置き換えてください。 

gcloud config set project <your-project>

ステップ2: サービスアカウントを作成する

Vertex AI APIを呼び出す際にApertureが使用する、専用のサービスアカウントを作成します。 

gcloud iam service-accounts create aperture-vertex \
  --display-name="Aperture Vertex AI"

これにより、プロジェクト内に aperture-vertex という名前のサービスアカウントが作成されます。
Apertureはこのアカウントを使って、Vertex AI APIと認証し、リクエスト用のベアラートークンを生成します。

ステップ3: IAMロールを付与する

サービスアカウントには、2つのIAMロールが必要です。
1つはVertex AI APIを呼び出すため、もう1つは利用可能なモデルを一覧表示するためのものです。

  1. サービスアカウントがVertex AIモデルへリクエストを送信できるようにする aiplatform.user ロールを付与します。 
    gcloud projects add-iam-policy-binding <your-project> \
  --member="serviceAccount:aperture-vertex@<your-project>.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
  2. サービスアカウントが利用可能なモデルを一覧表示できるようにする serviceUsageConsumer ロールを付与します。 
    gcloud projects add-iam-policy-binding <your-project> \
  --member="serviceAccount:aperture-vertex@<your-project>.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

ステップ4: JSONキーファイルを生成する

サービスアカウントのJSONキーファイルを作成します。
Apertureはこのキーファイルを使って、Vertex AIリクエスト用のベアラートークンを発行します。 

gcloud iam service-accounts keys create aperture-vertex-key.json \
  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com

これにより、現在のディレクトリに aperture-vertex-key.json というファイルが作成されます。
このファイルには、Apertureが認証に必要とする秘密鍵とプロジェクトのメタデータが含まれています。

このファイルは安全に保管してください。
秘密鍵は紛失すると復元できず、ファイルにアクセスできる人は誰でも、そのサービスアカウントとして認証できてしまいます。

ステップ5: キーファイルをBase64エンコードする

Apertureは、プロバイダー設定の中で、キーファイルをBase64エンコードされた文字列として要求します。
キーファイルをエンコードし、その結果をクリップボードにコピーします。

macOSの場合:

cat aperture-vertex-key.json | base64 | pbcopy

Linuxの場合:

cat aperture-vertex-key.json | base64 -w 0

エンコードした文字列は、次のステップでプロバイダーの apikey フィールドの値として使用します。

ステップ6: ApertureでVertexプロバイダーを設定する

Apertureダッシュボードを使って、Apertureの構成にVertexプロバイダーを追加します。
次の例は、GoogleとAnthropicの両方のモデルを有効にした構成を示しています。 

{
  "providers": {
    "vertex": {
      "baseurl": "https://aiplatform.googleapis.com",
      "apikey": "keyfile::<base64-encoded-key>",
      "models": [
        "gemini-2.5-flash",
        "gemini-2.5-pro",
        "claude-opus-4-7",
        "claude-sonnet-4-6",
        "claude-haiku-4-5@20251001"
      ],
      "compatibility": {
        "google_generate_content": true,
        "google_raw_predict": true,
        "experimental_gemini_cli_vertex_compat": true
      }
    }
  }
}

<base64-encoded-key> は、前のステップで得たBase64エンコード文字列に置き換えてください。
keyfile:: という接頭辞は、その値がプレーンなAPIキーではなく、Base64エンコードされたサービスアカウントのキーファイルであることをApertureに伝えます。
Apertureはキーファイルをデコードして project_id を抽出し、それを使ってVertex AI用のリクエストパスを書き換えます（たとえば、_aperture_auto_vertex_project_id_ プレースホルダを埋めます）。

keyfile:: 認証を使う場合、authorization フィールドは不要です。
ApertureはキーファイルからOAuthのベアラートークンを自動的に生成し、authorization フィールドをバイパスします。

compatibility フラグは、プロバイダーがどのVertex AI API形式を受け入れるかを制御します。

プロバイダーがGoogleとAnthropicの両方のモデルを提供する場合は、google_generate_content と google_raw_predict を有効にします。
一方の種類のみを提供する場合は、対応するフラグを有効にしてください。
互換性フラグの完全な一覧については、プロバイダー互換性リファレンスを参照してください。

プロバイダーを設定したら、Vertexモデルを必要とするユーザーまたはグループにモデルへのアクセスを許可してください。

プロバイダーを検証する

  1. Apertureダッシュボードを開き、Vertexプロバイダーが期待どおりのモデルとともに表示されることを確認します。
  2. Claude Codeなど、Vertexプロバイダーを使うように設定したツールから、テストリクエストを送信します。
  3. Apertureダッシュボードのセッション一覧で、そのリクエストに対応する新しいエントリを確認します。セッションには、モデル名、トークン数、タイムスタンプが表示されます。

リクエストが成功し、ダッシュボードに表示されれば、Vertexプロバイダーは正しく設定されています。
リクエストが失敗する場合は、Apertureのトラブルシューティングガイドを参照してください。

サービスアカウントキーを管理する

認証情報をローテーションする場合や、プロバイダーを廃止する場合は、サービスアカウントキーを一覧表示または失効させます。

サービスアカウントのキーを一覧表示する

サービスアカウントに関連付けられたすべてのキーを一覧表示するには、次のコマンドを実行します。 

gcloud iam service-accounts keys list \
  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com

出力には、サービスアカウントのすべてのキーが一覧表示されます。
出力中の key-id は、JSONキーファイルの private_key_id フィールドと一致します。

キーを失効させる

特定のキーを key-id で指定して削除します。 

gcloud iam service-accounts keys delete <key-id> \
  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com

キーを失効させたら、新しいキーファイルを生成し、Apertureのプロバイダー設定内のBase64エンコード値を更新してください。
失効させたキーを使用するリクエストは、ただちに失敗します。