Monitora gli endpoint di AI Search

Le metriche degli endpoint di AI Search riportano stato di salute, frequenza di query, latenza, errori per sorgente e tasso di ingestione per le ultime 169 ore. Utilizza queste metriche per monitorare gli endpoint ed eseguire il debug dei problemi. Visualizza le metriche nella scheda Metriche dell'endpoint, oppure recuperale con l'API REST, la CLI di Databricks o l'SDK di Databricks.

Usa le metriche endpoint per:

  • Scopri se le query fallite provengono dall'endpoint del modello di embedding o da AI Search.
  • Vedi perché le query restituiscono errori 429 (Troppe richieste).
  • Controlla se le scritture in un indice avvengono contemporaneamente a picchi di latenza o errori.

Requirements

Visualizza le metriche nell'interfaccia utente

Per visualizzare le metriche di un endpoint:

  1. Nella barra laterale sinistra fare clic su Calcolo.
  2. Fai clic sulla scheda AI Search , quindi clicca sul nome dell'endpoint.
  3. Nella pagina endpoint, fai clic sulla scheda Metriche .
  4. Seleziona un intervallo di tempo: Ultimi 15 minuti, Ultima ora, Ultime 6 ore, Ultimo giorno o Ultima settimana.

La scheda Metriche mostra i seguenti grafici:

Chart Cosa mostra
Stato di integrità Lo stato di salute dell'endpoint nel tempo.
Concorrenza dell'endpoint La concorrenza allocata per l'endpoint.
Richieste al secondo Query al secondo, per percorso (ottimizzato e non ottimizzato).
Tasso di errore (%) La percentuale di query che hanno restituito errori, inclusi 429 errori. Usa il filtro sorgente per vedere da dove provengono gli errori. Consulta "Filtra errori per sorgente".
Latenza della richiesta (ms) Latenza delle query a p50 e p99, per percorso. Usa il filtro per tipo di query per mostrare query ANN,Hybrid o Full-text .
Tasso di ingestione (righe/sec) Righe scritte agli indici dell'endpoint al secondo, per operazione. Solo gli endpoint standard. Vedi Leggi la velocità di ingestione. Quando l'endpoint ha due o più indici, usa il filtro indice per mostrare un indice.

L'immagine seguente mostra il grafico Tasso di errore (%) con il filtro della sorgente degli errori.

Grafico del tasso di errore nella scheda Metriche dell'endpoint AI Search con i filtri Tutto, Incorporamento, Ricerca AI e Sorgente Non Categorizzata.

Filtra gli errori per sorgente

Nel grafico Tasso di errore (%), filtra per fonte di errore:

  • Tutti: ogni richiesta fallita.
  • Embedding: la chiamata all'endpoint del modello di embedding non è riuscita.
  • AI Search: il fallimento è stato causato dall'endpoint AI Search o dalla richiesta stessa, come un filtro non valido o un errore di autorizzazione.
  • Non categorizzato: la fonte del guasto non è stata segnalata. Questo può accadere su endpoint ottimizzati per lo storage, ad esempio quando una query va in timeout.

Gli errori verificatisi prima che il tracciamento sorgente fosse disponibile compaiono solo sotto All.

Leggi la velocità di ingestione

Il grafico Tasso di ingestione (righe/sec) mostra le righe scritte negli indici dell'endpoint tramite pipeline di sincronizzazione e tramite upsert e cancellazioni dirette:

  • Inserimenti, Aggiornamenti e Cancellazioni: righe scritte, per operazione. Questi includono aggiornamenti che non modificano una riga e cancellazioni di righe che non esistono.
  • Totale: la somma degli inserimenti, degli aggiornamenti e delle cancellazioni.
  • Incluse: righe incluse per indici Delta Sync che utilizzano embedding gestiti da Databricks. Se una sincronizzazione si riavvia, le stesse righe contano di nuovo. Le righe incorporate non fanno parte di Total.

Una frequenza di 0 righe al secondo significa che non sono avvenute scrizioni in quell'intervallo. Non significa che l'indice sia aggiornato, e le scritture piccole e poco frequenti potrebbero non comparire.

L'immagine seguente mostra il grafico del tasso di ingestione (righe/sec) per un endpoint con indici Delta Sync.

Grafico del tasso di ingestione nella scheda Metriche dell'endpoint AI Search che mostra righe totali, inserite, aggiornate, cancellate e incorporate al secondo.

Recupera le metriche con l'API

AI Search (precedentemente Vector Search) mantiene il nome Vector Search nel percorso API delle metriche, nel gruppo di comandi CLI e nel servizio Databricks SDK. Per recuperare le metriche in modo programmatico, invia una POST richiesta a /api/2.0/vector-search/endpoints/{name}/metrics. Il corpo della richiesta contiene:

  • start_time (obbligatorio): l'inizio dell'intervallo temporale, come timestamp RFC 3339. Deve essere nelle ultime 169 ore.
  • end_time: la fine dell'intervallo temporale, come timestamp RFC 3339. Il valore predefinito è l'ora corrente.
  • granularity_in_seconds: l'intervallo tra i punti dati. Il minimo è 60. Vedere Limitazioni.
  • metrics: l'elenco delle metriche da restituire. Ogni voce ha un name, opzionale labels, e, per la latenza, un percentile. Vedi Metriche disponibili.

Ogni etichetta ha una name e una value. Il value è un'espressione regolare, non una corrispondenza esatta. Un'etichetta filtra il risultato e lo divide per quell'etichetta, quindi un valore di .+ restituisce una serie per ciascun valore dell'etichetta.

Il seguente esempio serve curl a restituire le query fallite al secondo in una finestra di un'ora, con una serie per ciascuna fonte di errore:

curl -X POST "https://<workspace-url>/api/2.0/vector-search/endpoints/my-endpoint/metrics" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-11-06T20:00:00Z",
    "end_time": "2026-11-06T21:00:00Z",
    "granularity_in_seconds": 60,
    "metrics": [
      {
        "name": "IndexRequestErrorSourceCount",
        "labels": [{ "name": "error_source", "value": ".+" }]
      }
    ]
  }'

La risposta contiene una voce in metric_values per ogni serie. Ogni timestamp è in secondi dall'epoca Unix:

{
  "metric_values": [
    {
      "metric": {
        "name": "IndexRequestErrorSourceCount",
        "labels": [{ "name": "error_source", "value": "EMBEDDING" }]
      },
      "values": [
        { "timestamp": 1793995200, "value": 0.0 },
        { "timestamp": 1793995260, "value": 1.5 }
      ]
    }
  ]
}

Il seguente esempio utilizza l'SDK Databricks per Python per restituire la latenza di query p99 per l'ultimo giorno:

from datetime import datetime, timedelta, timezone

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.vectorsearch import Metric

w = WorkspaceClient()
end = datetime.now(timezone.utc)
start = end - timedelta(days=1)

response = w.vector_search_endpoints.retrieve_user_visible_metrics(
    name="my-endpoint",
    start_time=start.isoformat(),
    end_time=end.isoformat(),
    granularity_in_seconds=300,
    metrics=[Metric(name="IndexRequestLatency", percentile=0.99)],
)

for series in response.metric_values:
    print(series.metric.labels, series.values[-1])

Il databricks-ai-search pacchetto Python non include un metodo metrics. Utilizza l'SDK Databricks, la CLI Databricks o l'API REST.

Il seguente esempio utilizza la CLI Databricks per restituire le righe ingerite al secondo, con una serie per ogni operazione. Passa le metriche con --json:

databricks vector-search-endpoints retrieve-user-visible-metrics my-endpoint --json '{
  "start_time": "2026-11-06T00:00:00Z",
  "metrics": [
    {
      "name": "IndexIngestedRows",
      "labels": [{ "name": "operation", "value": ".+" }]
    }
  ]
}'

L'API non pagina. Il campo page_token della richiesta viene ignorato e la risposta non include un next_page_token. Ogni risposta restituisce tutti i punti dati in un'unica pagina.

Metriche disponibili

Metriche degli endpoint

Le metriche endpoint descrivono l'endpoint nel suo insieme e non accettano etichette.

Metrica Unità Description
EndpointHealthStatus Codice di stato Lo stato endpoint: 0 PROVISIONING, 1 ONLINE, 2 OFFLINE, 3 NOT_READY, 4 RED_STATE, 5 YELLOW_STATE, 6 DELETED, 7 STOPPING, 8 STOPPED, 9 STARTING.
EndpointConcurrency Conteggio La concorrenza allocata per l'endpoint.

Metriche di query

Le metriche di query coprono solo le richieste di query.

Metrica Unità Description
IndexRequestCount Richieste al secondo Il tasso di interrogazione.
IndexRequestLatency Millisecondi Latenza delle query. Richiede percentile: uno di 0.5, 0.75, 0.9, 0.95, o 0.99.

Entrambe le metriche accettano queste etichette:

  • request_path: NETWORK_OPTIMIZED_ROUTE (percorso ottimizzato) oppure HIGH_LATENCY_ROUTE (percorso non ottimizzato). La risposta contiene una serie per ciascun percorso.
  • query_type: ANN, HYBRID, oppure FULL_TEXT.
  • response_code: il codice di stato HTTP, come 200 o 429.
  • index_name: il nome completo dell'indice.

Metrica sorgente di errore

Metrica Unità Description
IndexRequestErrorSourceCount Query non riuscite al secondo Query non riuscite, in base all'origine dell'errore.

L'etichetta error_source contiene questi valori:

Value Nome dell'interfaccia utente Meaning
EMBEDDING Embedding La chiamata all'endpoint del modello di embedding è fallita.
VECTOR_SEARCH AI Search Il fallimento è stato dovuto all'endpoint AI Search o alla richiesta stessa. Usare response_code per separare gli errori del chiamante come 400 o 403 da errori dell'endpoint.
UNATTRIBUTED Non categorizzato La causa del guasto non è stata segnalata. Questo può accadere su endpoint ottimizzati per lo storage, ad esempio quando una query va in timeout.

Questa metrica accetta anche le etichette response_code, request_path, query_type e index_name.

metriche guida 429

Le metriche di guida 429 si applicano agli endpoint standard.

Metrica Unità Description
IndexRequestGuidanceCount Richieste al secondo Query, in base alla causa di eventuali errori 429.
IndexRequestGuidancePeakRate Richieste al secondo La frequenza di richiesta di punta oraria sulla rotta non ottimizzata (HIGH_LATENCY_ROUTE). Esclude il traffico dei percorsi ottimizzati e non accetta etichette.

IndexRequestGuidanceCount accetta l'etichetta failure_cause . Per una risposta diversa da 429, il valore è NONE. Per una risposta 429, il valore è uno di:

Value Meaning
REJECTED L'endpoint ha respinto la query perché la sua coda di richieste era piena.
CIRCUIT_BREAKER L'endpoint è rimasto a corto di memoria e ha respinto la query.
CAPACITY_BLOCK L'endpoint o l'indice ha superato la sua capacità.
PAGINATION Troppi contesti di paginazione aperti.
EMBEDDING_LIMIT L'endpoint del modello di embedding ha applicato un limite di frequenza alla query.
UC_LIMIT La query ha raggiunto un limite di frequenza di Unity Catalog.
TIMEOUT La query è andata in timeout a causa di sovraccarico, di una query lenta o del warmup.
OTHER Qualsiasi altro errore 429.

IndexRequestGuidanceCount accetta anche le auth_type etichette (OAUTH, TOKEN, , oppure OTHER), num_results_bucket (LE_10 o GT_10), request_path, query_type, e index_name le etichette.

Metriche di ingestione

Le metriche di ingestione sono disponibili solo per gli endpoint standard.

Metrica Unità Description
IndexIngestedRows Righe al secondo Righe scritte dalle pipeline Delta Sync e da upsert e cancellazioni Direct Vector Access. Accetta l'etichetta operation (INSERT, UPDATE, oppure DELETE) e l'etichetta index_name .
IndexEmbeddedRows Righe al secondo Righe incorporate negli indici Delta Sync che utilizzano embedding gestiti da Databricks. Una riesecuzione conta di nuovo le stesse righe. Accetta l'etichetta index_name .

Troubleshooting

Errori del modello di embedding

Se la sorgente di errore di Embedding aumenta, verifica l'endpoint del modello di incorporamento. Per instradare le query verso un endpoint dedicato o a throughput provisionato, vedi Risoluzione degli errori 429. Per evitare la chiamata di embedding nel percorso della query, passa query_vector invece di query_text.

Se la sorgente di errore AI Search aumenta, suddividete IndexRequestErrorSourceCount per response_code. Un codice 4xx di solito significa che la richiesta non è valida o non autorizzata. Un codice 429 significa che la query era soggetta a limitazione della frequenza. Per trovare la causa, vedi Queries return 429 errors.

Le query restituiscono 429 errori

Dividi IndexRequestGuidanceCount per failure_cause. EMBEDDING_LIMIT punta all'endpoint del modello di incorporamento. REJECTED, CIRCUIT_BREAKER, e TIMEOUT possono indicare il carico dell'endpoint o la pressione delle risorse. Per la scalabilità del throughput, vedi Scalare il throughput dell'endpoint AI Search con QPS elevato.

Per CAPACITY_BLOCK, controlla l'errore relativo alla capacità dell'endpoint o dell'indice. Riduci il volume di dati indicizzati o contatta il supporto Databricks per aumentare la quota.

Se auth_type visualizza TOKEN, passa a autenticazione OAuth del service principal.

Latenza o errori aumentano durante le sincronizzazioni

Confronta il grafico del tasso di ingestione (righe/sec) con la latenza delle richieste (ms) e il tasso di errore (%). Se i picchi coincidono con le scritture, programma le sincronizzazioni fuori dalle ore di punta delle query o riduci il volume di scrittura.

Il grafico di ingestione non appare

Il grafico appare solo per gli endpoint standard. L'API restituisce is not supported for this endpoint type altri tipi di endpoint e is not available in this region nelle regioni in cui le metriche di ingestione non sono disponibili.

L'API restituisce is not a valid UserVisibleMetricType

Il nome della metrica è scritto in modo errato o non è disponibile. Un nome metrico non valido fa fallire l'intera richiesta, quindi rimuovilo e riprova.

Limitations

  • Le metriche sono disponibili per le ultime 169 ore. Se start_time è più vecchio, la richiesta fallisce.
  • Il minimo granularity_in_seconds è 60. Un intervallo di 1 minuto viene restituito solo per intervalli di tempo di 1 ora o meno. Per intervalli di tempo più lunghi, l'intervallo è di 5 minuti o più.
  • Una serie può contenere al massimo 10.080 punti dati. Se una richiesta supera questo limite, accorcia l'intervallo temporale o aumenta granularity_in_seconds.
  • Le metriche di ingestione sono disponibili solo per gli endpoint standard. Non sono disponibili per endpoint ottimizzati per lo storage.

Risorse aggiuntive