Condividi tramite

Implementare un agente per un'applicazione di intelligenza artificiale generativa

  • Articolo

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Questo articolo illustra come implementare l'agente AI usando l'API deploy() da databricks.agents.

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. Consultare Registrare la catena in Unity Catalog.

  • Installare l’SDK databricks-agents.

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

Implementare l’agente tramite deploy()

L’API 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.
  • Abilita l’app di recensione per l’agente. L’app di recensione consente agli stakeholder di chattare con l’agente e inviare commenti e suggerimenti usando l'interfaccia utente dell'app di recensione.
  • Registra ogni richiesta all’app di recensione 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 implementare. Questo modello di feedback è il meccanismo che consente di accettare commenti e suggerimenti dall’app di recensione 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 recensione 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 avanzata dall’agente

deploy() Crea tre tabelle di inferenza per ogni distribuzione per registrare richieste e risposte da e verso l’endpoint di servizio dell’agente. Gli utenti possono aspettarsi che i dati si trovano in queste tabelle 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 deriva in definitiva dalla tabella del payload non elaborato. È 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 è stato abilitato il firewall di Archiviazione di Azure, contattare il team dell’account Databricks per abilitare le tabelle di inferenza per gli endpoint.

Tabella Nome tabella Unity Catalog di esempio Informazioni su ciascuna 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

Quando si crea il modello che serve l’endpoint per la distribuzione dell’agente, Databricks verifica che l’autore della distribuzione disponga delle autorizzazioni necessarie per le risorse dipendenti e consenta il pass-through di autenticazione automatica.

Per gli agenti con versione LangChain, le risorse dipendenti vengono dedotte automaticamente durante la creazione e la registrazione dell’agente. Tali risorse vengono registrate nel file resources.yaml nell’artefatto del modello registrato. Durante la distribuzione, databricks.agents.deploy crea automaticamente i token OAuth M2M necessari per accedere e comunicare con queste dipendenze delle risorse dedotte.

Per gli agenti con versione PyFunc, è necessario specificare manualmente tutte le dipendenze delle risorse durante la registrazione dell’agente distribuito nel parametro resources. Vedere Specificare le risorse per l'agente PyFunc o LangChain. Durante la distribuzione, databricks.agents.deploy crea un token OAuth M2M con accesso alle risorse specificate nel parametro e lo distribuisce all’agente implementato resources.

Pass-through di autenticazione automatica

Nella tabella seguente sono elencate le funzionalità che supportano il pass-through di autenticazione automatica. Il pass-through di autenticazione automatica usa le credenziali dell'autore della distribuzione per l’autenticazione automatica in base alle funzionalità supportate.

Funzionalità Versione mlflow minima
Indici di ricerca vettoriali Richiede mlflow la versione 2.13.1 o successiva
Endpoint di gestione dei modelli Richiede mlflow la versione 2.13.1 o successiva
Warehouse SQL Richiede mlflow la versione 2.16.1 o successiva
Funzioni Unity Catalog Richiede mlflow la versione 2.16.1 o successiva

Autenticazione manuale

Se si dispone di una risorsa dipendente che non supporta il pass-through di autenticazione automatica o se si vogliono utilizzare credenziali diverse da quelle dell’autore della distribuzione, è possibile fornire manualmente le credenziali utilizzando variabili di ambiente basate su segreti. Ad esempio, se si usa Databricks SDK nell’agente per accedere ad altri tipi di risorse dipendenti, è possibile impostare le variabili di ambiente descritte in Autenticazione unificata del client Databricks.

Ottenere le applicazioni implementate

Di seguito viene illustrato come ottenere gli agenti implementati.

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 databricks_request_id, includere {"databricks_options": {"return_trace": True}} nella richiesta originale all'endpoint di gestione dell'agente. La risposta dell'endpoint agente includerà quindi l'oggetto 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. Vedere 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 DATABRICKS_TOKEN variabile di ambiente 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