Questo tutorial mostra come integrare un'applicazione basata su un modello linguistico di grandi dimensioni (LLM) con la generazione basata sul recupero (RAG) con i file PDF che carichi in un bucket Cloud Storage.
Questa guida utilizza un database come spazio di archiviazione e motore di ricerca semantica che contiene le rappresentazioni (gli embedding) dei documenti caricati. Utilizzi il framework Langchain per interagire con gli embedding e utilizzi i modelli Gemini disponibili tramite Vertex AI.
Langchain è un popolare framework Python open source che semplifica molte attività di machine learning e dispone di interfacce per l'integrazione con diversi database di vettori e servizi di AI.
Questo tutorial è rivolto a amministratori e architetti della piattaforma cloud, ingegneri ML e professionisti MLOps (DevOps) interessati a eseguire il deployment di applicazioni LLM RAG su GKE e Cloud Storage.
Obiettivi
In questo tutorial imparerai a:
- Crea e implementa un'applicazione per creare e archiviare gli embedding dei documenti in un database di vettori.
- Automatizzare l'applicazione per attivare il caricamento di nuovi documenti in un bucket Cloud Storage.
- Esegui il deployment di un'applicazione di chatbot che utilizza la ricerca semantica per rispondere alle domande in base ai contenuti del documento.
Architettura di deployment
In questo tutorial crei un bucket Cloud Storage, un attivatore Eventarc e i seguenti servizi:
embed-docs
: Eventarc attiva questo servizio ogni volta che un utente carica un nuovo documento nel bucket Cloud Storage. Il servizio avvia un job Kubernetes che crea gli embedding per il documento caricato e li inserisce in un database vettoriale.chatbot
: questo Servizio risponde a domande in linguaggio naturale sui documenti caricati utilizzando la ricerca semantica e l'API Gemini.
Il seguente diagramma mostra la procedura di caricamento e vettorizzazione dei documenti:
Nel diagramma, l'utente carica i file nel bucket Cloud Storage.
Eventarc si iscrive agli eventi metadataUpdated
degli oggetti per il
secchio e utilizza il forwarder di eventi di Eventarc, che è un workload
Kubernetes, per chiamare il servizio embed-docs
quando carichi un nuovo documento. Il servizio crea quindi gli incorporamenti per il documento caricato. Il embed-docs
servizio memorizza gli embedding in un database vettoriale utilizzando il
modello di embedding di Vertex AI.
Il seguente diagramma mostra la procedura per porre domande sui contenuti del documento caricato utilizzando il servizio chatbot
:
Gli utenti possono porre domande usando un linguaggio naturale e il chatbot genera risposte in base esclusivamente ai contenuti dei file caricati. Il chatbot recupera il contesto dal database vettoriale utilizzando la ricerca semantica, quindi invia la domanda e il contesto a Gemini.
Costi
In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi in base all'utilizzo previsto,
utilizza il Calcolatore prezzi.
Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.
Prima di iniziare
In questo tutorial utilizzerai Cloud Shell per eseguire comandi. Cloud Shell è un ambiente shell per la gestione delle risorse ospitate su Google Cloud. Cloud Shell include gli strumenti a riga di comando Google Cloud CLI, kubectl e Terraform preinstallati. Se non utilizzi Cloud Shell, installa Google Cloud CLI.
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI, Cloud Build, Eventarc, Artifact Registry APIs:
gcloud services enable aiplatform.googleapis.com
cloudbuild.googleapis.com eventarc.googleapis.com artifactregistry.googleapis.com - Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI, Cloud Build, Eventarc, Artifact Registry APIs:
gcloud services enable aiplatform.googleapis.com
cloudbuild.googleapis.com eventarc.googleapis.com artifactregistry.googleapis.com -
Grant roles to your user account. Run the following command once for each of the following IAM roles:
eventarc.admin
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
Crea un cluster
Crea un cluster Qdrant, Elasticsearch o Postgres:
Qdrant
Segui le istruzioni riportate in Eseguire il deployment di un database di vettori Qdrant su GKE per creare un cluster Qdrant in esecuzione in un cluster GKE in modalità Autopilot o in modalità Standard.
Elasticsearch
Segui le istruzioni riportate in Eseguire il deployment di un database di vettori Elasticsearch su GKE per creare un cluster Elasticsearch in esecuzione su un cluster GKE in modalità Autopilot o Standard.
PGVector
Segui le istruzioni riportate in Eseguire il deployment di un database vettoriale PostgreSQL su GKE per creare un cluster Postgres con PGVector in esecuzione su un cluster GKE in modalità Autopilot o Standard.
Weaviate
Segui le istruzioni per eseguire il deployment di un database di vettori Weaviate su GKE per creare un cluster Weaviate in esecuzione su un cluster GKE in modalità Autopilot o Standard.
Configura l'ambiente
Configura l'ambiente con Cloud Shell:
Imposta le variabili di ambiente per il progetto:
Qdrant
export PROJECT_ID=PROJECT_ID export KUBERNETES_CLUSTER_PREFIX=qdrant export REGION=us-central1 export DB_NAMESPACE=qdrant
Sostituisci
PROJECT_ID
con il tuo ID progetto Google Cloud.Elasticsearch
export PROJECT_ID=PROJECT_ID export KUBERNETES_CLUSTER_PREFIX=elasticsearch export REGION=us-central1 export DB_NAMESPACE=elastic
Sostituisci
PROJECT_ID
con il tuo ID progetto Google Cloud.PGVector
export PROJECT_ID=PROJECT_ID export KUBERNETES_CLUSTER_PREFIX=postgres export REGION=us-central1 export DB_NAMESPACE=pg-ns
Sostituisci
PROJECT_ID
con il tuo ID progetto Google Cloud.Weaviate
export PROJECT_ID=PROJECT_ID export KUBERNETES_CLUSTER_PREFIX=weaviate export REGION=us-central1 export DB_NAMESPACE=weaviate
Sostituisci
PROJECT_ID
con il tuo ID progetto Google Cloud.Verifica che il cluster GKE sia in esecuzione:
gcloud container clusters list --project=${PROJECT_ID} --region=${REGION}
L'output è simile al seguente:
NAME LOCATION MASTER_VERSION MASTER_IP MACHINE_TYPE NODE_VERSION NUM_NODES STATUS [KUBERNETES_CLUSTER_PREFIX]-cluster us-central1 1.30.1-gke.1329003 <EXTERNAL IP> e2-standard-2 1.30.1-gke.1329003 6 RUNNING
Clona il repository di codice campione da GitHub:
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
Vai alla directory
databases
:cd kubernetes-engine-samples/databases
Prepara l'infrastruttura
Crea un repository Artifact Registry, crea immagini Docker ed esegui il push delle immagini Docker in Artifact Registry:
Crea un repository Artifact Registry:
gcloud artifacts repositories create ${KUBERNETES_CLUSTER_PREFIX}-images \ --repository-format=docker \ --location=${REGION} \ --description="Vector database images repository" \ --async
Imposta le autorizzazioni
storage.objectAdmin
eartifactregistry.admin
sull'account di servizio Compute Engine per utilizzare Cloud Build per creare ed eseguire il push di immagini Docker per i serviziembed-docs
echatbot
.export PROJECT_NUMBER=PROJECT_NUMBER gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ --role="roles/storage.objectAdmin" gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ --role="roles/artifactregistry.admin"
Sostituisci
PROJECT_NUMBER
con il numero del tuo progetto Google Cloud.Crea immagini Docker per i servizi
embed-docs
echatbot
. L'immagineembed-docs
contiene il codice Python sia per l'applicazione che riceve le richieste del forwarder Eventarc sia per il job di incorporamento.Qdrant
export DOCKER_REPO="${REGION}-docker.pkg.dev/${PROJECT_ID}/${KUBERNETES_CLUSTER_PREFIX}-images" gcloud builds submit qdrant/docker/chatbot --region=${REGION} \ --tag ${DOCKER_REPO}/chatbot:1.0 --async gcloud builds submit qdrant/docker/embed-docs --region=${REGION} \ --tag ${DOCKER_REPO}/embed-docs:1.0 --async
Elasticsearch
export DOCKER_REPO="${REGION}-docker.pkg.dev/${PROJECT_ID}/${KUBERNETES_CLUSTER_PREFIX}-images" gcloud builds submit elasticsearch/docker/chatbot --region=${REGION} \ --tag ${DOCKER_REPO}/chatbot:1.0 --async gcloud builds submit elasticsearch/docker/embed-docs --region=${REGION} \ --tag ${DOCKER_REPO}/embed-docs:1.0 --async
PGVector
export DOCKER_REPO="${REGION}-docker.pkg.dev/${PROJECT_ID}/${KUBERNETES_CLUSTER_PREFIX}-images" gcloud builds submit postgres-pgvector/docker/chatbot --region=${REGION} \ --tag ${DOCKER_REPO}/chatbot:1.0 --async gcloud builds submit postgres-pgvector/docker/embed-docs --region=${REGION} \ --tag ${DOCKER_REPO}/embed-docs:1.0 --async
Weaviate
export DOCKER_REPO="${REGION}-docker.pkg.dev/${PROJECT_ID}/${KUBERNETES_CLUSTER_PREFIX}-images" gcloud builds submit weaviate/docker/chatbot --region=${REGION} \ --tag ${DOCKER_REPO}/chatbot:1.0 --async gcloud builds submit weaviate/docker/embed-docs --region=${REGION} \ --tag ${DOCKER_REPO}/embed-docs:1.0 --async
Verifica le immagini:
gcloud artifacts docker images list $DOCKER_REPO \ --project=$PROJECT_ID \ --format="value(IMAGE)"
L'output è simile al seguente:
$REGION-docker.pkg.dev/$PROJECT_ID/${KUBERNETES_CLUSTER_PREFIX}-images/chatbot $REGION-docker.pkg.dev/$PROJECT_ID/${KUBERNETES_CLUSTER_PREFIX}-images/embed-docs
Esegui il deployment di un account di servizio Kubernetes con le autorizzazioni per eseguire job Kubernetes:
Qdrant
sed "s/<PROJECT_ID>/$PROJECT_ID/;s/<CLUSTER_PREFIX>/$KUBERNETES_CLUSTER_PREFIX/" qdrant/manifests/05-rag/service-account.yaml | kubectl -n qdrant apply -f -
Elasticsearch
sed "s/<PROJECT_ID>/$PROJECT_ID/;s/<CLUSTER_PREFIX>/$KUBERNETES_CLUSTER_PREFIX/" elasticsearch/manifests/05-rag/service-account.yaml | kubectl -n elastic apply -f -
PGVector
sed "s/<PROJECT_ID>/$PROJECT_ID/;s/<CLUSTER_PREFIX>/$KUBERNETES_CLUSTER_PREFIX/" postgres-pgvector/manifests/03-rag/service-account.yaml | kubectl -n pg-ns apply -f -
Weaviate
sed "s/<PROJECT_ID>/$PROJECT_ID/;s/<CLUSTER_PREFIX>/$KUBERNETES_CLUSTER_PREFIX/" weaviate/manifests/04-rag/service-account.yaml | kubectl -n weaviate apply -f -
Quando utilizzi Terraform per creare il cluster GKE e hai impostato
create_service_account
su true, verrà creato e utilizzato un account di servizio separato dal cluster e dai nodi. Concedi il ruoloartifactregistry.serviceAgent
a questo account di servizio Compute Engine per consentire ai nodi di estrarre l'immagine dall'Artifact Registry creato perembed-docs
echatbot
.export CLUSTER_SERVICE_ACCOUNT=$(gcloud container clusters describe ${KUBERNETES_CLUSTER_PREFIX}-cluster \ --region=${REGION} \ --format="value(nodeConfig.serviceAccount)") gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:${CLUSTER_SERVICE_ACCOUNT}" \ --role="roles/artifactregistry.serviceAgent"
Se non concedi l'accesso all'account di servizio, i tuoi nodi potrebbero riscontrare un problema di autorizzazione quando tentano di estrarre l'immagine da Artifact Registry durante il deployment dei servizi
embed-docs
echatbot
.Esegui il deployment di un deployment Kubernetes per i servizi
embed-docs
echatbot
:Qdrant
sed "s|<DOCKER_REPO>|$DOCKER_REPO|" qdrant/manifests/05-rag/chatbot.yaml | kubectl -n qdrant apply -f - sed "s|<DOCKER_REPO>|$DOCKER_REPO|" qdrant/manifests/05-rag/docs-embedder.yaml | kubectl -n qdrant apply -f -
Elasticsearch
sed "s|<DOCKER_REPO>|$DOCKER_REPO|" elasticsearch/manifests/05-rag/chatbot.yaml | kubectl -n elastic apply -f - sed "s|<DOCKER_REPO>|$DOCKER_REPO|" elasticsearch/manifests/05-rag/docs-embedder.yaml | kubectl -n elastic apply -f -
PGVector
sed "s|<DOCKER_REPO>|$DOCKER_REPO|" postgres-pgvector/manifests/03-rag/chatbot.yaml | kubectl -n pg-ns apply -f - sed "s|<DOCKER_REPO>|$DOCKER_REPO|" postgres-pgvector/manifests/03-rag/docs-embedder.yaml | kubectl -n pg-ns apply -f -
Weaviate
sed "s|<DOCKER_REPO>|$DOCKER_REPO|" weaviate/manifests/04-rag/chatbot.yaml | kubectl -n weaviate apply -f - sed "s|<DOCKER_REPO>|$DOCKER_REPO|" weaviate/manifests/04-rag/docs-embedder.yaml | kubectl -n weaviate apply -f -
Abilita gli trigger Eventarc per GKE:
gcloud eventarc gke-destinations init
Quando richiesto, inserisci
y
.Esegui il deployment del bucket Cloud Storage e crea un attivatore Eventarc utilizzando Terraform:
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token) terraform -chdir=vector-database/terraform/cloud-storage init terraform -chdir=vector-database/terraform/cloud-storage apply \ -var project_id=${PROJECT_ID} \ -var region=${REGION} \ -var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX} \ -var db_namespace=${DB_NAMESPACE}
Quando richiesto, digita
yes
. Il completamento del comando potrebbe richiedere diversi minuti.Terraform crea le seguenti risorse:
- Un bucket Cloud Storage per caricare i documenti
- Un trigger Eventarc
- Un account di servizio Google Cloud denominato
service_account_eventarc_name
con l'autorizzazione per utilizzare Eventarc. - Un account di servizio Google Cloud denominato
service_account_bucket_name
con l'autorizzazione a leggere il bucket e accedere ai modelli Vertex AI.
L'output è simile al seguente:
... # Several lines of output omitted Apply complete! Resources: 15 added, 0 changed, 0 destroyed. ... # Several lines of output omitted
Carica documenti ed esegui query sul chatbot
Carica i documenti di esempio ed esegui query per eseguire ricerche tra i documenti di esempio utilizzando il chatbot:
Carica il documento di esempio
carbon-free-energy.pdf
nel bucket:gsutil cp vector-database/documents/carbon-free-energy.pdf gs://${PROJECT_ID}-${KUBERNETES_CLUSTER_PREFIX}-training-docs
Verifica che il job di incorporamento del documento sia stato completato correttamente:
kubectl get job -n ${DB_NAMESPACE}
L'output è simile al seguente:
NAME COMPLETIONS DURATION AGE docs-embedder1716570453361446 1/1 32s 71s
Recupera l'indirizzo IP esterno del bilanciatore del carico:
export EXTERNAL_IP=$(kubectl -n ${DB_NAMESPACE} get svc chatbot --output jsonpath='{.status.loadBalancer.ingress[0].ip}') echo http://${EXTERNAL_IP}:80
Apri l'indirizzo IP esterno nel browser web:
http://EXTERNAL_IP
Il chatbot risponde con un messaggio simile al seguente:
How can I help you?
Fai domande sui contenuti dei documenti caricati. Se il chatbot non riesce a trovare nulla, risponde
I don't know
. Ad esempio, potresti chiedere quanto segue:You: Hi, what are Google plans for the future?
Un esempio di output del chatbot è simile al seguente:
Bot: Google intends to run on carbon-free energy everywhere, at all times by 2030. To achieve this, it will rely on a combination of renewable energy sources, such as wind and solar, and carbon-free technologies, such as battery storage.
Fai al chatbot una domanda che non è nel contesto del documento caricato. Ad esempio, potresti chiedere quanto segue:
You: What are Google plans to colonize Mars?
Un esempio di output del chatbot è simile al seguente:
Bot: I don't know. The provided context does not mention anything about Google's plans to colonize Mars.
Informazioni sul codice dell'applicazione
Questa sezione spiega come funziona il codice dell'applicazione. All'interno delle immagini Docker sono presenti tre script:
endpoint.py
: riceve gli eventi Eventarc a ogni caricamento del documento e avvia i job Kubernetes per elaborarli.embedding-job.py
: scarica i documenti dal bucket, crea gli embedding e li inserisce nel database di vettori.chat.py
: esegue query sui contenuti dei documenti archiviati.
Il diagramma mostra il processo di generazione delle risposte utilizzando i dati dei documenti:
Nel diagramma, l'applicazione carica un file PDF, lo suddivide in blocchi, poi in vettori e li invia a un database di vettori. In seguito, un utente pone una domanda al chatbot. La catena RAG utilizza la ricerca semantica per eseguire ricerche nel database vettoriale, quindi restituisce il contesto insieme alla domanda all'LLM. L'LLM risponde alla domanda e la memorizza nella cronologia della chat.
Informazioni su endpoint.py
Questo file elabora i messaggi di Eventarc, crea un job Kubernetes per incorporare il documento e accetta richieste da qualsiasi luogo sulla porta 5001
Qdrant
Elasticsearch
PGVector
Weaviate
Informazioni su embedding-job.py
Questo file elabora i documenti e li invia al database di vettori.
Qdrant
Elasticsearch
PGVector
Weaviate
Informazioni su chat.py
Questo file configura il modello in modo che risponda alle domande utilizzando solo il contesto fornito e le risposte precedenti. Se il contesto o la cronologia della conversazione non corrisponde a nessun dato, il modello restituisce I don't know
.
Qdrant
Elasticsearch
PGVector
Weaviate
Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
Elimina il progetto
Il modo più semplice per evitare la fatturazione è eliminare il progetto che hai creato per questo tutorial.
Delete a Google Cloud project:
gcloud projects delete PROJECT_ID
Se hai eliminato il progetto, la pulizia è completata. Se non hai eliminato il progetto, procedi con l'eliminazione delle singole risorse.
Elimina singole risorse
Elimina il repository Artifact Registry:
gcloud artifacts repositories delete ${KUBERNETES_CLUSTER_PREFIX}-images \ --location=${REGION} \ --async
Quando richiesto, digita
y
.Elimina il bucket Cloud Storage e l'attivatore Eventarc:
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token) terraform -chdir=vector-database/terraform/cloud-storage destroy \ -var project_id=${PROJECT_ID} \ -var region=${REGION} \ -var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX} \ -var db_namespace=${DB_NAMESPACE}
Quando richiesto, digita
yes
.Eventarc richiede un endpoint di destinazione valido sia durante la creazione sia durante l'eliminazione.
Passaggi successivi
- Scopri le best practice per il deployment dei database su GKE.
- Scopri le soluzioni per eseguire carichi di lavoro con utilizzo intensivo di dati con GKE.