Agent zum Ermitteln Ihrer Daten erstellen

Der Knowledge Catalog-Discovery-Agent ist ein KI-basierter Assistent, der die Suchrelevanz für komplexe Abfragen in natürlicher Sprache basierend auf den Suchfunktionen des Knowledge Catalog verbessert. Durch die Optimierung des Verständnisses und der Formulierung von Abfragen liefert sie genauere Ergebnisse als die Standard-Knowledge Catalog Search API. Diese Funktion ist besonders bei komplexen oder langen Abfragen wichtig.

Anwendungsfälle

Der Discovery-Agent bietet eine umfassende Konversationsumgebung für Szenarien wie die folgenden:

  • Komplexe oder kombinierte Absichten und Einschränkungen: Suchanfragen mit mehreren Kriterien verarbeiten, z. B. Datasets in us-central1 finden, aber Ressourcen in BigQuery ausschließen.
  • Geschäftsorientierte Suche: Daten-Assets werden anhand von Absicht und Geschäftskontext und nicht anhand von genauen technischen Begriffen gefunden.
  • Mehrstufige Suche: Sie können Ihre Suche durch einen Dialog verfeinern, um die Ergebnisse einzugrenzen.

Der Discovery-Agent basiert auf der semantischen Suche von Knowledge Catalog, die eine sofort einsatzbereite hybride Suche bietet. Sie können die semantische Suche von Knowledge Catalog weiterhin direkt verwenden, wenn Sie Suchanfragen mit hoher Absicht (wenn Sie die spezifische Ressource oder Spalte kennen), Anforderungen mit niedriger Latenz oder eine hybride Suche ohne Einrichtung verarbeiten müssen.

Funktionsweise

Der Discovery-Agent führt die folgenden Schritte aus, um auf eine Suchanfrage zu antworten:

  1. Analysiert die Eingabe auf die Absicht, die Anfrage zu verstehen, generiert mehrere Suchvarianten und ordnet Begriffe Metadatenfiltern zu.
  2. Sucht mithilfe der semantischen Suche von Knowledge Catalog nach Ressourcen.
  3. Sortiert die zusammengeführten Ergebnisse nach Relevanz.

Das folgende Diagramm zeigt die Details des Prozesses:

Discovery-Agent-Prozess für Suchanfragen.
Verarbeitungspfad für Suchanfragen im Discovery-Agenten.

Der KI-Agent verwendet die Knowledge Catalog Search API, um relevanteGoogle Cloud -Ressourcen abzurufen. Das folgende Code-Snippet zeigt, wie der Agent die semantische Suche im Knowledge Catalog aufruft:


      # 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}

Hinweis

Damit Sie den Knowledge Catalog-Erkennungs-Agent ausführen können, müssen die folgenden Anforderungen erfüllt sein:

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Google Cloud Projekt iam.gserviceaccount.comzuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung des Discovery-Agents benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die für die Verwendung des Discovery-Agents erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind für die Verwendung des Discovery-Agents erforderlich:

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

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

APIs aktivieren

Wenn Sie den Knowledge Catalog-Discovery-Agent verwenden möchten, aktivieren Sie die folgenden APIs in Ihrem Projekt: Dataplex API, Vertex AI API und Service Usage API.

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

Umgebung einrichten

So richten Sie die Entwicklungsumgebung für den Discovery-Agent ein:

  1. Klonen Sie das dataplex-labs-Repository.

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

  2. Wechseln Sie in das Agentenverzeichnis:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Erstellen und aktivieren Sie eine virtuelle Python-Umgebung und installieren Sie dann die in der Datei requirements.txt aufgeführten Abhängigkeiten:

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

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Richten Sie die Umgebungsvariablen mit dem folgenden Befehl ein:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Ersetzen Sie Folgendes:

    • PROJECT_ID durch die ID Ihres Projekts

Discovery-Agent als Root-Agent ausführen

So führen Sie den Discovery-Agent direkt als Root-Agent aus:

  1. Benennen Sie in der Datei agent.py im Ordner knowledge_catalog_discovery_agent die Variable discovery_agent in root_agent um.

  2. Führen Sie den Agent mit dem Befehl adk run aus:

    adk run path/to/agent/parent/folder

    Ersetzen Sie Folgendes:

    • path/to/agent/parent/folder durch das übergeordnete Verzeichnis, das den Ordner mit Ihrem Agenten enthält. Wenn sich Ihr Agent beispielsweise in knowledge_catalog_discovery_agent/ befindet, führen Sie adk run im Verzeichnis agents/ aus.

Discovery-Agent als Agententool ausführen

So binden Sie den Discovery-Agent in einen größeren benutzerdefinierten Agent wie my_custom_agent ein:

  1. Richten Sie Ihre Projektstruktur so ein, dass sie das Discovery-Agent-Modul enthält:

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

  2. Importieren Sie in der Datei agent.py Ihres benutzerdefinierten KI-Agenten den Discovery-Agenten und verwenden Sie ihn als Agenten-Tool. Beispiel:

    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. Führen Sie den Agent mit dem Befehl adk run aus:

    adk run path/to/agent/parent/folder

    Ersetzen Sie Folgendes:

    • path/to/agent/parent/folder durch das übergeordnete Verzeichnis, das den Ordner my_custom_agent/ enthält. Wenn sich Ihr Agent beispielsweise in agents/my_custom_agent/ befindet, führen Sie adk run im Verzeichnis agents/ aus.

Nächste Schritte