Een agent implementeren voor generatieve AI-toepassing

In dit artikel wordt beschreven hoe u uw AI-agent implementeert in Mosaic AI Model Serving met behulp van de deploy()-functie uit de python-API van het Agent Framework Python API.

Het implementeren van agents op Mosaic AI Model Serving biedt de volgende voordelen:

• Model Serving beheert automatisch schalen, logboekregistratie, versiebeheer en toegangsbeheer, zodat u zich kunt richten op het ontwikkelen van kwaliteitsagents.
• Deskundigen kunnen de Review App gebruiken om te communiceren met de uitgerolde agent en feedback te geven die kan worden opgenomen in uw monitoring en evaluaties.
• U kunt de agent bewaken door een evaluatie uit te voeren op live verkeer. Hoewel gebruikersverkeer de grondwaarheid niet bevat, voeren LLM’s (en de aangepaste metriek die u hebt gemaakt) een evaluatie zonder supervisie uit.

Vereisten

• MLflow 2.13.1 of hoger om agents te implementeren met behulp van de deploy() API van databricks.agents.

• Registreer een AI-agent bij Unity Catalog. Zie De agent registreren bij Unity Catalog.

• Voor het implementeren van agents van buiten een Databricks-notebook is databricks-agents SDK-versie 0.12.0 of hoger vereist.

• Installeer de databricks-agents SDK.

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

Een agent implementeren met behulp van deploy()

De functie deploy() doet het volgende:

• Hiermee creëert u CPU-modelserve-eindpunten voor uw agent die kunnen worden geïntegreerd in uw gebruikersgerichte toepassing.

  • Als u de kosten voor niet-actieve eindpunten wilt verlagen (ten koste van verhoogde tijd voor het uitvoeren van initiële query's), kunt u schalen tot nul voor uw servereindpunt inschakelen door door te geven scale_to_zero_enabled=True aan deploy(). Zie de verwachtingen voor het schalen van eindpunten.
  • Hiermee maakt u inferentietabellen mogelijk met AI Gateway op het modelserveerpunt. Zie Modellen monitoren met behulp van inferentietabellen die AI Gateway ondersteunen.

  Notitie

  Voor streaming-antwoordlogboeken worden alleen velden en traceringen die compatibel zijn met ChatCompletion samengevoegd.

  • Databricks levert automatisch kortdurende inloggegevens voor serviceprincipals aan de agentcode die op het eindpunt draait. De referenties hebben de minimale machtigingen om toegang te krijgen tot door Databricks beheerde resources, zoals gedefinieerd bij het loggen van het model. Voordat u deze referenties genereert, zorgt Databricks ervoor dat de eigenaar van het eindpunt over de juiste machtigingen beschikt om escalatie van bevoegdheden en onbevoegde toegang te voorkomen. Zie Authenticatie voor afhankelijke resources.
    • Als u resourceafhankelijkheden hebt die niet door Databricks worden beheerd, bijvoorbeeld met behulp van Pinecone, kunt u omgevingsvariabelen met geheimen doorgeven aan de deploy()-API. Zie Toegang tot resources configureren vanuit het model dat eindpunten bedient.

• Hiermee schakelt u de beoordelings-app voor uw agent in. Met de beoordelings-app kunnen belanghebbenden chatten met de agent en feedback geven met behulp van de gebruikersinterface van de beoordelings-app.

• Legt elke aanvraag vast voor de Review-app of REST API in een inferentietabel. De vastgelegde gegevens omvatten queryaanvragen, antwoorden en tussenliggende traceringsgegevens van MLflow Tracing.

• Hiermee maakt u een feedbackmodel met dezelfde catalogus en hetzelfde schema als de agent die u wilt implementeren. Dit feedbackmodel is het mechanisme waarmee u feedback van de beoordelings-app kunt accepteren en kunt registreren bij een deductietabel. Dit model wordt bediend via hetzelfde CPU-servereindpunt als uw geïmplementeerde agent. Omdat voor dit eindpunt deductietabellen zijn ingeschakeld, is het mogelijk om feedback van de beoordelings-app te registreren bij een deductietabel.

Notitie

Het kan tot 15 minuten duren voordat implementaties zijn voltooid. Het duurt 10 tot 30 minuten voordat onbewerkte JSON-nettoladingen binnenkomen en de opgemaakte logboeken worden ongeveer elk uur verwerkt vanuit de onbewerkte nettoladingen.

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

Authenticatie voor afhankelijke bronnen

AI-agents moeten vaak worden geverifieerd bij andere resources om taken te voltooien. Een agent moet bijvoorbeeld toegang krijgen tot een Vector Search-index om een query uit te voeren op ongestructureerde gegevens.

Uw agent kan één van de volgende methoden gebruiken om zich te verifiëren bij afhankelijke resources wanneer u deze achter een eindpunt voor modeldiensten plaatst.

1. Automatic authentication pass-through: Declareer Databricks-resourceafhankelijkheden voor uw agent tijdens het inloggen. Databricks kan automatisch kortdurende inloggegevens inrichten, roteren en beheren wanneer uw agent wordt ingezet om veilig toegang te krijgen tot bronnen. Databricks raadt aan om waar mogelijk automatische verificatiepassthrough te gebruiken.
2. handmatige authenticatie: specifeer handmatig langdurig geldige referenties tijdens de implementatie van de agent. Gebruik handmatige verificatie voor Databricks-resources die geen ondersteuning bieden voor automatische verificatiepassthrough of voor externe API-toegang.

passthrough voor automatische verificatie

Model Serving ondersteunt automatische verificatiepassthrough voor de meest voorkomende typen Databricks-resources die door agents worden gebruikt.

Als u automatische verificatiepassthrough wilt inschakelen, moet u tijdens het aanmeldproces van agents afhankelijkheden specificeren.

Vervolgens, wanneer u de agent achter een eindpunt bedient, voert Databricks de volgende stappen uit:

1. machtigingsverificatie: Databricks controleert of de maker van het eindpunt toegang heeft tot alle gespecificeerde afhankelijkheden tijdens de agent logging.

2. Service-principalcreatie en -rechten: Er wordt een service-principal gemaakt voor de versie van het agentmodel en deze krijgt automatisch leestoegang tot de agentresources.

   Notitie

   De service-principal die door het systeem is gegenereerd, verschijnt niet in API- of UI-lijsten. Als de versie van het agentmodel wordt verwijderd van het endpoint, wordt de service-principal ook verwijderd.

3. Referenties inrichten en roulatie: Kortstondige referenties (een M2M OAuth-token) voor de service-principal worden in het eindpunt geïnjecteerd, zodat agentcode toegang kan verkrijgen tot de resources van Databricks. Databricks roteert ook de referenties, zodat uw agent veilige toegang kan blijven houden tot afhankelijke middelen.

Dit verificatiegedrag is vergelijkbaar met het gedrag 'Als eigenaar uitvoeren' voor Databricks-dashboards: downstream-resources zoals Unity Catalog-tabellen worden geopend met behulp van de referenties van een service-principal met minimale toegang tot afhankelijke resources.

De volgende tabel bevat de Databricks-resources die ondersteuning bieden voor automatische verificatie via passthrough en de machtigingen die de auteur van het eindpunt moet hebben voor de implementatie van de agent.

Notitie

Unity Catalog-resources vereisen tevens USE SCHEMA in het bovenliggende schema en USE CATALOG in de bovenliggende catalogus.

Brontype	Machtiging
SQL Warehouse	Eindpunt gebruiken
Eindpunt voor modelserving	Kan opvragen
Unity Catalog-functie	EXECUTEREN
Genieruimte	Kan worden uitgevoerd
Vectorzoekindex	Kan gebruiken
Unity Catalog-tabel	SELECT

Handmatige verificatie

U kunt ook handmatig referenties opgeven met behulp van op geheimen gebaseerde omgevingsvariabelen. Handmatige verificatie kan handig zijn in de volgende scenario's:

• De afhankelijke resource biedt geen ondersteuning voor automatische verificatiepassthrough.
• De agent heeft toegang tot een externe resource of API.
• De agent moet andere inloggegevens gebruiken dan die van de agent-deployer.

Als u bijvoorbeeld de Databricks SDK in uw agent wilt gebruiken voor toegang tot andere afhankelijke resources, kunt u de omgevingsvariabelen instellen die worden beschreven in Geïntegreerde verificatie van databricks-clients.

Uitgerolde agents bewaken

Nadat een agent is geïmplementeerd in Databricks Model Serving, kunt u ai Gateway-deductietabellen gebruiken om de geïmplementeerde agent te bewaken. De inferentietabellen bevatten gedetailleerde logboeken met aanvragen, antwoorden, agenttraceringen en feedback van de agent in de beoordelingsapplicatie. Met deze informatie kunt u problemen opsporen, prestaties bewaken en een gouden gegevensset maken voor offline evaluatie.

Zie Uitgerolde agents bewaken met inferentietabellen.

Geïmplementeerde toepassingen ophalen

Hieronder ziet u hoe u uw uitgerolde agenten kunt ophalen.

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

Feedback geven over een geïmplementeerde agent (experimenteel)

Wanneer u uw agent implementeert met agents.deploy(), maakt en implementeert het agentframework ook een versie van het 'feedbackmodel' binnen hetzelfde eindpunt, waarop u query's kunt uitvoeren om feedback te geven over uw agenttoepassing. Feedbackvermeldingen verschijnen als verzoekregels binnen de inferentietabel die is gekoppeld aan het eindpunt van uw agent.

Houd er rekening mee dat dit gedrag experimenteel is : Databricks kan een eersteklas API bieden voor het geven van feedback over een geïmplementeerde agent in de toekomst. Voor toekomstige functionaliteit is mogelijk migratie naar deze API vereist.

Beperkingen van deze API zijn onder andere:

• De feedback-API heeft geen invoervalidatie. Deze reageert altijd met succes, zelfs als er ongeldige invoer is doorgegeven.
• Voor de feedback-API moet u de Databricks-gegenereerde request_id van de aanvraag van het agenteindpunt doorgeven waarop u feedback wilt geven. Om de databricks_request_id te verkrijgen, neemt u {"databricks_options": {"return_trace": True}} op in uw oorspronkelijke aanvraag voor de agent die het eindpunt bedient. Het antwoord op het eindpunt van de agent bevat vervolgens de databricks_request_id die is gekoppeld aan de aanvraag, zodat u die aanvraag-id kunt doorgeven aan de feedback-API wanneer u feedback geeft over het antwoord van de agent.
• Feedback wordt verzameld met behulp van deductietabellen. Zie inferentietabelbeperkingen.

De volgende voorbeeldaanvraag geeft feedback over het agenteindpunt met de naam 'your-agent-endpoint-name', en gaat ervan uit dat de DATABRICKS_TOKEN omgevingsvariabele is ingesteld op een Databricks REST API-token.

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

U kunt extra of andere sleutel-waardeparen doorgeven in de text_assessments.ratings en retrieval_assessments.ratings velden om verschillende typen feedback te geven. In het voorbeeld geeft de feedbackpayload aan dat de reactie van de agent op de aanvraag met ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 juist, nauwkeurig en gebaseerd op de context was die is opgehaald door een retrievertool.

Aanvullende bronnen

• Wat is de evaluatie van de AI-agent van Mosaic?
• De beoordelings-app gebruiken voor menselijke beoordelingen van een GEN AI-app