Pular para o conteúdo principal

Instrumente seu aplicativo

Saiba como instrumentar seu aplicativo GenAI com o MLflow Tracing para capturar e visualizar o fluxo de execução do seu aplicativo. O MLflow oferece duas abordagens principais para implementar o rastreamento:

Pré-requisitos​

Este guia requer o seguinte pacote:

  • mlflow[databricks]> =3.1: Funcionalidade principal do MLflow com recurso GenAI e conectividade Databricks.
  • openai > =1.0.0 : Só é necessário executar o Quick começar Examples abaixo (se estiver usando outros provedores do LLM, instale seus respectivos SDKs)

Instale o pacote necessário:

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

Recomendação da versão do MLflow

Embora o recurso de rastreamento esteja disponível em MLflow 2.15.0+, é altamente recomendável instalar MLflow 3 (especificamente 3.1 ou mais recente se estiver usando mlflow[databricks] ) para obter os recursos mais recentes do GenAI, incluindo recurso de rastreamento expandido e suporte robusto.

dica

O senhor está correndo em um notebook Databricks ? O MLflow é pré-instalado no tempo de execução do Databricks. O senhor só precisa instalar pacotes adicionais, como openai, se estiver usando provedores externos de LLM.

Executando localmente? O senhor precisará instalar todos os pacotes listados acima.

Configuração do ambiente​

Antes de executar os exemplos abaixo, configure seu ambiente:

Configurar a autenticação do Databricks​

nota

Se estiver executando esse código em um notebook Databricks , o senhor pode ignorar essa configuração de autenticação. MLflow usará automaticamente o contexto de autenticação do Notebook.

Se estiver executando esse código fora da Databricks (por exemplo, em seu IDE local), o senhor precisará configurar a autenticação:

Python
import os

# Set Databricks authentication (only needed when running outside Databricks)
os.environ["DATABRICKS_HOST"] = "https://your-workspace.databricks.com"  # Your workspace URL
os.environ["DATABRICKS_TOKEN"] = "your-databricks-token"  # Your access token

Configurar a chave API​

Defina sua chave do provedor LLM API como variável de ambiente:

Python
import os

# Set your OpenAI API key (if using OpenAI models)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# Set other provider keys as needed
# os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-key"
# os.environ["GOOGLE_API_KEY"] = "your-google-key"
dica

O senhor também pode definir essas variáveis de ambiente no site shell antes de executar o script:

Bash
# For Databricks authentication (if running outside Databricks)
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# For LLM providers
export OPENAI_API_KEY="your-api-key-here"

Abordagens de rastreamento​

  1. Rastreamento automático : basta adicionar 1 linha de código mlflow.<library>.autolog() para capturar automaticamente a lógica do seu aplicativo. O rastreamento automático funciona imediatamente com mais de 20 bibliotecas e estruturas compatíveis
  2. Rastreamento manual : Projetado para lógica personalizada e fluxo de trabalho complexo, o rastreamento manual oferece controle total sobre o que é rastreado e como, usando APIs de alto nível (decoradores e gerenciadores de contexto fluentes) ou APIsde baixo nível.
nota

O rastreamento automático e manual podem ser usados juntos. Por exemplo, o senhor pode usar o rastreamento automático do SDK da OpenAI e o rastreamento manual para combinar várias chamadas LLM em um único rastreamento que represente a lógica de ponta a ponta do seu aplicativo.

Exemplos rápidos de começar​

Exemplo de rastreamento automático​

Habilite o rastreamento automático de sua biblioteca favorita com apenas uma linha de código:

Python
import mlflow
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"  # Replace with your actual API key

# Set up MLflow tracking
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/auto-tracing-demo")

# Enable automatic tracing for OpenAI
mlflow.openai.autolog()

# Your existing code works unchanged
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is MLflow?"}],
    max_tokens=100
)

print(response.choices[0].message.content)
# Traces are automatically captured and logged!

Exemplo de rastreamento manual​

Use o decorador @mlflow.trace para instrumentar suas funções personalizadas:

Python
import mlflow
from mlflow.entities import SpanType
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"  # Replace with your actual API key

# Set up MLflow tracking
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/manual-tracing-demo")

# Enable automatic tracing for OpenAI
mlflow.openai.autolog()

@mlflow.trace(name="RAG Pipeline", span_type=SpanType.CHAIN)
def answer_question(question: str) -> str:
    """A simple RAG pipeline with manual tracing."""

    # Step 1: Retrieve context (manually traced)
    context = retrieve_context(question)

    # Step 2: Generate answer (automatically traced by OpenAI autolog)
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Context: {context}"},
            {"role": "user", "content": question}
        ],
        max_tokens=150
    )

    return response.choices[0].message.content

@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_context(question: str) -> str:
    """Simulate context retrieval."""
    # Simulate retrieval logic
    return f"Relevant context for: {question}"

# Execute the traced pipeline
result = answer_question("What is MLflow Tracing?")
print(result)

Qual é a abordagem correta para meu caso de uso?​

Geralmente, recomendamos começar com o rastreamento automático e passar para o rastreamento manual somente se a lógica do seu aplicativo não for capturada com precisão ou se você precisar de mais controle.

Determine a melhor abordagem de rastreamento para seu caso de uso com base em como você está escrevendo o código do seu aplicativo:

  1. Uso de uma única biblioteca de criação de GenAI (por exemplo, LangGraph, CrewAI, OpenAI Agents, Bedrock Agents etc.)

    • Use o rastreamento auotomático adicionando uma integração de uma linha da nossa página de integrações para a biblioteca selecionada: mlflow.<library>.autolog()

  2. Usar diretamente os SDKs de um provedor de LLM (por exemplo, OpenAI SDK, Anthropic SDK, Bedrock SDK etc.)

  3. Uso de várias estruturas de autoria ou combinação de uma estrutura de autoria com um SDK do provedor de LLM (por exemplo, LangGraph E OpenAI SDK, etc.)

    • Ativar o rastreamento automático para cada estrutura / SDK
    • Adicione decoradores de rastreamento manual para combinar chamadas para várias estruturas ou SDKs em um único rastreamento

  4. Todas as outras abordagens ou você precisa de um controle refinado

    • Use o rastreamento manual
      • Começar com o APIsde alto nível (decorador@mlflow.trace e gerenciadores de contexto fluentes), que proporcionam um equilíbrio entre controle e facilidade de uso
      • Use as APIs de baixo nível somente se as APIs de alto nível não lhe derem controle suficiente

Exibir rastreamentos de registros​

Visão geral do Trace

dica

Comece com o rastreamento automático para obter ganhos rápidos e, em seguida, adicione o rastreamento manual quando precisar de mais controle. A combinação de ambas as abordagens oferece uma observabilidade abrangente em seus aplicativos GenAI.

Próximas etapas​

Continue sua jornada com estas ações recomendadas e o tutorial.

Guia de referência​

Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.

Última atualização em