Nasazení agenta pro aplikace generující AI

2025-06-12

V tomto článku se dozvíte, jak nasadit svého agenta AI do služby Mosaic AI Model Serving pomocí funkce deploy() z rozhraní Python API Agent Framework.

Nasazení agentů na obsluhu modelu AI v systému Mosaic nabízí následující výhody:

Obsluha modelů spravuje automatické škálování, protokolování, správu verzí a řízení přístupu, takže se můžete soustředit na vývoj agentů kvality.
Odborníci na danou problematiku můžou pomocí aplikace Review pracovat s nasazeným agentem a poskytovat zpětnou vazbu, kterou můžete začlenit do monitorování a hodnocení.
Můžete sledovat agenta vyhodnocováním živého provozu. I když uživatelský provoz nebude zahrnovat skutečnou hodnotu, LLM porotci (a vlastní metrika, kterou jste vytvořili) provádějí nezávislé hodnocení.

Požadavky

MLflow ve verzi 2.13.1 a vyšší pro nasazení agentů pomocí API deploy() 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šší.
Tvůrce koncového bodu (uživatel nasazující agenta) musí mít CREATE VOLUME oprávnění ke schématu katalogu Unity vybranému k ukládání tabulek odvozování v době nasazení. Tím zajistíte, že se ve schématu dají vytvořit relevantní tabulky posouzení a protokolování. Viz Povolení a zakázání odvozovacích tabulek.

databricks-agents Nainstalujte sadu SDK.

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

Nasazení agenta pomocí `deploy()`

Pomocí deploy() nasaďte agenta do koncového bodu obsluhy modelu.

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

Funkce deploy() ve výchozím nastavení provádí následující akce:

`deploy()` akce	Popis
Vytvoření modelu procesoru obsluhující koncové body	Zpřístupňuje agenta uživatelům aplikace tím, že ho obsluhuje prostřednictvím koncového bodu obsluhy modelu.
Zřízení krátkodobých přihlašovacích údajů pro službu principal	Databricks automaticky poskytuje krátkodobé přihlašovací údaje s minimálními oprávněními pro přístup k prostředkům spravovaným službou Databricks definovaným při protokolování modelu. Databricks zkontroluje, jestli má vlastník koncového bodu potřebná oprávnění před vydáním přihlašovacích údajů, aby se zabránilo eskalaci oprávnění a neoprávněnému přístupu. Viz Ověřování závislých prostředků. Pokud váš agent závisí na prostředku, který není spravován Databricks, můžete do `deploy()` předat proměnné prostředí s tajemstvími. Viz Konfigurace přístupu k prostředkům z modelů obsluhujících koncové body.
Povolit aplikaci pro kontrolu	Umožňuje zúčastněným stranám komunikovat s agentem a poskytovat zpětnou vazbu. Viz Použití aplikace pro provádění lidských recenzí generativní AI aplikace (MLflow 2).
Povolení odvozovacích tabulek	Monitorujte a odstraňujte chyby agentů protokolováním vstupů a odpovědí. U `ChatAgent` a `ChatModel` agentů jsou u brány AI povoleny tabulky odvozování. Pro jiná zastaralá schémata agenta se používají standardní tabulky odvozování . V případě protokolů odezvy streamování jsou agregovaná pouze pole a stopa kompatibilní s `ChatAgent` a `ChatCompletion`.
Protokolování požadavků rozhraní REST API a kontrola zpětné vazby k aplikacím	Zaznamenává požadavky rozhraní API a zpětnou vazbu do tabulky inferencí. Vytvořte model zpětné vazby , který bude přijímat a protokolovat zpětnou vazbu z aplikace Pro kontrolu. Tento model je obsluhován ve stejném procesoru na stejném koncovém bodě jako váš nasazený agent.
Povolení monitorování Lakehouse pro Gen AI (beta verze)	Vyžaduje registraci ve službě Lakehouse Monitoring for Gen AI beta. Základní monitorování je automaticky povoleno pro trasování nasazených agentů.
Povolení trasování a monitorování v reálném čase pomocí MLflow 3 (beta verze)	Vyžaduje přihlášení do beta verze programu monitorování Lakehouse pro Gen AI a používání MLflow 3.0 nebo novější. Kromě zaznamenávání stop z nasazených agentů do inference tabulek pro dlouhodobější úložiště, Databricks zaznamenává stopy z vašeho nasazeného agenta do experimentu MLflow pro viditelnost v reálném čase. Tím se snižuje latence monitorování a ladění. Při vytváření nového koncového bodu prostřednictvím `agents.deploy()` se monitorování a trasování konfiguruje tak, aby četlo a zapisovalo z aktuálně aktivního experimentu MLflow. Nakonfigurujte experiment pro konkrétní koncový bod voláním `mlflow.set_experiment()` před vyvoláním `agents.deploy()` vytvoření koncového bodu. Do tohoto experimentu se zapíší záznamy ze všech obsluhovaných agentů v koncovém bodu (včetně agentů přidaných do koncového bodu prostřednictvím následných volání).`agents.deploy()` Monitorování počítá metriky kvality na trasách v tomto experimentu. Ve výchozím nastavení se konfigurují jenom základní metriky monitorování. Pokud chcete přidat soudce LLM a další, podívejte se na Nastavení monitorová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.

Přizpůsobení nasazení

Pokud chcete nasazení přizpůsobit, můžete předat další argumenty deploy(). Můžete například povolit škálování na nulu pro nečinné koncové body předáním scale_to_zero_enabled=True. Tím se sníží náklady, ale zvýší se doba obsluhy počátečních dotazů.

Další parametry najdete v tématu Python API pro Databricks Agenty.

Získat a odstranit nasazení agenta

Načítání nebo správa stávajících nasazení agentů:

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)

Ověřování pro závislé zdroje

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í podřízených zdrojů, když ho nasazujete za koncovým bodem nasazení modelu.

Automatické předávání ověřování: Během protokolování deklarujte závislosti prostředků Databricks pro agenta. 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í autentizace, pokud je to možné.
Ověřování jménem uživatele: Umožňuje používat přihlašovací údaje koncového uživatele agenta pro přístup k rozhraním REST API a prostředkům Databricks.
ruční ověřování: Ručně zadejte dlouhodobé přihlašovací údaje během nasazování agenta. Použijte ruční ověřování pro prostředky Databricks, které nepodporují automatické předávání ověřování, nebo pro externí přístup k rozhraní API.

automatické předání ověřování

Služba pro poskytování modelů podporuje automatické předání ověřování pro nejběžnější typy zdrojů Databricks používané agenty.

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

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

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.
Vytváření a udělování oprávnění služebního účtu: Služební účet je vytvořen pro verzi modelu agenta a automaticky mu je udělen přístup k prostředkům agenta pro čtení.

Poznámka:

Objekt "service principal" generovaný systémem se nezobrazuje v seznamech API ani uživatelského rozhraní. Pokud je z koncového bodu odstraněna verze modelu agenta, bude odstraněn také principál služby.
Zřizování a rotace přihlašovacích údajů: Krátkodobé přihlašovací údaje (token OAuth M2M) pro principál služby jsou vloženy do koncového bodu, což agentovému kódu umožňuje přistupovat k prostředkům Databricks. Databricks také obměňuje přihlašovací údaje, což zajišťuje, že váš agent má 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ík“ pro řídicí panely Databricks – následné zdroje, jako jsou tabulky Unity Catalog, jsou přístupné pomocí přihlašovacích údajů hlavní služby s nejnižšími oprávněními k závislým zdrojům.

Následující tabulka uvádí prostředky Databricks, podporující automatické předávání ověřování, a oprávnění, která musí mít tvůrce koncového bodu při nasazování agenta.

Poznámka:

Prostředky katalogu Unity rovněž potřebují USE SCHEMA na nadřazeném schématu a USE CATALOG na nadřazeném katalogu.

Typ prostředku	Povolení
SQL Warehouse	Použít koncový bod
Koncový bod pro obsluhu modelu	Může provádět dotazy
Funkce katalogu Unity	VYKONAT
Genie space	Může běžet
Index vektorové vyhledávání	Lze použít
Tabulka katalogu Unity	SELECT

Autentizace z pověření uživatele

Ověřování jménem uživatele umožňuje vývojářům agentů přistupovat k citlivým prostředkům Databricks pomocí přihlašovacích údajů koncového uživatele agenta. Pokud chcete povolit přístup k prostředkům jménem uživatele, existují dva kroky:

V kódu agenta zajistěte, aby byl k prostředku Databricks přístup pomocí klienta, který má povolenou autentizaci jménem uživatele. Další informace najdete v tématu Nasazení agenta pomocí ověřování jménem uživatele .
V době protokolování agenta zadejte rozsahy rozhraní REST API koncového uživatele (například vectorsearch.vector-search-endpoints) vyžadované vaším agentem. Po následném nasazení může váš agent přistupovat k prostředkům Databricks jménem koncového uživatele, ale pouze pomocí zadaných oborů. Další informace o rozsazích rozhraní API najdete v tématu Ověření jménem uživatele.

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.

Monitorování nasazených agentů

Po nasazení agenta do obsluhy modelu Databricks můžete k monitorování nasazeného agenta použít tabulky odvozování AI Gateway. Tabulky odvozování obsahují podrobné protokoly požadavků, odpovědí, trasování agentů a zpětné vazby agentů z aplikace pro kontrolu. Tyto informace vám umožní ladit problémy, monitorovat výkon a vytvořit zlatou datovou sadu pro offline vyhodnocení.

Důležité

Je-li MLflow 3 nainstalován ve vašem vývojovém prostředí při volání agents.deploy(), váš koncový bod bude zaznamenávat trasování MLflow v reálném čase do experimentu MLflow, který bude aktivován v době volání agents.deploy(). Před nasazením můžete zavolat mlflow.set_experiment() ke změně aktivního experimentu.

Další podrobnosti najdete v dokumentaci k MLflow .

Viz Ladění a sledování aplikace pomocí trasování.

Získejte nasazené aplikace

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

Podívejte se na Python API agentů Databricks.

Poskytnutí zpětné vazby k nasazenému agentovi (experimentální)

Když nasadíte agenta pomocí agents.deploy(), rozhraní agenta rovněž vytvoří a nasadí verzi modelu "zpětné vazby" ve stejném koncovém bodu, na který můžete odeslat zpětnou vazbu k aplikaci agenta. Položky zpětné vazby se zobrazí jako řádky požadavků v inferenční tabulce , které jsou spojené s bodem obsluhy vašeho služební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, abyste předali request_id, který byl vygenerován službou Databricks, a který se týká požadavku koncového bodu agenta, k němuž chcete poskytnout zpětnou vazbu. Pokud chcete získat databricks_request_id, zahrňte {"databricks_options": {"return_trace": True}} do původní žádosti pro agenta obsluhujícího koncový bod. 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í tabulky odvození.

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 proměnná prostředí DATABRICKS_TOKEN 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 Lakeflow Declarative Pipelines"
                      }
                  ],
                  "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 retrieval_assessments.ratings můžete předat další nebo různé páry klíč-hodnota a poskytnout tak různé typy zpětné vazby. V tomto příkladu datový obsah zpětné vazby označuje, že odpověď agenta na požadavek s ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 byla správná, přesná a podložená v kontextu získaném pomocí nástroje Retriever.

Sdílet prostřednictvím