Condividi tramite

Implementare un agente per un'applicazione di intelligenza artificiale generativa

  • Articolo

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Questo articolo illustra come distribuire l'agente di intelligenza artificiale usando la deploy() funzione dall'API Python di Agent Framework.

Requisiti

  • MLflow 2.13.1 o versione successiva per implementare gli agenti usando l’API deploy() da databricks.agents.

  • Registrare un agente di intelligenza artificiale in Unity Catalog. Consulta Registrare l'agente in Unity Catalog.

  • La distribuzione di agenti dall'esterno di un notebook di Databricks richiede databricks-agents SDK versione 0.12.0 o successiva.

  • Installare l’SDK databricks-agents.

    %pip install databricks-agents
dbutils.library.restartPython()

Implementare l’agente tramite deploy()

La funzione deploy() esegue le operazioni seguenti:

  • Crea un modello di CPU che serve gli endpoint per l’agente che può essere integrato nell'applicazione rivolta all’utente.

    Nota

    Per i log di risposta in streaming, vengono aggregati solo i campi e le tracce compatibili con ChatCompletion.

  • Abilita l’app di recensione per l’agente. L'app di revisione consente agli stakeholder di chattare con l'agente e inviare commenti e suggerimenti usando l'interfaccia utente dell'app di revisione.

  • Registra ogni richiesta all'APP di revisione o all'API REST a una tabella di inferenza. I dati registrati includono richieste di query, risposte e dati di traccia intermedi da MLflow Tracing.

  • Crea un modello di feedback con lo stesso catalogo e schema dell'agente che si sta tentando di distribuire. Questo modello di feedback è il meccanismo che consente di accettare commenti e suggerimenti dall'app di revisione e registrarlo in una tabella di inferenza. Questo modello viene servito nello stesso modello di CPU che gestisce l’endpoint dell’agente implementato. Poiché questo endpoint di servizio dispone di tabelle di inferenza abilitate, è possibile registrare commenti e suggerimenti dall'app di revisione a una tabella di inferenza.

Nota

Il completamento dell’implementazione può richiedere fino a 15 minuti. I payload JSON non elaborati richiedono 10 - 30 minuti per arrivare e i log formattati vengono elaborati dai payload non elaborati circa ogni ora.


from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

tabelle di inferenza potenziate da agente

Il deploy() crea tre tabelle di inferenza per ogni distribuzione per registrare le richieste e le risposte da e verso l'endpoint di gestione dell'agente. Gli utenti possono aspettarsi che i dati si trovino nella tabella del payload entro un'ora dall'interazione con la distribuzione.

Il popolamento dei log delle richieste di payload e dei log di valutazione potrebbe richiedere più tempo, ma alla fine derivano dalla tabella grezza del payload. È possibile estrarre manualmente i log di richiesta e valutazione dalla tabella del payload. Le eliminazioni e gli aggiornamenti alla tabella del payload non vengono riflesse nei log delle richieste di payload o nei log di valutazione del payload.

Nota

Se hai attivato il Firewall di Archiviazione di Azure, contatta il team del tuo account Databricks per permettere l'utilizzo delle tabelle di inferenza per gli endpoint.

Tavolo Nome tabella catalogo Unity di esempio Che cos'è in ogni tabella
Payload {catalog_name}.{schema_name}.{model_name}_payload Payload di richiesta e risposta JSON non elaborati
Log delle richieste di payload {catalog_name}.{schema_name}.{model_name}_payload_request_logs Richieste e risposte formattate, tracce MLflow
Log di valutazione del payload {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Feedback formattato, come fornito nell’app di recensione, per ogni richiesta

Di seguito viene illustrato lo schema per la tabella dei log delle richieste.

Nome colonna Tipo Descrizione
client_request_id String ID richiesta client, in genere null.
databricks_request_id String ID richiesta di Databricks.
date Data Data della richiesta.
timestamp_ms Lungo Data e ora espressa in millisecondi.
timestamp Timestamp: Data e ora della richiesta.
status_code Intero Codice di stato dell’endpoint.
execution_time_ms Lungo Millisecondi di esecuzione totali.
conversation_id String ID conversazione estratto dai log delle richieste.
request String Ultima query dell’utente dalla conversazione dell’utente. Questa operazione viene estratta dalla richiesta RAG.
response String Ultima risposta all’utente. Questa operazione viene estratta dalla richiesta RAG.
request_raw String La dichiarazione di stringa di richiesta.
response_raw String La dichiarazione di stringa di risposta.
trace String Dichiarazione di stringa della traccia estratta dalla databricks_options struttura della risposta.
sampling_fraction Double Frazione di campionamento.
request_metadata Mappa[Stringa, Stringa] Mappa dei metadati correlati all’endpoint di servizio del modello associato alla richiesta. Questa mappa contiene il nome dell’endpoint, il nome del modello e la versione del modello usati per l’endpoint.
schema_version String Intero per la versione dello schema.

Di seguito è riportato lo schema per la tabella dei log di valutazione.

Nome colonna Tipo Descrizione
request_id String ID richiesta di Databricks.
step_id String Derivato dalla valutazione del recupero.
source Struct Campo struttura contenente le informazioni su chi ha creato la valutazione.
timestamp Timestamp: Data e ora della richiesta.
text_assessment Struct Campo struttura contenente i dati per qualsiasi feedback sulle risposte dell’agente dall’app di recensione.
retrieval_assessment Struct Campo struttura contenente i dati per qualsiasi feedback sui documenti recuperati per una risposta.

Autenticazione per le risorse dipendenti

Gli agenti di intelligenza artificiale spesso devono eseguire l'autenticazione ad altre risorse per completare le attività. Ad esempio, un agente potrebbe dover accedere a un indice di ricerca vettoriale per eseguire query su dati non strutturati.

Il tuo agente può utilizzare uno dei seguenti metodi per autenticarsi alle risorse dipendenti quando lo si serve dietro un endpoint di Model Serving.

  1. trasmissione automatica dell'autenticazione: dichiarare le dipendenze sulle risorse di Databricks per l'agente durante l'acquisizione dei log. Databricks può automaticamente approvvigionare, ruotare e gestire le credenziali di breve durata quando l'agente viene distribuito per consentire un accesso sicuro alle risorse. Databricks consiglia di usare il pass-through di autenticazione automatica, se possibile.
  2. autenticazione manuale: specificare manualmente le credenziali con validità prolungata durante la distribuzione dell'agente. Usare l'autenticazione manuale per le risorse di Databricks che non supportano il pass-through di autenticazione automatica o per l'accesso all'API esterna.

Pass-through di autenticazione automatica

Model Serving supporta il pass-through di autenticazione automatica per i tipi più comuni di risorse di Databricks usati dagli agenti.

Per abilitare il pass-through di autenticazione automatica, è necessario specificare le dipendenze durante la registrazione dell'agente.

Quindi, quando si gestisce l'agente dietro un endpoint, Databricks esegue i passaggi seguenti:

  1. Verifica delle autorizzazioni: Databricks verifica che l'autore dell'endpoint possa accedere a tutte le dipendenze specificate durante il logging dell'agente.

  2. Creazione e concessione del principale del servizio: Viene creato un principale del servizio per la versione del modello dell'agente e viene concesso automaticamente l'accesso in lettura alle risorse dell'agente.

    Nota

    L'entità principale servizio generata dal sistema non appare nelle liste API o dell'interfaccia utente. Se la versione del modello dell'agente viene rimossa dall'endpoint, viene eliminato anche il principale del servizio.

  3. provisioning e rotazione delle credenziali: credenziali di breve durata (un token OAuth M2M M2M) per l'entità servizio vengono inserite nell'endpoint, consentendo al codice dell'agente di accedere alle risorse di Databricks. Databricks sostituisce regolarmente le credenziali, assicurandosi che l'agente abbia un accesso continuo e sicuro alle risorse dipendenti.

Questo comportamento di autenticazione è simile al comportamento "Run as owner" per i dashboard di Databricks. Le risorse downstream come le tabelle di Unity Catalog sono accessibili usando le credenziali di un'entità servizio con accesso con privilegi minimi alle risorse dipendenti.

Nella tabella seguente sono elencate le risorse di Databricks che supportano il pass-through di autenticazione automatica e le autorizzazioni che l'autore dell'endpoint deve avere durante la distribuzione dell'agente.

Nota

Le risorse del catalogo unity richiedono anche USE SCHEMA nello schema padre e USE CATALOG nel catalogo padre.

Tipo di risorsa Autorizzazione
SQL Warehouse Usare l'endpoint
Endpoint di gestione del modello Può eseguire query
Funzione Catalogo Unity ESEGUIRE
Spazio genie Può eseguire
Indice di ricerca vettoriale Può usare
Tabella del catalogo Unity SELECT

Autenticazione manuale

È anche possibile specificare manualmente le credenziali usando le variabili di ambiente basate su segreti . L'autenticazione manuale può essere utile negli scenari seguenti:

  • La risorsa dipendente non supporta il pass-through di autenticazione automatica.
  • L'agente accede a una risorsa o un'API esterna.
  • L'agente deve usare credenziali diverse da quelle del deployer dell'agente.

Ad esempio, per usare Databricks SDK nell'agente per accedere ad altre risorse dipendenti, è possibile impostare le variabili di ambiente descritte in l'autenticazione unificata del client Databricks.

Visualizzare le applicazioni distribuite

Di seguito viene illustrato come ottenere gli agenti distribuiti.

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

Fornire commenti e suggerimenti su un agente distribuito (sperimentale)

Quando si distribuisce l'agente con agents.deploy(), il framework agente crea e distribuisce anche una versione del modello di "feedback" all'interno dello stesso endpoint, che è possibile eseguire una query per fornire commenti e suggerimenti sull'applicazione agente. Le voci di feedback vengono visualizzate come righe di richiesta all'interno della tabella di inferenza associata all'endpoint di gestione dell'agente.

Si noti che questo comportamento è sperimentale: Databricks può fornire un'API di prima classe per fornire commenti e suggerimenti su un agente distribuito in futuro e le funzionalità future potrebbero richiedere la migrazione a questa API.

Le limitazioni di questa API includono:

  • L'API di feedback non dispone della convalida dell'input, ma risponde sempre correttamente, anche se ha superato input non valido.
  • L'API di feedback richiede il passaggio di Databricks generato request_id dalla richiesta dell'endpoint dell'agente in cui si vuole fornire commenti e suggerimenti. Per ottenere il databricks_request_id, includere {"databricks_options": {"return_trace": True}} nella richiesta originale all'endpoint servito dall'agente. La risposta dell'endpoint agente includerà quindi il databricks_request_id associato alla richiesta in modo da poter passare di nuovo l'ID richiesta all'API di feedback quando si forniscono commenti e suggerimenti sulla risposta dell'agente.
  • Il feedback viene raccolto usando le tabelle di inferenza. Vedi limitazioni della tabella di inferenza.

La richiesta di esempio seguente fornisce commenti e suggerimenti sull'endpoint dell'agente denominato "your-agent-endpoint-name" e presuppone che la variabile di ambiente DATABRICKS_TOKEN sia impostata su un token API REST di Databricks.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about Delta Live Tables"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

È possibile passare coppie chiave-valore aggiuntive o diverse nei text_assessments.ratings campi e retrieval_assessments.ratings per fornire diversi tipi di feedback. Nell'esempio, il payload del feedback indica che la risposta dell'agente alla richiesta con ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 è corretta, accurata e a terra nel contesto recuperato da uno strumento di recupero.

Risorse aggiuntive