Comece agora: MLflow Tracing para GenAI em um IDE local.

Este guia de início rápido ajuda você a integrar seu aplicativo GenAI com MLflow Tracing se você usa um ambiente de desenvolvimento local, como uma IDE (VS Code, PyCharm, Cursor ou outras) ou um ambiente Notebook hospedado localmente, como o Jupyter. Se você usa um Notebook Databricks , consulte o guia de início rápido do NotebookDatabricks .

Este tutorial irá guiá-lo através dos seguintes passos:

• Criando um experimento do MLflow em seu workspace do Databricks
• Conectando seu ambiente de desenvolvimento local ao experimento
• Executando um aplicativo GenAI simples localmente em sua máquina
• Visualizando os dados de rastreamento carregados por upload em seu Workspace Databricks

Pré-requisitos

• Acesso a um workspace Databricks .

Etapa 1: Instalar o MLflow

Instale o MLflow com conectividade Databricks:

Bash

pip install --upgrade "mlflow[databricks]>=3.1" openai

o passo 2: Criar um novo experimento MLflow

Um experimento MLflow é o contêiner para sua aplicação GenAI. Para mais informações, veja Experimentos.

1. Abra seu workspace Databricks .
2. Na barra lateral esquerda, em AI/ML , clique em Experimentos .
3. Na parte superior da página Experimentos, clique em Aplicativos e agentes GenAI .
4. Para obter o ID e o caminho do experimento, clique no ícone de informações. no canto superior esquerdo. Você usará esses valores em etapas posteriores.

Etapa 3: Conecte seu ambiente ao MLflow

Os trechos de código a seguir mostram como configurar a autenticação usando um access token pessoal (PAT) Databricks . O MLflow também funciona com os outros métodos de autenticação suportados pelo Databricks.

Use environment variables

1. No seu experimento MLflow , clique no ícone do menu de três pontos (kebab). > Registrar rastreamentos localmente > Gerar chave API .

2. Copie e execute o código gerado em seu terminal.

   Bash

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

Use a .env file

1. No seu experimento MLflow , clique no ícone do menu de três pontos (kebab). > Registrar rastreamentos localmente > Gerar chave API .

2. Copie o código gerado para um arquivo .env na raiz do seu projeto.

   Bash

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

3. Instale o pacote python-dotenv .

   Bash

   pip install python-dotenv

4. Carregue a variável de ambiente no seu código:

   Python

   # At the beginning of your Python script
   from dotenv import load_dotenv
   
   # Load environment variables from .env file
   load_dotenv()

O passo 3b (recomendado): ativar o armazenamento de rastreamento do Unity Catalog

Os passos acima usam o backend de experimento gerenciado, que é o caminho mais rápido para o seu primeiro rastreamento, mas limita os rastreamentos a 100.000 por experimento. Para armazenamento escalável e governado sem limite de rastreamento, o Databricks recomenda vincular seu experimento a um local de rastreamento do Unity Catalog.

Adicione o seguinte ao seu ambiente de terminal (juntamente com as variáveis do o passo 3):

Bash

export MLFLOW_TRACING_SQL_WAREHOUSE_ID=<warehouse-id>

Ao criar app.py na Etapa 4, adicione o seguinte no topo antes de quaisquer chamadas de rastreamento:

Python

import mlflow
from mlflow.entities.trace_location import UnityCatalog

mlflow.set_experiment(
    experiment_id="<experiment-id>",  # the ID you copied in Step 2
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

Para detalhes completos da configuração, consulte Armazenar rastreamentos OpenTelemetry no Unity Catalog.

Etapa 4: criar e instrumentar seu aplicativo

Crie sua aplicação de GenAI com rastreamento ativado. O código é executado inteiramente em sua máquina local e faz upload de rastreamentos para seu experimento do MLflow no workspace do Databricks.

1. Crie um arquivo Python chamado app.py no diretório do seu projeto.

2. Inicialize um cliente OpenAI para se conectar a LLMs hospedados pela Databricks ou LLMs hospedados pela OpenAI.

Databricks-hosted LLMs

Use databricks-openai para obter um cliente OpenAI que se conecta a LLMs hospedados no Databricks. Selecione um modelo dentre os modelos de fundação disponíveis.

Python

import mlflow
from databricks_openai import DatabricksOpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Traces are written to the experiment set by MLFLOW_EXPERIMENT_ID and the
# tracking server set by MLFLOW_TRACKING_URI, both configured in the previous step

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-5"

OpenAI-hosted LLMs

Use o SDK nativo do OpenAI para se conectar a modelos hospedados pelo OpenAI. Selecione um modelo dentre os modelos OpenAI disponíveis.

Python

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

# Traces are written to the experiment set by MLFLOW_EXPERIMENT_ID and the
# tracking server set by MLFLOW_TRACKING_URI, both configured in the previous step

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-5"

3. 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(
           # Uses a Databricks-hosted LLM by default. To use an AI Gateway, Model Serving endpoint, or your own OpenAI credentials, replace `model_name` with a valid model such as `gpt-5`.
           model=model_name,
           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)

4. execução do aplicativo:

   Bash

   python app.py

   Este código tem execução local: o arquivo app.py reside em sua máquina, e as variáveis de ambiente do passo 3 informam ao cliente MLflow onde fazer upload dos dados de rastreamento. Para alterar o prompt ou a lógica do agente, edite o arquivo local e faça uma nova execução.

Para obter detalhes sobre como adicionar rastreamento a aplicativos, consulte Adicionar rastreamentos a aplicativos: rastreamento automático e manual e IntegraçõesMLflow Tracing (mais de 20 integrações de biblioteca).

o passo 5: visualizar o rastreamento no MLflow

Quando um rastreamento aparece na interface do usuário do Databricks, seu código teve uma execução em seu laptop e o rastreamento foi enviado via HTTPS.

1. Retorne à experiência do MLflow que você selecionou no o passo 2.
2. O rastreamento gerado aparece na tab Rastreamentos .
3. Clique no traço para view os detalhes.

Entenda o rastreamento

O novo rastreamento 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

Mesmo esse rastro mínimo revela informações úteis sobre o comportamento do seu aplicativo, incluindo:

• 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:

• MLflow Tracing - Observabilidade GenAI — comece aqui para um aprendizado aprofundado sobre MLflow Tracing.
• IntegraçõesMLflow Tracing — Mais de 20 bibliotecas com integrações de rastreamento automático.
• Conceitos de rastreamento — Compreenda os fundamentos do MLflow Tracing.