Sdílet prostřednictvím

Nasazení agenta pro aplikaci generující AI

  • Článek

Důležité

Tato funkce je ve verzi Public Preview.

Tento článek ukazuje, jak nasadit agenta AI pomocí deploy() funkce z rozhraní Api Pythonu pro rozhraní Agent Framework.

Požadavky

  • MLflow 2.13.1 nebo vyšší pro nasazení agentů pomocí deploy() rozhraní API z databricks.agents.

  • Zaregistrujte agenta AI do katalogu Unity. Viz Zaregistrujte agenta do Katalogu Unity.

  • Nasazení agentů mimo poznámkový blok Databricks vyžaduje databricks-agents SDK verze 0.12.0 nebo vyšší.

  • databricks-agents Nainstalujte sadu SDK.

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

Nasazení agenta pomocí deploy()

Funkce deploy() provede následující:

  • Vytvoří model procesoru obsluhující koncové body pro vašeho agenta, který je možné integrovat do aplikace určené pro uživatele.
    • Pokud chcete snížit náklady na nečinné koncové body (na úkor zvýšené doby obsluhy počátečních dotazů), můžete povolit škálování na nulu pro obsluhující koncový bod předáním scale_to_zero_enabled=Truedeploy()do . Viz očekávání škálování koncových bodů.
    • Tabulky odvozování jsou povolené na těchto koncových bodech obsluhy modelu. Viz Tabulky odvozování pro monitorování a ladění modelů.
    • Databricks automaticky poskytuje krátkodobé přihlašovací údaje uživatelského účtu služby pro agentový kód spuštěný v koncovém bodu. Přihlašovací údaje mají minimální oprávnění pro přístup k prostředkům, které spravuje platforma Databricks , jak je definováno v souvislosti s protokolováním modelu. Před generováním těchto přihlašovacích údajů databricks zajistí, že vlastník koncového bodu má příslušná oprávnění, aby se zabránilo eskalaci oprávnění a neoprávněnému přístupu. Viz Ověřování závislých prostředků.
  • Povolí aplikaci Review pro vašeho agenta. Aplikace Review umožňuje účastníkům chatovat s agentem a poskytovat zpětnou vazbu pomocí UI aplikace Review.
  • Protokoluje všechny požadavky do tabulky odvozování aplikace nebo rozhraní REST API. Protokolovaná data zahrnují požadavky na dotazy, odpovědi a zprostředkující data trasování z trasování MLflow.
  • Vytvoří model zpětné vazby se stejným katalogem a schématem jako agent, který se pokoušíte nasadit. Tento model zpětné vazby je mechanismus, který umožňuje přijmout zpětnou vazbu z aplikace review a protokolovat ji do tabulky odvozování. Tento model se obsluhuje ve stejném modelu procesoru, který slouží koncovému bodu jako nasazený agent. Vzhledem k tomu, že tento koncový bod obsluhy má povolené tabulky odvozování, je možné protokolovat zpětnou vazbu z aplikace Review do tabulky odvozování.

Poznámka:

Dokončení nasazení může trvat až 15 minut. Doručení nezpracovaných datových částí JSON trvá 10 až 30 minut a formátované protokoly se zpracovávají z nezpracovaných datových částí přibližně každou hodinu.


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

Tabulky odvození rozšířeného agenta

Vytvoří deploy() tři tabulky odvozování pro každé nasazení za účelem protokolování požadavků a odpovědí do a z koncového bodu obsluhujícího agenta. Uživatelé můžou očekávat, že data budou v tabulce datové části do hodiny od interakce s nasazením.

Naplnění protokolů žádostí datové části a protokolů posouzení může trvat déle, ale nakonec se odvozují z tabulky nezpracované datové části. Protokoly žádostí a posouzení můžete extrahovat sami z tabulky datové části. Odstranění a aktualizace tabulky datové části se neprojeví v protokolech žádostí o datovou část ani v protokolech posouzení datové části.

Poznámka:

Pokud máte povolenou bránu firewall služby Azure Storage, obraťte se na tým účtu Databricks a povolte tabulky odvozování pro vaše koncové body.

Table Příklad názvu tabulky katalogu Unity Co je v každé tabulce
Datová část {catalog_name}.{schema_name}.{model_name}_payload Nezpracované datové části požadavků JSON a odpovědí
Protokoly žádostí o datovou část {catalog_name}.{schema_name}.{model_name}_payload_request_logs Formátované požadavky a odpovědi, trasování MLflow
Protokoly posouzení datové části {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Naformátovaná zpětná vazba, jak je uvedeno v aplikaci pro kontrolu, pro každý požadavek

Následující příklad ukazuje schéma tabulky protokolů požadavků.

Název sloupce Typ Description
client_request_id String ID požadavku klienta, obvykle null.
databricks_request_id String ID požadavku Databricks
date Datum Datum žádosti.
timestamp_ms Dlouhé celé číslo Časové razítko v milisekundách
timestamp Časové razítko Časové razítko požadavku.
status_code Celé číslo Stavový kód koncového bodu
execution_time_ms Dlouhé celé číslo Celkový počet milisekund provádění.
conversation_id String ID konverzace extrahované z protokolů požadavků
request String Poslední dotaz uživatele z konverzace uživatele. Tento požadavek se extrahuje z požadavku RAG.
response String Poslední odpověď na uživatele. Tento požadavek se extrahuje z požadavku RAG.
request_raw String Řetězcová reprezentace požadavku.
response_raw String Řetězcová reprezentace odpovědi
trace String Řetězcové znázornění trasování extrahovaného ze databricks_options struktury odpovědi
sampling_fraction Hodnota s dvojitou přesností Vzorkování zlomku.
request_metadata Map[Řetězec, Řetězec] Mapa metadat souvisejících s koncovým bodem obsluhující model přidružený k požadavku Tato mapa obsahuje název koncového bodu, název modelu a verzi modelu používanou pro váš koncový bod.
schema_version String Celé číslo pro verzi schématu.

Následuje schéma tabulky protokolů posouzení.

Název sloupce Typ Description
request_id String ID požadavku Databricks
step_id String Odvozeno z posouzení načítání.
source Struktura Pole struktury obsahující informace o tom, kdo posouzení vytvořil.
timestamp Časové razítko Časové razítko požadavku.
text_assessment Struktura Pole struktury obsahující data pro jakoukoli zpětnou vazbu k odpovědím agenta z aplikace pro kontrolu
retrieval_assessment Struktura Pole struktury obsahující data pro zpětnou vazbu k dokumentům načteným pro odpověď.

Ověřování pro závislé prostředky

Agenti umělé inteligence se často potřebují ověřit v jiných prostředcích, aby mohli provádět úlohy. Například agent může potřebovat přístup k indexu vektorového vyhledávání pro dotazování na nestrukturovaná data.

Váš agent může použít jednu z následujících metod k ověření závislých prostředků, když ho obsluhujete za koncovým bodem obsluhy modelu:

  1. automatického předávání ověřování: Deklarujte závislosti prostředků Databricks pro vašeho agenta během protokolování. Databricks může automaticky zřizovat, obměňovat a spravovat krátkodobé přihlašovací údaje při nasazení vašeho agenta pro bezpečný přístup k prostředkům. Databricks doporučuje používat automatické předávání ověřování, pokud je to možné.
  2. ruční ověřování: Ručně zadejte dlouhodobé přihlašovací údaje během nasazování agenta. Pro prostředky Databricks, které nepodporují předávání automatického ověřování nebo pro externí přístup k rozhraní API, použijte ruční ověřování.

Předávání automatického ověřování

Obsluha modelů podporuje předávání automatického ověřování pro nejběžnější typy prostředků Databricks používaných agenty.

Chcete-li povolit předávání automatického ověřování, musíte zadat závislosti při přihlašování agenta.

Když pak obsluhujete agenta za koncovým bodem, Databricks provede následující kroky:

  1. ověření oprávnění: Databricks ověří, že tvůrce koncového bodu má přístup ke všem závislostem zadaným během přihlášení agenta.

  2. vytvoření a uděleníinstančního objektu: Instanční objekt se vytvoří pro verzi modelu agenta a automaticky se udělí přístup pro čtení k prostředkům agenta.

    Poznámka:

    Instanční objekt vygenerovaný systémem se nezobrazuje ve výpisech rozhraní API ani uživatelského rozhraní. Pokud se z koncového bodu odebere verze modelu agenta, odstraní se také zástupce služby.

  3. Zřizování a obměna přihlašovacích údajů: Dočasné přihlašovací údaje (token OAuth M2M) pro služební principál se vkládají do koncového bodu, což umožňuje kódu agenta přístup k prostředkům Databricks. Databricks také obměňuje přihlašovací údaje a zajišťuje, aby váš agent měl nepřetržitý a zabezpečený přístup k závislým prostředkům.

Toto chování ověřování se podobá chování "Spustit jako vlastníka" pro řídicí panely Databricks – podřízené prostředky, jako jsou tabulky Katalogu Unity, jsou přístupné pomocí přihlašovacích údajů instančního objektu s přístupem s nejnižšími oprávněními k závislým prostředkům.

Následující tabulka uvádí zdroje Databricks, které podporují automatické předávání autentizace, a oprávnění, která musí mít tvůrce koncového bodu pro nasazení agenta.

Poznámka:

Prostředky katalogu Unity vyžadují také USE SCHEMA v nadřazeném schématu a USE CATALOG v nadřazeném katalogu.

Typ prostředku Oprávnění
SQL Warehouse Použití koncového bodu
Koncový bod obsluhy modelu Může dotazovat
Funkce katalogu Unity VYKONAT
Genie space Může běžet
Index vektorové vyhledávání Může použít
Tabulka katalogu Unity VYBRAT

Ruční ověřování

Přihlašovací údaje můžete také zadat ručně pomocí proměnných prostředí založených na tajných kódech. Ruční ověřování může být užitečné v následujících scénářích:

  • Závislý prostředek nepodporuje automatický průchod ověřováním.
  • Agent přistupuje k externímu prostředku nebo rozhraní API.
  • Agent musí používat jiné přihlašovací údaje, než jsou přihlašovací údaje nasazeného agenta.

Pokud chcete například použít sadu Databricks SDK ve vašem agentovi pro přístup k dalším závislým prostředkům, můžete nastavit proměnné prostředí popsané v sjednocené ověřování klienta Databricks.

Získání nasazených aplikací

Následující příklad ukazuje, jak získat nasazené agenty.

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

Poskytnutí zpětné vazby k nasazeným agentem (experimentální)

Když nasadíte agenta pomocí agents.deploy()rozhraní agenta, rozhraní agenta také vytvoří a nasadí verzi modelu zpětné vazby ve stejném koncovém bodu, na který můžete zadat zpětnou vazbu k aplikaci agenta. Položky zpětné vazby se zobrazí jako řádky požadavků v tabulce odvozování přidružené ke koncovému bodu obsluhujícího agenta.

Toto chování je experimentální: Databricks může poskytnout prvotřídní rozhraní API pro poskytování zpětné vazby k nasazeným agentům v budoucnu a budoucí funkce můžou vyžadovat migraci na toto rozhraní API.

Mezi omezení tohoto rozhraní API patří:

  • Rozhraní API pro zpětnou vazbu nemá ověření vstupu – vždy úspěšně reaguje, i když bylo předáno neplatné zadání.
  • Rozhraní API pro zpětnou vazbu vyžaduje předání požadavku koncového bodu agenta vygenerovaného request_id službou Databricks, ke kterému chcete poskytnout zpětnou vazbu. Pokud chcete získat , zahrňte databricks_request_id ho {"databricks_options": {"return_trace": True}}do původního požadavku do koncového bodu obsluhujícího agenta. Odpověď koncového bodu agenta pak zahrne databricks_request_id přidružené k požadavku, abyste mohli id požadavku předat zpět do rozhraní API pro zpětnou vazbu při poskytování zpětné vazby k odpovědi agenta.
  • Zpětná vazba se shromažďuje pomocí odvozovacích tabulek. Viz omezení odvozovací tabulky.

Následující příklad požadavku poskytuje zpětnou vazbu ke koncovému bodu agenta s názvem "your-agent-endpoint-name" a předpokládá, že DATABRICKS_TOKEN proměnná prostředí je nastavená na token rozhraní REST API Databricks.

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

Do polí text_assessments.ratings a polí můžete předat další nebo různé páry retrieval_assessments.ratings klíč-hodnota a poskytnout tak různé typy zpětné vazby. V tomto příkladu datová část zpětné vazby označuje, že odpověď agenta na požadavek s ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 byla správná, přesná a uzemněná v kontextu načteného nástrojem retrieveru.

Další materiály