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 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 gli Agentic Workflows interattivi. Puoi utilizzare questo contesto compatto e pronto per gli LLM per basare i tuoi agenti nella valutazione e nell'utilizzo degli asset di dati.

Puoi utilizzare il metodo lookupContext per qualsiasi asset di dati archiviato in Knowledge Catalog, ad esempio tabelle BigQuery, set di dati e routine, nonché domini di dati e altre voci.

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 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 di contesto Descrizione
    Metadati tecnici Schemi delle risorse e configurazioni fisiche, come le strategie di partizionamento e clustering di BigQuery e le definizioni delle routine BigQuery, inclusi argomenti, tipi restituiti e codice sorgente.
    Metadati operativi Unioni e altre relazioni, basate sui log delle query storiche e sugli insight 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, ispezionano 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 Output dei controlli automatici della qualità dei dati rispetto a regole predefinite.
    Contesto sugli asset di dati correlati Contesto sugli asset di dati correlati, come i termini del glossario o altri asset correlati, ad esempio 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 avere i 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, 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 dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Recuperare il contesto per un asset di dati

Per recuperare il contesto per 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 per 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, nel formato 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 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 context_budget.

Una richiesta di esempio che recupera il contesto per una tabella BigQuery è la 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 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}")

Recuperare il contesto per le routine

Puoi utilizzare il metodo lookupContext per recuperare il contesto per le routine BigQuery, come le funzioni definite dall'utente, le funzioni di tabella e le stored procedure. Gli agenti possono utilizzare questo contesto per capire cosa fa una routine e come chiamarla, ad esempio quando generano query SQL. Il contesto per una routine include le seguenti informazioni:

  • Il tipo di routine, ad esempio funzione scalare, funzione di tabella o procedura.
  • La lingua della routine.
  • Gli argomenti e il tipo restituito della routine.
  • Il codice sorgente della routine (corpo della definizione).
  • Descrizioni e altri metadati di Knowledge Catalog.

Per recuperare il contesto per una routine, includi il nome della voce della routine nell'elenco resources della richiesta. Il nome della voce ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che contiene la routine.
  • LOCATION: la località del set di dati che contiene la routine (ad esempio, us).
  • DATASET_ID: l'ID del set di dati che contiene la routine.
  • ROUTINE_ID: l'ID della routine.

Quali sono alcune best practice per le ricerche di contesto?

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

  • Richiedi la lunghezza selezionata del contesto di output con il parametro context_budget. Il metodo lookupContext mira a 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 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