1. 简介
在此 Codelab 中,您将学习如何在 Google Kubernetes Engine (GKE) 上部署 AlloyDB Omni,并将其与 EmbeddingGemma 和 Gemma 4 等开放模型结合使用,以进行嵌入和预测。在同一集群中运行数据库和模型可减少网络延迟,并避免对第三方服务的依赖。由于数据绝不会离开您的环境,因此这也有助于满足合规性和数据驻留要求。

前提条件
- 对 Google Cloud 和 Google Cloud 控制台有基本的了解
- 对 Kubernetes 和 GKE 有基本了解
- 熟悉命令行界面和 Google Cloud Shell
学习内容
- 如何在 GKE 集群上部署 AlloyDB Omni
- 如何连接到 AlloyDB Omni
- 如何将数据加载到 AlloyDB Omni
- 如何将 AI 模型(嵌入和 LLM)部署到 GKE
- 如何在 AlloyDB Omni 中注册 AI 模型
- 如何为语义搜索生成嵌入
- 如何在 AlloyDB Omni 中运行语义搜索查询
- 如何在 AlloyDB Omni 中创建和使用向量索引
所需条件
- Google Cloud 账号和 Google Cloud 项目
- 网络浏览器,例如 Chrome
2. 设置和要求
项目设置
- 登录 Google Cloud 控制台。如果您还没有 Gmail 或 Google Workspace 账号,请创建一个。使用个人账号,而非工作或学校账号。
- 创建新项目或选择现有项目。在 Google Cloud 控制台标题中,点击选择项目,然后点击新建项目。

在选择项目窗口中,点击新建项目以打开项目创建对话框。

在对话框中,输入项目名称,然后选择您的组织或位置。

- 项目名称是此项目参与者的显示名称。Google API 不会使用项目名称,您可以随时更改项目名称。
- 项目 ID 在所有 Google Cloud 项目中是唯一的,并且是不可变的(一经设置便无法更改)。Google Cloud 控制台会自动生成一个唯一 ID,您也可以自行提供。在本 Codelab 中,您将使用
占位符引用项目 ID。 - 项目编号是某些 API 使用的第三个标识符。如需了解详情,请参阅 Resource Manager 文档。
启用结算功能
如果您使用 Google Cloud 赠金设置了结算信息,则可以跳过此步骤。
如需设置个人结算账号,请在 Google Cloud 控制台中启用结算功能。
- 完成本实验所需的 Google Cloud 资源费用不到 5 美元。
- 请按照本实验末尾的清理步骤删除资源,以免产生更多费用。
- 新用户符合参与 $300 USD 免费试用计划的条件。
启动 Cloud Shell
在此 Codelab 中,您将使用 Google Cloud Shell,这是一个在云端运行的命令行环境。
在 Google Cloud 控制台中,点击右上角工具栏中的激活 Cloud Shell 图标:

或者,按 G 键再按 S 键,或直接打开 Google Cloud Shell。
连接后,Cloud Shell 会显示终端提示:

Cloud Shell 包含永久性存储空间和开发者工具。您可以在浏览器中运行此 Codelab 中的所有步骤。
3. 启用 API
如需将 Google Kubernetes Engine (GKE) 用于 AlloyDB Omni 和模型部署,请在 Google Cloud 云项目中启用 Compute Engine API 和 GKE API。
在 Cloud Shell 中,验证是否已配置项目 ID:
PROJECT_ID=$(gcloud config get-value project)
echo $PROJECT_ID
如果您的项目 ID 未定义,请进行配置:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
启用必需的 API:
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
预期输出:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=test-project-001-402417 student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417 Updated property [core/project]. student@cloudshell:~ (test-project-001-402417)$ gcloud services enable compute.googleapis.com gcloud services enable container.googleapis.com Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
您可以在文档中了解每个已启用的 API。
4. 在 GKE 上部署 AlloyDB Omni
如需在 GKE 上部署 AlloyDB Omni,请按照 AlloyDB Omni 操作器要求准备 Kubernetes 集群。
创建 GKE 集群
部署 Autopilot GKE 集群,以运行 AlloyDB Omni、Operator 和监控容器。使用 Autopilot,我们可以简化部署 - 系统会自动分配 AlloyDB Omni 操作器、集群和其他组件的所有资源。
选择您要部署资源的区域。选择地理位置上靠近您所在位置的区域:
export LOCATION=<your region>
为部署设置环境变量:
export PROJECT_ID=$(gcloud config get-value project)
export CLUSTER_NAME=alloydb-ai-gke
创建 Autopilot GKE 集群:
gcloud container clusters create-auto ${CLUSTER_NAME} \
--project=${PROJECT_ID} \
--region=${LOCATION}
预期的控制台输出:
student@cloudshell:~ (test-project-001-402417)$ export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME=alloydb-ai-gke
Your active configuration is: [test-project-001-402417]
student@cloudshell:~ (test-project-001-402417)$ gcloud container clusters create-auto ${CLUSTER_NAME} \
> --project=${PROJECT_ID} \
> --region=${LOCATION}
Creating cluster alloydb-ai-gke in us-east4... Cluster is being health-checked.
..⠹
Creating cluster alloydb-ai-gke in us-east4... Cluster is being health-checked
(Kubernetes Control Plane is healthy)...done.
Created [https://container.googleapis.com/v1/projects/gleb-genai-002/zones/us-east4/clusters/alloydb-ai-gke].
To inspect the contents of your cluster, go to: https://console.cloud.google.com/kubernetes/workload_/gcloud/us-east4/alloydb-ai-gke?project=gleb-genai-002
kubeconfig entry generated for alloydb-ai-gke.
NAME LOCATION MASTER_VERSION MASTER_IP MACHINE_TYPE NODE_VERSION NUM_NODES STATUS STACK_TYPE
alloydb-ai-gke us-east4 1.36.4-gke.1391002 34.145.214.51 ek-standard-8 1.36.4-gke.1391002 3 RUNNING IPV4
准备集群
安装所需组件,例如 Kubernetes 的证书控制器 cert-manager。如需了解详情,请参阅 cert-manager 安装文档。
Cloud Shell 包含 Kubernetes 命令行工具 kubectl 和 helm。使用 gcloud 获取集群凭据:
gcloud container clusters get-credentials ${CLUSTER_NAME} --region=${LOCATION}
使用 helm 安装 cert-manager:
helm install \
cert-manager oci://quay.io/jetstack/charts/cert-manager \
--version v1.21.2 \
--namespace cert-manager \
--create-namespace \
--set featureGates="ServerSideApply=true" \
--set global.leaderElection.namespace=cert-manager \
--set "extraArgs={--certificate-request-minimum-backoff-duration=15s,--certificate-request-maximum-backoff-duration=5m}" \
--set crds.enabled=true
预期的控制台输出(已隐去部分信息):
student@cloudshell:~$ elm install \
> cert-manager oci://quay.io/jetstack/charts/cert-manager \
> --version v1.21.2 \
> --namespace cert-manager \
> --create-namespace \
> --set featureGates="ServerSideApply=true" \
> --set global.leaderElection.namespace=cert-manager \
> --set "extraArgs={--certificate-request-minimum-backoff-duration=15s,--certificate-request-maximum-backoff-duration=5m}" \
> --set crds.enabled=true
Pulled: quay.io/jetstack/charts/cert-manager:v1.21.2
Digest: sha256:634dce9c13b56677a2c05e2ab76c312d0be2664022d5dd05815da67e1fd5f610
I1016 12:25:06.128464 30644 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Deployment cert-manager/cert-manager-cainjector: defaulted unspecified 'cpu' resource for containers [cert-manager-cainjector] (see http://g.co/gke/autopilot-defaults)."
I1016 12:25:06.129972 30644 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Deployment cert-manager/cert-manager: defaulted unspecified 'cpu' resource for containers [cert-manager-controller] (see http://g.co/gke/autopilot-defaults)."
I1016 12:25:06.134580 30644 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Deployment cert-manager/cert-manager-webhook: defaulted unspecified 'cpu' resource for containers [cert-manager-webhook] (see http://g.co/gke/autopilot-defaults)."
I1016 12:25:06.250590 30644 warnings.go:107] "Warning: AdmissionWebhookController: mutated namespaceselector of the webhooks to enforce GKE Autopilot policies."
I1016 12:25:09.758249 30644 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Job cert-manager/cert-manager-startupapicheck: defaulted unspecified 'cpu' resource for containers [cert-manager-startupapicheck] (see http://g.co/gke/autopilot-defaults)."
NAME: cert-manager
LAST DEPLOYED: Fri Oct 16 12:24:57 2026
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
cert-manager v1.21.2 has been deployed successfully!
安装 AlloyDB Omni 操作器
使用 Helm 安装 AlloyDB Omni 操作器。
下载并安装 AlloyDB Omni 操作器图表:
helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \
--version 1.9.0 \
--create-namespace \
--namespace alloydb-omni-system \
$(helm install --help | grep -q -- '--rollback-on-failure' && echo '--rollback-on-failure' || echo '--atomic') \
--timeout 5m
预期的控制台输出(已隐去部分信息):
student@cloudshell:~$ helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \ > --version 1.9.0 \ > --create-namespace \ > --namespace alloydb-omni-system \ > $(helm install --help | grep -q -- '--rollback-on-failure' && echo '--rollback-on-failure' || echo '--atomic') \ > --timeout 5m Pulled: gcr.io/alloydb-omni/alloydbomni-operator:1.9.0 Digest: sha256:4f6cc3f0c1fbe003ab7d0119afee516e5c67ec950cd2909b418e5a3f6f09d1f6 I1016 12:28:50.088533 30982 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Deployment alloydb-omni-system/fleet-controller-manager: adjusted 'cpu' resource to meet requirements for containers [fleet-manager] (see http://g.co/gke/autopilot-defaults)." I1016 12:28:50.092917 30982 warnings.go:107] "Warning: autopilot-default-resources-mutator:Autopilot updated Deployment alloydb-omni-system/local-controller-manager: adjusted 'cpu' resource to meet requirements for containers [local-manager] (see http://g.co/gke/autopilot-defaults)." I1016 12:28:50.229717 30982 warnings.go:107] "Warning: AdmissionWebhookController: mutated namespaceselector of the webhooks to enforce GKE Autopilot policies." I1016 12:28:50.238578 30982 warnings.go:107] "Warning: AdmissionWebhookController: mutated namespaceselector of the webhooks to enforce GKE Autopilot policies." NAME: alloydbomni-operator LAST DEPLOYED: Fri Oct 16 12:28:45 2026 NAMESPACE: alloydb-omni-system STATUS: deployed REVISION: 1 DESCRIPTION: Install complete TEST SUITE: None
部署数据库集群。
以下清单配置了一个启用了 googleMLExtension 且具有内部负载均衡器的数据库集群:
cat << 'EOF' > my-omni.yaml
apiVersion: v1
kind: Secret
metadata:
name: db-pw-my-omni
type: Opaque
data:
my-omni: "VmVyeVN0cm9uZ1Bhc3N3b3Jk"
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
name: my-omni
spec:
databaseVersion: "18.4.0"
primarySpec:
adminUser:
passwordRef:
name: db-pw-my-omni
features:
googleMLExtension:
enabled: true
resources:
cpu: 1
memory: 8Gi
disks:
- name: DataDisk
size: 20Gi
dbLoadBalancerOptions:
annotations:
networking.gke.io/load-balancer-type: "internal"
allowExternalIncomingTraffic: true
EOF
密码 Secret 值是 VeryStrongPassword 的 Base64 表示形式。在生产环境中,请使用 Google Secret Manager 管理密码。如需了解详情,请参阅 Secret Manager 文档。
清单会保存为 my-omni.yaml。在 Cloud Shell 中,点击终端窗口右上角的打开编辑器,然后阅读该文件。

阅读 my-omni.yaml 清单后,点击打开终端以返回命令提示符。

应用 my-omni.yaml 清单:
kubectl apply -f my-omni.yaml
预期的控制台输出:
secret/db-pw-my-omni created dbcluster.alloydbomni.dbadmin.goog/my-omni created
检查 my-omni 集群的状态:
kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default
在部署期间,数据库集群会经历各个设置阶段,直到达到 DBClusterReady 状态。
预期的控制台输出:
$ kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default NAME PRIMARYENDPOINT PRIMARYPHASE DBCLUSTERPHASE HAREADYSTATUS HAREADYREASON my-omni 10.131.0.33 Ready DBClusterReady
(可选)您可以使用 kubectl log 命令监控集群部署:
kubectl logs -l alloydbomni.internal.dbadmin.goog/dbcluster=my-omni --all-containers -f
连接到 AlloyDB Omni
集群准备就绪后,使用 PostgreSQL 客户端 (psql) 连接到数据库 Pod。密码为 VeryStrongPassword,如 my-omni.yaml 中所定义:
DB_CLUSTER_NAME=my-omni
DB_CLUSTER_NAMESPACE=default
DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=$DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n $DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n $DB_CLUSTER_NAMESPACE -c database -- psql -h localhost -U postgres
控制台输出示例:
DB_CLUSTER_NAME=my-omni
DB_CLUSTER_NAMESPACE=default
DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=$DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n $DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n $DB_CLUSTER_NAMESPACE -c database -- psql -h localhost -U postgres
Password for user postgres:
psql (18.4)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_128_GCM_SHA256, compression: off, ALPN: postgresql)
Type "help" for help.
postgres=#
输入 \q 并按 Enter 键,退出 psql 会话:
postgres=# \q
5. 在 GKE 上部署 EmbeddingGemma 模型
如需测试 AlloyDB Omni AI 与本地模型的集成,请将嵌入模型部署到 GKE 集群。本教程使用 Google 的 EmbeddingGemma 模型。
获取 Hugging Face 令牌
本教程将部署 Hugging Face 中的 EmbeddingGemma 模型。如需访问模型权重,请生成 Hugging Face 访问令牌:
- 登录或创建 Hugging Face 账号。
- 前往您的个人资料 > 访问令牌。
- 点击创建新令牌。
- 输入令牌名称,然后选择读取角色。
- 点击创建令牌,然后复制生成的令牌值。
- 如果您之前未接受过模型条款,请在 EmbeddingGemma 模型页面上接受。
在 Cloud Shell 中创建一个包含 Hugging Face 令牌的 Kubernetes Secret(将令牌占位符替换为您的令牌):
export HF_TOKEN=<YOUR_HUGGING_FACE_TOKEN>
kubectl create secret generic hf-secret \
--from-literal=hf_api_token=$HF_TOKEN \
--dry-run=client -o yaml | kubectl apply -f -
准备部署清单
如需部署模型,请使用 Hugging Face 的文本嵌入推理 (TEI) 容器软件包。如需了解详情,请参阅 Hugging Face GKE TEI 文档。
从 GitHub 克隆部署代码库:
git clone https://github.com/huggingface/Google-Cloud-Containers
检查并修改 CPU 配置清单:
edit Google-Cloud-Containers/examples/gke/tei-deployment/cpu-config/deployment.yaml
更新后的 CPU 部署清单:
apiVersion: apps/v1
kind: Deployment
metadata:
name: tei-deployment
spec:
replicas: 1
selector:
matchLabels:
app: tei-server
template:
metadata:
labels:
app: tei-server
hf.co/model: Google--embeddinggemma-300m
hf.co/task: text-embeddings
spec:
containers:
- name: tei-container
image: ghcr.io/huggingface/text-embeddings-inference:cpu-latest
resources:
requests:
cpu: "6"
memory: "24Gi"
limits:
cpu: "6"
memory: "24Gi"
env:
- name: MODEL_ID
value: google/embeddinggemma-300m
- name: NUM_SHARD
value: "1"
- name: PORT
value: "8080"
- name: HF_TOKEN
valueFrom:
secretKeyRef:
name: hf-secret
key: hf_api_token
volumeMounts:
- mountPath: /tmp
name: tmp
volumes:
- name: tmp
emptyDir: {}
nodeSelector:
cloud.google.com/machine-family: "c3"
按 ctrl+s 保存更改,然后切换回终端。
部署模型
应用清单以部署 TEI 服务器:
kubectl apply -f Google-Cloud-Containers/examples/gke/tei-deployment/cpu-config
监控部署,直到其处于就绪状态:
printf "Waiting for model to load..."; until kubectl logs -l app=tei-server --tail=50 2>/dev/null | grep -q "Ready"; do printf "."; sleep 3; done; printf '\n\033[1;32m========================================\n[SUCCESS] Model is loaded and ready!\nYou can now proceed to the next step.\n========================================\033[0m\n'
检查 tei-service Kubernetes 服务:
kubectl get service tei-service
预期输出:
student@cloudshell$ kubectl get service tei-service NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE tei-service ClusterIP 34.118.233.48 <none> 8080/TCP 10m
服务 CLUSTER-IP 在内部通过 http://34.118.233.48:8080/embed 处理请求。
使用 kubectl port-forward 在本地测试模型端点:
kubectl port-forward service/tei-service 8080:8080
点击终端顶部的 +,打开第二个 Cloud Shell 标签页:

在新标签页中,使用 curl 测试嵌入生成:
curl http://localhost:8080/embed \
-X POST \
-d '{"inputs":"Test"}' \
-H 'Content-Type: application/json'
预期输出(向量数组):
curl http://localhost:8080/embed \
> -X POST \
> -d '{"inputs":"Test"}' \
> -H 'Content-Type: application/json'
[[-0.018975832,0.0071419072,0.06347208,0.022992613,0.014205903
...
-0.03677433,0.01636146,0.06731572]]
在第一个标签页中按 ctrl+c 停止端口转发。
6. 在 AlloyDB Omni 中注册嵌入模型
如需从 AlloyDB Omni 使用已部署的模型,请创建数据库、定义转换函数并注册模型端点。
创建客户端虚拟机和数据库
在同一 VPC 中创建一个 Compute Engine 虚拟机实例,作为客户端跳板主机:

在 Cloud Shell 中,创建客户端虚拟机:
export ZONE=${LOCATION}-a
gcloud compute instances create instance-1 \
--zone=$ZONE
检索 AlloyDB Omni 端点 IP:
echo "INSTANCE_IP=$(kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default -o jsonpath='{.status.primary.endpoint}')"
预期输出:
INSTANCE_IP=10.128.0.33
INSTANCE_IP 值是 AlloyDB Omni 集群的内部负载均衡器 IP。在此示例中,该网址为 10.131.0.33。
使用 SSH 连接到虚拟机实例:
gcloud compute ssh instance-1 --zone=$ZONE
在 instance-1 上的 SSH 会话中,安装 PostgreSQL 客户端:
sudo apt-get update && sudo apt-get install --yes postgresql-client
导出 AlloyDB Omni 负载均衡器 IP(替换为您的 PRIMARYENDPOINT IP):
export INSTANCE_IP=10.131.0.33
使用 psql 连接到 AlloyDB Omni(密码为 VeryStrongPassword):
psql "host=$INSTANCE_IP user=postgres sslmode=require"
在 psql 会话中,创建 demo 数据库:
CREATE DATABASE demo;
切换到 demo 数据库:
\c demo
创建转换函数
自定义嵌入端点需要输入和输出转换函数,以便在 AlloyDB Omni 和模型 API 之间调整数据格式。
创建输入转换函数:
CREATE OR REPLACE FUNCTION tei_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
transformed_input JSON;
BEGIN
SELECT json_build_object('inputs', input_text, 'truncate', true)::JSON INTO transformed_input;
RETURN transformed_input;
END;
$$;
预期输出:
demo=# CREATE OR REPLACE FUNCTION tei_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
transformed_input JSON;
BEGIN
SELECT json_build_object('inputs', input_text, 'truncate', true)::JSON INTO transformed_input;
RETURN transformed_input;
END;
$$;
CREATE FUNCTION
demo=#
创建输出转换函数,以解析向量数组响应:
CREATE OR REPLACE FUNCTION tei_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;
$$;
预期输出:
demo=# CREATE OR REPLACE FUNCTION tei_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; $$; CREATE FUNCTION demo=#
注册模型
使用 google_ml.create_model 过程在 AlloyDB Omni 中注册模型。将 http://tei-service:8080/embed 指定为 model_request_url,以将请求路由到 Kubernetes 集群服务:
CALL
google_ml.create_model(
model_id => 'embeddinggemma',
model_request_url => 'http://tei-service:8080/embed',
model_provider => 'custom',
model_type => 'text_embedding',
model_in_transform_fn => 'tei_text_input_transform',
model_out_transform_fn => 'tei_text_output_transform');
预期输出:
demo=# CALL
google_ml.create_model(
model_id => 'embeddinggemma',
model_request_url => 'http://tei-service:8080/embed',
model_provider => 'custom',
model_type => 'text_embedding',
model_in_transform_fn => 'tei_text_input_transform',
model_out_transform_fn => 'tei_text_output_transform');
CALL
demo=#
使用示例 SQL 查询测试已注册的模型:
SELECT google_ml.embedding('embeddinggemma', 'What is AlloyDB Omni?');
该函数会返回由在 GKE 上运行的本地 EmbeddingGemma 模型生成的实数数组表示法。
按 q 可返回到 psql 会话提示。
退出 psql 会话:
\q
7. 使用示例数据测试模型
加载示例数据
本教程使用 Cymbal 零售数据集来演示向量相似度搜索。您将使用 Google Cloud SDK 和 PostgreSQL 客户端将数据导入 AlloyDB Omni。
在 instance-1 上的 SSH 会话中,连接到演示数据库并启用 vector 扩展程序:
psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"
在 psql 会话中:
CREATE EXTENSION IF NOT EXISTS vector;
退出 psql 会话:
\q
下载架构并将其应用于 demo 数据库,以创建表:
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=demo"
预期输出:
student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=demo" Password for user postgres: SET SET SET SET SET set_config ------------ (1 row) SET SET SET SET SET SET CREATE TABLE ALTER TABLE CREATE TABLE ALTER TABLE CREATE TABLE ALTER TABLE CREATE TABLE ALTER TABLE CREATE SEQUENCE ALTER TABLE ALTER SEQUENCE ALTER TABLE ALTER TABLE ALTER TABLE student@cloudshell:~$
验证创建的表:
psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\dt+"
预期输出:
student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\dt+"
Password for user postgres:
List of relations
Schema | Name | Type | Owner | Persistence | Access method | Size | Description
--------+------------------+-------+----------+-------------+---------------+------------+-------------
public | cymbal_embedding | table | postgres | permanent | heap | 8192 bytes |
public | cymbal_inventory | table | postgres | permanent | heap | 8192 bytes |
public | cymbal_products | table | postgres | permanent | heap | 8192 bytes |
public | cymbal_stores | table | postgres | permanent | heap | 8192 bytes |
(4 rows)
将数据加载到 cymbal_products 表中:
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_products from stdin csv header"
预期输出:
student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_products from stdin csv header" COPY 941 student@cloudshell:~$
以下是 cymbal_products 表中的几行示例。
psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT uniq_id,left(product_name,30),left(product_description,50),sale_price FROM cymbal_products limit 3"
预期输出:
student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT uniq_id,left(product_name,30),left(product_description,50),sale_price FROM cymbal_products limit 3"
Password for user postgres:
uniq_id | left | left | sale_price
----------------------------------+--------------------------------+----------------------------------------------------+------------
a73d5f754f225ecb9fdc64232a57bc37 | Laundry Tub Strainer Cup | Laundry tub strainer cup Chrome For 1-.50, drain | 11.74
41b8993891aa7d39352f092ace8f3a86 | LED Starry Star Night Light La | LED Starry Star Night Light Laser Projector 3D Oc | 46.97
ed4a5c1b02990a1bebec908d416fe801 | Surya Horizon HRZ-1060 Area Ru | The 100% polypropylene construction of the Surya | 77.4
(3 rows)
student@cloudshell:~$
将数据加载到 cymbal_inventory 表中:
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_inventory from stdin csv header"
预期输出:
student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_inventory from stdin csv header" Password for user postgres: COPY 263861 student@cloudshell:~$
以下是 cymbal_inventory 表中的几行示例。
psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT * FROM cymbal_inventory LIMIT 3"
输出:
student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT * FROM cymbal_inventory LIMIT 3"
Password for user postgres:
store_id | uniq_id | inventory
----------+----------------------------------+-----------
1583 | adc4964a6138d1148b1d98c557546695 | 5
1490 | adc4964a6138d1148b1d98c557546695 | 4
1492 | adc4964a6138d1148b1d98c557546695 | 3
(3 rows)
student@cloudshell:~$
将数据加载到 cymbal_stores 表中:
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_stores from stdin csv header"
预期的控制台输出:
student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_stores from stdin csv header" Password for user postgres: COPY 4654 student@cloudshell:~$
以下是 cymbal_stores 表中的几行示例。
psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT store_id, name, zip_code FROM cymbal_stores limit 3"
输出:
student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT store_id, name, zip_code FROM cymbal_stores limit 3"
Password for user postgres:
store_id | name | zip_code
----------+-------------------+----------
1990 | Mayaguez Store | 680
2267 | Ware Supercenter | 1082
4359 | Ponce Supercenter | 780
(3 rows)
student@cloudshell:~$
构建嵌入
使用 psql 连接到演示数据库,并根据 cymbal_products 表中描述的产品说明为这些产品构建嵌入。
连接到演示数据库:
psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"
使用 vector 类型的 embedding 列来存储为商品说明生成的文本嵌入。
启用查询计时:
\timing
为每个商品说明生成嵌入,并将其存储在 cymbal_embedding 表中:
INSERT INTO cymbal_embedding (uniq_id, embedding)
SELECT uniq_id, google_ml.embedding('embeddinggemma', product_description)::vector
FROM cymbal_products;
预期输出:
demo=# INSERT INTO cymbal_embedding(uniq_id,embedding) SELECT uniq_id, google_ml.embedding('embeddinggemma',product_description)::vector FROM cymbal_products;
INSERT 0 941
Time: 497878.136 ms (08:17.878)
demo=#
运行语义搜索查询
在 psql 会话中,使用余弦距离 (<=>) 找出与问题 "What kind of fruit trees grow well here?" 最匹配的前五款商品:
SELECT
cp.product_name,
left(cp.product_description, 80) AS description,
cp.sale_price,
cs.zip_code,
(ce.embedding <=> google_ml.embedding('embeddinggemma', 'What kind of fruit trees grow well here?')::vector) AS distance
FROM
cymbal_products cp
JOIN cymbal_embedding ce ON ce.uniq_id = cp.uniq_id
JOIN cymbal_inventory ci ON ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON cs.store_id = ci.store_id
WHERE
ci.inventory > 0
AND cs.store_id = 1583
ORDER BY
distance ASC
LIMIT 5;
预期输出:
demo=# SELECT
cp.product_name,
left(cp.product_description,80) as description,
cp.sale_price,
cs.zip_code,
(ce.embedding <=> google_ml.embedding('embeddinggemma','What kind of fruit trees grow well here?')::vector) as distance
FROM
cymbal_products cp
JOIN cymbal_embedding ce on ce.uniq_id=cp.uniq_id
JOIN cymbal_inventory ci on ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on cs.store_id=ci.store_id
WHERE
ci.inventory > 0
AND cs.store_id = 1583
ORDER BY
distance ASC
LIMIT 5;
product_name | description | sale_price | zip_code | distance
-----------------------+----------------------------------------------------------------------------------+------------+----------+--------------------
Cherry Tree | This is a beautiful cherry tree that will produce delicious cherries. It is an d | 75.00 | 93230 | 0.5210549378080666
California Lilac | This is a beautiful lilac tree that can grow to be over 10 feet tall. It is an d | 5.00 | 93230 | 0.5639421771781971
Toyon | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e | 10.00 | 93230 | 0.5670010914504852
Rose Bush | This is a beautiful rose bush that will produce fragrant roses. It is a perennia | 50.00 | 93230 | 0.5731542622882957
California Peppertree | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e | 25.00 | 93230 | 0.5750934653011995
(5 rows)
Time: 83.610 ms
demo=#
查询运行了 83 毫秒,并返回了 cymbal_products 表中符合请求且在 1583 号商店中有库存的树木列表。
构建 ANN 索引
如果数据集较小,则可以轻松使用精确搜索来扫描所有嵌入,但当数据量增加时,加载和响应时间也会增加。为了提高性能,您可以基于嵌入数据构建索引。以下示例展示了如何使用 Google ScaNN 索引处理向量数据。
如果您断开了与演示数据库的连接,请重新连接:
psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"
启用 alloydb_scann 扩展程序:
CREATE EXTENSION IF NOT EXISTS alloydb_scann;
在 embedding 列上创建 ScaNN 索引:
CREATE INDEX cymbal_products_embeddings_scann ON cymbal_embedding
USING scann (embedding cosine)
WITH (num_leaves=10, max_num_levels = 1);
重新运行语义搜索查询,以比较执行性能:
SELECT
cp.product_name,
left(cp.product_description, 80) AS description,
cp.sale_price,
cs.zip_code,
(ce.embedding <=> google_ml.embedding('embeddinggemma', 'What kind of fruit trees grow well here?')::vector) AS distance
FROM
cymbal_products cp
JOIN cymbal_embedding ce ON ce.uniq_id = cp.uniq_id
JOIN cymbal_inventory ci ON ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON cs.store_id = ci.store_id
WHERE
ci.inventory > 0
AND cs.store_id = 1583
ORDER BY
distance ASC
LIMIT 5;
预期输出:
demo=# SELECT
cp.product_name,
left(cp.product_description,80) as description,
cp.sale_price,
cs.zip_code,
(ce.embedding <=> google_ml.embedding('embeddinggemma', 'What kind of fruit trees grow well here?')::vector) AS distance
FROM
cymbal_products cp
JOIN cymbal_embedding ce ON ce.uniq_id = cp.uniq_id
JOIN cymbal_inventory ci ON ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON cs.store_id = ci.store_id
WHERE
ci.inventory > 0
AND cs.store_id = 1583
ORDER BY
distance ASC
LIMIT 5;
product_name | description | sale_price | zip_code | distance
-----------------------+----------------------------------------------------------------------------------+------------+----------+--------------------
Cherry Tree | This is a beautiful cherry tree that will produce delicious cherries. It is an d | 75.00 | 93230 | 0.5210549378080666
California Lilac | This is a beautiful lilac tree that can grow to be over 10 feet tall. It is an d | 5.00 | 93230 | 0.5639421771781971
Toyon | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e | 10.00 | 93230 | 0.5670010914504852
Rose Bush | This is a beautiful rose bush that will produce fragrant roses. It is a perennia | 50.00 | 93230 | 0.5731542622882957
California Peppertree | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e | 25.00 | 93230 | 0.5750934653011995
(5 rows)
Time: 64.783 ms
查询执行时间略有缩短,在数据集较大时,提升效果会更加明显。返回的数据应与我们在没有索引的情况下获得的数据相同或非常相似。
尝试其他查询,并参阅文档,详细了解如何优化向量索引。
退出 psql 会话:
\q
按 Ctrl+D 或输入 exit,断开与 instance-1 SSH 会话的连接,返回 Google Cloud Shell。
8. 使用 vLLM 部署 Gemma
为 Gemma 添加节点池
首先,查看您所在区域有哪些节点类型可用:
gcloud compute accelerator-types list --filter="zone:${LOCATION}"
您应该会看到可用加速器类型的列表,其中包括 nvidia-l4 加速器。
使用 vLLM 为 Google Gemini 4 12B 模型创建部署清单:
cat << 'EOF' > gemma-12b-gpu-vllm-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: gemma-12b-gpu-vllm-deployment
spec:
replicas: 1
selector:
matchLabels:
app: gemma-12b-gpu-vllm
template:
metadata:
labels:
app: gemma-12b-gpu-vllm
ai.gke.io/model: gemma-4-12b-it
ai.gke.io/inference-server: vllm
examples.ai.gke.io/source: user-guide
spec:
containers:
- name: inference-server
image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:latest
resources:
requests:
cpu: "4"
memory: "16Gi"
ephemeral-storage: "30Gi"
nvidia.com/gpu: "1"
limits:
cpu: "8"
memory: "24Gi"
ephemeral-storage: "30Gi"
nvidia.com/gpu: "1"
command: ["python3", "-m", "vllm.entrypoints.api_server"]
args:
- --model=$(MODEL_ID)
- --host=0.0.0.0
- --port=8000
- --tensor-parallel-size=1
- --enable-log-requests
- --enable-chunked-prefill
- --enable-prefix-caching
- --enable-auto-tool-choice
- --generation-config=auto
- --tool-call-parser=gemma4
- --dtype=bfloat16
- --max-num-seqs=16
- --max-model-len=32768
- --gpu-memory-utilization=0.95
- --reasoning-parser=gemma4
- --trust-remote-code
- --quantization=fp8
env:
- name: LD_LIBRARY_PATH
value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
- name: MODEL_ID
value: google/gemma-4-12b-it
- name: HF_TOKEN
valueFrom:
secretKeyRef:
name: hf-secret
key: hf_api_token
volumeMounts:
- mountPath: /dev/shm
name: dshm
volumes:
- name: dshm
emptyDir:
medium: Memory
nodeSelector:
cloud.google.com/gke-accelerator: nvidia-l4
cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
name: gemma-12b-gpu-vllm-service
spec:
selector:
app: gemma-12b-gpu-vllm
type: ClusterIP
ports:
- protocol: TCP
port: 8000
targetPort: 8000
EOF
应用保存的 gemma-12b-gpu-vllm-deployment.yaml 部署:
kubectl apply -f gemma-12b-gpu-vllm-deployment.yaml
预期输出:
$ kubectl apply -f gemma-12b-gpu-vllm-deployment.yaml deployment.apps/gemma-12b-gpu-vllm-deployment created service/gemma-12b-gpu-vllm-service created
等待部署完成并加载模型。这可能需要几分钟时间。
printf "Waiting for model to load..."; until kubectl logs -l app=gemma-12b-gpu-vllm --tail=50 2>/dev/null | grep -q "Application startup complete"; do printf "."; sleep 3; done; printf '\n\033[1;32m========================================\n[SUCCESS] Model is loaded and ready!\nYou can now proceed to the next step.\n========================================\033[0m\n'
预期输出:
Waiting for model to load... ======================================== [SUCCESS] Model is loaded and ready! You can now proceed to the next step. ========================================
测试模型。启用端口转发以访问模型:
kubectl port-forward svc/gemma-12b-gpu-vllm-service 8090:8000
在另一个终端窗口中,使用 curl 向模型发送提示:
curl http://localhost:8090/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "system", "content": "You are a helpful assistant running on GKE."},
{"role": "user", "content": "What is AlloyDB Omni."}
],
"temperature": 0.7
}' | jq -r '.choices[0].message.content'
预期输出:
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 3957 100 3761 100 196 85 4 0:00:49 0:00:43 0:00:06 830
**AlloyDB Omni** is a fully managed, PostgreSQL-compatible database engine from Google Cloud that can be run **on-premises, in other clouds, or in your own data centers.**
To understand it simply: It allows you to run the high-performance, enterprise-grade capabilities of Google's **AlloyDB** (a cloud-native database) on your own infrastructure.
Here is a breakdown of what makes it significant:
### 1. The "Best of Both Worlds" Architecture
Normally, you have to choose between:
* **Managed Cloud Databases:** Easy to scale and manage, but you are locked into the cloud provider's infrastructure.
* **Self-Managed Databases:** You have full control over the hardware/location, but you are responsible for scaling, patching, and high availability.
**AlloyDB Omni** bridges this gap. It provides the advanced features of a cloud-native database (like intelligent indexing, high availability, and massive scalability) while allowing you to run it anywhere.
在第一个终端中,按 Ctrl+C 停止端口转发(如果仍在运行)。
9. 在 AlloyDB Omni 中注册 Gemma 4 模型
使用 google_ml.create_model 过程在 AlloyDB Omni 中注册 Gemma 12B 模型。将 http://gemma-12b-gpu-vllm-service:8000/v1/chat/completions 指定为 model_request_url,以将请求路由到 Kubernetes 集群服务:
检索 AlloyDB Omni 端点 IP:
echo "INSTANCE_IP=$(kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default -o jsonpath='{.status.primary.endpoint}')"
使用 SSH 连接到虚拟机实例:
gcloud compute ssh instance-1 --zone=$ZONE
连接到虚拟机后,导出上一步中的 INSTANCE_IP 变量(10.128.0.33 值仅作为示例,请将其替换为您的 IP):
export INSTANCE_IP=10.128.0.33
导出 AlloyDB 密码:
export PGPASSWORD=VeryStrongPassword
连接到 demo 数据库:
psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"
在 psql 会话中注册模型:
CALL
google_ml.create_model(
model_id => 'gemma-12b-gpu',
model_request_url => 'http://gemma-12b-gpu-vllm-service:8000/v1/chat/completions',
model_provider => 'custom',
model_type => 'llm');
使用示例 SQL 查询测试模型:
SELECT google_ml.predict_row(
model_id => 'gemma-12b-gpu',
request_body => json_build_object(
'messages', json_build_array(
json_build_object('role', 'user', 'content', 'What is AlloyDB Omni?'))))->'choices'->0->'message'->'content';
按 q 退出结果窗口,返回 psql 提示
在 AlloyDB Omni 中将 Vector Search 与 LLM RAG 结合使用
将 Vector Search 与 LLM 请求结合使用,以演示 LLM 的 RAG(检索增强生成)。
在 plsql 中运行 SQL 查询:
WITH trees AS (
SELECT
cp.product_name,
cp.product_description AS description,
cp.sale_price,
cs.zip_code,
cp.uniq_id AS product_id
FROM
cymbal_products cp
JOIN cymbal_embedding ce ON ce.uniq_id = cp.uniq_id
JOIN cymbal_inventory ci ON ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON cs.store_id = ci.store_id
WHERE
ci.inventory>0
AND cs.store_id = 1583
ORDER BY
(ce.embedding <=> embedding('embeddinggemma',
'What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1),
prompt AS (
SELECT
'You are a friendly advisor helping to find a product based on the customer''s needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","product_description":"some description","sale_price":10}
Here is the list of products:' || json_agg(trees) || 'The customer asked "What kind of fruit trees grow well here?"
You should give information about the product, price and some supplemental information' AS prompt_text
FROM
trees),
response AS (
SELECT
google_ml.predict_row(
model_id =>'gemma-12b-gpu',
request_body => json_build_object(
'messages', json_build_array(
json_build_object('role', 'user', 'content',prompt_text)
)))->'choices'->0->'message'->'content' AS resp
FROM
prompt)
SELECT
REPLACE(resp::text, '\n', CHR(10))
FROM
response;
预期输出:
----------------------------------------------------------------------------------------------------------------------------------------------
"Hello there! I'd be happy to help you find the perfect tree for your garden. +
+
Based on your location, we have a wonderful option that would grow beautifully in your area: +
+
**Cherry Tree** +
* **Price:** $75.00 +
* **Description:** This is a stunning deciduous tree that not only provides a beautiful landscape but also produces delicious cherries. +
* **Supplemental Information:** +
* **Growth:** It grows to about 15 feet tall. +
* **Appearance:** You can look forward to dark green leaves in the summer that transform into a vibrant red in the fall. +
* **Benefits:** It's a great choice if you're looking for both fruit and extra shade or privacy in your yard. +
* **Care Tips:** It performs best in a cool, moist climate with sandy soil. Since you are in a suitable zone, it should thrive nicely!+
+
Would you like more details on how to plant this, or would you like to proceed with an order?"
(1 row)
该查询会通过向量搜索结果来补充 LLM 的提示。
尝试其他查询并试验 RAG 模式。所呈现架构的优势在于其完全自给自足。数据不会发送到集群外部,并且可以在完全隔离的环境中运行。
退出psql会话:
\q
断开与虚拟机的 SSH 会话:
exit
别忘了,AlloyDB Omni 还有更多功能和实验。
10. 清理环境
为避免系统向您的 Google Cloud 账号持续收取费用,请删除此 Codelab 中创建的资源。
删除 GKE 集群
在 Cloud Shell 中,删除 GKE 集群:
export PROJECT_ID=$(gcloud config get-value project)
export CLUSTER_NAME=alloydb-ai-gke
gcloud container clusters delete ${CLUSTER_NAME} \
--project=${PROJECT_ID} \
--region=${LOCATION}
预期输出:
student@cloudshell:~$ gcloud container clusters delete ${CLUSTER_NAME} \
> --project=${PROJECT_ID} \
> --region=${LOCATION}
The following clusters will be deleted.
- [alloydb-ai-gke] in [us-east4]
Do you want to continue (Y/n)? Y
Deleting cluster alloydb-ai-gke...done.
Deleted
删除客户端虚拟机
在 Cloud Shell 中,删除 Compute Engine 实例:
export PROJECT_ID=$(gcloud config get-value project)
gcloud compute instances delete instance-1 \
--project=${PROJECT_ID} \
--zone=${ZONE}
预期输出:
student@cloudshell:~$ export PROJECT_ID=$(gcloud config get project)
export ZONE=us-east4-a
gcloud compute instances delete instance-1 \
--project=${PROJECT_ID} \
--zone=${ZONE}
Your active configuration is: [cloudshell-5399]
The following instances will be deleted. Any attached disks configured to be auto-deleted will be deleted unless they are attached to any other instances or the `--keep-disks` flag is given and specifies them for keeping. Deleting a disk
is irreversible and any data on the disk will be lost.
- [instance-1] in [us-east4-a]
Do you want to continue (Y/n)? Y
Deleted
如果您为此 Codelab 创建了一个新项目,则可以选择在 Google Cloud Resource Manager 中删除整个项目。
11. 恭喜
恭喜您完成此 Codelab!
所学内容
- 如何在 GKE 集群上部署 AlloyDB Omni
- 如何连接到 AlloyDB Omni
- 如何将数据加载到 AlloyDB Omni
- 如何将 AI 模型(嵌入和 LLM)部署到 GKE
- 如何在 AlloyDB Omni 中注册 AI 模型
- 如何为语义搜索生成嵌入
- 如何在 AlloyDB Omni 中运行语义搜索查询
- 如何在 AlloyDB Omni 中创建和使用向量索引
如需详细了解如何在 AlloyDB Omni 中使用 AI,请参阅文档。
调查问卷
输出: