Agent zum Ermitteln Ihrer Daten erstellen

Der Knowledge Catalog-Erkennungsagent 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 Abfrageverständnisses und der Abfrageformulierung liefert er genauere Ergebnisse als die standardmäßige Knowledge Catalog Search API. Diese Funktion ist besonders für komplexe oder lange Abfragen wichtig.

Anwendungsfälle

Der Erkennungsagent bietet eine umfassende, konversationelle Erfahrung für Szenarien wie:

  • Komplexe oder kombinierte Intents und Einschränkungen:Behandeln von Suchanfragen mit mehreren Kriterien, z. B. Suchen nach Datasets in us-central1, aber Ausschließen von Ressourcen in BigQuery.
  • Geschäftsorientierte Suche:Suchen nach Daten-Assets basierend auf Intent und Geschäftskontext anstatt nach genauen technischen Begriffen.
  • Mehrstufige Suche:Verfeinern der Suche durch einen konversationellen Dialog, um die Ergebnisse einzugrenzen.

Der Erkennungsagent basiert auf der semantischen Suche von Knowledge Catalog, die eine sofort einsatzbereite Hybridsuche bietet. Sie können die semantische Suche von Knowledge Catalog weiterhin direkt verwenden, wenn Sie Suchanfragen mit hoher Kaufabsicht (wenn Sie die spezifische Ressource oder Spalte kennen), niedrigen Latenzanforderungen oder eine Hybridsuche ohne Einrichtung verarbeiten müssen.

Funktionsweise

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

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

Das folgende Diagramm enthält die Details des Prozesses:

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

Der Agent verwendet die Knowledge Catalog Search API, um relevante Google Cloud Ressourcen abzurufen. Das folgende Code-Snippet zeigt, wie der Agent die semantische Suche von 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,
          }
      )

      # Extract useful metadata to share with the agent.
      entries = [
          {
              "entry_name": result.dataplex_entry.name,
              "system": result.dataplex_entry.entry_source.system,
              "resource_id": result.dataplex_entry.entry_source.resource,
              "display_name": result.dataplex_entry.entry_source.display_name,
          }
          for result in response.results
      ]

      return {"results": entries}

Hinweis

Damit Sie den Knowledge Catalog-Erkennungsagenten 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 Erkennungsagenten 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 zur Verwendung des Erkennungsagenten erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Für die Verwendung des Erkennungsagenten sind die folgenden Berechtigungen 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-Erkennungsagenten verwenden möchten, aktivieren Sie die folgenden APIs in Ihrem Projekt: 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 Erkennungsagenten ein:

  1. Klonen Sie das dataplex-labs-Repository.

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

  2. Wechseln Sie zum Agentenverzeichnis:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Erstellen und aktivieren Sie eine virtuelle Python-Umgebung und installieren Sie dann die in der requirements.txt Datei 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. Legen Sie die Umgebungsvariablen mit dem folgenden Befehl fest:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Ersetzen Sie Folgendes:

    • PROJECT_ID durch die ID Ihres Projekts

Erkennungsagent als Root-Agent ausführen

So führen Sie den Erkennungsagenten 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 Agenten mit dem adk run Befehl 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 aus dem Verzeichnis agents/ aus.

Erkennungsagent als Sub-Agent ausführen

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

  1. Richten Sie Ihre Projektstruktur so ein, dass sie das Erkennungsagentenmodul 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 Agenten den Erkennungsagenten und verwenden Sie ihn als Agententool. 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 Agenten 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 aus dem Verzeichnis agents/ aus.

Nächste Schritte