Zaznamenávání a registrace agentů AI

2025-06-12

Protokolování agentů AI s využitím architektury agenta Mosaic AI Záznam agenta je základem vývojového procesu. Protokolování zaznamenává "bod v čase" kódu a konfigurace agenta, abyste mohli vyhodnotit kvalitu konfigurace.

Požadavky

Vytvořte agenta umělé inteligence, než ho zaznamenáte.

Databricks doporučuje nainstalovat nejnovější verzi databricks-sdk.

% pip install databricks-sdk

protokolování založené na kódu

Databricks doporučuje při protokolování agentů používat funkci MLflow Models from Code.

V tomto přístupu se kód agenta zachytí jako soubor Pythonu a prostředí Pythonu se zachytí jako seznam balíčků. Po nasazení agenta se prostředí Pythonu obnoví a kód agenta se spustí, aby se agent načetl do paměti, aby se mohl vyvolat při zavolání koncového bodu.

Tento přístup můžete spojit s použitím rozhraní API pro ověřování před nasazením, jako je mlflow.models.predict(), abyste zajistili, že agent při nasazování pro obsluhu spolehlivě běží.

Pokud chcete zobrazit příklad protokolování založeného na kódu, podívejte se na ukázkové poznámkové bloky ChatAgent.

Určení podpisu modelu během protokolování

Poznámka:

Databricks doporučuje vytvořit agenta pomocí rozhraní ChatAgent. Pokud používáte ChatAgent, můžete tuto část přeskočit; MLflow automaticky odvodí platný podpis pro vašeho agenta.

Pokud nepoužíváte rozhraní ChatAgent, musíte použít jednu z následujících metod k určení podpisu modelu agenta MLflow v době protokolování:

Ruční definování podpisu
Pomocí funkcí odvozování podpisů modelu MLflow můžete automaticky vygenerovat podpis agenta na základě zadaného vstupního příkladu. Tento přístup je pohodlnější než ruční definování podpisu.

Podpis modelu MLflow ověřuje vstupy a výstupy, aby se zajistilo, že agent správně komunikuje s podřízenými nástroji, jako je AI Playground a revizní aplikace. Také vás provede dalšími aplikacemi, jak efektivně používat agenta.

Příklady LangChain a PyFunc níže používají odvozování podpisů modelu.

Pokud byste raději v době protokolování explicitně definovali podpis modelu, přečtěte si dokumentaci MLflow – jak protokolovat modely pomocí podpisů.

Protokolování založené na kódu pomocí jazyka LangChain

Následující pokyny a ukázka kódu ukazují, jak zaznamenat agenta pomocí LangChain.

Vytvořte poznámkový blok nebo soubor Pythonu pomocí kódu. V tomto příkladu má poznámkový blok nebo soubor název agent.py. Poznámkový blok nebo soubor musí obsahovat agenta LangChain, který se zde označuje jako lc_agent.
Do poznámkového bloku nebo souboru přidejte mlflow.models.set_model(lc_agent).
Vytvořte nový poznámkový blok, který bude sloužit jako poznámkový blok ovladače (označovaný driver.py v tomto příkladu).
V poznámkovém bloku ovladače pomocí následujícího kódu spusťte agent.py a zapište výsledky do modelu MLflow:
```
mlflow.langchain.log_model(lc_model="/path/to/agent.py", resources=list_of_databricks_resources)
```
Parametr resources deklaruje prostředky spravované službou Databricks potřebné k poskytování agenta, jako je index vektorového vyhledávání nebo obsluha koncového bodu, který slouží jako základní model. Další informace najdete v tématu Ověřování pro prostředky Databricks.
Nasaďte model. Viz Nasazení agenta pro aplikace generující AI.
Když je obslužné prostředí načteno, spustí se agent.py.
Když přijde žádost o obsluhu, lc_agent.invoke(...) se zavolá.


import mlflow

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

# example using langchain
with mlflow.start_run():
  logged_agent_info = mlflow.langchain.log_model(
    lc_model=code_path,
    model_config=config_path, # If you specify this parameter, this configuration is used by agent code. The development_config is overwritten.
    artifact_path="agent", # This string is used as the path inside the MLflow model where artifacts are stored
    input_example=input_example, # Must be a valid input to the agent
    example_no_conversion=True, # Required
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.langchain.load_model(logged_agent_info.model_uri)
model.invoke(example)

protokolování založené na kódu pomocí PyFunc

Následující pokyny a ukázka kódu ukazují, jak protokolovat agenta pomocí PyFunc.

Vytvořte poznámkový blok nebo soubor Pythonu pomocí kódu. V tomto příkladu má poznámkový blok nebo soubor název agent.py. Poznámkový blok nebo soubor musí obsahovat třídu PyFunc s názvem PyFuncClass.
Zahrnout mlflow.models.set_model(PyFuncClass) do poznámkového bloku nebo souboru
Vytvořte nový poznámkový blok, který bude sloužit jako poznámkový blok ovladače (označovaný driver.py v tomto příkladu).
V poznámkovém bloku ovladače spusťte následující kód agent.py a použijte log_model() k protokolování výsledků do modelu MLflow:
```
mlflow.pyfunc.log_model(python_model="/path/to/agent.py", resources=list_of_databricks_resources)
```
Parametr resources deklaruje prostředky spravované službou Databricks potřebné k poskytování agenta, jako je index vektorového vyhledávání nebo obsluha koncového bodu, který slouží jako základní model. Další informace najdete v tématu Ověřování pro prostředky Databricks.
Nasaďte model. Viz Nasazení agenta pro aplikace generující AI.
Když je obslužné prostředí načteno, spustí se agent.py.
Když přijde žádost o obsluhu, PyFuncClass.predict(...) se zavolá.

import mlflow
from mlflow.models.resources import (
    DatabricksServingEndpoint,
    DatabricksVectorSearchIndex,
)

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model=agent_notebook_path,
    artifact_path="agent",
    input_example=input_example,
    resources=resources_path,
    example_no_conversion=True,
    resources=[
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
    ]
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.pyfunc.load_model(logged_agent_info.model_uri)
model.invoke(example)

Ověřování prostředků Databricks

Agenti AI se často musí ověřovat 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.

Jak je popsáno v tématu Ověřování závislých prostředků, služba Model Serving podporuje ověřování u prostředků spravovaných službou Databricks i u externích prostředků při nasazování agenta.

Obsluha modelů podporuje dva různé druhy ověřování pro prostředky spravované službou Databricks:

Ověřování systému: Umožňuje instančnímu objektu agenta přístup k jakýmkoli závislým prostředkům zadaným v době protokolování agenta. To je užitečné pro přístup ke sdíleným nebo necitlivým prostředkům, například index vektorového vyhledávání obsahující veřejnou dokumentaci.
[Beta] Ověřování jménem uživatele: Umožňuje agentovi používat přihlašovací údaje koncového uživatele pro přístup k prostředkům Databricks. To je užitečné ve scénářích, kdy váš agent potřebuje přistupovat k citlivým datům nebo dotazovat vzdálená rozhraní API, aby mohli provádět akce pro jednotlivé uživatele.

Specifikace prostředků pro předávání automatického ověřování (systémové ověřování)

Databricks pro nejběžnější typy prostředků podporuje a doporučuje, aby byly závislosti prostředků agenta deklarovány již během protokolování. To umožňuje automatické předávání ověřovacích údajů při nasazování agenta - Databricks automaticky zřizuje, obměňuje a spravuje krátkodobé přístupové údaje pro zabezpečený přístup k těmto závislým prostředkům z koncového bodu agenta.

Pokud chcete povolit předávání automatického ověřování, zadejte závislé prostředky pomocí resources parametru log_model() rozhraní API, jak je znázorněno v následujícím kódu.

import mlflow
from mlflow.models.resources import (
  DatabricksVectorSearchIndex,
  DatabricksServingEndpoint,
  DatabricksSQLWarehouse,
  DatabricksFunction,
  DatabricksGenieSpace,
  DatabricksTable,
  DatabricksUCConnection
)

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model=agent_notebook_path,
    artifact_path="agent",
    input_example=input_example,
    example_no_conversion=True,
    # Specify resources for automatic authentication passthrough
    resources=[
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
      DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
      DatabricksFunction(function_name="ml.tools.python_exec"),
      DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
      DatabricksTable(table_name="your_table_name"),
      DatabricksUCConnection(connection_name="your_connection_name"),
    ]
  )

Databricks doporučuje ručně zadat resources pro všechny varianty agenta.

Poznámka:

Pokud při logování agentů LangChain pomocí mlflow.langchain.log_model(...)nezadáte prostředky, MLflow provádí automatické odvozování prostředků v rámci možností. To ale nemusí zachytávat všechny závislosti, což vede k chybám autorizace při obsluhě nebo dotazování agenta.

Následující tabulka uvádí prostředky Databricks, které podporují automatické předávání autentizace, a minimální verzi mlflow potřebnou k zaznamenání prostředku.

Typ prostředku	Minimální `mlflow` verze potřebná k protokolování prostředku
Index vektorové vyhledávání	Vyžaduje `mlflow` ve verzi 2.13.1 nebo novější.
Koncový bod obsluhy modelu	Vyžaduje `mlflow` ve verzi 2.13.1 nebo novější.
SQL Warehouse	Vyžaduje `mlflow` 2.16.1 nebo vyšší.
Funkce Unity Catalog	Vyžaduje `mlflow` 2.16.1 nebo vyšší.
Genie space	Vyžaduje `mlflow` verzi 2.17.1 nebo vyšší.
Tabulka katalogu Unity	Vyžaduje verzi `mlflow` 2.18.0 nebo vyšší.
Připojení katalogu Unity	Vyžaduje `mlflow` verzi 2.17.1 nebo vyšší.

Autentizace z pověření uživatele

Důležité

Tato funkce je v beta verzi.

Při zaznamenávání agenta, který používá ověřování jménem koncového uživatele, uveďte minimální sadu rozsahů Databricks API potřebných k tomu, aby bylo možné v kódu agenta provádět akce za koncového uživatele. Tím se zajistí, že má agent přístup s nejnižšími oprávněními k provádění akcí jménem koncového uživatele při nasazení, což zvyšuje zabezpečení tím, že brání neoprávněným akcím a minimalizuje riziko zneužití tokenu.

Níže je seznam oborů potřebných pro přístup k několika běžným typům prostředků Databricks.

Prostředek Databricks	Požadované obory rozhraní API
Index vektorové vyhledávání	`serving.serving-endpoints`,`vectorsearch.vector-search-endpoints`,`vectorsearch.vector-search-indexes`
Koncový bod obsluhy modelu	`serving.serving-endpoints`
SQL Warehouse	`sql.statement-execution`,`sql.warehouses`
Spojení UC	`catalog.connections`
Genie Space	`dashboards.genie`

Pokud chcete povolit ověřování jménem uživatele, pošlete MLflow AuthPolicy do log_model(), jak je znázorněno v následujícím příkladu. MLflow AuthPolicy má dvě komponenty:

system_auth_policy: Zadejte prostředky pro ověřování systému. Agenti obvykle používají ověřování systému pro sdílené prostředky (např. k dotazování modelů obsluhujících koncové body) v kombinaci s ověřováním jménem uživatele pro přístup k citlivým prostředkům nebo rozhraním API.
user_auth_policy: Určete rozsahy API, které váš agent potřebuje pro autentifikaci jménem uživatele

from mlflow.models.resources import DatabricksServingEndpoint
from mlflow.models.auth_policy import SystemAuthPolicy, UserAuthPolicy, AuthPolicy

resources = [
    DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct")
]
# Specify resources here for system authentication
system_auth_policy = SystemAuthPolicy(resources=resources)

# Specify the minimal set of API scopes needed for on-behalf-of-user authentication
	# When deployed, the agent can access Databricks resources and APIs
	# on behalf of the end user, but only via REST APIs that are covered by the list of
	# scopes below

user_auth_policy = UserAuthPolicy(
    api_scopes=[
        "serving.serving-endpoints",
        "vectorsearch.vector-search-endpoints",
        "vectorsearch.vector-search-indexes",
    ]
)

with mlflow.start_run():
    logged_agent_info = mlflow.pyfunc.log_model(
        ...
        # Instead of passing `resources` (which only supports system authentication),
	        # pass an auth_policy to log_model to enable both system authentication and
	        # on-behalf-of-user authentication
        auth_policy=AuthPolicy(
            system_auth_policy=system_auth_policy,
            user_auth_policy=user_auth_policy
        )
    )

Automatické ověřování pro klienty OpenAI

Pokud váš agent používá klienta OpenAI, použijte sadu Databricks SDK k automatickému ověření během nasazování. Sada Databricks SDK poskytuje obálku pro vytváření klienta OpenAI s automaticky nakonfigurovanou get_open_ai_client()autorizací. V poznámkovém bloku spusťte následující příkaz:

% pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

Pak určete jako součást resources koncový bod pro obsluhu modelu, který se automaticky autorizuje v době nasazení.

registrace agenta do katalogu Unity

Před nasazením agenta musíte agenta zaregistrovat do katalogu Unity. Registrace agenta zabalí ho jako model v katalogu Unity. V důsledku toho můžete pro autorizaci prostředků v agentu použít oprávnění katalogu Unity.

import mlflow

mlflow.set_registry_uri("databricks-uc")

catalog_name = "test_catalog"
schema_name = "schema"
model_name = "agent_name"

model_name = catalog_name + "." + schema_name + "." + model_name
uc_model_info = mlflow.register_model(model_uri=logged_agent_info.model_uri, name=model_name)

Viz mlflow.register_model().

Sdílet prostřednictvím