Zaznamenávání a registrace agentů AI

Článek
03/11/2025

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 používat modely MLflow z funkcí kódu při protokolování agentů.

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 naleznete v části Specifikace prostředků pro automatické předávání ověřování.
Nasaďte model. Viz Nasazení agenta pro generování aplikace 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 pomocí následujícího kódu spusťte agent.py a zapište výsledky 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 naleznete v části Specifikace prostředků pro automatické předávání ověřování.
Nasazení modelu. Viz Nasazení agenta pro generování aplikace AI.
Jakmile 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-mixtral-8x7b-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)

Určete zdroje pro automatické předávání ověřovacích údajů

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.

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 automatické ověřování, zadejte závislé prostředky pomocí parametru resources v rozhraní API log_model(), jak je uvedeno 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-mixtral-8x7b-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šší.

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 vytvoření klienta OpenAI s automaticky nakonfigurovanou 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)

Sdílet prostřednictvím