Install AlloyDB AI in AlloyDB Omni

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:

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.

  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, my-service@my-project.iam.gserviceaccount.com.

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.

    docker stop CONTAINER_NAME
    docker rm CONTAINER_NAME
    docker stop CONTAINER_NAME
    docker rm CONTAINER_NAME
    podman stop CONTAINER_NAME
    podman rm CONTAINER_NAME
    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 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 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 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 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 exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
    docker exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json
    docker exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
    docker exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json
    podman exec CONTAINER_NAME chown postgres /etc/postgresql/private-key.json
    podman exec CONTAINER_NAME chmod 600 /etc/postgresql/private-key.json
    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 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 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 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 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 restart CONTAINER_NAME
    
    docker restart CONTAINER_NAME
    
    podman restart CONTAINER_NAME
    
    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 exec -it CONTAINER_NAME psql -U postgres
docker exec -it CONTAINER_NAME psql -U postgres
podman exec -it CONTAINER_NAME psql -U postgres
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) 

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