Começar: MLflow Tracing para GenAI (IDE local)
Este início rápido ajuda você a integrar seu aplicativo GenAI com MLflow Tracing se você usar um ambiente de desenvolvimento local, como um IDE (VS Code, PyCharm, Cursor ou outros) ou um ambiente Notebook hospedado localmente (Jupyter ou outros). Se você usa um Databricks Notebook, use o início rápido do Databricks Notebook .
O que você vai conseguir
Ao final deste tutorial, o senhor terá:
- Um experimento MLflow para seu aplicativo GenAI
- Seu ambiente de desenvolvimento local conectado ao MLflow
- Um aplicativo GenAI simples instrumentado com o MLflow Tracing
- Um rastro desse aplicativo em seu experimento MLflow
Pré-requisitos
- Databricks Workspace : Acesso a um site Databricks workspace.
Etapa 1: Instalar o MLflow
Ao trabalhar em seu IDE local, o senhor precisa instalar o MLflow com a conectividade Databricks.
pip install --upgrade "mlflow[databricks]>=3.1" openai
o passo 2: Criar um novo experimento MLflow
Um experimento MLflow é o contêiner para seu aplicativo GenAI. Saiba mais sobre experimentos na seção de conceitos.
- Abra o site Databricks workspace
- Na barra lateral esquerda, em AI/ML , clique em Experimentos .
- Na parte superior da página Experimentos, clique em Aplicativos e agentes GenAI
- Obtenha o ID e o caminho do experimento clicando no ícone de informação
no canto superior esquerdo. Você os usará mais tarde.
Etapa 3: Conecte seu ambiente ao MLflow
Os trechos de código abaixo mostram como configurar a autenticação usando um token de acesso pessoal Databricks . O MLflow também funciona com outros métodos de autenticação suportados pelo Databricks.
- Use environment variables
- Use a .env file
-
No seu experimento MLflow , clique no ícone do menu Kebab
> registrar rastros localmente > clique em Gerar chave API .
-
Copie e execute o código gerado em seu terminal.
Bashexport DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
export MLFLOW_TRACKING_URI=databricks
export MLFLOW_REGISTRY_URI=databricks-uc
export MLFLOW_EXPERIMENT_ID=<experiment-id>
-
No seu experimento MLflow , clique no ícone do menu Kebab
> registrar rastros localmente > clique em Gerar chave API .
-
Copie o código gerado para um arquivo
.env
na raiz do seu projetoBashDATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
MLFLOW_TRACKING_URI=databricks
MLFLOW_REGISTRY_URI=databricks-uc
MLFLOW_EXPERIMENT_ID=<experiment-id> -
Instale o pacote
python-dotenv
Bashpip install python-dotenv
-
Carregar variável de ambiente em seu código
Python# At the beginning of your Python script
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
Etapa 4: criar e instrumentar seu aplicativo
Crie seu aplicativo GenAI com rastreamento habilitado.
-
Crie um arquivo Python chamado
app.py
no diretório do seu projeto. -
Inicialize um cliente OpenAI para se conectar a LLMs hospedados pela Databricks ou LLMs hospedados pela OpenAI.
- Databricks-hosted LLMs
- OpenAI-hosted LLMs
Use o MLflow para obter um cliente OpenAI que se conecta aos LLMs hospedados pela Databricks. Selecione um modelo dentre os modelos de base disponíveis.
import mlflow
from databricks.sdk import WorkspaceClient
# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()
# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")
# Create an OpenAI client that is connected to Databricks-hosted LLMs
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()
# Select an LLM
model_name = "databricks-claude-sonnet-4"
Use o SDK nativo do OpenAI para se conectar a modelos hospedados pelo OpenAI. Selecione um modelo dentre os modelos OpenAI disponíveis.
import mlflow
import os
import openai
# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured
# Enable auto-tracing for OpenAI
mlflow.openai.autolog()
# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")
# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()
# Select an LLM
model_name = "gpt-4o-mini"
-
Defina e execute sua aplicação:
Use o decorador
@mlflow.trace
, que facilita o rastreamento de qualquer função Python, combinado com a instrumentação automática do OpenAI para capturar os detalhes da chamada para o OpenAI SDK.Python# Use the trace decorator to capture the application's entry point
@mlflow.trace
def my_app(input: str):
# This call is automatically instrumented by `mlflow.openai.autolog()`
response = client.chat.completions.create(
model=model_name, # This example uses a Databricks hosted LLM - you can replace this with any AI Gateway or Model Serving endpoint. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
messages=[
{
"role": "system",
"content": "You are a helpful assistant.",
},
{
"role": "user",
"content": input,
},
],
)
return response.choices[0].message.content
result = my_app(input="What is MLflow?")
print(result) -
execução do aplicativo
Bashpython app.py
Para obter detalhes sobre como adicionar rastreamento a aplicativos, consulte o guia de instrumentação de rastreamento e as mais de 20 integrações de biblioteca.
o passo 5: visualizar o rastreamento no MLflow
- Navegue de volta para a interface do experimento do MLflow.
- Agora você verá o rastreamento gerado na tab Rastreamentos .
- Clique no rastreamento para view seus detalhes.
Compreendendo o traço
O rastreamento que você acabou de criar mostra:
-
Raiz span : representa as entradas para a função
my_app(...)
- Período filho : representa a solicitação de conclusão do OpenAI
-
Atributos : Contém metadados como nome do modelo, contagem de tokens e informações de tempo
-
Entradas : as mensagens enviadas para o modelo
-
Saídas : A resposta recebida do modelo
Esse simples rastreamento já fornece percepções valiosas sobre o comportamento do seu aplicativo, como, por exemplo, o que o senhor está fazendo?
- O que foi perguntado
- Qual resposta foi gerada
- Quanto tempo demorou a solicitação
- Quantos tokens foram usados (afetando o custo)
Para aplicativos mais complexos, como sistemas RAG ou agentes de várias etapas, o MLflow Tracing oferece ainda mais valor ao revelar o funcionamento interno de cada componente e etapa.
guia e referências
Para detalhes sobre conceitos e recursos neste guia, consulte:
- GuiaMLflow Tracing - comece aqui para aprender mais sobre MLflow Tracing
- IntegraçõesMLflow Tracing - mais de 20 bibliotecas com integrações de rastreamento automático
- Conceitos de rastreamento - Entenda os fundamentos do MLflow Tracing