Panoramica dei set di contesti

I set di contesto di Knowledge Catalog ti consentono di pacchettizzare schemi di dati, definizioni semantiche e pattern di query convalidati in container di conoscenza limitati e specifici per il dominio. Questa conoscenza mirata del dominio fornisce un grounding affidabile alle applicazioni di AI autonome come Gemini Enterprise e gli agenti personalizzati, in modo che possano operare con un'elevata precisione.

Questo documento è rivolto ad architetti di dati, responsabili della governance e ingegneri AI che vogliono capire in che modo i set di contesto strutturano la conoscenza del dominio per gli agenti AI.

Che cos'è un set di contesti?

Un set di contesto è un gruppo di voci di Knowledge Catalog specializzato (un container logico per i record di metadati) che pacchettizza una raccolta autonoma di informazioni semantiche e riferimenti ad asset di dati per domini analitici e agenti AI specifici.

All'interno di questo container, le conoscenze sono organizzate in voci, che rappresentano singoli concetti aziendali, documenti o asset di dati. Queste voci sono arricchite con aspetti, ovvero attributi di metadati modulari che memorizzano dettagli specifici come termini aziendali, modelli SQL e documentazione Markdown.

Anziché costringere gli agenti a cercare nell'intero catalogo aziendale, il che introduce latenza, spreca token di prompt e rischia di generare risposte allucinate, i set di contesto stabiliscono container di conoscenza ermetici e con ambito di dominio che gli agenti possono consultare con alta precisione.

Poiché i set di contesto fungono da container amministrativi, puoi organizzare i metadati in base alla proprietà del progetto e applicare policy di controllo dell'accesso di Identity and Access Management (IAM) a tutte le voci raggruppate contemporaneamente senza configurare le autorizzazioni singolarmente. Per saperne di più su gruppi di voci, voci e aspetti, consulta Informazioni sulla gestione dei metadati.

Requisiti di grounding degli agenti AI

Man mano che le organizzazioni implementano agenti AI autonomi (come Gemini Enterprise, Antigravity e agenti personalizzati dell'Agent Development Kit) per orchestrare i workflow dei dati e generare analisi, gli agenti richiedono un grounding affidabile:

  • Definizioni semantiche: che cosa significa una colonna o una metrica specifica in termini di business?
  • Pattern di query convalidati: in che modo gli esperti di dominio hanno eseguito query e unito queste tabelle?
  • Regole operative: quali policy aziendali, criteri di eccezione e procedure operative standard (SOP) regolano questi dati?

Il seguente diagramma dell'architettura illustra come le quattro convenzioni di denominazione logica principali operano insieme all'interno del confine del gruppo di voci per fornire un grounding alle applicazioni di AI downstream:

Le quattro convenzioni di denominazione all'interno di un confine di un set di contesti che limitano le ricerche degli agenti AI.
Figura 1. Le quattro convenzioni di denominazione selezionate all'interno di un confine di un gruppo di voci di un set di contesto.

Sebbene un set di contesto non richieda rigorosamente ogni tipo di voce per funzionare, ti consigliamo di organizzare le voci utilizzando le seguenti convenzioni di denominazione logica. L'utilizzo di queste convenzioni di denominazione aiuta a garantire che gli utenti umani e gli agenti autonomi possano scoprire e interpretare le conoscenze in modo coerente:

Pattern di denominazione Tipo di voce Descrizione e scopo Aspetti collegati
Concetti aziendali concepts_<id> generic Termini del glossario aziendale, definizioni delle metriche, acronimi e formule di calcolo. glossary-term-aspect, contacts.
Documenti documents_<path> document Contesto narrativo, procedure operative standard (SOP), wiki di onboarding e riferimenti alla documentazione esterna. Document, overview (link e Markdown RTF).
Modelli di query query-templates_<path> query-template Modelli di query SQL parametrizzati e pre-convalidati, logica di join ad alta frequenza e pattern di esecuzione. query-template (include campi come sources, intent, nlQuery, parameters e query).
Modelli semantici semantic-models_<id> semantic-model, semantic-entity, semantic-metric Modelli relazionali formali, definizioni di entità, gerarchie dimensionali e misure. semantic-model, semantic-entity, semantic-metric.

Concetti aziendali

Una voce di concetto aziendale (voce di tipo generico che utilizza la convenzione di denominazione concepts_*) definisce la terminologia aziendale standardizzata, le metriche di dominio, gli acronimi e le formule di calcolo (glossary-term-aspect).

Le sue funzionalità principali includono:

  • Allineamento della terminologia: elimina l'ambiguità della terminologia tra le unità aziendali e i team di analisi.
  • Formule KPI: fornisce formule matematiche e logica per gli indicatori chiave di prestazione (KPI) specifici del dominio.
  • Proprietà dell'organizzazione: stabilisce una chiara proprietà dell'organizzazione tramite gli aspetti di governance allegati (contacts).

Ad esempio, all'interno di un set di contesto di e-commerce, una voce in concepts_net_items_sold specifica il calcolo esatto delle unità nette vendute. Quando un agente riceve un prompt che chiede "articoli netti venduti", consulta la voce del concetto per applicare il calcolo verificato anziché inventare la logica SQL.

Rappresentazione di esempio della risorsa:

name: projects/cymbal-style/locations/us-central1/entryGroups/online-apparel-store/entries/concepts_net_items_sold
entryType: generic
aspects:
  dataplex-types.global.glossary-term-aspect:
    definition: "Calculates the absolute number of items sold minus customer returns in a given time period."

Documenti

Una voce di documento (voce di tipo documento che utilizza la convenzione di denominazione documents_*) memorizza il contesto narrativo e procedurale in Markdown strutturato (Document, overview).

Le sue funzionalità principali includono:

  • Procedure operative standard (SOP): acquisisce SOP, checklist dei runbook e guide di onboarding direttamente nel catalogo.
  • Policy di conformità: documenta le policy di conformità, i vincoli normativi (come le regole di gestione del GDPR o dell'HIPAA) e i criteri di eccezione.
  • Wiki di riferimento esterni: fa riferimento a wiki esterni attivi (come documenti Google, Atlassian Confluence, Notion o GitHub) tramite puntatori URI di origine (link overview).

Ad esempio, un set di contesti di abbigliamento include documents_return_policy_rules per istruire gli agenti su come escludere le vendite finalizzate e gli articoli danneggiati durante il trasporto nel calcolo dei tassi di reso standard.

Rappresentazione di esempio della risorsa:

name: projects/cymbal-style/locations/us-central1/entryGroups/online-apparel-store/entries/documents_return_policy_rules
entryType: document
aspects:
  dataplex-types.global.overview:
    content: "## Return Policy Rules\nItems marked FINAL_SALE or DAMAGED_IN_TRANSIT are excluded from return rates..."

Modelli di query

Una voce del modello di query (voce di tipo query-template che utilizza la convenzione di denominazione query-templates_*) contiene query SQL parametrizzate verificate da persone, mappate a intenti analitici comuni in linguaggio naturale (utilizzando l'aspetto query-template).

Le sue funzionalità principali includono:

  • Query pre-convalidate: memorizza percorsi di join, condizioni di filtro e pattern di aggregazione pre-convalidati per domande aziendali ad alta frequenza.
  • Parametrizzazione di runtime: supporta la sostituzione dei parametri di runtime (come @start_date, @region e @limit) per l'esecuzione dinamica degli agenti.
  • Prevenzione degli errori: evita join di tabelle allucinati ed errori di sintassi del dialetto SQL.

Ad esempio, quando un agente deve rispondere a una domanda sugli account con il rendimento migliore, trova una corrispondenza con query-templates_sales_top_accounts_by_arr e sostituisce l'intervallo di date richiesto nel template SQL verificato.

Rappresentazione di esempio della risorsa:

name: projects/cymbal-style/locations/us-central1/entryGroups/online-apparel-store/entries/query-templates_top_categories_by_season
entryType: query-template
aspects:
  dataplex-types.global.query-template:
    intent: "Which e-commerce product categories performed best this season?"
    query: "SELECT category, SUM(revenue) FROM sales WHERE season = @season GROUP BY category ORDER BY 2 DESC LIMIT @limit"
    parameters:
      -   name: "season"
        type: "STRING"
      -   name: "limit"
        type: "INTEGER"

Modelli semantici

Le voci del modello semantico (utilizzando i tipi di voce semantic-model, semantic-entity e semantic-metric con la convenzione di denominazione semantic-models_*) formalizzano le strutture relazionali, le gerarchie dimensionali e le misure di aggregazione nelle tabelle normalizzate.

Le sue funzionalità principali includono:

  • Definizione relazionale: definisce le chiavi primarie, le chiavi esterne e le cardinalità di join (ad esempio relazioni one-to-many o many-to-many).

  • Mappatura delle dimensioni aziendali: mappa le colonne sottostanti non elaborate alle dimensioni aziendali, alle granularità temporali e alle misure riutilizzabili.

  • Guida per gli agenti: guida gli agenti autonomi nell'assemblaggio di query analitiche complesse su più tabelle quando non esiste un modello di query esatto.

  • Astrazione della complessità sottostante: a differenza dei link di ingresso di join di schema non elaborati che documentano solo le connessioni meccaniche delle tabelle nel set di dati di origine, i modelli semantici operano a livello logico aziendale per impedire all'agente AI di generare allucinazioni di attraversamenti di diagrammi ER errati.

Ad esempio, un set di contesti di abbigliamento utilizza semantic-models_apparel_sales_model per definire il modo in cui warehouses, shipments e line_items si uniscono tra le tabelle dei fatti e delle dimensioni dello schema a stella.

Rappresentazione di esempio della risorsa:

name: projects/cymbal-style/locations/us-central1/entryGroups/online-apparel-store/entries/semantic-models_apparel_sales_model
entryType: semantic-model
aspects:
  dataplex-types.global.semantic-model:
    entities:
      -   name: "products"
      -   name: "orders"
    relationships:
      -   sourceEntity: "orders"
        foreignKey: "product_id"
        targetEntity: "products"
        primaryKey: "id"
        type: "MANY_TO_ONE"

Esempio: set di contesti di un negozio di abbigliamento online

Per mostrare come funzionano insieme le quattro convenzioni di denominazione, prendiamo in considerazione un rivenditore di abbigliamento online che esegue il deployment di un assistente AI per i merchandiser del negozio. Senza un contesto delimitato, l'agente potrebbe eseguire query su tabelle di gestione temporanea non elaborate o conteggiare in modo errato gli articoli più richiesti non sottraendo i resi dei clienti.

Per eseguire il grounding dell'agente, un data steward crea un set di contesto denominato online-apparel-store:


EntryGroup: projects/cymbal-style/locations/us-central1/entryGroups/online-apparel-store
(EntryGroup.type = "context-set")
│
├── concepts_* (Business concepts)
│   ├── concepts_net_items_sold
│   │     Formula: SUM(orders.quantity) - SUM(returns.quantity)
│   └── concepts_bestseller
│         Definition: Any clothing item with >= 500 net units sold within a 30-day window
│
├── documents_* (Documents and SOPs)
│   ├── documents_return_policy_rules
│   │     Markdown SOP: Exclude items marked 'FINAL_SALE' or 'DAMAGED_IN_TRANSIT' from standard return rates
│   └── documents_size_chart_guide
│         Markdown guide: Sizing conversions across US, UK, and EU clothing labels
│
├── query-templates_* (Golden SQL queries)
│   └── query-templates_top_categories_by_season
│         Verified SQL template with parameters: @season, @limit
│
└── semantic-models_* (Semantic models)
    └── semantic-models_apparel_sales_model
          Join keys: orders.product_id = products.product_id (many-to-one)
                     orders.order_id = returns.order_id (one-to-many)

Come un agente risolve un prompt

Quando un merchandiser chiede all'agente: "Quali sono stati i nostri 5 modelli di giacche invernali più venduti, esclusi i resi danneggiati?", l'agente risolve il prompt tramite il set di contesto:

  1. Ricerca del modello di query: l'agente controlla query-templates_* e trova una corrispondenza con query-templates_top_categories_by_season, sostituendo @season = 'Winter' e @limit = 5.

  2. Verifica del concetto: l'agente esamina concepts_net_items_sold e concepts_bestseller per confermare che gli articoli restituiti devono essere sottratti dalle quantità totali dell'ordine.

  3. Applicazione delle regole SOP: l'agente legge documents_return_policy_rules e aggiunge la condizione di filtro WHERE return_reason != 'DAMAGED_IN_TRANSIT'.

  4. Convalida dello schema e dei join: utilizzando semantic-models_apparel_sales_model e le tabelle @bigquery collegate, l'agente unisce store.orders, store.products e store.returns utilizzando chiavi esterne verificate ed esegue la query SQL.

Funzionalità dell'architettura

I set di contesto offrono diverse funzionalità di base per gli ambienti di dati aziendali:

  • Confini di esecuzione ermetici: limitando il contesto a un insieme selezionato di asset e voci semantiche, gli agenti operano all'interno di una sandbox ermetica. In questo modo, si elimina il rumore estraneo del catalogo, si contribuisce a garantire valutazioni deterministiche e si riduce al minimo l'utilizzo dei token.

  • Caricamento rapido e indicizzazione collettiva: i team possono caricare e indicizzare insiemi di concetti, query e documenti come un'unica operazione atomica, il che consente di eseguire l'integrazione con le pipeline di integrazione e deployment continui (CI/CD).

  • Pacchettizzazione zero-copy: i set di contesto pacchettizzano i metadati e le relazioni senza copiare o spostare lo spazio di archiviazione dei dati sottostante, evitando costi di archiviazione ridondanti e ritardi nella sincronizzazione dei dati.

Pattern di consultazione degli agenti

Gli agenti downstream utilizzano i set di contesto tramite il Model Context Protocol (MCP) o le API Knowledge Catalog dirette. Per saperne di più, consulta Recupera il contesto dei dati con le API Catalog. Per ottimizzare la latenza di risposta e ridurre al minimo il consumo di token, gli agenti seguono una gerarchia di consultazione a tre livelli:

  1. Corrispondenza dei modelli di query: l'agente cerca query-templates_*. Se un modello verificato corrisponde all'intent dell'utente, l'agente parametrizza la query e la esegue direttamente. In questo modo, ottieni la risposta più rapida con un rischio di errore della query quasi pari a zero.

  2. Assemblaggio del modello semantico: se nessun template di query corrisponde, l'agente valuta semantic-models_* per comprendere le relazioni tra le entità e costruire un'istruzione SQL multitabella.

  3. Consultazione di documenti e concetti: per casi limite ambigui (come le scadenze del calendario fiscale o le esclusioni delle contestazioni), l'agente legge concepts_* e documents_* per applicare le regole aziendali.

Utilizzo del contesto nelle applicazioni di AI generativa

Le applicazioni di AI generativa utilizzano set di contesti selezionati per comprendere la semantica del dominio aziendale, navigare in schemi complessi e generare SQL affidabile senza allucinazioni. In genere, le applicazioni utilizzano questi set di contesto tramite due pattern principali:

  • Rilevamento dinamico del contesto: negli ambienti di analisi conversazionale o self-service, gli utenti pongono domande ad hoc in linguaggio naturale. L'applicazione valuta dinamicamente l'intent dell'utente per identificare e recuperare il set di contesto più pertinente da Knowledge Catalog, inserendo la conoscenza del dominio recuperata nel prompt attivo.

  • Set di contesti preconfigurati: per le applicazioni di agenti dedicati, puoi preconfigurare l'agente con un riferimento esplicito al set di contesti fornendo l'URI della risorsa. L'associazione di un set di contesti dedicato fornisce un grounding deterministico, garantendo che tutte le interazioni utilizzino definizioni aziendali certificate senza overhead di ricerca in fase di runtime. L'agente eredita automaticamente i miglioramenti della qualità man mano che i workflow di arricchimento ricorrenti perfezionano il set di contesto nel tempo.

    Per ottimizzare queste funzionalità di arricchimento e autoapprendimento, ti consigliamo di specificare un modello Gemini 3.8 Flash o successivo nell'applicazione Gemini Enterprise. Per ulteriori informazioni sui passaggi di selezione del modello, consulta la sezione "Crea un agente utilizzando il Flow Builder" in Progetta agenti in Agent Studio.

Confronto tra set di contesti e costrutti correlati

Per scegliere il costrutto di metadati giusto per la tua architettura, scopri come i set di contesti di Knowledge Catalog si confrontano con le funzionalità della piattaforma correlate.

Set di contesti rispetto ai grafi di contesto

Il grafico di contesto e i set di contesto sono due costrutti separati con ruoli distinti nell'architettura di Knowledge Studio:

  • Grafico di contesto: la topologia semantica completa e in tempo reale della tua organizzazione. Collega gli asset di dati sottostanti, i termini del glossario aziendale e le tracce di interazione. Puoi esplorare e attraversare questo grafo aperto in modo interattivo nell'interfaccia Esplora.

  • Set di contesto: un'unità di pacchetto limitata, regionale e selezionata. Estrae e pacchettizza in modo ermetico un sottoinsieme specifico di conoscenze di dominio in un gruppo di voci (type="context-set") per consentire agli agenti AI downstream di eseguire query tramite il Model Context Protocol (MCP). Un set di contesto funge da sottografo coeso e ad alta densità all'interno del grafo di contesto più ampio.

Set di contesti Knowledge Catalog rispetto ai set di contesti del database

Sia Knowledge Catalog che i database operativi Google Cloud utilizzano il termine set di contesto per fare riferimento alle informazioni selezionate che costituiscono la base dei modelli di AI generativa.

Sebbene entrambe le varianti condividano la stessa architettura di base (vengono archiviate in modo nativo come set di contesto di Knowledge Catalog, ovvero gruppi di voci estensibili con type="context-set") e utilizzino le API Knowledge Catalog standard, hanno come target livelli diversi dello stack di dati aziendali:

  • Set di contesti di database (QueryData): creati per gestire database operativi e transazionali (come AlloyDB per PostgreSQL, Cloud SQL e Spanner). Questi set di contesto sono fortemente ottimizzati per le configurazioni SQL. Raggruppano modelli di query d'oro, metadati dello schema e facet di filtro che un agente di context engineering dedicato valuta per migliorare la traduzione da linguaggio naturale a SQL (NL2SQL) nei runtime operativi.
  • Set di contesti di Knowledge Catalog (Knowledge Studio): creati per gestire i patrimoni di dati analitici (come BigQuery, data lakehouse e prodotti di dati di Knowledge Catalog). Questi set di contesto raggruppano conoscenze più ampie e multimodali in più convenzioni di denominazione, tra cui concetti aziendali, wiki di documentazione Markdown e modelli semantici. Vengono selezionati utilizzando i workflow di arricchimento di Knowledge Studio e forniti agli agenti analitici downstream tramite il Model Context Protocol (MCP).

Set di contesto rispetto ai prodotti di dati

Comprendere come i set di contesto interagiscono con i prodotti di dati di Knowledge Catalog ti aiuta a stabilire confini chiari per la governance dei dati e dell'AI:

  • I prodotti di dati gestiscono le risorse sottostanti: i prodotti di dati raggruppano in modo sicuro risorse concrete come tabelle, bucket e stream BigQuery, stabilendo un'unità principale per la condivisione dei dati, i contratti di dati e controllo dell'accesso al piano dati.

  • I set di contesto raggruppano la semantica conversazionale: i set di contesto non concedono l'accesso ai dati, ma raggruppano le conoscenze del dominio, come concetti, modelli di query e documenti richiesti dagli agenti AI e dagli esseri umani per comprendere i dati. I data steward possono collegare un set di contesto a un prodotto di dati dichiarandolo nei riferimenti additional_context del prodotto.

Sicurezza e governance di livello enterprise

I set di contesto si integrano con i controlli di sicurezza e governance di Google Cloud per contribuire a proteggere i metadati aziendali sensibili:

  • Ruoli IAM dei set di contesto: poiché i set di contesto spesso contengono informazioni semantiche sensibili, l'accesso è regolato dai ruoli IAM applicati direttamente al gruppo di voci context-set. In questo modo puoi organizzare le conoscenze curate per regione geografica e proprietà del dominio, concedendo le autorizzazioni di modifica agli amministratori del dominio e le autorizzazioni in lettura agli agenti AI che le utilizzano. Per creare un set di contesti, devi disporre dell'autorizzazione IAM dataplex.entryGroups.setIamPolicy. Questa autorizzazione è necessaria per concederti automaticamente le autorizzazioni di proprietario durante la creazione del set di contesti. Puoi ottenere questa autorizzazione tramite ruoli predefiniti come Dataplex Catalog Admin (roles/dataplex.catalogAdmin) o Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner).

  • Sicurezza dei dati sottostanti zero-copy: concedere a un agente l'accesso a un set di contesto consente all'agente di leggere i metadati semantici e i modelli di query, ma non bypassa i controlli di accesso alle tabelle sottostanti. Per eseguire una query SQL su BigQuery o leggere i file in Cloud Storage, l'identità che esegue la query deve disporre delle autorizzazioni IAM del piano dati richieste su queste risorse sottostanti.

  • Governance human-in-the-loop: quando le attività di arricchimento autonome di Knowledge Studio estraggono nuovi concetti, SOP o modelli di query dai log operativi, le proposte vengono messe in fase di staging come richieste di modifica revisionabili. I data steward esaminano i confronti delle differenze e i punteggi di valutazione prima di approvare le modifiche a un set di contesto di produzione. Per saperne di più sulla revisione delle proposte, consulta Gestisci le richieste.

  • Identità di esecuzione gestita dall'utente: le attività di arricchimento automatico che compilano i set di contesto vengono eseguite con un service account gestito dall'utente di cui l'agente di servizio Dataplex simula l'identità tramite il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator).

Ambito e limiti dell'anteprima

Durante l'anteprima, i set di contesto operano entro i seguenti limiti:

  • Ambito regionale: i set di contesto globali collegati ad asset di dati regionali non sono supportati. Un set di contesti deve essere in linea con i confini regionali degli asset che pacchettizza.

  • Interfacce di creazione e consumo: puoi creare set di contesto tramite il container di Knowledge Studio nella console Google Cloud , mantenendoli logicamente distinti dai gruppi di voci amministrative standard di Knowledge Catalog. Puoi compilare automaticamente i set di contesto tramite i workflow di arricchimento di Knowledge Studio. Gli agenti AI downstream possono scoprire ed eseguire query sui set di contesto in modo programmatico utilizzando le API Knowledge Catalog (ListEntries e LookupEntry) e il Model Context Protocol (MCP). Per saperne di più, consulta Informazioni sui server MCP.

  • Fatturazione: Knowledge Catalog non addebita uno SKU autonomo separato per la creazione di gruppi di voci di set di contesto.

  • Quote condivise: poiché i set di contesto sono fondamentalmente gruppi di voci specializzati (type="context-set"), utilizzano e condividono le stesse quote di risorse dei gruppi di voci standard di Knowledge Catalog.

Passaggi successivi

Concetto

Scopri come orchestrare un contesto di informazioni aggiuntive, creare set di contesti e fare il grounding degli agenti AI utilizzando le interfacce di Knowledge Studio.

Attività

Utilizza il canvas visivo di Knowledge Studio per chattare con i tuoi dati e tracciare le relazioni semantiche.

Concetto

Comprendi in che modo voci, gruppi di voci e aspetti formano la base strutturale dei set di contesto.

Concetto

Esporre set di contesti e metadati avanzati agli agenti di AI generativa downstream utilizzando MCP.

Attività

Scopri e recupera in modo programmatico i set di contesti per il ragionamento dell'AI generativa utilizzando le API "ListEntries" e "LookupEntry".

Attività

Scopri come creare, visualizzare, modificare ed eliminare i set di contesto in per organizzare la conoscenza del dominio.