Fehlerbehebung bei Gemini Enterprise-Datenspeichern

Auf dieser Seite können Sie Probleme mit Gemini Enterprise-Datenspeichern diagnostizieren und beheben. Wenn ein Datenspeicher keine Informationen abrufen kann, können Sie das Problem selbst beheben, indem Sie einen zusammenhängenden, schrittweisen Beobachtbarkeitsprozess durchlaufen.

Damit Sie sich ein vollständiges Bild von einem Fehler machen können, sollten Sie wissen, wie die Beobachtbarkeitstools von Google Cloudzusammenarbeiten:

  • Cloud Monitoring: Erkennt, wann ein Problem auftritt. Damit können Sie allgemeine Trends und Fehlerraten ansehen und Benachrichtigungen für Ihre Datenspeicher einrichten.
  • Cloud Trace: Ermittelt, wo das Problem auftritt. Damit können Sie den Lebenszyklus einer Anfrage einsehen, Spans analysieren und genau feststellen, welcher Schritt eine hohe Latenz oder einen Fehler verursacht hat.
  • Cloud Logging: Erklärt, warum das Problem auftritt. Damit können Sie die genauen Fehlermeldungen und Nutzlasten im Zusammenhang mit einer fehlgeschlagenen Anfrage lesen.
  • Cloud-Audit-Logs: Identifiziert, wer oder welche Richtlinie die Aktion blockiert hat. Damit können Sie die Sicherheits-Compliance, Berechtigungsänderungen und administrative Aktionen verfolgen, die möglicherweise zu Zugriffsverweigerungen führen.

Debugging-Workflow

Wenn Sie ein Problem mit einem Datenspeicher untersuchen, gehen Sie so vor, um die Ursache zu isolieren und zu beheben:

  1. Trends bei Fehlerraten prüfen
  2. Fehlgeschlagene Anfrage finden
  3. Fehlernutzlast ansehen
  4. Audit-Logs zur Nutzung abgleichen

  1. Wechseln Sie in der Google Cloud Console zur Seite Metrics Explorer.

    Zum Metrics Explorer

  2. Prüfen Sie Ihre Dashboards und die Anzahl der Datenspeicheranfragen und filtern Sie nach Tool-ID und Engine-ID. So können Sie feststellen, ob es sich um einen einmaligen Fehler oder um ein weit verbreitetes systemisches Problem handelt, das sofortige Aufmerksamkeit erfordert.

Bestimmte fehlgeschlagene Anfrage finden

  1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

  2. Suchen Sie im Streudiagramm nach Traces mit einem Fehlersymbol (einem roten Ausrufezeichen) oder ungewöhnlich hoher Latenz.
  3. Klicken Sie auf einen Trace, um das zugehörige Gantt-Diagramm aufzurufen.
  4. Prüfen Sie den Span invoke_connector, um zu sehen, wo der Prozess ins Stocken geraten oder fehlgeschlagen ist.
  5. Außerdem finden Sie hier das eindeutige Assist-Token, das einer bestimmten Anfrage zugeordnet ist. Wenn Sie ein komplexes Problem an den Support von Google Cloud eskalieren müssen, geben Sie dieses Assist-Token an, um die Untersuchung zu beschleunigen.

Fehlernutzlast ansehen

  1. Klicken Sie im Trace Explorer auf den fehlerhaften Span.
  2. Klicken Sie im Detailbereich auf Logs anzeigen.
  3. Sie werden automatisch zu Cloud Logging weitergeleitet, wobei die Ansicht nach dieser Anfrage gefiltert ist. Hier können Sie die Rohdaten der Log-Nutzlast lesen, um die genaue Fehlersignatur (z. B. RESOURCE_EXHAUSTED oder PERMISSION_DENIED) zu ermitteln.

Audit-Logs zur Nutzung abgleichen

Wenn die Log-Nutzlast auf ein IAM-Problem, einen fehlenden Bereich oder eine verweigerte Berechtigung hinweist, vergleichen Sie die Cloud-Audit-Logs:

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

    Zum Log-Explorer

  2. Prüfen Sie den administrativen Verlauf. Prüfen Sie, ob Ihr Administrator vor Kurzem einen Aktionsfilter geändert oder eine erforderliche Berechtigung widerrufen hat.

Beispiel: Fehlgeschlagene Datenspeicheranfrage verfolgen

Angenommen, ein Nutzer fordert Ihren Gemini Enterprise-Agenten auf, den Status eines Jira-Vorgangs abzurufen, aber der Agent gibt eine allgemeine Fehlermeldung zurück. So verwenden Sie den Beobachtbarkeits-Workflow, um die Ursache zu finden:

  1. Fehlertrends prüfen: Bevor Sie nach einzelnen Fehlern suchen, sollten Sie herausfinden, wie weit verbreitet das Problem ist. Öffnen Sie den Metrics Explorer in Cloud Monitoring und filtern Sie die Messwerte für Datenspeicheranfragen nach tool_id: get_issue. Möglicherweise sehen Sie einen massiven, plötzlichen Anstieg der RESOURCE_EXHAUSTED-Fehler. Das bestätigt, dass es sich um ein systemisches Problem handelt und nicht nur um einen einmaligen Tippfehler des Nutzers.
  2. Fehlgeschlagene Anfrage finden: Öffnen Sie den Trace-Explorer und legen Sie den Zeitfilter auf die letzte Stunde fest. Im Streudiagramm sehen Sie eine Gruppe von Traces mit einem roten Fehlersymbol, das auf Fehler hinweist. Klicken Sie auf einen dieser aktuellen Traces, um ihn zu untersuchen.
  3. Gantt-Diagramm prüfen: Das Gantt-Diagramm visualisiert den Verlauf der Anfrage. Sie sehen einen erfolgreichen übergeordneten Span für das anfängliche Agenten-Routing, aber darunter ist ein fehlerhafter invoke_connector-Span verschachtelt, der speziell auf den Jira Cloud-Datenspeicher abzielt.
  4. Zu Logs wechseln: Klicken Sie auf den fehlerhaften invoke_connector-Span. Klicken Sie im Bereich „Trace-Details“ auf Logs anzeigen.

  5. Ursache ermitteln: Der Log-Explorer wird geöffnet und ist bereits nach der genauen Trace-ID gefiltert. Sie können jetzt die vom Datenspeicher generierte Log-Nutzlast prüfen, um den genauen Fehler zu ermitteln:

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    In dieser Nutzlast-Fehlermeldung sehen Sie das spezifische Tool (get_issue), das fehlgeschlagen ist, und die explizite Meldung, dass der Nutzer, der die Anfrage ausführt, keinen Zugriff auf die spezifische Ressource im Zielsystem hat.

  6. Lösung: Im Abschnitt Häufige Fehler können Sie diesen Fehler als Fehlender Endnutzer-Ressourcenzugriff identifizieren. Der Gemini Enterprise-Agent hat sich erfolgreich mit Jira Cloud verbunden, aber Jira Cloud hat die Anfrage abgelehnt, da der Nutzer nicht über die erforderlichen Berechtigungen verfügt. Bitten Sie Ihren Jira Cloud-Administrator, dem Nutzer Zugriff auf die entsprechende Ressource zu gewähren.

Häufige Fehler

Konzentrieren Sie sich beim Prüfen der Fehler-Nutzlasten in Cloud Logging auf die allgemeinen Fehlersignaturen. Die meisten Datenspeicherfehler können vollständig selbst behoben werden. Suchen Sie den aufgetretenen Fehler in der folgenden Liste, um die Ursache zu ermitteln und das Problem zu beheben.

Authentifizierungs- und Zugriffsfehler

Diese Fehler treten auf, wenn Probleme mit Anmeldedaten, Bereichen oder Verwaltungsrichtlinien den Zugriff auf die erforderlichen Ressourcen verhindern. Wenn diese Fehler auftreten, können Sie Cloud-Audit-Logs verwenden, um kürzlich vorgenommene IAM-Änderungen, Aktualisierungen von Aktionsfiltern oder widerrufene Berechtigungen zu debuggen.

Abgelaufenes oder ungültiges OAuth-Token

  • Fehlersignatur: HTTP request failed with status code 401 / 401 Unauthorized
  • Ursache: Das OAuth-Token ist abgelaufen oder ungültig.
  • Lösung: Autorisieren Sie den Datenspeicher in den Gemini Enterprise-Einstellungen neu, um ein neues Token zu generieren.

Tool durch einen Aktionsfilter blockiert

  • Fehlersignatur: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Ursache: Der Administrator hat das Tool mithilfe eines Aktionsfilters blockiert.
  • Lösung: Der Administrator muss die Zulassungsliste für Aktionen oder Tools aktualisieren.

Fehlende OAuth-Bereiche

  • Fehlersignaturen: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted ODER Cause: Insufficient Permission
  • Ursache: In der Anwendungsregistrierung auf der Drittanbieterplattform fehlen die erforderlichen Bereiche.
  • Lösung: Ein Administrator muss genau die im Protokoll genannten Bereiche gewähren und die App neu autorisieren.

Fehlende IAM-Projektberechtigungen

  • Fehlersignatur: Access Denied: User does not have [permission] / mcp.tools.call permission
  • Ursache: Dem Aufrufer oder Dienstkonto fehlen die erforderlichen Google Cloud IAM-Berechtigungen im Zielprojekt.
  • Lösung: Erteilen Sie dem Aufrufer die genannte IAM-Berechtigung.

Leistungs- und Drosselungsfehler

Diese Fehler werden ausgelöst, wenn das Anfragevolumen die von der Ziel-API oder dem Zieldienst festgelegten Limits überschreitet. Mit Cloud Trace können Sie genau feststellen, wie lange diese gedrosselten Anfragen hängen, bevor sie fehlschlagen.

429-Drosselung von Drittanbieter-APIs

  • Fehlersignatur: Cause: Request has been rate limited
  • Ursache: Sie senden Anfragen schneller, als die Drittanbieter-API zulässt.
  • Lösung: Reduzieren Sie die Anforderungsrate, implementieren Sie Backoff-Strategien oder fordern Sie beim Drittanbieter eine Kontingenterhöhung an.

Schaltfläche „Aktionen aktivieren“ ist nicht sichtbar

  • Fehlersignatur: Der Button Aktionen aktivieren ist nach dem Erstellen eines Datenspeichers in der Console nicht sichtbar oder deaktiviert.
  • Ursache: Der Datenspeicher hat eine eingeschränkte Funktionalität (z. B. nur föderierte Suche, nur Aufnahme oder nur Suche) und unterstützt keine Aktionen.
  • Lösung: Aktionen können für diese Datenspeichertypen nicht aktiviert werden.

Sichtbarkeits- und Ressourcenfehler

Diese Fehler weisen darauf hin, dass die Authentifizierung zwar erfolgreich war, der Nutzer oder die Anwendung jedoch nicht die erforderlichen Berechtigungen hat, um die angeforderten Daten aufzurufen oder mit ihnen zu interagieren.

Einschränkung der Sichtbarkeit für Drittanbieter

  • Fehlersignatur: 422 ... you do not have permission to view [Resource/Users]
  • Ursache: Eine Sichtbarkeitseinschränkung oder Organisationsrichtlinie auf der Drittanbieterplattform verhindert den Datenabruf.
  • Lösung: Passen Sie Ihre Mitgliedschaft in der Drittanbieterorganisation an oder reduzieren Sie das Limit für den Abfragebereich.

Fehlender Zugriff auf Endnutzerressourcen

  • Fehlersignatur: permission denied: [user] does not have access to [Resource]
  • Ursache: Der Endnutzer, der die Anfrage ausführt, hat keinen Zugriff auf die spezifische Komponente oder Ressource im Zielsystem.
  • Lösung: Gewähren Sie dem Nutzer direkt im Zielsystem Zugriff auf die Ressource.

System- und serverseitige Fehler

Diese Fehler sind auf Infrastrukturprobleme, Zeitüberschreitungen oder fehlerhafte Backend-Konfigurationen zurückzuführen und können in der Regel nicht selbst behoben werden.

Langsamer oder überlasteter Drittanbieter-Endpunkt

  • Fehlersignatur: context deadline exceeded
  • Ursache: Der Drittanbieter-Endpunkt ist langsam oder überlastet, was zu einer Zeitüberschreitung der Anfrage auf Google-Seite führt.
  • Lösung: Wiederholen Sie die Anfrage. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Google Cloud -Support, um die Zeitüberschreitung anzupassen.

Fehlerhafte Konfiguration der MCP-Server-Anmeldedatenbindung

  • Fehlersignatur: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Ursache: Es gibt ein serverseitiges Richtlinienproblem, bei dem die Bindung der MCP-Serveranmeldedaten falsch konfiguriert ist. Der Kunde kann hier nichts tun.
  • Lösung: Wenden Sie sich an den Google Cloud Support.

Support anfordern

Wenn ein dauerhafter context deadline exceeded- oder CredsPermissionException-Fehler auftritt, müssen Sie möglicherweise ein Support-Ticket beim Google Cloud Support einreichen.

Damit wir das Problem schneller beheben können, sollten Sie die folgenden Artefakte aus Ihren Beobachtbarkeitstools erfassen, bevor Sie ein Ticket erstellen:

  • Aus Cloud Logging: Die vollständige JSON-Lognutzlast des Fehlers.
  • Aus Cloud Trace: Das Assist-Token und die spezifischen Span-Details (einschließlich Trace-ID), die mit der fehlgeschlagenen Anfrage verknüpft sind.
  • Aus Audit-Logs zur Nutzung: Alle relevanten Zeitstempel für IAM-Änderungen oder Richtlinienänderungen, die das Problem möglicherweise verursacht haben.