Osservabilità per basi di conoscenza gestite

Per una knowledge base gestita, Amazon Bedrock pubblica metriche operative e log di ingestione AWS sul tuo account in modo che tu possa monitorare lo stato e l'utilizzo della tua knowledge base. Le metriche di runtime consentono di tenere traccia del volume delle richieste, degli errori e delle limitazioni per le operazioni API della knowledge base, mentre i log di importazione consentono di tenere traccia dello stato dei singoli documenti durante un processo di inserimento dei dati. Le sezioni seguenti descrivono i dati di osservabilità disponibili e come accedervi.

Metriche di runtime per le knowledge base gestite

Amazon Bedrock pubblica i parametri di runtime per le operazioni API della tua knowledge base su Amazon CloudWatch sotto lo spazio dei nomi. AWS/Bedrock/KnowledgeBases Utilizza questi parametri per monitorare il volume delle chiamate, i tassi di errore e la limitazione per operazioni come. Retrieve Le metriche vengono pubblicate sul tuo account senza costi aggiuntivi e vengono visualizzate nella console. CloudWatch

La tabella seguente descrive i parametri di runtime pubblicati da Amazon Bedrock per le knowledge base gestite.

Nome parametro	Unità	Description
Invocazioni	Conteggio	Numero di richieste all'operazione della knowledge base. Questa metrica viene pubblicata per ogni richiesta, incluse le richieste che generano un errore.
ClientErrors	Conteggio	Numero di richieste che hanno provocato un errore sul lato client (una 4xx risposta HTTP diversa dalla limitazione).
ServerErrors	Conteggio	Numero di richieste che hanno provocato un errore sul lato server (una risposta HTTP). 5xx
Throttles	Conteggio	Numero di richieste che sono state limitate (una risposta HTTP). 429 Le richieste limitate non vengono conteggiate come o. ClientErrors ServerErrors

Le Throttles metriche ClientErrorsServerErrors, e vengono pubblicate solo quando si verifica la condizione corrispondente. La Invocations metrica viene pubblicata per ogni richiesta.

Metrica aggiuntiva per l'operazione AgenticRetrieveStream

Oltre alle metriche nella tabella precedente, l'AgenticRetrieveStreamoperazione pubblica la metrica seguente.

Nome parametro	Unità	Description
TotalIterationCount	Conteggio	Il numero totale di iterazioni di recupero agentico eseguite durante la richiesta. Questa metrica viene pubblicata solo per l'AgenticRetrieveStreamoperazione, quando la richiesta viene completata correttamente.

Questa metrica utilizza la Operation dimensione con un valore di. AgenticRetrieveStream

Dimensioni per le metriche della knowledge base gestita

Amazon Bedrock utilizza le seguenti dimensioni per i parametri di runtime della Knowledge Base gestita.

Dimensione	Description
Operation	L'operazione dell'API della knowledge base per cui è pubblicata la metrica. I valori possibili sono Retrieve e AgenticRetrieveStream.
KnowledgeBaseId	La knowledge base a cui si rivolge la richiesta, nel formatoknowledge-base/knowledge-base-id. Questa dimensione è inclusa nell'Retrieveoperazione, che si rivolge a un'unica base di conoscenza. Le operazioni che non riguardano una singola base di conoscenza vengono pubblicate solo con la Operation dimensione.

Autorizzazioni per la pubblicazione delle metriche

Amazon Bedrock pubblica queste metriche sul tuo account utilizzando le credenziali associate alla richiesta:

• Per l'Retrieveoperazione, Amazon Bedrock utilizza il ruolo di servizio della knowledge base.

• Per altre operazioni, Amazon Bedrock utilizza le credenziali dell'identità chiamante (l'utente o il ruolo IAM che chiama l'operazione), tramite una sessione di accesso diretto.

Affinché le metriche possano essere pubblicate, è necessario consentire a tale identità di cloudwatch:PutMetricData richiedere il namespace. AWS/Bedrock/KnowledgeBases Allega una policy che conceda questa autorizzazione al ruolo del servizio della Knowledge Base e a qualsiasi identità che richiama le operazioni della Knowledge Base. L'esempio seguente concede l'autorizzazione richiesta.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "cloudwatch:PutMetricData",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "cloudwatch:namespace": "AWS/Bedrock/KnowledgeBases"
                }
            }
        }
    ]
}

La pubblicazione metrica è la soluzione migliore. Se l'identità non dispone dell'autorizzazione richiesta, le metriche corrispondenti non vengono pubblicate, ma la richiesta della Knowledge Base stessa non ne risente.

Visualizza le metriche di runtime

Puoi ottenere le metriche per la tua knowledge base con Console di gestione AWS AWS CLI, l'o l' CloudWatch API. Puoi utilizzare l' CloudWatch API tramite uno dei AWS Software Development Kit (SDK) o gli CloudWatch strumenti API.

Per visualizzare le metriche della Knowledge Base gestita nella CloudWatch console, vai alla sezione delle metriche nel riquadro di navigazione e seleziona l'opzione tutte le metriche, quindi cerca lo spazio dei nomi. AWS/Bedrock/KnowledgeBases

Devi disporre delle CloudWatch autorizzazioni appropriate per monitorare la tua knowledge base. CloudWatch Per ulteriori informazioni, consulta Authentication and Access Control for Amazon CloudWatch nella Amazon CloudWatch User Guide.

Parametri di storage per basi di conoscenza gestite

Per una knowledge base gestita, Amazon Bedrock pubblica una metrica di storage su Amazon CloudWatch nel namespace. AWS/Bedrock/KnowledgeBases Questa metrica riporta la dimensione grezza totale dei dati di origine archiviati nella knowledge base e viene pubblicata sul tuo account dopo il completamento di un processo di inserimento dei dati, in modo che tu possa tenere traccia della quantità di dati archiviata nella tua knowledge base nel tempo.

La tabella seguente descrive i parametri di storage pubblicati da Amazon Bedrock per le knowledge base gestite.

Nome parametro	Unità	Description
RawDataSize	Gigabyte	La dimensione grezza totale dei dati di origine archiviati nella knowledge base, in gigabyte. Questa metrica viene pubblicata dopo il completamento di un processo di inserimento dei dati.

La metrica di archiviazione utilizza la KnowledgeBaseId dimensione, nel formato. knowledge-base/knowledge-base-id

Osservabilità dell'ingestione per basi di conoscenza gestite

Amazon Bedrock emette log che tracciano lo stato di avanzamento di un processo di inserimento dati per la tua knowledge base gestita, incluso lo stato generale del lavoro e lo stato di ogni documento elaborato. Puoi utilizzare questi log per confermare quali documenti sono stati importati, scoprire perché un documento non è stato restituito nei risultati di recupero e risolvere i problemi di inserimento.

I log vengono consegnati a una destinazione configurata dall'utente (CloudWatch Logs, Amazon S3 o Amazon Data Firehose). Le sezioni seguenti descrivono come abilitare la consegna dei log, il ciclo di vita di un documento durante l'ingestione, i tipi di log che vengono emessi e le query di esempio.

Abilita la consegna dei log di ingestione

Per ricevere i log di ingestione, configura una consegna dei log per la tua knowledge base utilizzando l'API o l'API. Console di gestione AWS CloudWatch Puoi distribuire i log a CloudWatch Logs, Amazon S3 o Amazon Data Firehose.

Abilita la consegna dei log utilizzando la console

1. Apri la tua knowledge base: nella console Amazon Bedrock, apri la knowledge base gestita che desideri monitorare.

2. Aggiungi una consegna di log: modifica la knowledge base per aggiungere una consegna di log e configura i seguenti dettagli:

   • La destinazione di registrazione (CloudWatch Logs, Amazon S3 o Amazon Data Firehose).

   • (CloudWatch Registri) Il nome del gruppo di log.

   • (Amazon S3) Il nome del bucket.

   • (Amazon Data Firehose) Lo stream Firehose.

3. Conferma lo stato di consegna: verifica che lo stato di consegna del registro sia Delivery active nella console.

Abilita la consegna dei log utilizzando l' CloudWatch API

1. Ottieni l'ARN della tua knowledge base: chiama l'GetKnowledgeBaseAPI per ottenere l'Amazon Resource Name (ARN) della knowledge base. L'ARN di una knowledge base ha il seguente formato:. arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge-base-id

2. Chiamata PutDeliverySource: Utilizza l'PutDeliverySourceAPI per creare una fonte di distribuzione per la knowledge base. Passa l'ARN della knowledge base come resourceArn e specifica APPLICATION_LOGS come. logType

   {
       "logType": "APPLICATION_LOGS",
       "name": "my-knowledge-base-delivery-source",
       "resourceArn": "arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge_base_id"
   }

3. Chiamata PutDeliveryDestination: utilizza l'PutDeliveryDestinationAPI per configurare dove vengono archiviati i log. Specificare l'ARN di una destinazione CloudWatch Logs, Amazon S3 o Amazon Data Firehose. Puoi impostare su outputFormatjson,,plain, w3c o. raw parquet

   {
      "deliveryDestinationConfiguration": {
         "destinationResourceArn": "arn:aws:s3:::bucket-name"
      },
      "name": "my-knowledge-base-delivery-destination",
      "outputFormat": "json"
   }

   Se stai consegnando i log a un altro account, utilizza l'PutDeliveryDestinationPolicyAPI per allegare una policy AWS Identity and Access Management (IAM) all'account di destinazione.

4. Chiamata CreateDelivery: utilizza l'CreateDeliveryAPI per collegare l'origine di consegna alla destinazione di consegna.

   {
      "deliveryDestinationArn": "string",
      "deliverySourceName": "my-knowledge-base-delivery-source"
   }

Tipi di log e autorizzazioni supportati

Le knowledge base gestite supportano i seguenti tipi di log:

• APPLICATION_LOGS: registri che tengono traccia dello stato del processo di inserimento e di ogni documento elaborato durante il lavoro.

• TRACES: tracce distribuite (intervalli) per le operazioni di runtime. Le tracce vengono emesse solo per l'Retrieveoperazione e vengono consegnate a. AWS X-Ray Per ulteriori informazioni, consulta Traccia l'osservabilità per basi di conoscenza gestite.

Per abilitare la consegna dei log, l'utente o il ruolo devono disporre dell'bedrock:AllowVendedLogDeliveryForResourceautorizzazione per la risorsa della knowledge base, oltre alle autorizzazioni necessarie per scrivere nella destinazione scelta. Ad esempio, le politiche IAM per ciascuna destinazione, consulta le autorizzazioni dei registri di vendita per diverse destinazioni di consegna nella Amazon CloudWatch Logs User Guide.

Ciclo di vita del documento durante l'ingestione

Durante un processo di inserimento dei dati, ogni documento attraversa tre fasi e il registro del documento registra lo stato di ciascuna fase:

• Crawl (crawl_status): Amazon Bedrock recupera il documento dall'origine dati e determina se deve essere aggiunto, aggiornato o eliminato. Il crawl_action campo è impostato suADD, DELETE o. UNMODIFIED Un documento che UNMODIFIED viene ignorato nelle fasi rimanenti.

• Sync (sync_status): il documento viene inviato per l'elaborazione nella knowledge base.

• Index (index_status): il documento è suddiviso in blocchi, incorporato e mantenuto nella knowledge base. Il chunk_statistics campo riassume i blocchi che sono stati creati o eliminati.

Lo stato di ogni fase è o. SUCCESS FAILED Il connector_document_status campo riporta lo stato consolidato del documento e viene compilato solo quando un documento non viene elaborato. error_message

Tipi di log ed esempi

Amazon Bedrock emette due tipi di voci di registro per un processo di inserimento di una knowledge base gestita, distinte per il campo: event_type

• StartIngestionJob.StatusChanged— log a livello di processo che registrano lo stato di avanzamento dell'intero processo di ingestione, ad esempio l'inizio e il completamento della scansione. Il message campo contiene uno stato leggibile dall'uomo, ad esempio o. Crawling started Crawling completed

• StartIngestionJob.ResourceStatusChanged— registri a livello di documento che registrano lo stato di elaborazione di un singolo documento.

Di seguito è riportato un esempio di registro dello stato a livello di processo.

{
    "event_timestamp": 1718677300000,
    "event": {
        "ingestion_job_id": "<IngestionJobId>",
        "data_source_id": "<DataSourceId>",
        "knowledge_base_arn": "arn:aws:bedrock:<region>:<accountId>:knowledge-base/<KnowledgeBaseId>",
        "message": "Crawling started"
    },
    "event_version": "1.0",
    "event_type": "StartIngestionJob.StatusChanged",
    "level": "INFO"
}

Di seguito è riportato un esempio di registro a livello di documento che registra lo stato di elaborazione di un singolo documento.

{
    "event_timestamp": 1718677342332,
    "event": {
        "ingestion_job_id": "<IngestionJobId>",
        "data_source_id": "<DataSourceId>",
        "knowledge_base_arn": "arn:aws:bedrock:<region>:<accountId>:knowledge-base/<KnowledgeBaseId>",
        "document_id": "<DocumentId>",
        "source_uri": "<SourceUri>",
        "content_type": "<ContentType>",
        "crawl_action": "ADD" | "DELETE" | "UNMODIFIED",
        "index_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "crawl_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "sync_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "chunk_statistics": {
            "created": int,
            "deleted": int,
            "failed_to_create": int,
            "failed_to_delete": int
        },
        "error_message": "<ErrorMessage>"
    },
    "event_version": "1.0",
    "event_type": "StartIngestionJob.ResourceStatusChanged",
    "level": "INFO" | "ERROR"
}

Il error_message campo è presente solo quando un documento non viene elaborato. Il chunk_statistics campo riassume i blocchi che sono stati creati o eliminati per il documento.

Alcuni registri a livello di documento riportano un messaggio di stato del connettore anziché i campi di stato mostrati sopra. Questi registri includono un message campo con una descrizione leggibile dall'uomo (ad esempio, un messaggio che indica che un documento non può essere recuperato o eliminato) e un segno di, o. level INFO WARN ERROR

Query di esempio

Se invii log a Logs, puoi usare CloudWatch Logs Insights per interrogare i CloudWatch log di ingestione per la tua knowledge base. Di seguito sono riportate alcune domande comuni.

• Elenca tutti i documenti che non sono stati elaborati durante l'importazione, con i relativi messaggi di errore.

  filter event.connector_document_status.Status = "FAILED" | fields event.document_id, event.source_uri, event.error_message, @timestamp | sort @timestamp desc

• Trova tutte le voci di registro di un documento specifico in base alla posizione di origine.

  filter event.source_uri = "s3://<bucketName>/<objectKey>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc

• Elenca tutti i documenti elaborati da uno specifico processo di inserimento.

  filter event.ingestion_job_id = "<IngestionJobId>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc

• Visualizza lo stato di avanzamento complessivo di un processo di ingestione, incluso l'inizio e il completamento della scansione.

  filter event_type = "StartIngestionJob.StatusChanged" | fields event.message, @timestamp | sort @timestamp asc

Traccia l'osservabilità per basi di conoscenza gestite

Amazon Bedrock può emettere tracce distribuite (span) per le operazioni di runtime della knowledge base in modo da poter analizzare la latenza della richiesta e le fasi interne di una richiesta. Le tracce vengono emesse solo per l'Retrieveoperazione e vengono consegnate a. AWS X-Ray Trace Delivery utilizza la stessa pipeline di consegna dei log forniti utilizzata per i log di ingestione, con il tipo di TRACES registro e una destinazione di consegna. X-Ray

Abilita la consegna delle tracce utilizzando l'API CloudWatch

Per inviare tracce a AWS X-Ray, utilizza l' CloudWatch API per creare una consegna, seguendo questi passaggi.

1. Chiamata PutDeliverySource: utilizza l'PutDeliverySourceAPI per creare una fonte di consegna per la knowledge base. Passa l'ARN della knowledge base come resourceArn e specifica TRACES come. logType

2. Chiamata PutDeliveryDestination: utilizza l'PutDeliveryDestinationAPI con un deliveryDestinationType diXRAY. X-Ray è una destinazione gestita, quindi non si specifica undestinationResourceArn. Nota l'ARN restituito nella risposta.

3. Chiamata CreateDelivery: utilizza l'CreateDeliveryAPI per collegare il nome della fonte di consegna all'ARN della destinazione di X-Ray consegna.

Nota

Queste chiamate API sono idempotenti. Se una risorsa esiste già, puoi tranquillamente ignorare un o. ConflictException ResourceAlreadyExistsException

Autorizzazioni per la tracciabilità

Per abilitare l'invio della traccia, l'utente o il ruolo devono disporre dell'bedrock:AllowVendedLogDeliveryForResourceautorizzazione per la risorsa della knowledge base, oltre alle autorizzazioni necessarie per la consegna a. AWS X-Ray

Visualizza le tracce

Dopo aver abilitato l'invio delle tracce, richiama l'Retrieveoperazione per generare le tracce, quindi visualizzale nella AWS X-Ray console.

AgentCore osservabilità per le basi di conoscenza gestite

Amazon Bedrock integra i dati di osservabilità della knowledge base gestita con l'esperienza di osservabilità di Amazon Bedrock AgentCore, offrendoti una visione consolidata delle metriche e delle tracce della tua knowledge base insieme agli altri dati di telemetria. AgentCore

Non è richiesta alcuna configurazione aggiuntiva per questa integrazione. Dopo aver abilitato le metriche di runtime e la distribuzione delle tracce come descritto nelle sezioni precedenti, la pagina di AgentCore osservabilità viene compilata automaticamente con i dati della knowledge base corrispondenti. Non ci sono azioni aggiuntive da intraprendere.

Nota

AgentCore l'integrazione dell'osservabilità è disponibile solo per le basi di conoscenza gestite.

Assistenza clienti e risoluzione dei problemi

Amazon Bedrock Managed Knowledge Bases archivia temporaneamente le richieste dei clienti e i dati di recupero associati esclusivamente per fornire supporto di debug in risposta ai problemi segnalati dai clienti. AWS non accede a questi dati a meno che il cliente non acconsenta esplicitamente durante un intervento di supporto. Amazon Bedrock non utilizza questi dati per addestrare o migliorare i modelli sottostanti.