Dela via

Distribuera en agent för generativa AI-program

  • Artikel

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ån databricks.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()

Använd deploy() för att distribuera din agent till en modell som betjänar slutpunkten.

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

Funktionen deploy() utför följande åtgärder som standard:

  • Skapar processormodell som betjänar slutpunkter för att integrera din agent i användarinriktade program.

  • Aktiverar slutsatsdragningstabeller för att övervaka och felsöka agenter genom att logga indata och svar för begäranden.

    • För ChatAgent och ChatModel agenter aktiveras slutsatsdragningstabeller med AI Gateway.
    • För inaktuella agentscheman används standardinferenstabeller.
    • För svarsloggar för direktuppspelning aggregeras endast ChatAgent och ChatCompletion kompatibla fält och spårningar.

  • Tillhandahåller kortlivade autentiseringsuppgifter för tjänstens huvudnamn till agentkoden som körs i slutpunkten.

  • Aktiverar granskningsappen, så att intressenter kan interagera med agenten och ge feedback. Se Använd granskningsappen för mänskliga granskningar av en gen AI-app.

  • loggar REST API-begäranden och appfeedback till en slutledningstabell.

    • Skapar feedbackmodell för att acceptera feedback från granskningsappen och logga den till en slutsatstabell. Den här modellen hanteras i samma CPU-modell som betjänar slutpunkten som din distribuerade agent.

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.

Anpassa distribution

Om du vill anpassa distributionen kan du skicka ytterligare argument till deploy(). Du kan till exempel aktivera skalning till noll för inaktiva slutpunkter genom att skicka scale_to_zero_enabled=True. Detta minskar kostnaderna men ökar tiden för att hantera inledande frågor.

Fler parametrar finns i Databricks Agents Python API.

Hämta och ta bort agentdistributioner

Hämta eller hantera befintliga agentdistributioner:

from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

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:

  1. 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.
  2. 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 vidarebefordran av autentisering

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:

  1. Behörighetsverifiering: Databricks verifierar att slutpunktens skapare kan komma åt alla beroenden som anges under agentloggning.

  2. 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.

  3. 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ämta databricks_request_id, inkludera {"databricks_options": {"return_trace": True}} i din ursprungliga begäran till den serveringspunkt som hanteras av agenten. Agentens slutpunktssvar inkluderar sedan databricks_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.

Ytterligare resurser