Instrumentare applicazioni Node.js con MLflow Tracing

TypeScript SDK di MLflow offre funzionalità di traccia MLflow nelle applicazioni TypeScript e JavaScript. Aggiungere un'osservabilità pronta per la produzione alle applicazioni GenAI con modifiche minime al codice e sfruttare la potente piattaforma di analisi e monitoraggio di Databricks.

Requisiti

Per instrumentare le applicazioni Node.js con MLflow Tracing, installare quanto segue:

• mlflow-tracing dal registro npm
• Node.js 14 o versione successiva
• Un'area di lavoro di Databricks con accesso a esperimenti MLflow

Per la traccia automatica con OpenAI, è necessario:

• mlflow-openai dal registro npm

Configurare l'SDK

Installare il pacchetto

Installare il pacchetto dal registro npm:

npm install mlflow-tracing

Creare un esperimento in MLflow

1. Aprire l'area di lavoro di Databricks.
2. Nella barra laterale sinistra, in Intelligenza artificiale/Machine Learning, fare clic su Esperimenti.
3. Nella parte superiore della pagina Esperimenti fare clic su App e agenti GenAI.
4. Fare clic al nome dell'esperimento per trovare l'ID esperimento e annotarlo.

Configurare l'autenticazione

Scegliere uno dei metodi di autenticazione seguenti:

Variabili di ambiente

1. Nell'esperimento MLflow fare clic Icona >Registra tracce in locale> fare clic su Genera chiave API.
2. Copiare ed eseguire il codice generato nel terminale:

export DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com

File .env

1. Nell'esperimento MLflow fare clic Icona >Registra tracce in locale> fare clic su Genera chiave API.
2. Copiare il codice generato in un .env file nella radice del progetto:

DATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com

Inizializzare l'SDK

Nell'applicazione Node.js inizializzare l'SDK con l'ID esperimento:

import * as mlflow from 'mlflow-tracing';

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

Traccia automatica

Aggiungere una riga di codice per tracciare automaticamente le librerie supportate. MLflow Tracing TypeScript SDK supporta attualmente la traccia automatica per OpenAI SDK.

Per usare la traccia automatica per OpenAI, installare il mlflow-openai pacchetto:

npm install mlflow-openai

Eseguire quindi l'incapsulamento del client OpenAI con la funzione tracedOpenAI.

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?" },
  ],
});

Traccia manuale

Tracciare una funzione con API trace

L'API trace è utile quando si vuole tracciare una funzione.

Funzione denominata

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');

Funzione anonima

import * as mlflow from 'mlflow-tracing';

const getWeather = mlflow.trace(
  (city: string) => {
    return `The weather in ${city} is sunny`;
  },
  // When wrapping an anonymous function, specify the span name
  { name: 'get-weather' },
);

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

Nella chiamata della funzione tracciata, MLflow creerà automaticamente un intervallo che acquisisce:

• Argomenti di input
• Valore restituito
• Informazioni sull'eccezione se viene lanciata
• Latenza

Acquisizione di chiamate di funzione nidificate

Se si tracciano funzioni annidate, MLflow genererà una traccia con più segmenti, in cui la struttura dei segmenti acquisisce le chiamate di funzioni annidate.

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

La traccia sarà simile alla seguente:

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

Traccia di un metodo di classe con l'API @trace

TypeScript Versione 5.0+ supporta decoratori. MLflow Tracing supporta questa sintassi per tracciare facilmente i metodi della classe. MLflow creerà automaticamente un intervallo che acquisisce:

• Argomenti di input
• Valore restituito
• Informazioni sull'eccezione se viene lanciata
• Latenza

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?");

Traccia di un blocco di codice con l'API withSpan

L'API withSpan è utile quando si vuole tracciare un blocco di codice, non una funzione.

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 },
  },
);

Creare e terminare un intervallo in modo esplicito

Per ottenere un maggiore controllo sul ciclo di vita dell'intervallo, è possibile creare e terminare un intervallo in modo esplicito.

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',
});

Raggruppamento di tracce per utenti e sessioni

Molte applicazioni reali usano sessioni per gestire le interazioni utente a più turni. D'altra parte, le tracce vengono spesso generate per richiesta. MLflow supporta il raggruppamento delle tracce in base alle sessioni utente per comprendere il percorso di un utente finale e identificare i problemi. Per altri dettagli, vedere Aggiungere contesto alle tracce .

Applicazione full-stack di esempio

Vedere l'esempio di stack completo per un esempio completo di come usare MLflow Tracing TypeScript SDK in un'applicazione Node.js.

Passaggi successivi

Vedere le pagine seguenti:

• Esegui il debug e osserva la tua applicazione - Usa l'interfaccia utente di tracciamento per analizzare il comportamento e le prestazioni dell'applicazione
• Valutare la qualità delle app : sfruttare le tracce per valutare e migliorare sistematicamente la qualità delle applicazioni
• Monitoraggio della produzione - Tenere traccia delle metriche di qualità in tempo reale nell'ambiente di produzione