Nota: questo set di documentazione è destinato alle versioni Standard, Plus, con pagamento a consumo e Frontline di Gemini Enterprise. Per la documentazione della versione Business, consulta il Centro assistenza di Gemini Enterprise - versione Business.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Risoluzione dei problemi relativi agli archivi dati di Gemini Enterprise

Utilizza questa pagina per diagnosticare e risolvere eventuali problemi relativi ai datastore di Gemini Enterprise. Quando un datastore non riesce a recuperare le informazioni, puoi eseguire il debug del problema in modo indipendente seguendo un percorso di osservabilità coerente e passo passo.

Per avere un quadro completo di un errore, scopri come funzionano insieme gli strumenti di osservabilità di Google Cloud:

Cloud Monitoring: rileva quando si verifica un problema. Utilizzalo per visualizzare le tendenze di alto livello, le percentuali di errore e configurare gli avvisi per i datastore.
Cloud Trace: rileva dove si verifica il problema. Utilizzalo per visualizzare il ciclo di vita di una richiesta, analizzare gli intervalli e identificare esattamente il passaggio che ha causato una latenza elevata o un errore.
Cloud Logging: spiega perché si verifica il problema. Utilizzalo per leggere i messaggi di errore e i payload esatti associati a una richiesta non riuscita.
Cloud Audit Logs: identifica chi o quale criterio ha bloccato l'azione. Utilizzalo per monitorare la conformità alla sicurezza, le modifiche delle autorizzazioni e le azioni amministrative che potrebbero causare rifiuti di accesso.

Workflow di debug

Quando esamini un problema del datastore, segui questo workflow sequenziale per isolare e risolvere la causa principale:

Controlla le tendenze delle percentuali di errore
Trova la richiesta specifica non riuscita
Visualizza il payload di errore
Fai un controllo incrociato degli audit log sull'utilizzo

Controlla le tendenze delle percentuali di errore

Nella Google Cloud console, vai alla pagina Esplora metriche.

Vai a Esplora metriche
Controlla le dashboard ed esamina i conteggi delle richieste del datastore e filtra per ID strumento e ID motore. Puoi determinare se il problema è un errore una tantum o un picco sistemico diffuso che richiede attenzione immediata.

Trova la richiesta specifica non riuscita

Nella Google Cloud console, vai alla Esplora tracce pagina:
Vai a Esplora tracce

Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Esamina il grafico a dispersione per le tracce con un'icona di errore (un punto esclamativo rosso) o una latenza insolitamente elevata.
Fai clic su una traccia per visualizzarne il grafico di Gantt.
Controlla l'intervallo invoke_connector per vedere dove il processo si è bloccato o non è riuscito.
Inoltre, puoi trovare il token di assistenza univoco associato a una richiesta specifica. Se devi inoltrare un problema complesso all'assistenza Google Cloud , condividi questo token di assistenza per accelerare l'indagine.

Visualizza il payload di errore

Fai clic sull'intervallo non riuscito in Esplora tracce.
Nel riquadro dei dettagli, fai clic su Mostra log.
Viene eseguito automaticamente il pivot in Cloud Logging, filtrato in base alla richiesta esatta. Qui puoi leggere il payload del log non elaborato per identificare la firma esatta dell'errore (ad esempio RESOURCE_EXHAUSTED o PERMISSION_DENIED).

Fai un controllo incrociato agli audit log sull'utilizzo

Se il payload del log indica un problema IAM, un ambito mancante o un rifiuto di autorizzazione, fai un controllo incrociato con i Cloud Audit Logs:

Nella Google Cloud console, vai alla pagina Esplora log.

Vai a Esplora log
Esamina la cronologia amministrativa. Verifica se l'amministratore ha modificato di recente un filtro di azioni o ha revocato un'autorizzazione richiesta.

Esempio: Trace una richiesta di datastore non riuscita

Supponiamo che un utente chieda all'agente Gemini Enterprise di ottenere lo stato di un problema di Jira, ma l'agente restituisce un messaggio di errore generico. Ecco come utilizzare il workflow di osservabilità per trovare la causa principale:

Controlla le tendenze degli errori: prima di cercare singoli errori, devi sapere quanto è diffuso il problema. Apri Esplora metriche in Cloud Monitoring e filtra le metriche delle richieste del datastore in base a tool_id: get_issue. Potresti notare un picco improvviso e massiccio di errori RESOURCE_EXHAUSTED. Questo conferma che si tratta di un problema sistemico, non solo di un errore di battitura dell'utente una tantum.
Trova la richiesta non riuscita: apri Esplora tracce e imposta il filtro temporale sull'ultima ora. Nel grafico a dispersione, noterai un cluster di tracce con un'icona di errore rossa che indica errori. Fai clic su una di queste tracce recenti per esaminarla.
Esamina il grafico di Gantt: il grafico di Gantt visualizza il percorso della richiesta. Vedi un intervallo principale riuscito per il routing iniziale dell'agente, ma al suo interno è nidificato un intervallo invoke_connector non riuscito che ha come target specifico il datastore Jira Cloud.
Esegui il pivot ai log: fai clic sull'intervallo invoke_connector non riuscito. Nel riquadro dei dettagli della Trace, fai clic su Mostra log.
Identifica la causa principale: si apre Esplora log, prefiltrato in base all'ID traccia esatto. Ora puoi esaminare il payload del log generato dal datastore per identificare l'errore esatto:
```
"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 questo messaggio di errore del payload, puoi vedere lo strumento specifico (get_issue) che non è riuscito e il messaggio esplicito che indica che l'utente che esegue la richiesta non ha accesso alla risorsa specifica nel sistema di destinazione.
Risolvi: utilizzando la sezione Errori comuni, puoi identificare questo errore come un errore di accesso alle risorse dell'utente finale mancante. L'agente Gemini Enterprise si è connesso correttamente a Jira Cloud, ma Jira Cloud ha rifiutato la query perché l'utente non dispone delle autorizzazioni. Per risolvere il problema, chiedi all'amministratore di Jira Cloud di concedere all'utente l'accesso alla risorsa specifica.

Errori comuni

Quando esamini i payload di errore in Cloud Logging, concentrati sulle firme di errore generali. La maggior parte degli errori del datastore è completamente risolvibile autonomamente. Trova l'errore riscontrato nell'elenco seguente per determinare la causa principale e la correzione.

Errori di autenticazione e accesso

Questi errori si verificano quando si verificano problemi con le credenziali, gli ambiti o i criteri amministrativi che impediscono l'accesso alle risorse richieste. Se riscontri questi errori, Cloud Audit Logs è utile per eseguire il debug delle modifiche IAM recenti, degli aggiornamenti dei filtri di azioni o delle autorizzazioni revocate.

Token OAuth scaduto o non valido

Firma dell'errore: HTTP request failed with status code 401 / 401 Unauthorized
Causa principale: il token OAuth è scaduto o non è valido.
Soluzione: autorizza di nuovo il datastore nelle impostazioni di Gemini Enterprise per generare un nuovo token.

Strumento bloccato da un filtro di azioni

Firma dell'errore: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
Causa principale: l'amministratore ha bloccato lo strumento utilizzando un filtro di azioni.
Soluzione: l'amministratore deve aggiornare la lista consentita di azioni o strumenti.

Ambiti OAuth mancanti

Firme dell'errore: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted OR Cause: Insufficient Permission
Causa principale: la registrazione dell'applicazione nella piattaforma di terze parti non include gli ambiti richiesti.
Soluzione: un amministratore deve concedere gli ambiti esatti indicati nel log e autorizzare di nuovo l'app.

Autorizzazioni IAM del progetto mancanti

Firma dell'errore: Access Denied: User does not have [permission] / mcp.tools.call permission
Causa principale: il chiamante o account di servizio non dispone delle autorizzazioni Google Cloud IAM richieste nel progetto di destinazione.
Soluzione: concedi l'autorizzazione IAM denominata al chiamante.

Errori di prestazioni e limitazione

Questi errori vengono attivati quando i volumi di richieste superano i limiti impostati dall'API o dal servizio di destinazione. Cloud Trace ti aiuta a identificare esattamente per quanto tempo queste richieste limitate rimangono in sospeso prima di non riuscire.

Limitazione API di terze parti 429

Firma dell'errore: Cause: Request has been rate limited
Causa principale: stai inviando richieste più velocemente di quanto consentito dall'API di terze parti.
Soluzione: riduci il tasso di richieste, implementa strategie di backoff o richiedi un aumento della quota al fornitore di terze parti.

Errori di visibilità e risorse

Questi errori indicano che, sebbene l'autenticazione possa essere riuscita, l'utente o l'applicazione non dispone dei diritti specifici per visualizzare o interagire con i dati richiesti.

Limitazione della visibilità di terze parti

Firma dell'errore: 422 ... you do not have permission to view [Resource/Users]
Causa principale: una limitazione della visibilità o un criterio dell'organizzazione nella piattaforma di terze parti impedisce il recupero dei dati.
Soluzione: modifica l'appartenenza all'organizzazione di terze parti o riduci il limite dell'ambito della query.

Accesso alle risorse dell'utente finale mancante

Firma dell'errore: permission denied: [user] does not have access to [Resource]
Causa principale: l'utente finale che esegue la richiesta non ha accesso al componente o alla risorsa specifica nel sistema di destinazione.
Soluzione: concedi all'utente l'accesso alla risorsa direttamente nel sistema di destinazione.

Errori di sistema e lato server

Questi errori sono dovuti a problemi di infrastruttura, timeout o configurazioni errate del backend e in genere non sono risolvibili autonomamente.

Endpoint di terze parti lento o sovraccarico

Firma dell'errore: context deadline exceeded
Causa principale: l'endpoint di terze parti è lento o sovraccarico, il che causa il timeout della richiesta lato Google.
Soluzione: riprova a inviare la richiesta. Se l'errore persiste, contatta Google Cloud l'assistenza per la regolazione del timeout.

Configurazione errata del binding delle credenziali del server MCP

Firma dell'errore: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
Causa principale: si è verificato un problema con i criteri lato server in cui la configurazione del binding delle credenziali del server MCP è errata. Questa azione non è eseguibile dal cliente.
Soluzione: contatta l' Google Cloud assistenza.

Assistenza

Se riscontri un errore persistente context deadline exceeded o CredsPermissionException, potresti dover inviare una ticket di assistenza all'assistenza Google Cloud .

Per accelerare la risoluzione, raccogli i seguenti artefatti dagli strumenti di osservabilità prima di aprire una richiesta:

Da Cloud Logging: il payload del log JSON completo dell'errore.
Da Cloud Trace: il token di assistenza e i dettagli specifici dell'intervallo (incluso l'ID traccia) associati alla richiesta non riuscita.
Dagli audit log sull'utilizzo: eventuali timestamp di modifiche IAM o modifiche dei criteri pertinenti che potrebbero aver attivato il problema.

Risoluzione dei problemi relativi agli archivi dati di Gemini Enterprise Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.