Recuperare il contesto per gli asset di dati

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

Il metodo lookupContext colma il divario di contesto utilizzando una singola richiesta API per recuperare un bundle preformattato di metadati della risorsa ottimizzati per i flussi di lavoro agentici interattivi. Puoi utilizzare questo contesto compatto e pronto per LLM per basare i tuoi agenti sulla valutazione e sull'utilizzo degli asset di dati.

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

Come recuperare il contesto di un asset con il metodo lookupContext

  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 un asset specifico.

  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 dei contenuti Descrizione
    Metadati tecnici Schemi delle risorse e configurazioni fisiche, ad esempio strategie di partizionamento e clustering di BigQuery.
    Metadati operativi Unioni e altre relazioni, basate sui log delle query storiche e sugli insight sui dati. Per saperne di più, consulta 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 nulli e valori di esempio.
    Qualità dei dati Risultati del controllo automatico della qualità dei dati in base a regole predefinite.
    Contesto degli asset di dati correlati Contesto degli asset di dati correlati, ad esempio termini del glossario o altri asset correlati, come le tabelle unite di frequente. Il contesto restituito per gli asset correlati include la stessa gamma di elementi dell'asset o 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 aver abilitato 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 progetto: Google Cloud iam.gserviceaccount.com

  • Accesso in lettura alle risorse del catalogo, inclusi 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 del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Recuperare il contesto di 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 hai autorizzazioni per le risorse richieste, il metodo restituisce una risposta vuota.

REST

Per recuperare il contesto di un asset di 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 l'asset esiste (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 sulla relazione nel contesto.
  • OPTIONS: le opzioni che 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 di una tabella BigQuery è simile alla seguente:

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 Python nella guida rapida di Knowledge Catalog per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell' API Pythondi Knowledge Catalog.

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 di 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}")

Best practice per il metodo lookupContext

Per ottimizzare i risultati quando utilizzi il metodo lookupContext, tieni a mente 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, se includi più tabelle nell'elenco resources, l'API fornisce il contesto non solo per queste tabelle, ma anche per i possibili percorsi di unione tra di esse, 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