モデルを使用して予測を呼び出すか、エンベディングを生成する場合は、モデル エンドポイント管理にモデル エンドポイントを登録します。
モデルエンドポイント管理にモデルエンドポイントを登録する前に、google_ml_integration 拡張機能を有効にし、モデルエンドポイントで認証が必要な場合はモデル プロバイダに基づいて認証を設定する必要があります。
postgres のデフォルト ユーザー名でデータベースにアクセスしていることを確認します。
拡張機能を有効にする
関連する関数を使用するには、google_ml_integration 拡張機能を追加して有効にする必要があります。モデルのエンドポイント管理では、google_ml_integration 拡張機能がインストールされている必要があります。
インスタンスの
google_ml_integration.enable_model_supportデータベース フラグがonに設定されていることを確認します。データベース フラグの設定の詳細については、データベース フラグを構成するをご覧ください。省略可:
google_ml_integration拡張機能がすでにインストールされている場合は、最新バージョンに更新するように変更します。ALTER EXTENSION google_ml_integration UPDATE;psql を使用して
google_ml_integration拡張機能を追加します。CREATE EXTENSION IF NOT EXISTS google_ml_integration;省略可: モデルのメタデータを管理する権限を PostgreSQL の非スーパーユーザーに付与します。
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;NON_SUPER_USERは、スーパー以外の PostgreSQL ユーザー名に置き換えます。データベースでモデル エンドポイント管理を有効にします。
ALTER SYSTEM SET google_ml_integration.enable_model_support=on; SELECT pg_reload_conf();アウトバウンド接続が有効になっていることを確認します。
認証の設定
以降のセクションでは、モデル エンドポイントを登録する前に認証を設定する方法について説明します。
Vertex AI の認証を設定する
Google Vertex AI モデル エンドポイントを使用するには、AlloyDB Omni のインストール時に使用したサービス アカウントに Vertex AI の権限を追加する必要があります。詳細については、クラウドベースのモデルをクエリするように AlloyDB Omni インストールを構成するをご覧ください。
Secret Manager を使用して認証を設定する
モデル エンドポイントが Secret Manager を介した認証を処理しない場合、この手順は省略可能です。たとえば、モデル エンドポイントが HTTP ヘッダーを使用して認証情報を渡す場合や、認証をまったく使用しない場合などです。
API キーまたはベアラートークンを作成して使用する手順は次のとおりです。
Secret Manager で Secret を作成します。詳細については、シークレットを作成してシークレット バージョンにアクセスするをご覧ください。
シークレット パスは
google_ml.create_sm_secret()SQL 関数で使用されます。AlloyDB クラスタにシークレットへのアクセス権を付与します。
gcloud secrets add-iam-policy-binding 'SECRET_NAME' \ --member="serviceAccount:SERVICE_ACCOUNT_ID" \ --role="roles/secretmanager.secretAccessor"次のように置き換えます。
SECRET_NAME: Secret Manager のシークレット名。SERVICE_ACCOUNT_ID: 前の手順で作成したサービス アカウントの ID。これは、AlloyDB Omni のインストール時に使用したアカウントと同じであることを確認してください。これには、PROJECT_ID.iam.gserviceaccount.com接尾辞全体が含まれます。（例:my-service@my-project.iam.gserviceaccount.com）。このロールは、プロジェクト レベルでサービス アカウントに付与することもできます。詳細については、Identity and Access Management ポリシー バインディングを追加するをご覧ください。
ヘッダーを使用して認証を設定する
次の例は、エンベディング モデルへのリクエストに必要なヘッダーを含む JSON オブジェクトを返す関数を使用して認証を設定する方法を示しています。
CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
model_id VARCHAR(100),
input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
api_key VARCHAR(255) := 'API_KEY';
header_json JSON;
BEGIN
header_json := json_build_object(
'Content-Type', 'application/json',
'Authorization', 'Bearer ' || api_key
);
RETURN header_json;
END;
$$;
次のように置き換えます。
HEADER_GEN_FUNCTION: モデルの登録時に使用できるヘッダー生成関数の名前。API_KEY: モデル プロバイダの API キー。
テキスト エンベディング モデル
このセクションでは、モデル エンドポイント管理でモデル エンドポイントを登録する方法について説明します。
モデル エンドポイント管理では、事前登録済みのモデル エンドポイントとして、一部のテキスト エンベディング モデルと汎用 Vertex AI モデルがサポートされています。モデル ID を直接使用して、モデルタイプに基づいてエンベディングを生成したり、予測を呼び出したりできます。サポートされている事前登録済みモデルの詳細については、事前登録済みの Vertex AI モデルをご覧ください。
たとえば、事前登録された textembedding-gecko モデルを呼び出すには、エンベディング関数
を使用してモデルを直接呼び出します。
SELECT
google_ml.embedding(
model_id => 'textembedding-gecko',
content => 'AlloyDB is a managed, cloud-hosted SQL database service');
同様に、事前登録された gemini-1.5-pro:generateContent モデルを呼び出すには、予測関数を使用してモデルを直接呼び出します。
SELECT
json_array_elements(
google_ml.predict_row(
model_id => 'gemini-1.5-pro:generateContent',
request_body => '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
}
]
}
]
}'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
エンベディングを生成するには、事前登録済みモデル エンドポイントのエンベディングを生成する方法をご覧ください。予測を呼び出すには、事前登録済みのモデル エンドポイントの予測を呼び出す方法をご覧ください。
サポートが組み込まれたテキスト エンベディング モデル
モデル エンドポイント管理には、Vertex AI と OpenAI の一部モデルのサポートが組み込まれています。サポートが組み込まれているモデルの一覧については、サポートが組み込まれているモデルをご覧ください。
サポートが組み込まれているモデルの場合は、修飾名をモデルの修飾名として設定し、リクエスト URL を指定できます。モデル エンドポイント管理は、モデルを自動的に識別し、デフォルトの変換関数を設定します。
Vertex AI エンベディング モデル
次の手順では、組み込みサポートを使用して Vertex AI モデルを登録する方法を示します。例として、text-embedding-005 モデル エンドポイントと text-multilingual-embedding-002 モデル エンドポイントを使用します。
AlloyDB Omni の場合は、クラウドベースの Vertex AI モデルをクエリするように AlloyDB Omni を設定してください。
モデル作成関数を呼び出して、モデル エンドポイントを追加します。
text-embedding-005
CALL google_ml.create_model( model_id => 'text-embedding-005', model_request_url => 'publishers/google/models/text-embedding-005', model_provider => 'google', model_qualified_name => 'text-embedding-005', model_type => 'text_embedding', model_auth_type => 'alloydb_service_agent_iam');text-multilingual-embedding-002
CALL google_ml.create_model( model_id => 'text-multilingual-embedding-002', model_request_url => 'publishers/google/models/text-multilingual-embedding-002', model_provider => 'google', model_qualified_name => 'text-multilingual-embedding-002', model_type => 'text_embedding', model_auth_type => 'alloydb_service_agent_iam' model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform', model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');
関数が生成するリクエスト URL は、AlloyDB Omni サービス アカウントに関連付けられているプロジェクトを参照します。別のプロジェクトを参照する場合は、model_request_url を明示的に指定してください。
モデルが AlloyDB クラスタとは別のプロジェクトとリージョンに保存されている場合は、リクエスト URL を projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID に設定します。ここで、REGION_ID はモデルがホストされているリージョン、MODEL_ID は修飾されたモデル名です。
また、AlloyDB Omni がインストールされているプロジェクトのサービス アカウントに Vertex AI ユーザー（roles/aiplatform.user）ロールを付与して、他のプロジェクトでホストされているモデルにアクセスできるようにします。
Open AI テキスト エンベディング モデル
google_ml_integration 拡張機能は、デフォルトの変換関数を自動的に設定し、リモートの OpenAI モデルへの呼び出しを呼び出します。サポートが組み込まれている OpenAI モデルの一覧については、サポートが組み込まれているモデルをご覧ください。
次の例では、text-embedding-ada-002 OpenAI モデル エンドポイントを追加します。OpenAI text-embedding-3-small モデル エンドポイントと text-embedding-3-large モデル エンドポイントは、同じ手順で登録し、モデル固有のモデル修飾名を設定できます。
psqlを使用してデータベースに接続します。google_ml_integration拡張機能を作成して有効にする。- 認証用に OpenAI API キーを Secret Manager にシークレットとして追加します。
Secret Manager に保存されているシークレットを呼び出します。
CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');次のように置き換えます。
SECRET_ID: 設定したシークレット ID。モデル エンドポイントの登録時に使用されます（例:key1）。SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。PROJECT_ID: Google Cloud プロジェクトの ID。VERSION_NUMBER: シークレット ID のバージョン番号。
モデル作成関数を呼び出して、
text-embedding-ada-002モデル エンドポイントを登録します。CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'open_ai', model_type => 'text_embedding', model_qualified_name => 'text-embedding-ada-002', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID');次のように置き換えます。
MODEL_ID: 定義するモデル エンドポイントの一意の ID。このモデル ID は、モデル エンドポイントがエンベディングの生成または予測の呼び出しに必要なメタデータで参照されます。SECRET_ID: 前のgoogle_ml.create_sm_secret()手順で使用したシークレット ID。
エンベディングを生成するには、組み込みサポートを使用してモデル エンドポイントのエンベディングを生成する方法をご覧ください。
カスタム ホスト テキスト エンベディング モデル
このセクションでは、カスタム ホスト型モデル エンドポイントを登録する方法と、変換関数を作成する方法について説明します。必要に応じて、カスタム HTTP ヘッダーも作成します。カスタム ホスト型モデル エンドポイントは、ホストされている場所に関係なくすべてサポートされています。
次の例では、Cymbal でホストされている custom-embedding-model カスタムモデル エンドポイントを追加します。cymbal_text_input_transform 変換関数と cymbal_text_output_transform 変換関数は、モデルの入力形式と出力形式を予測関数の入力形式と出力形式に変換するために使用されます。
カスタム ホストされているテキスト エンベディング モデルのエンドポイントを登録するには、次の操作を行います。
psqlを使用してデータベースに接続します。Secret Manager に保存されているシークレットを呼び出します。
CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');次のように置き換えます。
SECRET_ID: 設定したシークレット ID。モデル エンドポイントの登録時に使用されます（例:key1）。SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。PROJECT_ID: Google Cloud プロジェクトの ID。VERSION_NUMBER: シークレット ID のバージョン番号。
テキスト エンベディング モデル エンドポイントの予測関数の次のシグネチャに基づいて、入力変換関数と出力変換関数を作成します。変換関数の作成方法の詳細については、変換関数の例をご覧ください。
次の例は、
custom-embedding-modelテキスト エンベディング モデル エンドポイントに固有の変換関数です。-- Input Transform Function corresponding to the custom model endpoint CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT) RETURNS JSON LANGUAGE plpgsql AS $$ DECLARE transformed_input JSON; model_qualified_name TEXT; BEGIN SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input; RETURN transformed_input; END; $$; -- Output Transform Function corresponding to the custom model endpoint CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON) RETURNS REAL[] LANGUAGE plpgsql AS $$ DECLARE transformed_output REAL[]; BEGIN SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output; RETURN transformed_output; END; $$;モデル作成関数を呼び出して、カスタム エンベディング モデル エンドポイントを登録します。
CALL google_ml.create_model( model_id => 'MODEL_ID', model_request_url => 'REQUEST_URL', model_provider => 'custom', model_type => 'text_embedding', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', model_qualified_name => 'MODEL_QUALIFIED_NAME', model_in_transform_fn => 'cymbal_text_input_transform', model_out_transform_fn => 'cymbal_text_output_transform');次のように置き換えます。
MODEL_ID: 必須。定義するモデル エンドポイントの一意の ID（custom-embedding-modelなど）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。REQUEST_URL: 必須。カスタム テキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（https://cymbal.com/models/text/embeddings/v1など）。MODEL_QUALIFIED_NAME: モデル エンドポイントで修飾名を使用する場合に必須です。モデル エンドポイントに複数のバージョンがある場合の完全修飾名。SECRET_ID: 前のgoogle_ml.create_sm_secret()手順で使用したシークレット ID。
汎用モデル
このセクションでは、Hugging Face、OpenAI、Vertex AI、Anthropic などのホスト型モデル プロバイダで利用可能な汎用モデル エンドポイントを登録する方法について説明します。このセクションでは、Hugging Face でホストされている汎用モデル エンドポイント、Vertex AI Model Garden の汎用 gemini-pro モデル、claude-haiku モデル エンドポイントを登録する例を示します。
入力と出力が JSON 形式であれば、任意の汎用モデル エンドポイントを登録できます。モデルのエンドポイント メタデータに基づいて、HTTP ヘッダーの生成やリクエスト URL の定義が必要になる場合があります。
事前登録済みの汎用モデルと組み込みサポート付きモデルの詳細については、サポートされているモデルをご覧ください。
Gemini モデル
一部の gemini-pro モデルは事前登録されているため、モデル ID を直接呼び出して予測を呼び出すことができます。クラウドベースの Vertex AI モデルをクエリするように AlloyDB Omni を設定していることを確認します。
次の例では、Vertex AI Model Garden の gemini-1.5-pro:generateContent モデル エンドポイントを使用します。
psqlを使用してデータベースに接続します。google_ml_integration拡張機能を作成して有効にする。事前登録済みのモデル ID を使用して予測を呼び出します。
SELECT json_array_elements( google_ml.predict_row( model_id => 'gemini-1.5-pro:generateContent', request_body => '{ "contents": [ { "role": "user", "parts": [ { "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation." } ] } ] }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
Hugging Face の汎用モデル
次の例では、Hugging Face でホストされている facebook/bart-large-mnli カスタム分類モデル エンドポイントを追加します。
psqlを使用してデータベースに接続します。google_ml_integration拡張機能を作成して有効にする。- 認証用に OpenAI API キーを Secret Manager にシークレットとして追加します。他の OpenAI モデルのシークレットをすでに作成している場合は、同じシークレットを再利用できます。
Secret Manager に保存されているシークレットを呼び出します。
CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');次のように置き換えます。
SECRET_ID: 設定したシークレット ID。モデル エンドポイントの登録時に使用されます。SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。PROJECT_ID: Google Cloud プロジェクトの ID。VERSION_NUMBER: シークレット ID のバージョン番号。
モデル作成関数を呼び出して、
facebook/bart-large-mnliモデル エンドポイントを登録します。CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'hugging_face', model_request_url => 'REQUEST_URL', model_qualified_name => 'MODEL_QUALIFIED_NAME', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID');次のように置き換えます。
MODEL_ID: 定義するモデル エンドポイントの一意の ID（例:custom-classification-model）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。REQUEST_URL: カスタムテキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（例:https://api-inference.huggingface.co/models/facebook/bart-large-mnli）。MODEL_QUALIFIED_NAME: モデル エンドポイント バージョンの完全修飾名（例:facebook/bart-large-mnli）。SECRET_ID: 前のgoogle_ml.create_sm_secret()手順で使用したシークレット ID。
Anthropic 汎用モデル
次の例では、claude-3-opus-20240229 モデル エンドポイントを追加します。モデル エンドポイント管理は、Anthropic モデルの登録に必要なヘッダー関数を提供します。
クラウドベースの Vertex AI モデルをクエリするように AlloyDB Omni を設定していることを確認します。
psqlを使用してデータベースに接続します。google_ml_integration拡張機能を作成して有効にする。Secret Manager
- 認証用にベアラートークンをシークレットとして Secret Manager に追加します。
Secret Manager に保存されているシークレットを呼び出します。
CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');次のように置き換えます。
SECRET_ID: 設定したシークレット ID。モデル エンドポイントの登録時に使用されます。SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。PROJECT_ID: Google Cloud プロジェクトの ID。VERSION_NUMBER: シークレット ID のバージョン番号。
モデル作成関数を呼び出して、
claude-3-opus-20240229モデル エンドポイントを登録します。CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');次のように置き換えます。
MODEL_ID: 定義するモデル エンドポイントの一意の ID（例:anthropic-opus）。このモデル ID は、モデル エンドポイントがエンベディングの生成または予測の呼び出しに必要なメタデータで参照されます。REQUEST_URL: カスタムテキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（例:https://api.anthropic.com/v1/messages）。
Auth ヘッダー
google_ml.anthropic_claude_header_gen_fnのデフォルトのヘッダー生成関数を使用するか、ヘッダー生成関数を作成します。CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON) RETURNS JSON LANGUAGE plpgsql AS $$ #variable_conflict use_variable BEGIN RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON; END; $$;次のように置き換えます。
ANTHROPIC_API_KEY: anthropic API キー。ANTHROPIC_VERSION（省略可）: 使用する特定のモデル バージョン（例:2023-06-01）。
モデル作成関数を呼び出して、
claude-3-opus-20240229モデル エンドポイントを登録します。CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');次のように置き換えます。
MODEL_ID: 定義するモデル エンドポイントの一意の ID（例:anthropic-opus）。このモデル ID は、モデル エンドポイントがエンベディングの生成または予測の呼び出しに必要なメタデータで参照されます。REQUEST_URL: カスタムテキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（例:https://api.anthropic.com/v1/messages）。
詳細については、汎用モデル エンドポイントの予測を呼び出す方法をご覧ください。
次のステップ
- モデル エンドポイント管理リファレンスについて学習する
- モデル エンドポイントを登録するためのサンプル テンプレートを使用する