Delen via

Een agent implementeren voor generatieve AI-toepassing

  • Artikel

Belangrijk

Deze functie is beschikbaar als openbare preview.

In dit artikel wordt beschreven hoe u uw AI-agent implementeert met behulp van de deploy() functie van de Python-API van Agent Framework.

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 maakt u CPU-model voor eindpunten voor uw agent die kan worden geïntegreerd in uw gebruikersgerichte toepassing.
  • 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.
  • Registreert elke aanvraag bij de Beoordelings-app of REST API naar een deductietabel. 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 geleverd in hetzelfde CPU-model 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

Door agents verbeterde deductietabellen

Er deploy() worden drie deductietabellen gemaakt voor elke implementatie om aanvragen en antwoorden van en naar het eindpunt van de agent te registreren. Gebruikers kunnen verwachten dat de gegevens zich binnen een uur na interactie met hun implementatie in de nettoladingtabel bevinden.

Het kan langer duren voordat de logboeken voor payloadaanvragen en evaluatielogboeken worden ingevuld, maar uiteindelijk worden afgeleid van de tabel met onbewerkte nettoladingen. U kunt zelf aanvraag- en evaluatielogboeken uit de nettoladingstabel extraheren. Verwijderingen en updates van de payloadtabel worden niet weergegeven in de logboeken van de nettoladingsaanvraag of in de logboeken voor de evaluatie van nettoladingen.

Notitie

Als Azure Storage Firewall is ingeschakeld, neemt u contact op met uw Databricks-accountteam om deductietabellen voor uw eindpunten in te schakelen.

Tabel Voorbeeld van de naam van de Unity Catalog-tabel Wat staat er in elke tabel?
Nettolading {catalog_name}.{schema_name}.{model_name}_payload Onbewerkte JSON-aanvraag- en antwoordpayloads
Logboeken voor nettoladingsaanvragen {catalog_name}.{schema_name}.{model_name}_payload_request_logs Opgemaakte aanvragen en antwoorden, MLflow-traceringen
Evaluatielogboeken van nettolading {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Opgemaakte feedback, zoals opgegeven in de beoordelings-app, voor elke aanvraag

Hieronder ziet u het schema voor de tabel met aanvraaglogboeken.

Kolomnaam Type Omschrijving
client_request_id String Clientaanvraag-id, meestal null.
databricks_request_id String Databricks-aanvraag-id.
date Datum Datum van aanvraag.
timestamp_ms Lang Tijdstempel in milliseconden.
timestamp Tijdstempel Tijdstempel van de aanvraag.
status_code Geheel getal Statuscode van eindpunt.
execution_time_ms Lang Totaal aantal milliseconden voor uitvoering.
conversation_id String Gespreks-id geëxtraheerd uit aanvraaglogboeken.
request String De laatste gebruikersquery uit het gesprek van de gebruiker. Dit wordt geëxtraheerd uit de RAG-aanvraag.
response String Het laatste antwoord op de gebruiker. Dit wordt geëxtraheerd uit de RAG-aanvraag.
request_raw String Tekenreeksweergave van aanvraag.
response_raw String Tekenreeksweergave van antwoord.
trace String Tekenreeksweergave van tracering geëxtraheerd uit de databricks_options antwoordstruct.
sampling_fraction Dubbel Steekproeffractie.
request_metadata Map[Tekenreeks, tekenreeks] Een kaart met metagegevens die betrekking hebben op het model dat het eindpunt biedt dat aan de aanvraag is gekoppeld. Deze kaart bevat de eindpuntnaam, modelnaam en modelversie die wordt gebruikt voor uw eindpunt.
schema_version String Geheel getal voor de schemaversie.

Hier volgt het schema voor de tabel met evaluatielogboeken.

Kolomnaam Type Omschrijving
request_id String Databricks-aanvraag-id.
step_id String Afgeleid van de evaluatie van het ophalen.
source Struct Een structveld met de informatie over wie de evaluatie heeft gemaakt.
timestamp Tijdstempel Tijdstempel van aanvraag.
text_assessment Struct Een structveld met de gegevens voor feedback over de reacties van de agent van de beoordelings-app.
retrieval_assessment Struct Een structveld met de gegevens voor feedback over de documenten die zijn opgehaald voor een antwoord.

Verificatie voor afhankelijke resources

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 een van de volgende methoden gebruiken om zich te verifiëren bij afhankelijke resources wanneer u deze achter een eindpunt voor modelleren toepast.

  1. Automatische verificatie doorsluizen: Declareer Databricks-resourceafhankelijkheden voor uw agent tijdens het loggen. Databricks kan referenties met een korte levensduur automatisch inrichten, roteren en beheren wanneer uw agent wordt geïmplementeerd om veilig toegang te krijgen tot resources. Databricks raadt aan om waar mogelijk automatische verificatiepassthrough te gebruiken.
  2. handmatige verificatie: specificeer handmatig langdurige 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 principal creatie en rechten: er wordt een service principal gemaakt voor de versie van het agentmodel, en automatisch krijgt deze leestoegang tot agentbronnen.

    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 uit het eindpunt, 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 heeft tot de resources van Databricks. Databricks roteert ook de referenties, zodat uw agent de toegang tot afhankelijke resources heeft voortgezet en beveiligd.

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 query's uitvoeren
Unity Catalog, functie EXECUTEREN
Genieruimte Kan worden uitgevoerd
Vectorzoekindex Kan gebruiken
Unity Catalog-tabel SELECTEREN

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 referenties gebruiken dan die van de agent-uitvoerder.

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.

Geïmplementeerde toepassingen ophalen

Hieronder ziet u hoe u uw geïmplementeerde agents 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 worden weergegeven als aanvraagrijen in de deductietabel 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 de Databricks-gegenereerde aanvraag voor het agenteindpunt worden doorgegeven request_id waarvoor u feedback wilt geven. Als u de aanvraag wilt ophalen, neemt databricks_request_id u de {"databricks_options": {"return_trace": True}}oorspronkelijke aanvraag op voor het eindpunt van de agent. 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 deductietabelbeperkingen.

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 Delta Live Tables"
                      }
                  ],
                  "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 nettolading van de feedback aan dat de reactie van de agent op de aanvraag met id 573d4a61-4adb-41bd-96db-0ec8cebc3744 juist, nauwkeurig en geaard was in context die is opgehaald door een retriever-hulpprogramma.

Aanvullende bronnen