Configurare Unity AI Gateway nei modelli che servono gli endpoint

Questo articolo illustra come configurare Unity AI Gateway in un endpoint di gestione del modello.

Requirements

• Un'area di lavoro di Databricks in un'area in cui è supportata la gestione del modello. Vedere Disponibilità delle funzionalità di gestione dei modelli.
• Endpoint di gestione di un modello. È possibile usare uno degli endpoint con pagamento in base al token preconfigurati nell'area di lavoro oppure eseguire le operazioni seguenti:
  • Per creare un endpoint per i modelli esterni, completare i passaggi 1 e 2 di Creare un endpoint di gestione di un modello esterno.
  • Per creare un endpoint per il throughput fornito, vedere API del modello di base per il throughput fornito.
  • Per creare un endpoint per un modello personalizzato, vedere Creare un endpoint.

Configurare Unity AI Gateway usando l'interfaccia utente

Nella sezione Unity AI Gateway della pagina di creazione dell'endpoint, è possibile configurare singolarmente le funzionalità del Gateway. Consultare Funzionalità supportate per le funzionalità disponibili sugli endpoint di erogazione dei modelli esterni e sugli endpoint con velocità effettiva provisionata.

La tabella seguente riepiloga come configurare Unity AI Gateway durante la creazione dell'endpoint usando l'interfaccia utente di gestione. Se si preferisce eseguire questa operazione a livello di codice, vedere l'esempio notebook.

Il diagramma seguente mostra un esempio di fallback in cui,

• Tre entità servite vengono gestite in un endpoint di gestione del modello.
• La richiesta viene originariamente instradata all'entità Serve 3.
• Se la richiesta restituisce una risposta 200, la richiesta ha avuto esito positivo in entità servita 3 e la richiesta e la relativa risposta vengono registrate nelle tabelle di registrazione dell'utilizzo e del payload dell'endpoint.
• Se la richiesta restituisce un errore 429 o 5xx su Entità Servita 3, la richiesta passa all'entità servita successiva nell'endpoint, Entità Servita 1.
  • Se la richiesta restituisce un errore 429 o 5xx su entità servita 1, la richiesta passa all'entità servita successiva nell'endpoint, entità servita 2.
  • Se la richiesta restituisce un errore 429 o 5xx nell'entità Servita 2, la richiesta ha esito negativo perché si tratta del numero massimo di entità di fallback. La richiesta non riuscita e l'errore di risposta vengono registrati nelle tabelle di rilevamento dell'utilizzo e registrazione del payload.

Configurare i guardrail dell'IA nell'interfaccia utente

Nella tabella seguente viene illustrato come configurare le protezioni supportate .

schemi della tabella di rilevamento dell'utilizzo

Nelle sezioni seguenti vengono riepilogati gli schemi della tabella di rilevamento dell'utilizzo per le tabelle di sistema system.serving.served_entities e system.serving.endpoint_usage.

schema della tabella di rilevamento dell'utilizzo system.serving.served_entities

La tabella del sistema di rilevamento dell'utilizzo system.serving.served_entities presenta lo schema seguente:

schema della tabella di rilevamento dell'utilizzo system.serving.endpoint_usage

La tabella del sistema di rilevamento dell'utilizzo system.serving.endpoint_usage presenta lo schema seguente:

Definire ulteriormente l'utilizzo con usage_context

Quando si esegue una query su un modello esterno con il rilevamento dell'utilizzo abilitato, è possibile fornire il usage_context parametro con il tipo Map[String, String]. Il mapping del contesto di utilizzo viene visualizzato nella tabella di rilevamento dell'utilizzo nella colonna usage_context. Le dimensioni della usage_context mappa non possono superare 10 KiB.

{
  "messages": [
    {
      "role": "user",
      "content": "What is Databricks?"
    }
  ],
  "max_tokens": 128,
  "usage_context":
    {
      "use_case": "external",
      "project": "project1",
      "priority": "high",
      "end_user_to_charge": "abcde12345",
      "a_b_test_group": "group_a"
    }
}

Se si usa il client Python OpenAI, è possibile specificare il usage_context includendolo nel parametro extra_body.

from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.chat.completions.create(
    model="databricks-claude-sonnet-4-5",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    temperature=0,
    extra_body={"usage_context": {"project": "project1"}},
)
answer = response.choices[0].message.content
print("Answer:", answer)

Gli amministratori dell'account possono aggregare righe diverse in base al contesto di utilizzo per ottenere informazioni dettagliate e aggiungere queste informazioni alle informazioni nella tabella di registrazione del payload. Ad esempio, è possibile aggiungere end_user_to_charge a usage_context per tenere traccia dell'attribuzione dei costi per gli utenti finali.

Monitorare l'utilizzo degli endpoint

Per monitorare l'utilizzo degli endpoint, è possibile unire le tabelle di sistema e le tabelle di inferenza per l'endpoint.

Unire tabelle di sistema

Questo esempio si applica agli endpoint esterni, con throughput di provisioning, a pagamento per token e ai modelli personalizzati.

Per unire le endpoint_usage tabelle di sistema e served_entities , usare il codice SQL seguente:

SELECT * FROM system.serving.endpoint_usage as eu
JOIN system.serving.served_entities as se
ON eu.served_entity_id = se.served_entity_id
WHERE created_by = "\<user_email\>";

Aggiornare le funzionalità del gateway di Intelligenza Artificiale Unity sugli endpoint

È possibile aggiornare le funzionalità del gateway di intelligenza artificiale Unity sugli endpoint di servizio modello che in precedenza avevano funzionalità abilitate e su quelli che non le avevano. Gli aggiornamenti alle configurazioni del gateway di intelligenza artificiale unity richiedono circa 20-40 secondi, tuttavia la limitazione della frequenza degli aggiornamenti può richiedere fino a 60 secondi.

Di seguito viene illustrato come aggiornare le funzionalità di Unity AI Gateway in un modello che serve un endpoint utilizzando la Serving UI.

Nella sezione Gateway della pagina endpoint è possibile visualizzare le funzionalità abilitate. Per aggiornare queste funzionalità, fare clic su Modifica Gateway di Intelligenza Artificiale Unity.

Esempio di notebook

Il notebook seguente illustra come abilitare e usare programmaticamente le funzionalità di Databricks Unity AI Gateway per gestire e governare i modelli dai provider. Per informazioni dettagliate sull'API REST, vedere PUT /api/2.0/serving-endpoints/{name}/ai-gateway .

Abilitare Databricks

Ottieni il notebook

Risorse aggiuntive

• Gateway di intelligenza artificiale Unity per la gestione degli endpoint.
• Monitorare i modelli serviti usando le tabelle di inferenza abilitate per il Unity AI Gateway.