Protokolování a registrace agentů AI

Článek
01/21/2025

Důležité

Tato funkce je ve verzi Public Preview.

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

Požadavky

Před protokolováním vytvořte agenta AI.

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ěží.

Kód, který protokoluje agenta nebo agentku, musí být v samostatném poznámkovém bloku než kód agenta. Tento poznámkový blok se nazývá poznámkový blok ovladače. Příklad poznámkového bloku najdete v příkladu poznámkových bloků.

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

Během protokolování musíte definovat MLflow Signaturu modelu, která určuje vstupní a výstupní schéma agenta. Podpis ověří 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.

Databricks doporučuje používat funkce odvozování podpisů modelu MLflow k automatickému vygenerování podpisu agenta na základě zadaného vstupního příkladu. Tento přístup je pohodlnější než ruční definování podpisu.

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 Určení prostředků pro předávání automatického ověřování.
Nasazení modelu. Viz Nasazení agenta pro generování aplikace AI.
Při načtení agent.py obslužného prostředí se spustí.
Když přijde žádost o obsluhu, lc_agent.invoke(...) zavolá se.


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 najdete v tématu Určení prostředků pro předávání automatického ověřování.
Nasazení modelu. Viz Nasazení agenta pro generování aplikace AI.
Při načtení agent.py obslužného prostředí se spustí.
Když přijde žádost o obsluhu, PyFuncClass.predict(...) zavolá se.

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 prostředky pro automatické předávání ověřování

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.

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.

Pro nejběžnější typy prostředků Databricks podporuje a doporučuje deklarovat závislosti prostředků agenta již při protokolování. To umožňuje automatické předávání ověřování při nasazení agenta – Databricks automaticky zřizuje, obměňuje a spravuje krátkodobé přihlašovací údaje pro bezpečný přístup k těmto závislostem prostředků z koncového bodu agenta.

Pokud chcete povolit automatické předávání ověřování, zadejte závislé prostředky pomocí parametru resources rozhraní API log_model(), 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,
)

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"),
    ]
  )

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í ověřování, a minimální verzi mlflow potřebnou k záznamu 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` verze 2.17.1 nebo vyšší.
Tabulka katalogu Unity	Vyžaduje verzi `mlflow` 2.18.0 nebo vyšší.

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)

Další kroky

Přidejte trasování do agenta AI.
Nasazení agenta AI

Sdílet prostřednictvím