Aumenta il throughput dell'endpoint di AI Search con QPS elevato

Per impostazione predefinita, gli endpoint standard supportano 20-200 QPS a seconda delle dimensioni dell'indice. Le applicazioni in tempo reale, come ad esempio barre di ricerca, sistemi di raccomandazione e corrispondenza delle entità, richiedono spesso 100-1000+ QPS. Solo sugli endpoint standard è possibile impostare un QPS di destinazione. Databricks effettua il provisioning dell'infrastruttura in modo che corrisponda al livello di velocità effettiva (il massimo sforzo, non garantito).

Usare un livello di QPS elevato quando:

• L'applicazione richiede più di 50 QPS di velocità effettiva sostenuta.
• Si ricevono errori 429 (troppe richieste) con carico normale.
• La latenza si riduce man mano che il traffico aumenta, anche quando l'utilizzo medio risulta basso.

Requisiti

• QPS elevato è disponibile solo per gli endpoint standard. Gli endpoint ottimizzati per l'archiviazione non sono supportati.
• Usare l'autenticazione OAuth del service principal e l'URL dell'indice per carichi di lavoro di produzione con QPS elevato. I token di accesso personale (PAT) e l'URL di query del workspace sono adatti alla prototipazione, ma non usano il percorso di query ottimizzato e sono limitati a poche decine di QPS.
• Per gli indici di sincronizzazione Delta che usano modelli di incorporamento gestiti per le query di testo, la route di query ottimizzata non è disponibile quando l'area di lavoro usa elenchi di accesso IP o connettività privata, ad esempio collegamento privato di Azure. In tale configurazione, l'endpoint potrebbe non raggiungere il QPS di destinazione configurato.

Configura il QPS di destinazione

Impostare un QPS di destinazione durante la creazione di un nuovo endpoint o l'aggiornamento di uno esistente. Viene effettuato automaticamente il provisioning della capacità aggiuntiva necessaria per soddisfare al meglio la velocità effettiva di destinazione. La scalabilità del throughput è fornita in modalità best effort e non è garantita: il QPS effettivo dipende dalle dimensioni dell'indice, dalla dimensionalità dei vettori, dalla complessità delle query e dall'uso dei filtri.

Interfaccia utente di Databricks

Quando si crea un nuovo endpoint:

1. Nella barra laterale sinistra fare clic su Calcolo.

2. Fare clic sulla scheda Ricerca intelligenza artificiale e fare clic su Crea endpoint.

   

3. In Impostazioni avanzate immettere il valore QPS di destinazione .

   

Quando si aggiorna un endpoint esistente:

1. Vai alla pagina dei dettagli dell'endpoint.

2. Nel pannello destro, fare clic sull'icona a forma di matita accanto a Target QPS.

   

3. Immettere il nuovo valore e fare clic su Salva.

   

PYTHON SDK

from databricks.ai_search.client import AISearchClient

client = AISearchClient()

# Create a new endpoint with target QPS
endpoint = client.create_endpoint(
    name="my-high-qps-endpoint",
    endpoint_type="STANDARD",
    target_qps=500,
)

# Update an existing endpoint's target QPS
response = client.update_endpoint(name="my-endpoint", target_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"Requested target QPS: {scaling_info.get('requested_target_qps')}")
print(f"State: {scaling_info.get('state')}")
# State is "SCALING_CHANGE_IN_PROGRESS" while capacity is being provisioned,
# then transitions to "SCALING_CHANGE_APPLIED"

REST API

Creare un endpoint con QPS di destinazione:

POST /api/2.0/vector-search/endpoints
{
  "name": "my-high-qps-endpoint",
  "endpoint_type": "STANDARD",
  "target_qps": 500
}

Aggiorna il QPS target di un endpoint esistente:

PATCH /api/2.0/vector-search/endpoints/<ENDPOINT_NAME>
{
  "target_qps": 500
}

Controllare lo stato di ridimensionamento:

GET /api/2.0/vector-search/endpoints/<ENDPOINT_NAME>

Il campo di risposta scaling_info mostra requested_target_qps e il ridimensionamento state. Lo stato è SCALING_CHANGE_IN_PROGRESS durante il provisioning della capacità, quindi passa a SCALING_CHANGE_APPLIED.

Eseguire una query sull'URL dell'indice

Dopo che lo stato di ridimensionamento dell'endpoint è SCALING_CHANGE_APPLIED, inviare query all'URL dell'indice utilizzando un token OAuth di un'entità di servizio. Questo URL è necessario per utilizzare la capacità di query aggiuntiva messa a disposizione da target_qps.

Per le applicazioni Python, chiamare get_index() una sola volta e riutilizzare l'oggetto indice restituito. L'SDK di Python invia query all'URL dell'indice.

from databricks.ai_search.client import AISearchClient

client = AISearchClient(
    service_principal_client_id="...",
    service_principal_client_secret="...",
    workspace_url="https://<workspace-url>",
)

index = client.get_index(endpoint_name="my-high-qps-endpoint", index_name="catalog.schema.index")

# Reuse this index object for every query.
index.similarity_search(query_vector=[...], columns=["id", "text"], num_results=10)

Per le applicazioni REST o non Python, ottenere prima l'URL dell'indice, quindi inviare richieste di query a tale URL. Il token deve essere un token OAuth di un service principal.

export WORKSPACE_URL=https://<workspace-url>
export INDEX_NAME=catalog.schema.index
export TOKEN=<oauth-token>

export INDEX_URL=$(curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "$WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME" \
  | jq -r '.status.index_url')

case "$INDEX_URL" in
  http://*|https://*) ;;
  *) INDEX_URL="https://$INDEX_URL" ;;
esac

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$INDEX_URL/query" \
  --data '{"num_results": 10, "query_vector": [...], "columns": ["id", "text"]}'

Non utilizzare l'URL di query del workspace, ad esempio /api/2.0/vector-search/indexes/<index_name>/query, per traffico di produzione con QPS elevato. Tale URL non usa la route di query ottimizzata e potrebbe restituire errori 429 prima che l'endpoint raggiunga il QPS di destinazione configurato.

Come si applica il ridimensionamento

Dopo aver impostato un QPS di destinazione, viene effettuato automaticamente il provisioning della capacità necessaria. Il nuovo livello di velocità effettiva viene applicato al termine del provisioning; non è necessario sincronizzare gli indici per attivare la modifica.

Risolvere i problemi relativi agli errori 429

Per i carichi di lavoro con QPS elevato, utilizza questi controlli per individuare il collo di bottiglia:

• Se si usa un PAT o l'URL di query del workspace, passare all'autenticazione OAuth del service principal e all'URL dell'indice.
• Se scaling_info.state è SCALING_CHANGE_IN_PROGRESS, attendere che lo stato cambi in SCALING_CHANGE_APPLIED.
• Se l'applicazione invia query vettoriali con query_vector, il modello di incorporamento non si trova nel percorso della query. Se gli errori 429 continuano dopo il completamento del ridimensionamento, ridurre la concorrenza delle richieste o impostare un valore superiore target_qps.
• Se l'applicazione invia query testuali a un indice Delta Sync con modelli di embedding gestiti da Databricks, il modello di embedding potrebbe essere il collo di bottiglia. Usare un modello di embedding più piccolo, ad esempio databricks-qwen3-embedding-0-6b, invece di databricks-gte-large-en, oppure usare un endpoint delle API di Foundation Model con throughput provisionato o un altro endpoint dedicato di Model Serving per gli embedding.

Limitations

• Nessuna scalabilità automatica: è necessario impostare manualmente QPS di destinazione in base al traffico previsto. Se il traffico supera il livello previsto, si verificano errori 429. Vedere Pianificare i picchi di query.
• Solo endpoint standard: gli endpoint ottimizzati per l'archiviazione non supportano target_qps.
• Percorso ottimizzato obbligatorio: il QPS di destinazione configurato si applica al traffico che utilizza l'autenticazione OAuth del service principal e l'URL dell'indice. Il traffico PAT e il traffico url di query dell'area di lavoro sono limitati a poche decine di QPS.
• I modelli di incorporamento gestiti possono aggiungere un secondo limite: per gli indici di Sincronizzazione Delta che usano un modello di incorporamento gestito per le query di testo, la velocità effettiva delle query dipende anche dall'endpoint di gestione del modello di incorporamento. Aumentare la capacità di gestione del modello, usare la velocità effettiva con provisioning o usare incorporamenti autogestito per una velocità effettiva delle query prevedibile.