Implementare un agente per un'applicazione di intelligenza artificiale generativa

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. Vedere 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.
  • Per ridurre i costi per gli endpoint inattivi (a scapito di un tempo maggiore per gestire le query iniziali), è possibile abilitare la scalabilità a zero per l'endpoint di gestione passando scale_to_zero_enabled=True a deploy(). Vedere Aspettative di ridimensionamento degli endpoint.
  • L'inferenza tables è abilitata in questi endpoint di gestione del modello. Vedi inferenza tables per monitoraggio e debug dei modelli.
  • Databricks fornisce automaticamente un principale servizio di breve durata credentials al codice agente in esecuzione nell'endpoint. Il credentials dispone delle autorizzazioni minime per accedere alle risorse gestite da Databricks definite durante la registrazione dei modelli. Prima di generare questi credentials, Databricks garantisce che il proprietario dell'endpoint disponga delle autorizzazioni appropriate per impedire l'escalation dei privilegi e l'accesso non autorizzato. Vedere Autenticazione per le risorse dipendenti.
    • Se si hanno dipendenze di risorse che non sono gestite da Databricks, ad esempio usando Pinecone, è possibile passare variabili di ambiente con segreti all'API deploy(). Vedere Configurare l’accesso alle risorse dagli endpoint di servizio dei modelli.
• 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 per un'inferenza table. I dati registrati includono richieste di query, risposte e dati di traccia intermedi da MLflow Tracing.
• Crea un modello di feedback avente lo stesso catalog e schema dell'agente che si sta tentando di distribuire. Questo modello di feedback è il meccanismo che consente di accettare feedback dall'app di revisione e registrarlo come un'inferenza table. Questo modello viene servito nello stesso modello di CPU che gestisce l’endpoint dell’agente implementato. Poiché questo endpoint di servizio ha inferenza tables abilitata, è possibile registrare commenti e suggerimenti dall'app di revisione a un'inferenza table.

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

Inferenza migliorata dall'agente tables

Il deploy() crea tre inferenza tables 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 troveranno nel payload table entro un'ora dall'interazione con la propria distribuzione.

La scrittura dei log delle richieste di payload e dei log di valutazione potrebbe richiedere più tempo, ma provengono in ultima analisi dal payload grezzo table. È possibile estrarre i log di richiesta e valutazione dal payload table manualmente. Le eliminazioni e gli aggiornamenti al payload table non vengono riflesse nei log delle richieste di payload o nei log di valutazione del payload.

Di seguito viene illustrato il schema per i log delle richieste table.

Di seguito è riportato il schema per i log di valutazione table.

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ò effettuare automaticamente il provisioning, la rotazione e la gestione di credentials di breve durata quando l'agente viene distribuito per accedere in modo sicuro alle risorse. Databricks consiglia di usare il pass-through di autenticazione automatica where possibile.
2. Autenticazione manuale: Specificare manualmente un token duraturo credentials 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: credentials a breve termine (un token OAuth M2M) per il principale del servizio vengono inseriti nell'endpoint, consentendo al codice dell'agente di accedere alle risorse di Databricks. Databricks ruota anche il credentials, assicurando che l'agente abbia l'accesso continuo e sicuro alle risorse dipendenti.

Questo comportamento di autenticazione è simile al comportamento "Run as owner" per i dashboard di Databricks: le risorse a valle, come Unity Catalogtables, sono accessibili usando la credentials di un principale del servizio con accesso a privilegi minimi alle risorse dipendenti.

L'table seguente elenca le risorse di Databricks che supportano l'autenticazione automatica e le autorizzazioni che l'autore dell'endpoint deve avere per distribuire l'agente.

Autenticazione manuale

È anche possibile fornire manualmente credentials usando 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 credentials diverso da quelli utilizzati dal deployer dell'agente.

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

Get applicazioni distribuite

Di seguito viene illustrato come get 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 dell'inferenza table 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 get il 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 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 l'inferenza tables. Vedere limitazioni di inferenza table.

La richiesta di esempio seguente fornisce feedback sull'endpoint dell'agente denominato "your-agent-endpoint-name" e presuppone che la variabile di ambiente DATABRICKS_TOKEN sia set per 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

• Che cos’è Mosaic AI Agent Evaluation?
• Get feedback sulla qualità di un'applicazione agentica