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 keten registreren bij Unity Catalog.

  • 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 uw belanghebbenden chatten met de agent en feedback geven via 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.

Machtigingsvereisten voor afhankelijke resources

Bij het implementeren van een model met afhankelijke resources moet de maker van het eindpunt de volgende machtigingen hebben, afhankelijk van het resourcetype:

Brontype Machtiging
Sql Warehouse Eindpunt gebruiken
Eindpunt voor modellering Kan query's uitvoeren
Unity Catalog, functie Uitvoeren
Genieruimte Uitvoeren
Vector Search-index ReadVectorIndex
Unity Catalog-tabel Kan lezen

Verificatie voor afhankelijke resources

Wanneer u het model voor eindpunt voor agentimplementatie maakt, controleert Databricks of de maker van het eindpunt machtigingen heeft voor toegang tot alle resources waarvan de agent afhankelijk is.

Voor LangChain-agents worden afhankelijke resources automatisch afgeleid tijdens het maken en vastleggen van agents. Deze resources worden vastgelegd in het resources.yaml bestand in het vastgelegde modelartefact. Tijdens de implementatie databricks.agents.deploy worden automatisch de M2M OAuth-tokens gemaakt die vereist zijn voor toegang tot en communicatie met deze uitgestelde resourceafhankelijkheden.

Voor pyFunc-agents moet u handmatig resourceafhankelijkheden opgeven tijdens de logboekregistratie van de geïmplementeerde agent in de resources parameter. Zie Resources opgeven voor PyFunc- of LangChain-agent. Tijdens de implementatie databricks.agents.deploy maakt u een M2M OAuth-token met toegang tot de resources die zijn opgegeven in de resources parameter en implementeert u dit in de geïmplementeerde agent.

Passthrough voor automatische verificatie

De volgende tabel bevat de functies die ondersteuning bieden voor automatische verificatiepassthrough. Automatische verificatiepassthrough gebruikt de referenties van de maker van de implementatie om automatisch te verifiëren bij ondersteunde functies.

Functie Minimale mlflow versie
Vectorzoekindexen Vereist mlflow 2.13.1 of hoger
Eindpunten voor modelbediening Vereist mlflow 2.13.1 of hoger
SQL-magazijnen Vereist mlflow 2.16.1 of hoger
Unity Catalog-functies Vereist mlflow 2.16.1 of hoger

Handmatige verificatie

Als u een afhankelijke resource hebt die geen ondersteuning biedt voor automatische verificatiepassthrough, of als u andere referenties dan die van de maker van de implementatie wilt gebruiken, kunt u handmatig referenties opgeven met behulp van omgevingsvariabelen op basis van geheimen. Als u bijvoorbeeld de Databricks SDK in uw agent gebruikt voor toegang tot andere typen afhankelijke resources, kunt u de omgevingsvariabelen instellen die worden beschreven in geïntegreerde verificatie van de Databricks-client.

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_options": {"return_trace": True}} u de databricks_request_idoorspronkelijke aanvraag op voor het eindpunt van de agent. Het antwoord op het eindpunt van de agent bevat vervolgens de databricks_request_id gekoppelde aanvraag, zodat u die aanvraag-id weer 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