Log e registro de agentes de AI (Model Serving)

info

Para novos casos de uso, a Databricks recomenda implantar agentes no Databricks Apps para controle total sobre o código do agente, a configuração do servidor e o fluxo de trabalho de implantação. Consulte Crie um agente de AI e o tenha implantado no Databricks Apps. Para migrar um agente existente, consulte Migre um agente do Model Serving para o Databricks Apps.

log agentes de AI usando agentes personalizados. O registro em log de um agente forma a base do processo de desenvolvimento. O registro em log captura um "point in time" do código e da configuração do agente para que a qualidade dele possa ser avaliada.

Requisitos

Crie um agente de AI antes de registrá-lo.

A Databricks recomenda instalar a versão mais recente do databricks-sdk.

Python

% pip install databricks-sdk

Registro baseado em código

A Databricks recomenda usar a funcionalidade Modelos a partir do Código do MLflow ao registrar agentes.

Nesta abordagem, o código do agente é capturado como um arquivo Python, e o ambiente Python é capturado como uma lista de pacotes. Quando o agente é implantado, o ambiente Python é restaurado, e o código do agente é colocado em execução para carregar o agente na memória para que ele possa ser invocado quando o endpoint for chamado.

É possível acoplar esta abordagem com o uso de APIs de validação de pré-implantação como mlflow.models.predict() para garantir que o agente execute de forma confiável quando implantado para servir.

Para ver um exemplo de registro baseado em código, consulte Notebooks de exemplo de autoria do ResponsesAgent.

Inferir a Assinatura do Modelo durante o registro

nota

A Databricks recomenda a criação de um agente usando a interface ResponsesAgent. Se estiver usando ResponsesAgent, você pode pular esta seção; o MLflow infere automaticamente uma assinatura válida para seu agente.

Se não estiver usando a interface ResponsesAgent, você deve usar um dos seguintes métodos para especificar a Assinatura de Modelo do MLflow do seu agente no momento do log:

1. Defina manualmente a assinatura
2. Use os recursos de inferência de assinatura de modelo do MLflow para gerar automaticamente a assinatura do agente com base em um exemplo de entrada que você fornece. Essa abordagem é mais conveniente do que definir a assinatura manualmente.

A assinatura do modelo MLflow valida entradas e saídas para garantir que o agente interaja corretamente com ferramentas a jusante como o AI Playground e o aplicativo de revisão. Também guia outros aplicativos sobre como usar o agente de forma eficaz.

Os exemplos de LangChain e PyFunc abaixo usam inferência de assinatura de modelo.

Se você preferir definir explicitamente uma Assinatura de Modelo por conta própria no momento do registro, consulte documentos do MLflow - Como trabalhar com modelos logged.

Log baseado em código com LangChain

As seguintes instruções e exemplo de código mostram como log um agente com LangChain.

1. Crie um Notebook ou arquivo Python com seu código. Para este exemplo, o Notebook ou arquivo é denominado agent.py. O notebook ou arquivo deve conter um agente LangChain, referenciado aqui como lc_agent.

2. Inclua mlflow.models.set_model(lc_agent) no Notebook ou arquivo.

3. Crie outro notebook para servir como o notebook do driver (chamado driver.py neste exemplo).

4. No Notebook do driver, use o código a seguir para execução do agent.py e log dos resultados em um modelo MLflow:

   Python

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

   O parâmetro resources declara recursos gerenciados pelo Databricks necessários para servir o agente, como um índice de AI Search ou endpoint de serviço que serve um modelo fundamental. Para obter mais informações, consulte Implementar o passthrough de autenticação automático.

5. Implante o modelo. Consulte Implante um agente para aplicações de AI generativa (Model Serving).

6. Quando o ambiente de serviço é carregado, é iniciada a execução de agent.py.

7. Quando chega uma solicitação de atendimento, lc_agent.invoke(...) é chamado.

Python

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)

Registro baseado em código com PyFunc

As instruções e o exemplo de código a seguir mostram como log um agente com PyFunc.

1. Crie um Notebook ou arquivo Python com seu código. Para este exemplo, o Notebook ou arquivo é denominado agent.py. O notebook ou arquivo deve conter uma classe PyFunc, nomeada PyFuncClass.

2. Inclua mlflow.models.set_model(PyFuncClass) no Notebook ou arquivo.

3. Crie outro notebook para servir como o notebook do driver (chamado driver.py neste exemplo).

4. No Notebook do driver, use o seguinte código para a execução de agent.py e use log_model() para logar os resultados em um modelo MLflow:

   Python

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

   O parâmetro resources declara recursos gerenciados pelo Databricks necessários para servir o agente, como um índice de AI Search ou endpoint de serviço que serve um modelo fundamental. Para obter mais informações, consulte Implementar o passthrough de autenticação automático.

5. Implante o modelo. Consulte Implante um agente para aplicações de AI generativa (Model Serving).

6. Quando o ambiente de serviço é carregado, é iniciada a execução de agent.py.

7. Quando chega uma solicitação de atendimento, PyFuncClass.predict(...) é chamado.

Python

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)

Autenticação para recursos do Databricks

Agentes de AI frequentemente precisam autenticar-se em outros recursos para concluir tarefas. Por exemplo, um agente implantado pode precisar acessar um índice de Pesquisa de AI para consultar dados não estruturados, ou acessar o Registro de Prompt para carregar prompts dinâmicos.

O passthrough de autenticação automático e a autenticação em nome de exigem configuração durante o registro do agente.

Fazer o registro do agente no Unity Catalog

Antes de implantar o agente, você deve realizar o registro do agente no Unity Catalog. O registro do agente o transforma em um pacote como um modelo no Unity Catalog. Como resultado, você pode usar as permissões do Unity Catalog para autorização de recursos no agente.

Python

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)

Consulte mlflow.register_model().

Recursos adicionais

• Adicionar rastreamentos a um agente de AI.
• Implantar um agente de AI.