最適化された AI 関数を使用してクエリを高速化する

AlloyDB for PostgreSQL で最適化された AI 関数を使用すると、運用コストを削減し、クエリの応答性を向上させることができます。最適化された AI 関数は、ほとんどのクエリをより小さく高速なプロキシモデルで処理し、必要な場合にのみ大規模な LLM にフォールバックすることで、行ごとの分類タスクやフィルタリング タスクでの大規模言語モデル（LLM）の使用を最小限に抑えます。

注: 最適化された AI 関数は、1 つのクエリで複数の ai.if() 句をサポートします。ただし、各 ai.if() 関数のすべての引数が 1 つのテーブル エイリアスを参照している必要があります。デフォルトでは、リモート LLM フォールバックを制御する google_ml_integration.proxy_models_enable_llm_fallback フラグが有効（on）になっています。

ai.if() などの AlloyDB AI 関数は、LLM へのリモート呼び出しによりレイテンシが高くなることがあります。最適化された関数は、ローカルでトレーニングされた小さなプロキシモデル（ロジスティック回帰モデルなど）を使用してクエリを処理することで、このレイテンシの問題に対処します。これらのモデルは、LLM の出力を信頼できる情報源として使用し、データのサンプルでトレーニングされます。

google_ml_integration.proxy_models_enable_accuracy_check フラグを使用して、実行時に精度チェックを実行するように構成できます。このフラグはデフォルトで off に設定されています。精度チェックでは、ベースライン LLM を使用してクエリから行のサンプルを評価し、精度が google_ml_integration.proxy_models_f1_score_threshold フラグで定義されたしきい値を満たしていることを確認します。精度チェックが失敗した場合、クエリは LLM の使用にフォールバックします（フォールバックが無効になっている場合はエラーをスローします）。

最適化された AI 関数のワークフロー

最適化された AI 関数を使用し、google_ml_integration.proxy_models_enable_accuracy_check フラグを true に設定すると、AlloyDB は次の処理を行います。

注: google_ml_integration.proxy_models_enable_llm_fallback フラグが off に設定されている場合、プロキシモデルがトレーニングされていないか、精度チェックに失敗すると、クエリはリモート LLM を呼び出す代わりにエラーを返します。

1. トレーニングをスケジュールする: テーブルで ai.if() 関数を含むクエリを実行すると、AlloyDB はバックグラウンドで軽量プロキシモデルのトレーニングを自動的にスケジュールします。

2. LLM にフォールバックする: プロキシモデルのトレーニング中、またはプロキシモデルが使用できない場合、AlloyDB はリモート LLM を使用してクエリを評価します（フォールバックが無効になっている場合を除く）。

3. 最適化されたクエリを実行する: モデルがトレーニングされると、AlloyDB はトレーニング済みのプロキシモデルを使用して後続のクエリをローカルで処理し、パフォーマンスを向上させます。

次の図は、最適化された AI 関数を使用してクエリを処理するロジックフローを示しています。

始める前に

最適化された AI 関数を使用する前に、次の操作を行います。

• psql を使用してデータベースに接続します。AlloyDB Studio を使用して、postgres ユーザーとして、またはデータが存在するテーブルへのアクセス権を持つユーザーとして接続することもできます。

• google_ml_integration 拡張機能のバージョン 1.6.3 以降がインストールされていることを確認します。

  SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
  

  出力は次のようになります。

   extversion 
  ------------
   1.6.3
  (1 row)
  

  拡張機能がインストールされていない場合、またはバージョン 1.6.3 より前の場合は、拡張機能を更新します。

  CREATE EXTENSION IF NOT EXISTS google_ml_integration;
  ALTER EXTENSION google_ml_integration UPDATE;
  

• Gemini Enterprise Agent Platform と連携するように AlloyDB を構成します。詳細については、Agent Platform と統合するをご覧ください。

• 次のインスタンス レベルのデータベース フラグが有効になっていることを確認します。詳細については、サポートされているデータベース フラグ、最適化された AI 関数のデータベース フラグ、インスタンスのデータベース フラグを構成するをご覧ください。

  • google_ml_integration.enable_model_support
  • google_ml_integration.enable_ai_query_engine
  • google_ml_integration.enable_ai_function_acceleration
  • google_ml_integration.enable_cost_optimized_ai_functions

• フォールバックと精度の検証のデータベース フラグを確認します。これらのフラグは、SQL（SET または ALTER DATABASE）を使用してセッション レベルまたはデータベース レベルで構成できます。

  • google_ml_integration.proxy_models_enable_llm_fallback: プロキシモデルが使用できない場合に、クエリがリモート LLM にフォールバックするかどうかを制御します。このフラグはデフォルトで on に設定されています。off に設定すると、データベースはリモート LLM にフォールバックする代わりにエラーをスローします。
  • google_ml_integration.proxy_models_enable_accuracy_check: ベースライン LLM に対するランタイム精度チェックを有効にします。このフラグはデフォルトで off に設定されています。

• 定期的な再トレーニングのデータベース フラグを確認します。

  • google_ml_integration.proxy_models_retraining_interval_minutes: バックグラウンドの再トレーニング ジョブの頻度を分単位で制御します。デフォルトは 1440（24 時間）です。0 に設定すると、定期的な再トレーニングが無効になります。
  • google_ml_integration.proxy_models_retraining_batch_size: 1 回のイテレーションで再トレーニングされるモデルの数を制御します（デフォルトは 1）。

• AlloyDB Omni の場合は、次の拡張機能が shared_preload_libraries に読み込まれていることを確認します。

  • google_job_scheduler
  • google_ml_integration

• クエリを実行するテーブルのエンベディングを生成します。詳細については、大規模なテーブルの自動ベクトル エンベディングを生成して管理するをご覧ください。

• 次の要件を考慮してください。

  • ソースデータ列は TEXT 型または VARCHAR 型である必要があります。
  • 最適化された AI 関数に入力を提供するエンベディング列は、REAL[] 型または VECTOR 型である必要があります。
  • 最適化された AI 関数は、Agent Platform の生成モデルが利用可能なリージョンでのみ使用できます。使用可能なリージョンの一覧については、デプロイとエンドポイントをご覧ください。

最適化されたクエリを実行する

次の例に沿って、ai.if() 関数を使用して標準の SELECT ステートメントを実行します。

1. restaurant_reviews テーブルを作成します。ソースデータを保持する review 列の型は TEXT で、クエリに使用される review_embedding 列の型は VECTOR(768) です。

   CREATE TABLE restaurant_reviews (
       id SERIAL,
       name VARCHAR(64),
       city VARCHAR(64),
       review TEXT,
       review_embedding VECTOR(768)
   );
   

2. ai.initialize_embeddings() プロシージャを使用して、ソースデータのベクトル エンベディングを生成します。

   CALL ai.initialize_embeddings(
       model_id => 'text-embedding-005',
       table_name => 'restaurant_reviews',
       content_column => 'review',
       embedding_column => 'review_embedding'
   );
   

   最適化された AI 関数は、軽量プロキシモデルのトレーニングと評価に特徴入力としてベクトル エンベディングを使用するため、エンベディングを生成する必要があります。プロキシモデルは、すべての行の未加工テキストをリモート LLM に送信するのではなく、ベクトル表現に対して直接、高速なローカル推論を実行します。エンベディングが生成されない場合、AlloyDB はプロキシモデルをトレーニングできず、リモート LLM ですべての行を評価するようにフォールバックします。

   エンベディングの要件は次のとおりです。

   • エンベディング列に NULL 値が含まれている場合、ai.if() 出力は NULL と評価されます。モデルのトレーニングと推論の両方に、有効なエンベディングが必要です。
   • クエリのエンベディング ディメンションが、トレーニング済みのプロキシモデルに保存されているディメンションと一致しない場合、ai.if() 関数はエラーをスローします。

   エンベディング オプションと増分更新の詳細については、大規模なテーブルの自動ベクトル エンベディングを生成して管理するをご覧ください。

3. ai.if() 関数を使用して SELECT ステートメントを実行します。このクエリは、最適化された AI 関数のプロキシモデルのトレーニングをバックグラウンドで自動的にスケジュールします。

   SELECT r.name, r.city
   FROM restaurant_reviews r
   WHERE ai.if('Is the following a positive review? Review: ' || r.review, r.review_embedding, 'gemini-3.5-flash-lite')
   GROUP BY r.name, r.city
   HAVING COUNT(*) > 500;
   

   最初のクエリ実行により、トレーニングが非同期でトリガーされます。プロキシモデルのトレーニング中に google_ml_integration.proxy_models_enable_llm_fallback フラグが on（デフォルト）に設定されている場合、AlloyDB はリモート LLM を使用してクエリを評価するようにフォールバックし、最適化された AI 関数がまだ使用できないという警告を返します。google_ml_integration.proxy_models_enable_llm_fallback が off に設定されている場合、クエリはフォールバックせずにエラーを返します。

   同じコンテンツ式（content_expr）、エンベディング列、テーブルに一致する後続のクエリでは、トレーニング済みのプロキシモデルを使用して高速化されます。行の値の更新、行の削除、テーブルへのデータの追加を行っても、AlloyDB が LLM にフォールバックすることはありません。プロキシモデルは引き続きデータをローカルで処理し、データドリフトは定期的なバックグラウンドでの再トレーニングによって対処されます。

   プロキシモデルは、関数タイプ、テーブル OID、コンテンツ式、エンベディング列（func_type、table_oid、content_expr、embedding_column）によって一意に識別されます。このアーキテクチャでは、ai.if() への入力が変更されない限り、異なる SQL クエリ間でモデルを共有できます。

   AlloyDB は、既存のプロキシモデルを使用せず、代わりに新しいプロキシモデルのバックグラウンド トレーニングを開始し、次のシナリオでリモート LLM にフォールバックします（google_ml_integration.proxy_models_enable_llm_fallback フラグの対象）。

   • ai.if() 内の CONTENT 式が変更される（プロンプト文字列や連結された列式が変更されるなど）。
   • ai.if() 内の EMBEDDING_COLUMN 名が変更されます。
   • llm_model_id パラメータが変更されます。
   • ランタイム精度チェックが有効になっていて、プロキシモデルがクエリの開始時に精度チェックに失敗した場合。

オンライン トレーニングとブロック実行

AlloyDB は、最適化された関数のオンライン トレーニング ワークフローをサポートしています。これは、google_ml_integration.proxy_models_enable_online_training データベース フラグによって制御されます。デフォルトでは、このフラグは off に設定されています。

このフラグが有効で、トレーニングされていない ai.if() 関数が実行されると、クエリはトレーニング プロセスをトリガーし、ブロッキング実行を使用します。最初のクエリは、バックグラウンド プロキシモデルのトレーニングが完了するまでアクティブにブロックして待機します。これにより、クエリは最適化されたプロキシモデルをすぐに利用し、最初の実行時にリモート LLM 推論の費用が発生しないようにします。

クエリがブロックされ、オンライン トレーニングの完了を待機する最大時間は、google_ml_integration.proxy_models_training_wait_timeout フラグ（秒単位、デフォルトは 60）で制御されます。この間隔内にトレーニングが完了しない場合、クエリはタイムアウトするか、フォールバック設定に従ってフォールバックします。

オンライン トレーニングを有効にするには:

-- Enable online training (blocking execution)
SET google_ml_integration.proxy_models_enable_online_training = on;

-- Set the maximum wait timeout in seconds (default is 60)
SET google_ml_integration.proxy_models_training_wait_timeout = 30;

リモート LLM フォールバックを構成する

デフォルトでは、リモート LLM へのフォールバックが有効になっています。プロキシモデルがトレーニングされていない、トレーニング中である、または精度チェックに失敗した場合、クエリはリモート LLM にフォールバックし、標準の Agent Platform API の費用が発生します。

フォールバック動作は、google_ml_integration.proxy_models_enable_llm_fallback データベース フラグを使用して構成できます。

• フォールバックが有効になっている場合（on、デフォルト）: プロキシモデルが使用できない場合、AlloyDB はリモート LLM を使用してクエリを評価し、警告を返します。

  WARNING: Optimized AI Function is unavailable. Expect reduced performance.
  

• フォールバックが無効になっている場合（off）: プロキシモデルが使用できない場合、または精度検証に失敗した場合、クエリはリモート LLM を呼び出す代わりに、すぐにエラーを発生させます。

  ERROR: Optimized AI Function: Optimized model fallback to LLM prevented by GUC google_ml_integration.proxy_models_enable_llm_fallback
  

現在のセッションで LLM フォールバックを無効にするには:

SET google_ml_integration.proxy_models_enable_llm_fallback = off;

データベース全体で LLM フォールバックを無効にするには:

ALTER DATABASE DATABASE_NAME SET google_ml_integration.proxy_models_enable_llm_fallback = off;

DATABASE_NAME は、実際のデータベースの名前に置き換えます。

ランタイム精度チェックを構成する

ランタイム精度チェックでは、リモート LLM を使用してクエリから行のサンプルを評価し、プロキシモデルが実行前にベースライン精度の要件を満たしていることを確認します。

精度チェックは、google_ml_integration.proxy_models_enable_accuracy_check データベース フラグ（デフォルトでは無効）によって制御されます。

現在のセッションで精度チェックを有効にするには:

SET google_ml_integration.proxy_models_enable_accuracy_check = on;

現在のセッションの精度チェックを無効にするには:

SET google_ml_integration.proxy_models_enable_accuracy_check = off;

データベース全体で精度チェックを有効にするには:

ALTER DATABASE DATABASE_NAME SET google_ml_integration.proxy_models_enable_accuracy_check = on;

既存のプロキシモデルを表示する

既存のプロキシモデルを検査し、トレーニング ステータスを確認して、モデルのメタデータを確認するには、google_ml.optimized_functions_view ビュー（または ai スキーマのエイリアス ai.optimized_functions_view）に対してクエリを実行します。

sql SELECT * FROM ai.optimized_functions_view;

このビューの列の説明については、ai.optimized_functions_view ビューをご覧ください。

このビューを table_name または status でフィルタして、モデルのトレーニングが完了したかどうか（READY）を確認したり、手動での再トレーニングに必要な正確な content_expr 値と embedding_column 値を特定したりできます。

プロキシモデルを再トレーニングして管理する

プロキシモデルは、最初のトレーニング時にテーブルに存在するデータでトレーニングされます。新しいデータがテーブルに追加された場合、または行が変更または削除された場合、プロキシモデルは時間の経過とともに古くなる可能性があります。データの変化に応じて精度を維持するために、プロキシモデルはバックグラウンドで定期的に自動的に再トレーニングすることも、オンデマンドで手動で再トレーニングすることもできます。

定期的なバックグラウンドでの再トレーニング

デフォルトの構成設定で 32 個以上の vCPU を持つインスタンスでは、AlloyDB はバックグラウンドでプロキシモデルを定期的に再トレーニングできます。

定期的な再トレーニングは、次のデータベース フラグによって制御されます。

• google_ml_integration.proxy_models_retraining_interval_minutes: バックグラウンドの再トレーニング ジョブの頻度を分単位で制御します。デフォルトは 1440（24 時間）です。0 に設定すると、定期的な再トレーニングが無効になります。
• google_ml_integration.proxy_models_retraining_batch_size: 1 回のイテレーションで再トレーニングされるモデルの数を制御します（デフォルトは 1）。

注: 32 個未満の vCPU を搭載したデータベース インスタンスでは、定期的なバックグラウンド自動再トレーニングはサポートされていません。このような場合や、大幅なデータ更新後にすぐに再トレーニングが必要な場合は、手動再トレーニングを使用します。

手動での再トレーニング

プロキシモデルは、ai スキーマの関数（または google_ml スキーマの同等の関数）を使用して手動で再トレーニングできます。

テーブルのすべてのモデルを再トレーニングする

特定のテーブルに関連付けられているすべてのプロキシモデルを再トレーニングする場合、またはテーブルのモデルのフィルタされたサブセットを再トレーニングする場合は、ai.retrain_optimized_models() を呼び出します。

SELECT ai.retrain_optimized_models(
  table_name => 'restaurant_reviews',
  embedding_column => 'review_embedding', -- Optional
  content_expr => '(''Is the following a positive review? Review: ''::text || review)', -- Optional
  llm_model_id => 'LLM_MODEL_ID' -- Optional
);

パラメータの説明については、ai.retrain_optimized_models() 関数をご覧ください。

モデル ID で特定のモデルを再トレーニングする

一意のモデル識別子を使用して特定のプロキシモデルを再トレーニングするには、model_id パラメータを指定して ai.retrain_optimized_model() を呼び出します。

SELECT ai.retrain_optimized_model(model_id => 'MODEL_ID');

パラメータの説明については、ai.retrain_optimized_model() 関数をご覧ください。

モデル トレーニング パラメータで特定のモデルを再トレーニングする

テーブル名、コンテンツ式、エンベディング列を使用して特定のプロキシモデルを再トレーニングするには、ai.retrain_optimized_model() を呼び出します。

SELECT ai.retrain_optimized_model(
  table_name => 'restaurant_reviews',
  embedding_column => 'review_embedding',
  content_expr => '(''Is the following a positive review? Review: ''::text || review)',
  llm_model_id => 'LLM_MODEL_ID' -- Optional
);

パラメータの説明については、ai.retrain_optimized_model() 関数をご覧ください。

プロキシモデルを削除する

次の関数を使用して、個々のプロキシモデルまたはすべてのモデルを削除できます。これらのオペレーションは、alloydbsuperuser 権限を持つユーザー、または管理者から権限を付与されたユーザーが実行する必要があります。

特定のプロキシモデルを削除するために必要な内部 model_id を確認するには、google_ml.proxy_models_expr_mapping テーブルに対してクエリを実行します。

SELECT model_id, table_oid::regclass, content_expr
FROM google_ml.proxy_models_expr_mapping;

-- Delete a specific proxy model
SELECT ai.delete_optimized_model('com_if_12345_67890');

-- Delete all proxy models and stop the background automated retraining job
CALL ai.delete_all_optimized_models();

モニタリング

バックグラウンド ワーカーのトレーニング ジョブをモニタリングし、モデルのオペレーション ステータスを確認できます。

モデルのトレーニング ステータスと履歴を確認する

プロキシモデルのトレーニングが完了したか、失敗したか、再トレーニング中かを確認するには、ai.optimized_functions_view をクエリします。

SELECT table_name, content_expr, status, last_trained_at, training_duration
FROM ai.optimized_functions_view;

[status] 列には、モデルの現在の運用ステータスが表示されます。次の値が表示されます。

• READY: プロキシモデルのトレーニングが正常に完了し、受信クエリを高速化する準備が整いました。
• UNTRAINED: モデルは登録またはスケジュールされていますが、バックグラウンド トレーニングはまだ完了していません。最初のバックグラウンド トレーニングが失敗すると、モデルは UNTRAINED 状態のままになり、クエリはリモート LLM にフォールバックします（フォールバックが無効になっている場合はエラーになります）。
• RETRAINING_IN_PROGRESS: バックグラウンドでの再トレーニングが進行中です。
• RETRAINING_FAILED: 最新のバックグラウンドまたは手動の再トレーニング実行が失敗しました。ほとんどのシナリオでは、再トレーニング前のモデルの重みが存在する場合、AlloyDB は推論に既存のモデルの重みを使用し続けます。既存のモデルの重みが利用できない場合（またはランタイム精度チェックが失敗した場合）、AlloyDB はモデルが正常に再トレーニングされるまで、リモート LLM（google_ml_integration.proxy_models_enable_llm_fallback の対象）を使用してクエリを評価するようにフォールバックします。

このビューで使用可能なすべての列の詳細については、既存のプロキシモデルを表示するをご覧ください。

制限事項

• 最適化された AI 関数は ai.if() 関数のみをサポートします。
• プロキシモデルの定期的なバックグラウンド自動再トレーニングは、32 個未満の vCPU を搭載したデータベース インスタンスではサポートされていません。
• 行レベルのセキュリティ（RLS）: 行レベルのセキュリティ（RLS）ポリシーを使用するテーブルでトレーニングされたモデルは、特定の開始ユーザーの権限でトレーニングすることで、セキュリティ情報が漏洩する可能性があります。RLS ポリシーが適用されたテーブルでのプロキシモデルのトレーニングは無効になっています。
• 入力の変更: ai.if() に指定されたソース コンテンツ列、エンベディング列、プロンプト文字列、ベース LLM モデル ID を変更すると、既存のプロキシモデルがバイパスされ、その組み合わせに対して新しいバックグラウンド トレーニング リクエストが開始されます。
• SQL の制限事項:
  • クエリには有効な FROM 句を含める必要があります。
  • AI 関数のすべての引数は、同じテーブル エイリアスから取得する必要があります。
  • ai.if() 式の列を、エンベディングのソース列として含めます。
  • ai.if() 関数をサブクエリまたは共通テーブル式（CTE）内に配置しないでください。

次のステップ

• 最適化された AI 関数のトラブルシューティング。