Gestire i set di contesto in AlloyDB Studio

Anteprima

Queste funzionalità sono ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici e ai Termini aggiuntivi per i prodotti in anteprima dell'AI generativa. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Quando utilizzi l'agente di progettazione del contesto, questo può creare e caricare automaticamente i set di contesti dalla tua interfaccia a riga di comando. Questo documento descrive come creare, modificare ed eliminare i set di contesto in AlloyDB per PostgreSQL Studio quando vuoi un'interfaccia visiva nella console Google Cloud per gestire i file dei set di contesto. Quando crei un set di contesto in AlloyDB Studio, questo lo archivia nel gruppo di set di contesto default del progetto per la regione selezionata e lo collega al database corrente. I nomi dei set di contesto (e i relativi ID dei set di contesto derivati) devono essere univoci all'interno del gruppo di set di contesto default del progetto per una determinata regione, in tutti i database e le istanze. In AlloyDB Studio, la creazione di un set di contesti con un nome il cui ID derivato esiste già non supera la convalida. Per sovrascrivere i contenuti mantenendo le associazioni al database, modifica il set di contesti esistente. Il caricamento diretto tramite l'agente di context engineering o l'API Dataplex con un ID set di contesto esistente sostituisce i contenuti e, se specificate, le associazioni di database.

L'elenco Set di contesto in AlloyDB Studio mostra solo i set di contesto nel gruppo di set di contesto default in tutte le regioni supportate collegate al database corrente. I set di contesto creati per un altro database o tramite l'API senza collegare la risorsa del database in databases (o in un gruppo di set di contesto personalizzato) non vengono visualizzati nell'elenco di AlloyDB Studio.

Per scoprire di più sui set di contesto, consulta la panoramica dei set di contesto.

Prima di iniziare

Completa i seguenti prerequisiti prima di creare o caricare un set di contesto.

I set di contesto possono essere creati nelle regioni us-central1, us-east1, europe-west4 e asia-southeast1.

Abilita i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

• API Data Analytics con Gemini
• API Gemini for Google Cloud
• API Knowledge Catalog

Prepara un cluster, un'istanza e un database AlloyDB per PostgreSQL

Assicurati di avere accesso a un cluster e a un'istanza AlloyDB esistenti o creane di nuovi.
Questo tutorial richiede un database nell'istanza AlloyDB. Per saperne di più, consulta Crea un database.

Ruoli e autorizzazioni richiesti

• Abilita l'autenticazione del database Identity and Access Management (IAM) sull'istanza impostando il flag di database alloydb.iam_authentication su on (alloydb.iam_authentication=on). Per saperne di più, consulta Abilita e disabilita l'autenticazione IAM.
• Aggiungi un utente o un account di servizio IAM al cluster a livello di database. Per saperne di più, consulta Gestisci l'autenticazione IAM.
• Concedi i ruoli roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer e roles/geminidataanalytics.queryDataUser all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi l'associazione delle policy IAM per un progetto.
• Per creare, caricare e gestire i set di contesto, concedi il ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) all'utente IAM a livello di progetto. Per saperne di più, consulta Autorizzazioni dei set di contesto.
• Devi anche concedere privilegi di sola lettura al database all'utente o al service account IAM.
  
  GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";
  
  Sostituisci USER_NAME con l'indirizzo email di un utente o l'indirizzo del account di servizio senza il suffisso . (ad esempio, [e-mail]). Devi utilizzare le virgolette intorno all'identificatore perché contiene caratteri speciali (@ e .).
  
  Per ulteriori informazioni, consulta Concedi le autorizzazioni appropriate per il database agli utenti IAM.

Concedi l'autorizzazione executesql all'istanza AlloyDB per PostgreSQL

Per concedere l'autorizzazione executesql all'istanza AlloyDB per PostgreSQL e impostare il campo dell'istanza dataApiAccess su ENABLED (obbligatorio per QueryData anche se l'impostazione predefinita consente alcuni servizi Google Cloud interni come AlloyDB Studio), utilizza il seguente comando curl:

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED"
     }'

Sostituisci quanto segue:

• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• LOCATION: la regione in cui si trova il cluster AlloyDB.
• CLUSTER_ID: l'ID del tuo cluster AlloyDB.
• INSTANCE_ID: l'ID dell'istanza AlloyDB.

Per eseguire i passaggi di questo tutorial, accedi a Google Cloud, quindi esegui l'autenticazione nel database utilizzando l'autenticazione IAM.

Crea un set di contesti

Per creare un set di contesti, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina AlloyDB.

   Vai ad AlloyDB

2. Seleziona un cluster dall'elenco.

3. Nel menu di navigazione, fai clic su AlloyDB Studio.

4. Accedi ad AlloyDB Studio utilizzando l'autenticazione IAM.

5. Nel riquadro Explorer, accanto a Set di contesto, fai clic su Visualizza azioni.

6. Fai clic su Crea set di contesti.

7. In Nome set di contesti, fornisci un nome univoco per il set di contesti. In AlloyDB Studio, il nome deve avere una lunghezza compresa tra 4 e 30 caratteri e non può iniziare con uno spazio vuoto. Studio ricava l'ID del set di contesto convertendo il nome in minuscolo e sostituendo i caratteri non alfanumerici con trattini (-). L'ID del set di contesto derivato deve essere univoco all'interno del gruppo di set di contesto default del progetto per la regione selezionata. Ad esempio, il nome del set di contesti querydata_e2e_test ha l'ID set di contesti querydata-e2e-test. Quando carichi un set di contesto direttamente utilizzando l'agente di context engineering o l'API Dataplex, l'ID del set di contesto è sensibile alle maiuscole, non può contenere barre (/) e non è limitato a un numero di caratteri compreso tra 4 e 30 o a caratteri alfanumerici, trattini e trattini bassi.

8. Facoltativo. In Descrizione set di contesti, aggiungi una descrizione per il set di contesti.

9. Facoltativo. Per caricare un file del set di contesto, fai clic su Sfoglia nella sezione Carica file del set di contesto e seleziona il file del set di contesto.

10. Facoltativo. Per scegliere una regione per il set di contesto, fai clic su Mostra opzioni avanzate e seleziona una regione in Seleziona una località (il valore predefinito è us-east1 per ogni creazione). Se scegli una regione diversa da us-east1, selezionala prima di inserire il nome del set di contesto in modo che AlloyDB Studio convalidi l'univocità del nome in quella regione.

11. Fai clic su Crea.

Nota: la creazione di un set di contesti da AlloyDB Studio può richiedere fino a qualche minuto, mentre AlloyDB Studio elabora il set di contesti. La creazione o il caricamento di un set di contesti tramite l'agente di progettazione del contesto o l'API Dataplex richiede in genere alcuni secondi.

Crea set di contesti

Se hai creato un set di contesti vuoto in Studio o vuoi aggiornarne uno esistente, segui i passaggi descritti in Crea e ottimizza i set di contesti con l'agente di context engineering per generare e ottimizzare un file del set di contesti. L'agente di progettazione del contesto può creare e caricare il set di contesto direttamente dalla CLI oppure puoi modificare il set di contesto in Studio per caricare manualmente il file del set di contesto.

Modifica un set di contesti

Per modificare un set di contesti, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina AlloyDB.

   Vai ad AlloyDB

2. Seleziona un cluster dall'elenco.

3. Nel menu di navigazione, fai clic su AlloyDB Studio.

4. Accedi ad AlloyDB Studio utilizzando l'autenticazione IAM.

5. Fai clic su Visualizza azioni accanto al set di contesti da modificare.

6. Fai clic su Modifica set di contesti.

7. Facoltativo. Modifica la descrizione del set di contesti.

8. Fai clic su Sfoglia nella sezione Carica file del set di contesti e seleziona il file del set di contesti.

9. Fai clic su Salva.

Elimina un set di contesti

Per eliminare un set di contesti, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina AlloyDB.

   Vai ad AlloyDB

2. Seleziona un cluster dall'elenco.

3. Nel menu di navigazione, fai clic su AlloyDB Studio.

4. Accedi ad AlloyDB Studio utilizzando l'autenticazione IAM.

5. Fai clic su Visualizza azioni accanto al set di contesti che vuoi eliminare.

6. Fai clic su Elimina set di contesti.

7. Nella finestra di dialogo di conferma Elimina set di contesti, inserisci l'ID del set di contesti.

8. Fai clic su Conferma per eliminare il set di contesti.

Nota: l'eliminazione di un database non comporta l'eliminazione dei relativi set di contesto. Per evitare set di contesti orfani che espongono ancora i dettagli dello schema, eliminali prima di eliminare il database.

Passaggi successivi

• Scopri di più sui set di contesti.
• Scopri come testare QueryData in AlloyDB Studio.
• Scopri come creare e ottimizzare i set di contesto con l'agente di context engineering.
• Scopri come integrare QueryData con un'applicazione.