vertexai.ragからagentplatformへの移行で踏んだ3つの罠

はじめに

ある日、Google Chat botのローカル開発中にこんな警告が出ました。

UserWarning: The `vertexai.rag` module is deprecated and will be removed in a future version.
Please migrate to the `agentplatform` client.

vertexai.ragが非推奨？ 公式ドキュメントには特に記載がない。でも警告はgoogle-cloud-aiplatform >= 1.160.0で追加されている。放置して突然動かなくなるのは避けたいので、移行することにしました。

結論から言うと、API自体の書き換えはシンプルでしたが、ドキュメントに書いていない罠が3つありました。この記事では、実際に踏んだ問題とその対処を共有します。

前提・環境

• google-cloud-aiplatform: 1.156.0 → 1.158.0以上にアップグレード
• Python 3.14（Cloud Functions 2nd gen）
• 移行対象のAPI: rag.retrieval_query(), rag.import_files(), rag.list_files(), rag.delete_file()

非推奨の状況を調べてみた

まず気になったのは、「本当に非推奨なのか？」という点です。

Google Cloudの公式非推奨リスト（Deprecated products/features）にはvertexai.ragの記載がありません。しかしソースコードを確認すると、google-cloud-aiplatform v1.160.0でvertexai/rag/__init__.pyにwarnings.warn()が明示的に追加されていました。

公式ドキュメントと実装の間にタイムラグがある状態です。警告が出ている以上、移行先のagentplatformモジュールが安定していれば早めに移行するのが得策と判断しました。

なお、agentplatformは別パッケージではなく、google-cloud-aiplatformパッケージ内のモジュールです。追加のインストールは不要で、import agentplatformで使えます。

APIの書き換え自体はシンプル

主要なメソッドのマッピングは以下の通りです。

最大の変更点は、モジュールレベル関数からクライアントインスタンスのメソッドに変わったことです。aiplatform.init()によるグローバル初期化が不要になり、代わりにagentplatform.Clientのインスタンスを使い回します。

from google.cloud import aiplatform
from vertexai import rag

aiplatform.init(project="my-project", location="asia-northeast1")

response = rag.retrieval_query(
    text=query,
    rag_resources=[rag.RagResource(rag_corpus=corpus_name)],
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=5,
        filter=rag.Filter(vector_distance_threshold=0.6),
    ),
)

import agentplatform
from agentplatform import types as ap_types
from google.genai import types

client = agentplatform.Client(project="my-project", location="asia-northeast1")

response = client.rag.retrieve_contexts(
    vertex_rag_store=types.VertexRagStore(
        rag_resources=[
            types.VertexRagStoreRagResource(rag_corpus=corpus_name),
        ],
    ),
    query=ap_types.RagQuery(
        text=query,
        rag_retrieval_config=types.RagRetrievalConfig(
            top_k=5,
            filter=types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.6,
            ),
        ),
    ),
)

レスポンスの構造（response.contexts.contexts[].text等）は変わらないので、呼び出し側の変更だけで済みます。

ここまでは順調でした。問題はこの先です。

罠1: 型の所有権が2つのモジュールに分裂している

移行で一番ハマったのがこれです。

agentplatformの型は2つのモジュールに分散しています。

厄介なのは、ローカルではどちらのモジュールからimportしてもエラーにならない点です。agentplatform.typesは内部的にgoogle.genai.typesを再エクスポートしているように見えるため、hasattr()チェックも通ります。

しかし本番環境（Cloud Functions）にデプロイすると、こうなりました。

AttributeError: module 'agentplatform._genai.types' has no attribute 'VertexRagStore'

ローカルとCloud Functionsでモジュールの解決順序が微妙に異なるためか、本番ではagentplatform.types.VertexRagStoreが見つからないのです。

対処: 型の正しい所有元を確認し、google.genai.typesから直接importする型とagentplatform.typesからimportする型を明確に分けました。

# google.genai.types から取る型
from google.genai import types
# types.VertexRagStore, types.RagRetrievalConfig, etc.

# agentplatform.types から取る型
from agentplatform import types as ap_types
# ap_types.RagQuery, ap_types.ImportRagFilesConfig, etc.

罠2: pandasが隠れた必須依存になっている

デプロイ直後、別のエラーが出ました。

ModuleNotFoundError: No module named 'pandas'

原因を追うと、agentplatform._genai.ragモジュールが内部で_gcs_utilsをモジュールレベルでimportしており、その_gcs_utilsがトップレベルでimport pandasしています。

つまり、agentplatformのRAG機能を使う場合、pandasが暗黙の必須依存になっています。google-cloud-aiplatformのpyproject.tomlではpandasはオプショナル依存ですが、RAGモジュールのimportパスではオプショナルではありません。

対処: pyproject.tomlにpandas>=1.0.0を追加しました。

dependencies = [
    "google-cloud-aiplatform>=1.158.0",
    "pandas>=1.0.0",  # agentplatform.rag のモジュールレベル import で必須
]

旧APIのvertexai.ragではpandasなしで動作していたため、移行時にのみ表面化する問題です。

罠3: agentplatformのRAGメソッドはバージョンごとに段階追加

agentplatform.Client.ragのメソッドは一度にすべて追加されたわけではなく、バージョンごとに段階的に追加されています。

import_filesが必要な場合、>=1.156.0では不十分で、>=1.158.0が最低要件です。公式ドキュメントにはこの段階的追加の記載がないため、バージョンを上げたのにAttributeErrorが出て首を傾げることになります。

対処: pyproject.tomlで>=1.158.0を明示し、必要なメソッドがすべて揃ったバージョンを指定しました。

list_filesの戻り値の変更に注意

罠とまでは言えませんが、list_filesの戻り値が変わっている点も注意が必要です。

# 旧: イテラブル
for rf in rag.list_files(corpus_name=corpus):
    print(rf.display_name)

# 新: ListRagFilesResponse オブジェクト
response = client.rag.list_files(name=corpus)
for rf in response.rag_files or []:
    print(rf.display_name)

旧APIはジェネレータを返していましたが、新APIはListRagFilesResponseオブジェクトを返します。.rag_filesプロパティがファイルのリスト（Noneの場合あり）を持つため、or []でガードするのが安全です。

まとめ

vertexai.ragからagentplatform.Client.ragへの移行で学んだことをまとめます。

API自体のマッピングは素直なので、これらの罠さえ知っていれば移行作業は半日もかからないと思います。同じ移行を検討している方の参考になれば幸いです。