Condividi tramite

Implementare un agente per un'applicazione di intelligenza artificiale generativa

  • Articolo

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

La distribuzione di agenti in Mosaic AI Model Serving offre i vantaggi seguenti:

  • Model Serving gestisce la scalabilità automatica, la registrazione, il controllo della versione e il controllo di accesso che consentono di concentrarsi sullo sviluppo di agenti di qualità.
  • Gli esperti in materia possono usare l'app di revisione per interagire con l'agente distribuito e fornire commenti e suggerimenti incorporati nel monitoraggio e nelle valutazioni.
  • È possibile monitorare l'agente eseguendo la valutazione sul traffico in tempo reale. Anche se il traffico degli utenti non includerà la verità di base, i giudici LLM (e la metrica personalizzata creata) eseguono una valutazione non supervisionata.

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. Vedi Registrare l'agente a 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 modelli di CPU che servono gli endpoint per il tuo agente e possono essere integrati nella tua applicazione per gli utenti.

    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

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. Passaggio automatico dell'autenticazione: Dichiarare le dipendenze dalle risorse di Databricks per l'agente durante la registrazione. 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 dell'entità servizio: Viene creata un'entità 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, anche il servizio principale viene eliminato.

  3. Provisioning e rotazione delle credenziali: credenziali di breve durata (un token OAuth M2M) per il service principal 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 di Unity Catalog ESEGUIRE
Spazio Genie Può correre
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 utilizzare credenziali diverse da quelle del responsabile della distribuzione 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.

Monitorare gli agenti distribuiti

Dopo aver distribuito un agente in Databricks Model Serving, è possibile usare le tabelle di inferenza del gateway di intelligenza artificiale per monitorare l'agente distribuito. Le tabelle di inferenza contengono log dettagliati di richieste, risposte, tracce dell'agente e feedback dell'agente dall'app di revisione. Queste informazioni consentono di eseguire il debug di problemi, monitorare le prestazioni e creare un set di dati golden per la valutazione offline.

Vedere Monitorare gli agenti distribuiti con tabelle di inferenza.

Visualizzare le applicazioni distribuite

Di seguito viene mostrato come ottenere i vostri 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 dell'agente crea e distribuisce anche una versione del modello di "feedback" all'interno dello stesso endpoint, che può essere interrogata per fornire feedback sull'applicazione dell'agente. Le voci di feedback vengono visualizzate come righe di richiesta nella tabella di inferenza associata all'endpoint di servizio 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 di inserire il request_id generato da Databricks della richiesta dell'endpoint dell'agente su cui si desidera fornire feedback. Per ottenere il databricks_request_id, includere {"databricks_options": {"return_trace": True}} nella richiesta originale all'agente che gestisce l'endpoint. 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 DLT"
                      }
                  ],
                  "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 basata sul contesto ottenuto da uno strumento di recupero.

Risorse aggiuntive