Loggen en registreren van AI-agenten

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 de modellen van MLflow te gebruiken vanuit codefunctionaliteit bij het registreren 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 Verificatie voor Databricks-resources voor meer informatie.

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

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 driver notebook de volgende code om agent.py uit te voeren en om de resultaten naar een MLflow-model te loggen met log_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 Verificatie voor Databricks-resources voor meer informatie.

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

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-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)

Verificatie voor Databricks-resources

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.

Model Serving ondersteunt twee verschillende soorten verificatie voor door Databricks beheerde resources:

1. Systeemverificatie: hiermee kan de service-principal van de agent toegang krijgen tot afhankelijke resources die zijn opgegeven tijdens de registratietijd van de agent. Dit is handig voor toegang tot gedeelde of niet-gevoelige resources, bijvoorbeeld een vectorzoekindex met openbare documentatie
2. [Bèta] Verificatie namens de gebruiker: hiermee kan de agent referenties van eindgebruikers gebruiken voor toegang tot Databricks-resources. Dit is handig voor scenario's waarin uw agent toegang moet hebben tot gevoelige gegevens of externe API's moet opvragen om acties per gebruiker uit te voeren

Resources opgeven voor automatische verificatiepassthrough (systeemverificatie)

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 resources parameter 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,
  DatabricksApp
)

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"),
      DatabricksApp(app_name="app_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

Authenticatie namens de gebruiker

Belangrijk

Deze functie bevindt zich in de bètaversie.

Wanneer u een agent aanmeldt die gebruikmaakt van verificatie namens de gebruiker, geeft u de minimale set Databricks-API-bereiken op die nodig zijn om acties uit te voeren als eindgebruiker in agentcode. Dit zorgt ervoor dat de agent toegang heeft tot minimale bevoegdheden om acties uit te voeren namens de eindgebruiker wanneer deze wordt geïmplementeerd, waardoor de beveiliging wordt verbeterd door onbevoegde acties te voorkomen en het risico op tokenmisbruik te minimaliseren.

Hieronder vindt u een lijst met scopes die nodig zijn voor toegang tot verschillende veelvoorkomende typen Databricks-resources.

Databricksresource	Vereiste API-toegangsgebieden
Vectorzoekindex	serving.serving-endpoints,vectorsearch.vector-search-endpoints,vectorsearch.vector-search-indexes
Eindpunt voor modellering	serving.serving-endpoints
SQL Warehouse	sql.statement-execution,sql.warehouses
UC-verbindingen	catalog.connections
Genie Space	dashboards.genie

Als u verificatie namens de gebruiker wilt inschakelen, geeft u een MLflow AuthPolicy door aan log_model(), zoals wordt weergegeven in het onderstaande voorbeeld. Een MLflow AuthPolicy heeft twee onderdelen:

• system_auth_policy: Geef resources op voor systeemverificatie. Normaal gesproken gebruiken agents systeemverificatie voor gedeelde resources (bijvoorbeeld om query's uit te voeren op eindpunten voor modellen) in combinatie met verificatie namens de gebruiker voor toegang tot gevoelige resources of API's
• user_auth_policy: Geef API-bereiken op die uw agent nodig heeft voor verificatie namens de gebruiker

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
        )
    )

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. get_open_ai_client() 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)

Zie mlflow.register_model().

Volgende stappen

• Traceringen toevoegen aan een AI-agent.
• Een AI-agent implementeren.