[[BigQuery]] の `AI.GENERATE()` や `AI.EMBED()` などで [[Vertex AI]] の [[Gemini]] や埋め込みモデルを呼ぶには、認証経路として [[BigQuery Cloud Resource Connection]] が必要になる。
ここでは、最初の 1 本の [[SQL]] が通るまでの最小手順を記録する。
> [!info]
> 公式チュートリアル [Generate text by using a Gemini model](https://docs.cloud.google.com/bigquery/docs/generate-text-tutorial-gemini) と併読すると、UI ベースの手順も確認できる。
## 前提
- 対象プロジェクトの [[IAM]] で BigQuery Connection Admin (`roles/bigquery.connectionAdmin`) と Project IAM Admin (`roles/resourcemanager.projectIamAdmin`) を持っている
- BigQuery データセットと揃えたいリージョン (例: `asia-northeast1`) を決めておく
## セットアップ手順
### 1. Vertex AI API を有効化
```bash
gcloud services enable aiplatform.googleapis.com \
--project={{ PROJECT_ID }}
```
### 2. Cloud Resource Connection を作成
```bash
bq mk --connection \
--location=asia-northeast1 \
--project_id={{ PROJECT_ID }} \
--connection_type=CLOUD_RESOURCE \
vertex-ai-connection
```
> [!tip]
> Connection のリージョンは、呼び出し側データセットと同一である必要がある。マルチリージョン (`us`, `eu`) と単一リージョン (`asia-northeast1` 等) を混在させるとクエリで弾かれる。
### 3. 接続のサービスアカウントを確認
作成時に自動生成される [[サービスアカウント]] の `serviceAccountId` を控える。
```bash
bq show --format=prettyjson --connection \
{{ PROJECT_ID }}.asia-northeast1.vertex-ai-connection
```
出力の `cloudResource.serviceAccountId` が対象。
### 4. Vertex AI User ロールを付与
```bash
gcloud projects add-iam-policy-binding {{ PROJECT_ID }} \
--member="serviceAccount:{{ SERVICE_ACCOUNT_EMAIL }}" \
--role="roles/aiplatform.user"
```
### 5. 動作確認
BigQuery コンソールで以下を実行し、Gemini の応答が返れば成功。
```sql
SELECT AI.GENERATE(
'hello',
connection_id => '{{ PROJECT_ID }}.asia-northeast1.vertex-ai-connection',
endpoint => 'gemini-2.5-flash'
).result;
```
> [!warning]
> `connection_id` の書式は `{{ PROJECT_ID }}.{{ LOCATION }}.{{ CONNECTION_ID }}` (ドット区切り)。フルパス (`projects/.../locations/.../connections/...`) 形式も受理される。
## このセットアップが効く範囲
この 1 本の Connection で、BigQuery 側の以下の関数がすべて使えるようになる。
- **[[BigQuery 汎用 AI 関数|汎用 AI 関数]]**: `AI.GENERATE*`, `AI.EMBED()` など (`connection_id` を直接指定)
- **タスク特化関数**: `ML.TRANSLATE()`, `ML.GENERATE_TEXT()` など (`CREATE MODEL ... REMOTE WITH CONNECTION` で指定)
- **Remote BQML モデル**: Vertex AI デプロイ済モデルへの参照
- **ベクトル検索**: `AI.EMBED()` 経由で埋め込みを作る文脈では間接的に必要
一方、[[BigQuery マネージド AI 関数|マネージド AI 関数]] ([[BigQuery AI.IF 関数|AI.IF()]] / [[BigQuery AI.SCORE 関数|AI.SCORE()]] / `AI.CLASSIFY()`) や分析系 AI 関数 (`AI.FORECAST()` 等) は Connection 不要。
## 関連ノート
- **[派生]** [[BigQuery AI 関数の料金は二重構造になる]]: 本ノートで接続した経路を実運用する際の費用見積もりの根拠になる