Agent zum Ermitteln Ihrer Daten erstellen

Der Knowledge Catalog-Erkennungs-Agent ist ein KI-basierter Assistent, der die Suchrelevanz für komplexe Anfragen in natürlicher Sprache auf Grundlage der Knowledge Catalog-Suchfunktionen verbessert. Durch die Optimierung des Verständnisses und der Formulierung von Anfragen liefert sie genauere Ergebnisse als die standardmäßige Knowledge Catalog Search API. Diese Funktion ist besonders wichtig für komplexe oder lange Anfragen.

Anwendungsfälle

Der Discovery-Agent bietet eine umfassende, dialogorientierte Erfahrung für Szenarien wie die folgenden:

  • Komplexe oder kombinierte Intentionen und Einschränkungen:Verarbeitung von Suchanfragen mit mehreren Kriterien, z. B. Datasets in us-central1 finden, aber Ressourcen in BigQuery ausschließen.
  • Geschäftsorientierte Suche:Datenassets werden auf Grundlage von Intention und Geschäftskontext ermittelt, anstatt dass exakte technische Begriffe abgeglichen werden.
  • Suche in mehreren Schritten:Sie können Ihre Suche durch einen Dialog verfeinern, um die Ergebnisse einzugrenzen.

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

Funktionsweise

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

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

Das folgende Diagramm enthält die Details des Prozesses:

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

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 Discovery-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 zum Verwenden 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, müssen Sie die folgenden APIs in Ihrem Projekt aktivieren: Knowledge Catalog API, Vertex AI API und Service Usage API.

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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 Agent-Verzeichnis:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Erstellen und aktivieren Sie eine virtuelle Python-Umgebung und installieren Sie dann die im requirements.txt-Dokument 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

Erkennungs-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.

Erkennungs-Agent als Agent-Tool ausführen

So integrieren Sie den Discovery-Agenten in einen größeren benutzerdefinierten Agenten wie my_custom_agent:

  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 agent.py-Datei Ihres benutzerdefinierten Agents den Discovery-Agent und verwenden Sie ihn als Agent-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