Delen via

Loggen en registreren van AI-agenten

  • Artikel

Meld AI-agents aan met behulp van Mosaic AI Agent Framework. Het loggen van een agent is de basis van het ontwikkelingsproces. Logboekregistratie legt een 'tijdstip' vast van de code en configuratie van de agent, zodat u de kwaliteit van de configuratie kunt evalueren.

Vereisten

Maak een AI-agent voordat u deze aanmeldt.

Databricks raadt aan de nieuwste versie van de databricks-sdkte installeren.

% pip install databricks-sdk

logboekregistratie op basis van code

Databricks raadt aan om MLflow’s Models from Code-functie te gebruiken bij het loggen van agents.

Bij deze benadering wordt de code van de agent vastgelegd als een Python-bestand en wordt de Python-omgeving vastgelegd als een lijst met pakketten. Wanneer de agent is geïmplementeerd, wordt de Python-omgeving hersteld en wordt de code van de agent uitgevoerd om de agent in het geheugen te laden, zodat deze kan worden aangeroepen wanneer het eindpunt wordt aangeroepen.

U kunt deze benadering koppelen aan het gebruik van validatie-API's vóór de implementatie, zoals mlflow.models.predict() om ervoor te zorgen dat de agent betrouwbaar wordt uitgevoerd wanneer deze wordt geïmplementeerd voor de service.

Als u een voorbeeld van logboekregistratie via code wilt zien, raadpleegt u voorbeeldnotebooks voor ChatAgent-creatie.

Modelhandtekening afleiden tijdens logboekregistratie

Notitie

Databricks raadt het ontwerpen van een agent aan met behulp van de ChatAgent-interface. Als u ChatAgent gebruikt, kunt u deze sectie overslaan; MLflow bepaalt automatisch een geldige handtekening voor uw agent.

Als u de ChatAgent-interface niet gebruikt, moet u een van de volgende methoden gebruiken om de MLflow-modelhandtekening van uw agent op te geven tijdens logboekregistratie:

  1. De handtekening handmatig definiëren
  2. Gebruik de inferentiemogelijkheden van MLflow Model Signature om automatisch de handtekening van de agent te genereren op basis van een invoervoorbeeld dat u opgeeft. Deze methode is handiger dan handmatig de handtekening te definiëren.

De handtekening van het MLflow-model valideert invoer en uitvoer om ervoor te zorgen dat de agent correct communiceert met downstreamhulpprogramma's zoals AI Playground en de beoordelings-app. Het geeft ook richtlijnen aan andere applicaties over hoe de agent effectief te gebruiken.

De LangChain en PyFunc voorbeelden hieronder maken gebruik van modelhandtekening-inferentie.

Zie MLflow-documentatie: Hoe modellen vast te leggen met modelhandtekeningenals u liever bij het loggen expliciet zelf een modelhandtekening definieert.

Logboekregistratie op basis van code met LangChain

In de volgende instructies en codevoorbeelden ziet u hoe u een agent kunt registreren met LangChain.

  1. Maak een notebook of Python-bestand met uw code. In dit voorbeeld heeft het notitieblok of bestand de naam agent.py. Het notebook of bestand moet een LangChain-agent bevatten, waarnaar hier wordt verwezen als lc_agent.

  2. Neem mlflow.models.set_model(lc_agent) op in het notitieblok of bestand.

  3. Maak een nieuw notitieblok om te fungeren als het stuurprogrammanotitieblok (in dit voorbeeld aangeroepen driver.py ).

  4. Gebruik in het stuurprogrammanotebook de volgende code om agent.py uit te voeren en de resultaten te registreren bij een MLflow-model:

    mlflow.langchain.log_model(lc_model="/path/to/agent.py", resources=list_of_databricks_resources)

    De resources parameter declareert door Databricks beheerde resources die nodig zijn om de agent te bedienen, zoals een vectorzoekindex of een eindpunt dat een basismodel dient. Zie Resources opgeven voor automatische verificatiepassthroughvoor meer informatie.

  5. Het model implementeren. Zie Een agent implementeren voor een generatieve AI-toepassing.

  6. Wanneer de serveromgeving wordt geladen, wordt agent.py uitgevoerd.

  7. Wanneer een dienstaanvraag binnenkomt, wordt lc_agent.invoke(...) aangeroepen.


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)

logboekregistratie op basis van code met PyFunc

De volgende instructies en codevoorbeelden laten zien hoe u een agent kunt registreren met PyFunc.

  1. Maak een notebook of Python-bestand met uw code. In dit voorbeeld heeft het notitieblok of bestand de naam agent.py. Het notebook of bestand moet een PyFunc-klasse bevatten met de naam PyFuncClass.

  2. Neem mlflow.models.set_model(PyFuncClass) op in het notitieblok of bestand.

  3. Maak een nieuw notitieblok om te fungeren als het stuurprogrammanotitieblok (in dit voorbeeld aangeroepen driver.py ).

  4. Gebruik in het stuurprogrammanotebook de volgende code om agent.py uit te voeren en de resultaten te registreren bij een MLflow-model:

    mlflow.pyfunc.log_model(python_model="/path/to/agent.py", resources=list_of_databricks_resources)

    De resources parameter declareert door Databricks beheerde resources die nodig zijn om de agent te bedienen, zoals een vectorzoekindex of een eindpunt dat een basismodel dient. Zie Resources opgeven voor automatische verificatiepassthroughvoor meer informatie.

  5. Het model implementeren. Zie Een agent implementeren voor een generatieve AI-toepassing.

  6. Wanneer de serveromgeving wordt geladen, wordt agent.py uitgevoerd.

  7. Wanneer een dienstaanvraag binnenkomt, wordt PyFuncClass.predict(...) aangeroepen.

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)

Specificeer bronnen voor automatische verificatiedoorvoer

AI-agents moeten zich vaak authenticeren bij andere bronnen om taken te voltooien. Een agent moet bijvoorbeeld toegang krijgen tot een Vector Search-index om een query uit te voeren op ongestructureerde gegevens.

Zoals beschreven in Verificatie voor afhankelijke resources, ondersteunt Model Serving verificatie bij zowel door Databricks beheerde als externe resources wanneer u de agent implementeert.

Voor de meest voorkomende Databricks-resourcetypen raadt Databricks aan en ondersteunt het vooraf declareren van resourceafhankelijkheden voor de agent tijdens het loggen. Hierdoor wordt automatische authenticatie-passthrough mogelijk gemaakt wanneer u de agent implementeert. Databricks voorziet, roteert en beheert automatisch kortstondige referenties om veilig toegang te krijgen tot deze resourceafhankelijkheden vanuit het agent-eindpunt.

Als u automatische verificatiepassthrough wilt inschakelen, geeft u afhankelijke resources op met behulp van de parameter resources van de log_model() API, zoals wordt weergegeven in de volgende code.

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 raadt u aan om handmatig resources op te geven voor alle agentversies.

Notitie

Als u geen middelen opgeeft bij het loggen van LangChain-agents met mlflow.langchain.log_model(...), voert MLflow naar beste vermogen automatische inferentie van middelen uit. Echter, dit kan niet alle afhankelijkheden vastleggen, wat resulteert in autorisatiefouten wanneer de agent wordt bediend of bevraagd.

De volgende tabel bevat de Databricks-resources die ondersteuning bieden voor automatische verificatie-passthrough en de minimale mlflow versie die vereist is om de resource te loggen.

Brontype Minimale mlflow versie die is vereist voor het registreren van de resource
Vectorzoekindex Vereist mlflow 2.13.1 of hoger
Eindpunt voor modelserver Vereist mlflow 2.13.1 of hoger
SQL Warehouse Vereist mlflow 2.16.1 of hoger
Unity Catalog-functie Vereist mlflow 2.16.1 of hoger
Genieruimte Vereist mlflow 2.17.1 of hoger
Unity Catalog-tabel Vereist mlflow 2.18.0 of hoger
Unity Catalog-verbinding Vereist mlflow 2.17.1 of hoger

Automatische verificatie voor OpenAI-clients

Als uw agent gebruikmaakt van de OpenAI-client, gebruikt u de Databricks SDK om automatisch te verifiëren tijdens de implementatie. Databricks SDK biedt een wrapper voor het maken van de OpenAI-client met automatisch geconfigureerde autorisatie. Voer het volgende uit in uw notebook:

% pip install databricks-sdk[openai]

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

Geef vervolgens eindpunt Model Serving op als onderdeel van resources voor automatische authenticatie tijdens implementatie.

de agent registreren bij Unity Catalog

Voordat u de agent implementeert, moet u de agent registreren bij Unity Catalog. Het registreren van agentpakketten zet ze om tot een model in de Unity Catalog. Als gevolg hiervan kunt u Unity Catalog-machtigingen gebruiken voor autorisatie voor resources in de agent.

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)

Volgende stappen