AI Studio で動いていたコードを Vertex AI に移したら何が変わったか — 個人開発者の移行作業ログ

「Gemini API（AI Studio）の無料枠が思ったより早く尽きた」「請求の透明性のために GCP プロジェクトに寄せたい」— そんな現実的な事情で、ある日 Vertex AI への移行を決めました。比較記事は山ほど読んでいたのですが、実際にコードを書き換えてみると、想定していたよりも「細かい差分」が多くて驚きました。本記事は、その移行作業中に手元で起きた具体的な変化を、コードの差分付きで残したものです。これから同じ作業をされる方の予習資料になれば嬉しいです。

なお、両者の特徴比較や用途別の選び方は Gemini API vs Vertex AI 比較ガイドに整理してありますので、そちらと併読いただくと判断の輪郭がはっきりします。

移行を考えるきっかけは「無料枠の終わり」ではなかった

正直に書きますと、私が移行に踏み切った決め手は無料枠ではありませんでした。Vertex AI に寄せると、Gemini API の利用料金が GCP プロジェクトの通常請求にまとまります。これが本業の経費処理上、毎月地味に効いてきます。AI Studio 経由の API キーは、別請求として個別に管理しないといけないため、本業で使っている Google Cloud と帳簿が分かれてしまうのです。

加えて、IAM ロール経由でアクセス制御ができる点も大きな魅力でした。AI Studio の API キーはローテーションこそできますが、「このサービスアカウントだけが本番でアクセスでき、開発用は別の権限」というような細かい権限分離は苦手です。Vertex AI 側ならサービスアカウント単位で roles/aiplatform.user を付与・剥奪できるので、運用上の不安が減ります。

SDK は同じでも、初期化の3行が完全に書き換わる

最大の発見は、google-genai SDK は両方で使えるのですが、初期化引数が完全に違うことでした。AI Studio 側で書いていたコードは、たった1行の API キー指定で完結します。

# AI Studio 経由（移行前）
from google import genai
 
client = genai.Client(api_key="YOUR_API_KEY")
 
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="日本語でこんにちはと挨拶してください",
)
print(response.text)
# 期待出力: こんにちは！

これを Vertex AI 側に移すと、初期化が vertexai=True フラグ付きの呼び出しに変わり、project と location を指定する必要があります。

# Vertex AI 経由（移行後）
from google import genai
 
client = genai.Client(
    vertexai=True,
    project="your-gcp-project-id",  # ← GCP プロジェクト ID
    location="asia-northeast1",      # ← 東京リージョン
)
 
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="日本語でこんにちはと挨拶してください",
)
print(response.text)
# 期待出力: こんにちは！

ポイントは「api_key を指定しないこと」です。Vertex AI は Application Default Credentials（ADC）を経由して認証するため、コードに認証情報を書きません。代わりに、実行環境で gcloud auth application-default login を済ませておくか、サービスアカウント JSON を GOOGLE_APPLICATION_CREDENTIALS 環境変数で指定します。

location を asia-northeast1（東京）にすると、日本のユーザー向けレイテンシが体感で1〜2割改善しました。AI Studio 側はリージョンを選べないので、これは Vertex AI ならではの利点です。

認証エラーで丸一日溶かした、たった1つの環境変数

移行作業で一番ハマったのが、認証エラーの解消でした。ローカルでは gcloud auth application-default login が通っていて動くのに、Cloud Run にデプロイした途端 403 Permission denied が返ってきます。

原因は単純で、Cloud Run のサービスアカウントに roles/aiplatform.user が付与されていなかっただけでした。ただ、エラーメッセージに「Vertex AI API へのアクセス権限が足りません」とは書かれず、ただ Permission denied on resource project ... とだけ表示されるので、ロール不足だと気づくのに時間がかかりました。

復旧手順を残しておきます。

# サービスアカウントの確認
gcloud run services describe my-app \
  --region asia-northeast1 \
  --format="value(spec.template.spec.serviceAccountName)"
 
# Vertex AI 利用権限の付与
gcloud projects add-iam-policy-binding your-gcp-project-id \
  --member="serviceAccount:<上記コマンドの出力>" \
  --role="roles/aiplatform.user"

このとき、もうひとつ罠があります。Vertex AI API そのものをプロジェクトで有効化していないと、ロールを付けても通らないのです。gcloud services enable aiplatform.googleapis.com を忘れないでください。詳しい認証エラーパターンは Vertex AI Gemini 認証エラーの直し方にまとめています。

レスポンスの形式が微妙に違う — 構造化出力で気づいた差異

ほとんどのレスポンスは AI Studio 側と互換ですが、構造化出力（response_schema）の挙動で1箇所だけ困りました。AI Studio 側ではトップレベル配列をそのまま返してくれていたのに、Vertex AI 側では一部のモデルで {"items": [...]} のようにラップされて返ることがあったのです。

私はこれをパースで失敗して気づきました。対策はシンプルで、レスポンス整形側で両方のケースを許容するように書き直しました。

import json
 
raw = response.text
data = json.loads(raw)
 
# 両方の形式を吸収する整形ヘルパー
def coerce_list(payload):
    """トップレベルが list なら list、dict なら 'items' / 'results' を取る"""
    if isinstance(payload, list):
        return payload
    if isinstance(payload, dict):
        for key in ("items", "results", "data"):
            if isinstance(payload.get(key), list):
                return payload[key]
    raise ValueError(f"unsupported response shape: {type(payload)}")
 
records = coerce_list(data)
print(f"取得件数: {len(records)}")

このような小さな差分は、移行直後にユニットテストで気づきにくく、本番のロギングを見て初めて分かることがあります。私は移行のしばらくは AI Studio 側のレスポンスもダンプして、両者を突き合わせる差分監視を回していました。

移行を終えて気づいた「Vertex AI に移して良かった」3つのこと

最後に、移行から1ヶ月ほど運用してみて、率直に良かったと感じている点を3つ挙げます。

第一に、請求の見通しが明確に良くなりました。GCP の課金画面で、Gemini の利用が他のサービス（Cloud Run、Cloud Storage など）と並んで一覧でき、本業のコスト管理ツールにそのまま乗ります。

第二に、ステージングと本番でサービスアカウントを分けられる安心感です。本番のキーが流出するリスクを実質ゼロにできましたし、開発時のうっかり本番呼び出しもロールで止められます。

第三に、東京リージョンを選んだことでレスポンスが少し速いです。体感差ではありますが、ストリーミングの初期トークンが目に見えて早く出てくる印象です。レイテンシ周りで悩まれている方は Gemini API レイテンシ最適化ガイドも参考にしてみてください。

移行作業そのものは、コードだけ見れば「クライアント初期化を書き換える」という小さな作業です。ただ、認証・権限・リージョン・レスポンス差分まで含めると、半日では終わらない仕事でした。これから移行される方は、まずローカルで vertexai=True クライアントが Hello World を返せるところまで確認し、その後で本番ワークロードを段階的にスイッチしていくのがおすすめです。本記事のコードがそのまま叩き台になれば嬉しく思います。