Pular para o conteúdo principal

Instrumentar aplicações Node.js com MLflow Tracing

O TypeScript SDKdoMLflow traz recursos MLflow Tracing para aplicativos TypeScript e JavaScript. Adicione observabilidade pronta para produção aos seus aplicativos GenAI com alterações mínimas de código e aproveite a poderosa plataforma de análise e monitoramento Databricks.

Requisitos​

dica

A Databricks recomenda instalar a versão mais recente do MLflow Tracing TypeScript SDK ao desenvolver aplicativos Node.js com rastreamento.

Para instrumentar seus aplicativos Node.js com o MLflow Tracing, instale o seguinte:

  • mlflow-tracing do registro npm
  • Node.js 14 ou acima
  • Um workspace Databricks com acesso aos experimentos MLflow

Para rastreamento automático com OpenAI, você também precisa:

Configurar o SDK​

Instalar o pacote​

Instale o pacote do registro npm:

Bash
npm install mlflow-tracing

Criar um experimento MLflow​

  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. Clique no Ícone de informação. ícone ao lado do nome do experimento para encontrar o ID do experimento e anotá-lo.

criar experimento

Configurar autenticação​

Escolha um dos seguintes métodos de autenticação:

  1. No seu experimento MLflow , clique em Ícone do menu de kebab. ícone > registrar rastreamentos localmente > clique em Gerar chave API .
  2. Copie e execute o código gerado no seu terminal:
Bash
export DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com

Inicializar o SDK​

No seu aplicativo Node.js, inicialize o SDK com o ID do experimento:

TypeScript
import * as mlflow from 'mlflow-tracing';

mlflow.init({
  trackingUri: 'databricks',
  experimentId: '<your-experiment-id>',
});

Rastreamento Automático​

Adicione uma linha de código para rastrear automaticamente a biblioteca suportada. O MLflow Tracing TypeScript SDK atualmente oferece suporte ao rastreamento automático para o OpenAI SDK.

Para usar o rastreamento automático para OpenAI, instale o pacote mlflow-openai :

Bash
npm install mlflow-openai

Em seguida, envolva o cliente OpenAI com a função tracedOpenAI :

TypeScript
import * as mlflow from 'mlflow-tracing';

// Initialize the tracing SDK
mlflow.init({
  trackingUri: 'databricks',
  experimentId: '<your-experiment-id>',
});

import { OpenAI } from 'openai';
import { tracedOpenAI } from 'mlflow-openai';

// Wrap the OpenAI client with the tracedOpenAI function
const client = tracedOpenAI(new OpenAI());

// Invoke the client as usual
const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'You are a helpful weather assistant.' },
    { role: 'user', content: "What's the weather like in Seattle?" },
  ],
});

Rastreamento manual​

Rastreando uma função com a API trace​

A API trace é útil quando você deseja rastrear uma função.

TypeScript
import * as mlflow from 'mlflow-tracing';

const getWeather = async (city: string) => {
  return `The weather in ${city} is sunny`;
};

// Wrap the function with mlflow.trace to create a traced function
const tracedGetWeather = mlflow.trace(getWeather, { name: 'get-weather' });

// Invoke the traced function as usual
const result = await tracedGetWeather('San Francisco');

Na invocação da função rastreada, o MLflow criará automaticamente um intervalo que captura:

  • Argumentos de entrada
  • Valor de retorno
  • Informação de exceção se lançada
  • Latência

Capturando chamadas de função aninhadas​

Se você rastrear funções aninhadas, o MLflow gerará um rastreamento com vários intervalos, onde a estrutura do intervalo captura as chamadas de função aninhadas.

TypeScript
const sum = mlflow.trace(
  (a: number, b: number) => {
    return a + b;
  },
  { name: 'sum' },
);

const multiply = mlflow.trace(
  (a: number, b: number) => {
    return a * b;
  },
  { name: 'multiply' },
);

const computeArea = mlflow.trace(
  (a: number, b: number, h: number) => {
    const sumOfBase = sum(a, b);
    const area = multiply(sumOfBase, h);
    return multiply(area, 0.5);
  },
  { name: 'compute-area' },
);

computeArea(1, 2, 3);

O rastreamento ficará assim:

- compute-area
  - sum (a=1, b=2)
  - multiply (a=3, b=3)
  - multiply (a=9, b=0.5)

Rastreando um método de classe com a API @trace​

O TypeScript versão 5.0+ oferece suporte a decoradores. O MLflow Tracing suporta essa sintaxe para rastrear métodos de classe facilmente. O MLflow criará automaticamente um intervalo que captura:

  • Argumentos de entrada
  • Valor de retorno
  • Informação de exceção se lançada
  • Latência
TypeScript
import * as mlflow from 'mlflow-tracing';

class MyClass {
  @mlflow.trace({ spanType: mlflow.SpanType.LLM })
  generateText(prompt: string) {
    return "It's sunny in Seattle!";
  }
}

const myClass = new MyClass();
myClass.generateText("What's the weather like in Seattle?");

Rastreando um bloco de código com a API withSpan​

A API withSpan é útil quando você deseja rastrear um bloco de código, não uma função.

TypeScript
import * as mlflow from 'mlflow-tracing';

const question = "What's the weather like in Seattle?";

const result = await mlflow.withSpan(
  async (span: mlflow.Span) => {
    return "It's sunny in Seattle!";
  },
  // Pass name, span type, and inputs as options.
  {
    name: 'generateText',
    spanType: mlflow.SpanType.TOOL,
    inputs: { prompt: question },
  },
);

Crie e encerre um intervalo explicitamente​

Para obter mais controle sobre o ciclo de vida do intervalo, você pode criar e encerrar um intervalo explicitamente.

TypeScript
import * as mlflow from 'mlflow-tracing';

const span = mlflow.startSpan({
  name: 'generateText',
  spanType: mlflow.SpanType.LLM,
  inputs: { prompt: question },
});

span.end({
  outputs: { answer: "It's sunny in Seattle!" },
  status: 'OK',
});

Agrupando Rastros por Usuários e Sessões​

Muitos aplicativos do mundo real usam sessões para manter interações de usuários em vários turnos. Por outro lado, os rastreamentos geralmente são gerados por solicitação. O MLflow oferece suporte ao agrupamento de rastreamentos por sessões de usuário para ajudar você a entender a jornada do usuário final e identificar problemas. Consulte o guia Rastrear usuários e sessões para obter mais detalhes.

Exemplo de aplicação full-stack​

Confira o exemplo de pilha completa para ver um exemplo completo de como usar o SDK TypeScript do MLflow Tracing em um aplicativo Node.js.

Próximos passos​

Veja as páginas seguintes:

Última atualização em