Crea un agente per scoprire i tuoi dati

L'agente di discovery open source per Knowledge Catalog (in precedenza Dataplex Universal Catalog) ti consente di trovare asset di dati pertinenti con query in linguaggio naturale complesse o lunghe. Utilizzando l'Agent Development Kit (ADK), puoi eseguire questo assistente basato sull'AI come agente principale o integrarlo come strumento in un agente personalizzato.

Casi d'uso

L'agente di discovery offre un'esperienza conversazionale avanzata per scenari come i seguenti:

  • Intenti e vincoli complessi o combinati: gestione delle richieste di ricerca con più criteri, ad esempio la ricerca di set di dati in us-central1, ma l'esclusione delle risorse in BigQuery.
  • Ricerca orientata al business: individuazione degli asset di dati in base all'intent e al contesto aziendale, anziché alla corrispondenza di termini tecnici esatti.
  • Esplorazione in più passaggi: perfezionamento della ricerca tramite un dialogo conversazionale per restringere i risultati.

L'agente di rilevamento si basa sulla ricerca semantica di Knowledge Catalog, che fornisce una ricerca ibrida pronta all'uso. Ottimizzando la comprensione e la formulazione delle query, l'agente fornisce risultati più accurati rispetto all'API Knowledge Catalog Search standard, in particolare per query complesse o lunghe. Puoi continuare a utilizzare la ricerca semantica di Knowledge Catalog direttamente per ricerche con intenzione di acquisto elevata (quando conosci la risorsa o la colonna specifica), query a bassa latenza o ricerca ibrida senza configurazione.

Come funziona

L'agente di discovery esegue i seguenti passaggi per rispondere a una query di ricerca:

  1. Analizza l'input per l'intent per comprendere la query, genera più varianti di ricerca e mappa i termini ai filtri dei metadati.
  2. Cerca le risorse utilizzando la ricerca semantica di Knowledge Catalog.
  3. Classifica i risultati uniti in base alla pertinenza.

Il seguente diagramma fornisce i dettagli del processo:

Processo dell'agente di discovery per le richieste di ricerca.
Percorso di elaborazione per le richieste di ricerca nell'agente di discovery.

L'agente si basa sull'API Knowledge Catalog Search per recuperare le risorseGoogle Cloud pertinenti. Il seguente snippet di codice mostra come l'agente chiama la ricerca semantica di Knowledge Catalog:


      # Configure the request parameters for the
      # call to Knowledge Catalog Semantic Search API.
      endpoint = "dataplex.googleapis.com"

      client = dataplex_v1.CatalogServiceClient(
          client_options={"api_endpoint": endpoint}
      )

      location = "global"
      consumer_project_id = "my-gcp-project"
      parent_name = f"projects/{consumer_project_id}/locations/{location}"

      # Call Knowledge Catalog Semantic Search API.
      response = client.search_entries(
          request={
              "name": parent_name,
              "query": query,
              "page_size": 50,
              "semantic_search": True,
          }
      )

      # Call Knowledge Catalog LookupContext for each search result
      # to retrieve rich, LLM-ready metadata.
      entries = []
      for result in response.results:
          entry_name = result.dataplex_entry.name
          
          # Prepare the LookupContext request for the specific resource
          lookup_request = {
              "name": parent_name,
              "resources": [entry_name]
          }
          
          # Call the LookupContext API
          lookup_response = client.lookup_context(request=lookup_request)
          
          # Extract the rich context YAML to share with the agent
          entries.append({
              "entry_name": entry_name,
              "context": lookup_response.context
          })

      return {"results": entries}

Prima di iniziare

Per eseguire l'agente di discovery di Knowledge Catalog, assicurati di soddisfare i seguenti requisiti:

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare l'agente di rilevamento, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto Google Cloud iam.gserviceaccount.com:

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per utilizzare l'agente di rilevamento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per utilizzare l'agente di rilevamento sono necessarie le seguenti autorizzazioni:

  • dataplex.projects.search
  • aiplatform.endpoints.predict
  • serviceusage.services.use

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Per utilizzare l'agente di rilevamento di Knowledge Catalog, abilita le seguenti API nel tuo progetto: API Dataplex, API Vertex AI e API Service Usage.

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 Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Configura l'ambiente

Per configurare l'ambiente di sviluppo per l'agente di rilevamento, segui questi passaggi:

  1. Clona il repository dataplex-labs.

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git

  2. Passa alla directory dell'agente:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Crea e attiva un ambiente virtuale Python, quindi installa le dipendenze elencate nel file requirements.txt:

    • google-adk (Agent Development Kit)
    • google-cloud-dataplex (client Python di Knowledge Catalog)
    • google-api-core
      python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Configura le variabili di ambiente con il seguente comando:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto.

Esegui l'agente di rilevamento come agente root

Per eseguire l'agente di rilevamento direttamente come agente root, segui questi passaggi:

  1. Nel file agent.py che si trova nella cartella knowledge_catalog_discovery_agent, rinomina la variabile discovery_agent in root_agent.

  2. Esegui l'agente utilizzando il comando adk run:

    adk run path/to/agent/parent/folder

    Sostituisci quanto segue:

    • path/to/agent/parent/folder con la directory principale che contiene la cartella con l'agente. Ad esempio, se l'agente si trova in knowledge_catalog_discovery_agent/, esegui adk run dalla directory agents/.

Esegui l'agente di discovery come strumento dell'agente

Per integrare l'agente di discovery in un agente personalizzato più grande, ad esempio my_custom_agent, segui questi passaggi:

  1. Configura la struttura del progetto in modo che contenga il modulo dell'agente di discovery:

    my_custom_agent/
├── agent.py
└── knowledge_catalog_discovery_agent/
    ├── SKILL.md
    ├── agent.py
    ├── tools.py
    └── utils.py

  2. Nel file agent.py dell'agente personalizzato, importa l'agente di discovery e utilizzalo come strumento dell'agente. Guarda l'esempio:

    root_agent = llm_agent.Agent(
    model=google_llm.Gemini(model=GEMINI_MODEL),
    name="my_custom_agent",
    instruction=(
        "You are a Custom Agent. Your goal is to help users understand"
        " their data landscape, evaluate data assets, and derive insights"
        " from available resources. **IMPORTANT**: You should use the"
        " `knowledge_catalog_discovery_agent` to search for and discover"
        " data assets. For best results, pass in the Natural Language user'"
        " query as is to the `knowledge_catalog_discovery_agent`. Once assets"
        " are found, you should analyze their metadata, compare them, and"
        " provide recommendations or summaries to the user to help them make"
        " decisions. Focus on general metadata summary and comparison."
    ),
    tools=[
        agent_tool.AgentTool(discovery_agent),
    ],
)

  3. Esegui l'agente utilizzando il comando adk run:

    adk run path/to/agent/parent/folder

    Sostituisci quanto segue:

    • path/to/agent/parent/folder con la directory principale che contiene la cartella my_custom_agent/. Ad esempio, se l'agente si trova in agents/my_custom_agent/, esegui adk run dalla directory agents/.

Passaggi successivi