Agentes de rastreamento implantados fora do Databricks

O MLflow Tracing oferece observabilidade abrangente para agentes de AI de produção implantados fora do Databricks, capturando detalhes de execução e enviando-os para seu workspace do Databricks, onde você pode visualizá-los na IU do MLflow.

Esta página aborda a implantação de agentes fora do Databricks com rastreamento habilitado. Se o seu agente for implantado no Databricks, consulte Rastrear agentes implantados no Databricks.

Armazene rastreamentos no Unity Catalog

Rastreamentos do seu agente hospedado externamente são enviados para o seu workspace Databricks e registrados em um experimento MLflow, que é o ponto de entrada para visualizá-los na UI do MLflow. O que difere é o *local de armazenamento* que suporta o experimento. Você tem duas opções:

• Armazenamento do Unity Catalog (recomendado para produção): vincule o experimento a um local de rastreamento do Unity Catalog para que os rastreamentos cheguem nas tabelas Delta do Unity Catalog. Isso requer alguma configuração antes da implantação. Em troca, obtém-se retenção de longo prazo de grandes volumes de rastreamento, sem limite por experimento. Os rastreamentos são governados por permissões de catálogo, esquema e tabela do Unity Catalog, e você pode query-los diretamente com SQL por meio de um warehouse do Databricks SQL.
• Armazenamento baseado em experimento (default): Se você não configurar um local de rastreamento, os rastreamentos serão armazenados como artefatos de experimento. Isso é conveniente para desenvolvimento, mas tem um limite de rastreamento por experimento e não é otimizado para consultar grandes volumes de rastreamentos de produção.

Como o armazenamento do Unity Catalog é executado fora do Databricks neste caso, crie o experimento com suporte do Unity Catalog a partir de um notebook do Databricks e, em seguida, referencie-o pelo nome ou ID nas variáveis de ambiente abaixo. Consulte Armazenar rastreamentos do OpenTelemetry no Unity Catalog para obter a configuração completa, os pré-requisitos e as permissões. A leitura desses rastreamentos requer um SQL warehouse: defina MLFLOW_TRACING_SQL_WAREHOUSE_ID antes de chamar mlflow.search_traces() ou mlflow.get_trace() em um experimento do Unity Catalog. Consulte Integração de SQL warehouse.

Pré-requisitos

Instale o pacote necessário. A tabela a seguir descreve suas opções:

Pacote	Caso de uso recomendado	Benefícios
mlflow-tracing SDK de Python ou SDK de TypeScript	Implantações de produção	Dependências mínimas para implantações rápidas e enxutas desempenho otimizado para rastreamento de grandes volumes Focado no rastreamento do lado do cliente para monitoramento da produção
mlflow[databricks]	Desenvolvimento e experimentação	Conjunto completo de recursos de experimentação MLflow (UI, LLM-as-a-judge, ferramentas de desenvolvimento e muito mais) Inclui todas as ferramentas e utilidades de desenvolvimento

Pacote	Caso de uso recomendado	Benefícios
mlflow-tracing SDK de Python ou SDK de TypeScript	Implantações de produção	Dependências mínimas para implantações rápidas e enxutas desempenho otimizado para rastreamento de grandes volumes Focado no rastreamento do lado do cliente para monitoramento da produção
mlflow[databricks]	Desenvolvimento e experimentação	Conjunto completo de recursos de experimentação MLflow (UI, LLM-as-a-judge, ferramentas de desenvolvimento e muito mais) Inclui todas as ferramentas e utilidades de desenvolvimento

Python

## Install mlflow-tracing for production deployment tracing
%pip install --upgrade "mlflow-tracing==3.1.0"

## Install mlflow for experimentation and development
%pip install --upgrade "mlflow[databricks]==3.1.0"

Configuração básica de rastreamento

Configure a implementação do aplicativo para se conectar ao Databricks workspace para que o Databricks possa coletar traces.

Configure as seguintes variáveis de ambiente:

Bash

# Required: Set the Databricks workspace host and authentication token
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# Required: Set MLflow Tracking URI to "databricks" to log to Databricks
export MLFLOW_TRACKING_URI=databricks

# Required: Configure the experiment name for organizing traces (must be a workspace path)
export MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

Exemplos de implantação

Após definir as variáveis de ambiente, passe-as para sua aplicação. Clique na aba para ver como passar os detalhes de conexão para diferentes frameworks.

Docker

Para implementações em Docker, passe a variável de ambiente por meio da configuração do contêiner:

Dockerfile

# Dockerfile
FROM python:3.11-slim

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . /app
WORKDIR /app

# Set default environment variables (can be overridden at runtime)
ENV DATABRICKS_HOST=""
ENV DATABRICKS_TOKEN=""
ENV MLFLOW_TRACKING_URI=databricks
ENV MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

CMD ["python", "app.py"]

executar o contêiner com variável de ambiente:

Bash

docker run -d \
  -e DATABRICKS_HOST="https://your-workspace.cloud.databricks.com" \
  -e DATABRICKS_TOKEN="your-databricks-token" \
  -e MLFLOW_TRACKING_URI=databricks \
  -e MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app" \
  -e APP_VERSION="1.0.0" \
  your-app:latest

Kubernetes

Para implantações do Kubernetes, passe a variável de ambiente usando ConfigMaps e Secrets:

YAML

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: databricks-config
data:
  DATABRICKS_HOST: 'https://your-workspace.cloud.databricks.com'
  MLFLOW_TRACKING_URI: databricks
  MLFLOW_EXPERIMENT_NAME: '/Shared/production-genai-app'

---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: databricks-secrets
type: Opaque
stringData:
  DATABRICKS_TOKEN: 'your-databricks-token'

---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: genai-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-app:latest
          envFrom:
            - configMapRef:
                name: databricks-config
            - secretRef:
                name: databricks-secrets
          env:
            - name: APP_VERSION
              value: '1.0.0'

Verificar a coleta de traços

Depois de implantar o aplicativo, verifique se os rastros foram coletados corretamente:

Python

import mlflow
from mlflow.client import MlflowClient
import os

# Ensure MLflow is configured for Databricks
mlflow.set_tracking_uri("databricks")

# Check connection to MLflow server
client = MlflowClient()
try:
    # List recent experiments to verify connectivity
    experiments = client.search_experiments()
    print(f"Connected to MLflow. Found {len(experiments)} experiments.")

    # Check if traces are being logged
    traces = mlflow.search_traces(
        experiment_names=[os.getenv("MLFLOW_EXPERIMENT_NAME", "/Shared/production-genai-app")],
        max_results=5
    )
    print(f"Found {len(traces)} recent traces.")
except Exception as e:
    print(f"Error connecting to MLflow: {e}")
    print(f"Check your authentication and connectivity")

Recursos adicionais

• Visualizar rastreamentos na interface do usuário Databricks MLflow - visualizar rastreamentos na interface do usuário MLflow .
• Armazene rastreamentos do OpenTelemetry no Unity Catalog - Armazene rastreamentos de produção em tabelas Delta governadas para retenção e análise de longo prazo.
• Monitoramento de produção - Executar avaliadores em rastreamentos de produção para monitorar a qualidade do aplicativo.
• Adicione contexto a rastreamentos – Anexe IDs de usuário ou sessão, tags personalizadas ou feedback do usuário para melhor depuração e percepções.