Install AlloyDB AI in AlloyDB Omni

Note: Your use of AlloyDB Omni is subject to the agreement between you and Google that governs Google Cloud offerings. If you do not have a Google Cloud account, or have not otherwise entered into an agreement with Google that governs Google Cloud offerings, please do not proceed or download this software until you have done so. To create a Google Cloud account, see the Google Cloud homepage.

This page shows you how to install AlloyDB Omni and integrate AlloyDB AI.

AlloyDB AI is a suite of features included with AlloyDB Omni that let you build enterprise generative AI applications. For more information about the AI/ML functionality of AlloyDB, see Build generative AI applications.

AlloyDB Omni with AlloyDB AI lets you query remote ML models to work with online predictions and text embeddings generated from ML models. AlloyDB Omni with AlloyDB AI can also process vector embeddings from other content such as an image, for example, if you use the google_ml.predict_row interface and do the translation yourself in the query.

Based on where you want to install AlloyDB Omni with AlloyDB AI, select one of the following options:

Single-server Kubernetes GDC air-gapped

Configure your AlloyDB Omni instance to query remote models

AlloyDB Omni can query remote ML models using the google_ml_integration extension.

Optionally, if you want to query Vertex AI models, you must configure AlloyDB Omni service account with Vertex AI before installing AlloyDB Omni.

To configure AlloyDB Omni to query remote models, follow these steps:

1. Create a service account with Google Cloud.

2. Create a service account key, in JSON format, and download it. Make a note of the service account key because you use it later in this procedure.

   Note: Service account keys are a security risk if not managed correctly. You are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

   If you acquired the service account key from an external source, you must validate it before use. For more information, see Security requirements for externally sourced credentials".

3. Copy the service account key that you created to KEY_PATH. The key path should be a path on your host accessible, and owned, by the user that will run your AlloyDB Omni container.

4. Enable the Vertex AI API in your Google Cloud project.

   gcloud services enable aiplatform.googleapis.com
   

5. Add Vertex AI Identity and Access Management (IAM) permissions to the appropriate project and service account.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_ID" \
       --role="roles/aiplatform.user"
   

   Replace the following:

   • PROJECT_ID: ID of your Google Cloud project.

   • SERVICE_ACCOUNT_ID: ID of the service account that you created in the step one. This includes the full @PROJECT_ID.iam.gserviceaccount.com suffix. For example, [e-mail].

Configure AlloyDB AI for AlloyDB Omni

To install AlloyDB Omni and integrate AlloyDB AI, complete the following steps as the root user:

1. Complete all of the steps listed in Configure your AlloyDB Omni to query cloud-based models.

2. If an existing container of the same name exists, stop and remove it.

   Caution: Ensure that the data for your container is mounted on a volume that points to a directory on your host. This keeps your data safe between containers.

   Docker

   docker stop CONTAINER_NAME
   docker rm CONTAINER_NAME

   Docker

   docker stop CONTAINER_NAME
   docker rm CONTAINER_NAME

   Podman

   podman stop CONTAINER_NAME
   podman rm CONTAINER_NAME

   Podman

   podman stop CONTAINER_NAME
   podman rm CONTAINER_NAME

   Replace the following:

   • CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.

3. Start a new AlloyDB Omni container mounting the key into the container.

   Docker

   docker run -d --name CONTAINER_NAME \
   -e POSTGRES_PASSWORD=NEW_PASSWORD \
   -v DATA_DIR:/var/lib/postgresql/data \
   -v "KEY_PATH":/etc/postgresql/private-key.json \
   -p HOST_PORT:5432 \
   --restart=always \
   google/alloydbomni:latest
   

   Docker

   docker run -d --name CONTAINER_NAME \
   -e POSTGRES_PASSWORD=NEW_PASSWORD \
   -v DATA_DIR:/var/lib/postgresql/data \
   -v "KEY_PATH":/etc/postgresql/private-key.json \
   -p HOST_PORT:5432 \
   --restart=always \
   google/alloydbomni:latest
   

   Podman

   podman run -d --name CONTAINER_NAME \
   -e POSTGRES_PASSWORD=NEW_PASSWORD \
   -v DATA_DIR:/var/lib/postgresql/data \
   -v "KEY_PATH":/etc/postgresql/private-key.json \
   -p HOST_PORT:5432 \
   --restart=always \
   docker.io/google/alloydbomni:latest
   

   Podman

   podman run -d --name CONTAINER_NAME \
   -e POSTGRES_PASSWORD=NEW_PASSWORD \
   -v DATA_DIR:/var/lib/postgresql/data \
   -v "KEY_PATH":/etc/postgresql/private-key.json \
   -p HOST_PORT:5432 \
   --restart=always \
   docker.io/google/alloydbomni:latest
   

   Replace the following variables:

   • CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.
   • NEW_PASSWORD: Password assigned to the new container's postgres user after its creation. Note that NEW_PASSWORD will only set a new password when DATA_DIR is a new location.
   • DATA_DIR: Host directory path that your data is stored in.
   • KEY_PATH: Path for your service account key file.
   • HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.

4. Make the key file readable by the postgres user inside the AlloyDB Omni container.

   Docker

   docker exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
   docker exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json

   Docker

   docker exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
   docker exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json

   Podman

   podman exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
   podman exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json

   Podman

   podman exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
   podman exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json

   Replace the following variables:

   • CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.
   • KEY_PATH: Host path for your service account key file.

5. Update AlloyDB Omni by adding the following configuration options.

   Docker

   docker exec CONTAINER_NAME sh -c "cat << EOF >> /var/lib/postgresql/data/postgresql.conf
   omni_enable_ml_agent_process = 'on'
   omni_google_cloud_private_key_file_path = '/etc/postgresql/private-key.json'
   EOF"
   

   Docker

   docker exec CONTAINER_NAME sh -c "cat << EOF >> /var/lib/postgresql/data/postgresql.conf
   omni_enable_ml_agent_process = 'on'
   omni_google_cloud_private_key_file_path = '/etc/postgresql/private-key.json'
   EOF"
   

   Podman

   podman exec CONTAINER_NAME sh -c "cat << EOF >> /var/lib/postgresql/data/postgresql.conf
   omni_enable_ml_agent_process = 'on'
   omni_google_cloud_private_key_file_path = '/etc/postgresql/private-key.json'
   EOF"
   

   Podman

   podman exec CONTAINER_NAME sh -c "cat << EOF >> /var/lib/postgresql/data/postgresql.conf
   omni_enable_ml_agent_process = 'on'
   omni_google_cloud_private_key_file_path = '/etc/postgresql/private-key.json'
   EOF"
   

   Replace the following variables:

   • CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.

6. Restart the AlloyDB Omni container.

   Docker

   docker restart CONTAINER_NAME
   

   Docker

   docker restart CONTAINER_NAME
   

   Podman

   podman restart CONTAINER_NAME
   

   Podman

   podman restart CONTAINER_NAME
   

   Replace the following variable:

   • CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.

Connect using the containerized psql

To connect to the AlloyDB Omni database server using its own containerized copy of psql, run the following command:

Docker

docker exec -it CONTAINER_NAME psql -U postgres

Docker

docker exec -it CONTAINER_NAME psql -U postgres

Podman

podman exec -it CONTAINER_NAME psql -U postgres

Podman

podman exec -it CONTAINER_NAME psql -U postgres

Replace the following variable:

• CONTAINER_NAME: Name to assign your AlloyDB Omni container in your host machine's container registry. For example, my-omni-1.

Verify AlloyDB Omni with AlloyDB AI installation

To verify your installation is successful and uses model prediction, enter the following:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

SELECT array_dims(embedding('text-embedding-005', 'AlloyDB AI')::real[]);

The output looks similar to the following:

array_dims
------------
[1:768]
(1 row) 

Note: Vertex AI model support is governed by Vertex AI model versioning and lifecycle guidelines. For more information about stable versions, see Model versions and lifecycle.

In the previous query, the embedding() call generates embeddings for the input text AlloyDB AI. array_dims returns the dimensions of the array returned by embedding(). Since the text-embedding-005 model returns an output with 768 dimensions, the output is [768].

What's next

• Run and connect to AlloyDB Omni
• Manage AlloyDB Omni
• Build generative AI applications using AlloyDB AI
• Register and call remote AI models