Installera en agent för generativ AI-applikation
Den här artikeln visar hur du distribuerar din AI-agent till Mosaic AI Model Serving med hjälp av funktionen deploy()
från python-API:et Agent Framework.
Distribution av agenter på Mosaic AI Model Serving ger följande fördelar:
- Modellservern hanterar automatisk skalning, loggning, versionskontroll och åtkomstkontroll så att du kan fokusera på att utveckla kvalitetsagenter.
- Ämnesexperter kan använda granskningsappen för att interagera med den distribuerade agenten och ge feedback som ingår i dina övervaknings- och utvärderingar.
- Du kan övervaka agenten genom att utvärdera live-trafik. Även om användartrafiken inte innehåller grundsanningen utför LLM-domare (och det anpassade mått som du skapade) en oövervakad utvärdering.
Krav
MLflow 2.13.1 eller senare för att distribuera agenter med hjälp av API:et
deploy()
fråndatabricks.agents
.Registrera en AI-agent i Unity Catalog. Se Registrera agenten till Unity Catalog.
Distribuera agenter utanför en Databricks notebook kräver
databricks-agents
SDK version 0.12.0 eller senare.Installera
databricks-agents
-SDK:et.%pip install databricks-agents dbutils.library.restartPython()
Distribuera en agent med hjälp av deploy()
Funktionen deploy() gör följande:
Skapar processormodell som betjänar slutpunkter för din agent som kan integreras i ditt användarinriktade program.
- Om du vill minska kostnaden för inaktiva slutpunkter (på bekostnad av ökad tid för att hantera inledande frågor) kan du aktivera skalning till noll för serverdelsslutpunkten genom att skicka
scale_to_zero_enabled=True
tilldeploy()
. Se Förväntningar på slutpunktsskalning. - Aktiverar slutsatsdragningstabeller med AI Gateway på den modell som betjänar slutpunkten. Se Övervaka hanterade modeller med hjälp av AI Gateway-aktiverade slutsatsdragningstabeller.
Anteckning
För svarsloggar för direktuppspelning aggregeras endast ChatCompletion-kompatibla fält och spårningar.
- Databricks tillhandahåller automatiskt temporära autentiseringsuppgifter för tjänsteprincipal till agentkod som körs i slutpunkten. Autentiseringsuppgifterna har de minsta behörigheterna för att komma åt Databricks-hanterade resurser som definierats under modellloggning. Innan du genererar dessa autentiseringsuppgifter ser Databricks till att slutpunktsägaren har rätt behörighet för att förhindra eskalering av privilegier och obehörig åtkomst. Se Autentisering för beroende resurser.
- Om du har resursberoenden som inte hanteras av Databricks, till exempel med Hjälp av Pinecone, kan du skicka in miljövariabler med hemligheter till
deploy()
-API:et. Se Konfigurera åtkomst till resurser från modellserverslutpunkter.
- Om du har resursberoenden som inte hanteras av Databricks, till exempel med Hjälp av Pinecone, kan du skicka in miljövariabler med hemligheter till
- Om du vill minska kostnaden för inaktiva slutpunkter (på bekostnad av ökad tid för att hantera inledande frågor) kan du aktivera skalning till noll för serverdelsslutpunkten genom att skicka
Aktiverar granskningsappen för din agent. Med granskningsappen kan intressenter chatta med agenten och ge feedback med hjälp av användargränssnittet för granskningsappen.
Loggar varje begäran till granskningsappen eller REST-API:et till en slutsatsdragningstabell. De data som loggas innehåller frågebegäranden, svar och mellanliggande spårningsdata från MLflow Tracing.
Skapar en feedbackmodell med samma katalog och schema som agenten som du försöker distribuera. Den här feedbackmodellen är den mekanism som gör det möjligt att ta emot feedback från granskningsappen och logga den till en slutsatsdragningstabell. Den här modellen hanteras i samma CPU-modell som betjänar slutpunkten som din distribuerade agent. Eftersom den här serverslutpunkten har inferenstabeller aktiverade går det att logga feedback från granskningsappen till en slutsatsdragningstabell.
Anteckning
Distributioner kan ta upp till 15 minuter att slutföra. Det tar 10–30 minuter att ta emot råa JSON-nyttolaster och de formaterade loggarna bearbetas från rånyttolasten ungefär varje timme.
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
Autentisering för beroende resurser
AI-agenter behöver ofta autentisera till andra resurser för att slutföra uppgifter. En agent kan till exempel behöva komma åt ett Vector Search-index för att köra frågor mot ostrukturerade data.
Din agent kan använda någon av följande metoder för att autentisera till beroende resurser när du hanterar den bakom en modellserverslutpunkt:
- Automatisk autentiseringsgenomströmning: Deklarera Databricks-resursberoenden under loggning för din agent. Databricks kan automatiskt etablera, rotera och hantera kortlivade autentiseringsuppgifter när din agent distribueras för säker åtkomst till resurser. Databricks rekommenderar att du använder automatisk autentiseringspassering där det är möjligt.
- Manuell autentisering: Ange långvariga autentiseringsuppgifter manuellt under distributionen av agenter. Använd manuell autentisering för Databricks-resurser som inte stöder automatisk autentiseringsgenomströmning eller för extern API-åtkomst.
automatisk autentiseringsgenomströmning
Modellservern stöder automatisk autentiseringsgenomströmning för de vanligaste typerna av Databricks-resurser som används av agenter.
Om du vill aktivera automatisk autentiseringspassering måste du specificera beroenden för agentloggning.
När du sedan hanterar agenten bakom en slutpunkt utför Databricks följande steg:
Behörighetsverifiering: Databricks verifierar att slutpunktens skapare kan komma åt alla beroenden som anges under agentloggning.
Tjänstens huvudkonto skapas och beviljas: Ett huvudkonto för tjänsten skapas för versionen av agentmodellen och beviljas automatiskt läsbehörighet till agentresurser.
Anteckning
Det systemgenererade tjänstens huvudnamn visas inte i API- eller användargränssnittslistor. Om agentmodellversionen tas bort från slutpunkten, tas även tjänstens huvudprincip bort.
Etablering och rotation av autentiseringsuppgifter: Kortlivade autentiseringsuppgifter (en M2M OAuth-token) för tjänstens huvudnamn matas in i slutpunkten, vilket ger agentkoden åtkomst till Databricks-resurser. Databricks roterar också autentiseringsuppgifterna, vilket säkerställer att din agent har fortsatt säker åtkomst till beroende resurser.
Det här autentiseringsbeteendet liknar "Kör som ägare"-beteendet för Databricks-instrumentpaneler – underordnade resurser såsom Unity Catalog-tabeller används med autentiseringsuppgifterna för en tjänstens principal, vilken har minimal behörighet till beroende resurser.
I följande tabell visas de Databricks-resurser som stöder automatisk autentiseringsgenomströmning och de behörigheter som slutpunktens skapare måste ha när agenten distribueras.
Anteckning
Unity Catalog-resurser kräver också USE SCHEMA
i det överordnade schemat och USE CATALOG
i den överordnade katalogen.
Resurstyp | Behörighet |
---|---|
SQL Warehouse | Använd slutpunkt |
Modelltjänstslutpunkt | Kan göra förfrågningar |
Unity-katalogfunktion | UTFÖRA |
Genieområde | Kan köras |
Index för vektorsökning | Kan använda |
Unity-katalogtabell | SELECT |
Manuell autentisering
Du kan också ange autentiseringsuppgifter manuellt med hjälp av hemlighetsbaserade miljövariabler. Manuell autentisering kan vara till hjälp i följande scenarier:
- Den beroende resursen stöder inte automatisk autentiseringsgenomströmning.
- Agenten har åtkomst till en extern resurs eller ett API.
- Agenten måste använda andra autentiseringsuppgifter än agentdistributionsverktygets.
Om du till exempel vill använda Databricks SDK i din agent för att få åtkomst till andra beroende resurser kan du ange miljövariablerna som beskrivs i Databricks-klientens enhetliga autentisering.
Övervaka distribuerade agenter
När en agent har distribuerats till Databricks Model Serving kan du använda AI Gateway-slutsatsdragningstabeller för att övervaka den distribuerade agenten. Slutsatsdragningstabellerna innehåller detaljerade loggar med begäranden, svar, agentspårningar och agentfeedback från granskningsappen. Med den här informationen kan du felsöka problem, övervaka prestanda och skapa en gyllene datauppsättning för offlineutvärdering.
Se Övervaka utplacerade agenter med inferenstabeller.
Hämta distribuerade program
Följande visar hur du hämtar dina utplacerade agenter.
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
Ge feedback om en distribuerad agent (experimentell)
När du distribuerar din agent med agents.deploy()
skapar och distribuerar agentramverket även en "feedback"-modellversion inom samma slutpunkt, som du kan fråga för att ge feedback om ditt agentprogram. Feedbackposter visas som begäranderader i den inferenstabell som är associerad med din agentens tjänsteslutpunkt.
Observera att det här beteendet är experimentellt: Databricks kan ge ett förstklassigt API för att ge feedback om en distribuerad agent i framtiden, och framtida funktioner kan kräva migrering till det här API:et.
Begränsningar i det här API:et är:
- Feedback-API:et saknar validering av indata – det svarar alltid korrekt, även om ogiltiga indata skickas.
- Feedback-API:et kräver att du skickar in det Databricks-genererade
request_id
från den agentens slutpunktsbegäran som du vill ge feedback om. För att hämtadatabricks_request_id
, inkludera{"databricks_options": {"return_trace": True}}
i din ursprungliga begäran till den serveringspunkt som hanteras av agenten. Agentens slutpunktssvar inkluderar sedandatabricks_request_id
som är associerad med begäran så att du kan skicka tillbaka begärans-ID till feedback-API:et när du ger feedback på agentsvaret. - Feedback samlas in med hjälp av slutsatsdragningstabeller. Se begränsningar i slutsatsdragningstabellen.
Följande exempelbegäran ger feedback om agentslutpunkten med namnet "your-agent-endpoint-name" och förutsätter att DATABRICKS_TOKEN
miljövariabeln är inställd på en 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
Du kan skicka ytterligare eller olika nyckel/värde-par i fälten text_assessments.ratings
och retrieval_assessments.ratings
för att ge olika typer av feedback. I exemplet anger återkopplingsinformationen att agentens svar på begäran med ID 573d4a61-4adb-41bd-96db-0ec8cebc3744
var korrekt, exakt och grundat i kontext som hämtades av ett verktyg för informationshämtning.