Crea un agente per scoprire i tuoi dati

L'agente di rilevamento di Knowledge Catalog è un assistente basato sull'AI che migliora la pertinenza della ricerca per query complesse in linguaggio naturale in base alle funzionalità di ricerca di Knowledge Catalog. Ottimizzando la comprensione e la formulazione delle query, fornisce risultati più accurati rispetto all'API Knowledge Catalog Search standard. Questa funzionalità è fondamentale soprattutto per query complesse o lunghe.

Casi d'uso

L'agente di scoperta offre un'esperienza conversazionale ricca 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 di risorse in BigQuery.
  • Ricerca orientata al business: individuazione degli asset di dati in base all'intento e al contesto aziendale anziché alla corrispondenza esatta dei termini tecnici.
  • Esplorazione in più passaggi:perfezionamento della ricerca tramite un dialogo conversazionale per restringere i risultati.

L'agente di rilevamento è basato sulla ricerca semantica di Knowledge Catalog, che ti offre la ricerca ibrida predefinita. Puoi continuare a utilizzare la ricerca semantica di Knowledge Catalog direttamente quando devi elaborare ricerche con intenzione di acquisto elevata (quando conosci la risorsa o la colonna specifica), requisiti di bassa latenza o ricerca ibrida senza configurazione.

Come funziona

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

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

Il seguente diagramma fornisce i dettagli della procedura:

Procedura dell'agente di rilevamento per le richieste di ricerca.
Percorso di elaborazione per le richieste di ricerca nell'agente di scoperta.

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 rilevamento 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 Google Cloud progetto :

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 Knowledge Catalog, 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 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.

Abilita le API

Configura l'ambiente

Per configurare l'ambiente di sviluppo per l'agente di rilevamento:

  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. Imposta le variabili di ambiente con il comando seguente:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Sostituisci quanto segue:

    • PROJECT_ID con l'ID del tuo progetto

Esegui l'agente di rilevamento come agente root

Per eseguire l'agente di rilevamento direttamente come agente root:

  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 il tuo agente risiede in knowledge_catalog_discovery_agent/, esegui adk run dalla directory agents/.

Eseguire l'agente di rilevamento come strumento dell'agente

Per integrare l'agente di rilevamento in un agente personalizzato più grande, ad esempio my_custom_agent:

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

    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 scoperta e utilizzalo come strumento dell'agente. Vedi 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 il tuo agente si trova in agents/my_custom_agent/, esegui adk run dalla directory agents/.

Passaggi successivi