Recuperare il contesto per gli asset di dati

Il contesto che circonda i tuoi dati fornisce alle tue applicazioni di AI una profonda comprensione dei tuoi asset di dati, migliorando l'accuratezza e la pertinenza delle risposte generate dagli LLM.

Il metodo lookupContext colma il divario di contesto utilizzando una singola richiesta API per recuperare un bundle preformattato di metadati degli asset di dati ottimizzati per i flussi di lavoro interattivi degli agenti. Puoi utilizzare questo contesto compatto e pronto per gli LLM per aiutare gli agenti a valutare e utilizzare gli asset di dati.

Puoi utilizzare il metodo lookupContext per qualsiasi asset di dati archiviato in Knowledge Catalog, ad esempio tabelle, set di dati BigQuery o qualsiasi altra voce.

In che modo gli agenti possono ottenere il contesto dei dati?

  1. L'agente recupera gli asset di dati potenzialmente pertinenti per il recupero del contesto, ad esempio utilizzando la ricerca semantica di Knowledge Catalog.
  2. L'agente utilizza il metodo lookupContext per effettuare una singola chiamata API o una richiesta di strumento MCP che recupera il contesto per una risorsa specifica.

  3. Il metodo restituisce una risposta contenente un blocco di testo preformattato. A seconda del parametro format specificato nella richiesta, il documento può essere in formato YAML, XML o JSON.

    La risposta contiene i seguenti elementi di contesto:

    Elemento di contesto Descrizione
    Metadati tecnici Schemi delle risorse e configurazioni fisiche, come le strategie di partizionamento e clustering di BigQuery.
    Metadati operativi Join e altre relazioni, basati su log delle query storici e approfondimenti sui dati. Per saperne di più, vedi Visualizzare le relazioni tra i dati.
    Descrizioni delle attività Termini aziendali correlati, panoramiche, annotazioni del catalogo, descrizioni acquisite nel sistema di origine e generate automaticamente in Knowledge Catalog e linee guida.

    Nota: puoi utilizzare l'aspetto delle linee guida sugli asset di dati per acquisire un contesto aggiuntivo utile per gli agenti quando scoprono, esaminano o utilizzano gli asset di dati.
    Profilo di dati Statistiche di distribuzione, conteggi dei valori distinti, rapporti null e valori di esempio.
    Qualità dei dati Output del controllo automatico della qualità dei dati in base a regole predefinite.
    Contesto sugli asset di dati correlati Contesto sugli asset di dati correlati, ad esempio termini del glossario o altri asset correlati, come tabelle unite di frequente. Il contesto restituito per gli asset correlati include la stessa gamma di elementi degli asset principali.

  4. L'agente utilizza questa risposta per guidare la selezione degli asset pertinenti o il loro utilizzo.

Prima di iniziare

Prima di utilizzare il metodo lookupContext, assicurati di disporre dei ruoli necessari e di abilitare le API richieste.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per chiamare il metodo lookupContext, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo Google Cloud progetto iam.gserviceaccount.com:

  • Accesso in lettura alle risorse del catalogo, tra cui voci, gruppi di voci e glossari: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Per utilizzare il metodo lookupContext, abilita le seguenti API nel tuo progetto:

  • API Knowledge Catalog

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Recuperare il contesto per un asset di dati

Per recuperare il contesto di un asset di dati, accedi direttamente al metodo lookupContext con l'API Dataplex o utilizza il server Model Context Protocol (MCP) remoto di Knowledge Catalog o MCP Toolbox for Databases.

Il metodo lookupContext filtra le risorse in base alle tue autorizzazioni. La risposta contiene dati solo per gli asset a cui la tua identità dispone delle autorizzazioni Identity and Access Management (IAM) necessarie per accedere. Se non disponi di autorizzazioni per le risorse richieste, il metodo restituisce una risposta vuota.

REST

Per recuperare il contesto di una risorsa dati, invia la seguente richiesta:

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo Google Cloud progetto
  • LOCATION: la regione in cui esiste l'asset (ad esempio us-central1)
  • RESOURCES: fino a dieci nomi di voci per cui recuperare il contesto, formattati come projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Per più risorse, l'API stabilisce relazioni tra le risorse richieste, ad esempio unioni di schemi frequenti, e restituisce le informazioni sulle relazioni nel contesto.
  • OPTIONS: le opzioni che ti consentono di definire il contesto:
    • format è il formato del file di contesto. Ad esempio, yaml.
    • context_budget è il numero di caratteri a cui è limitata la risposta. Se imposti il parametro all_schema_fields su true, l'API restituisce tutti i campi dello schema indipendentemente dal valore di context_budget.

Una richiesta di esempio che recupera il contesto per una tabella BigQuery ha il seguente aspetto:

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

La risposta è un blocco di testo preformattato simile al seguente:

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Knowledge Catalog per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Knowledge Catalog Python.

Per eseguire l'autenticazione in Knowledge Catalog, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

L'esempio seguente mostra come recuperare il contesto per una tabella BigQuery:

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

Quali sono alcune best practice per le ricerche contestuali?

Per ottimizzare i risultati quando utilizzi il metodo lookupContext, tieni presenti le seguenti best practice:

  • Richiedi la lunghezza selezionata del contesto di output con il parametro context_budget. Il metodo lookupContext cercherà di inserire il contesto più pertinente nell'output il più vicino possibile ai limiti prescritti dal parametro.
  • Puoi elencare fino a dieci asset di dati nell'elenco resources. Ad esempio, l'inclusione di più tabelle nell'elenco resources fa sì che l'API fornisca il contesto non solo per queste tabelle, ma anche per i possibili percorsi di join tra loro, fornendo quindi le indicazioni necessarie su come utilizzare queste tabelle insieme.
  • Utilizza l'opzione format, ad esempio yaml o json, che si allinea meglio alla logica di analisi dell'LLM o dell'agente per evitare trasformazioni costose.

Passaggi successivi