Instrumenter les applications Node.js avec MLflow Tracing

Le SDK TypeScript de MLflow apporte les capacités de MLflow Tracing aux applications TypeScript et JavaScript. Ajoutez une observabilité prête pour la production à vos applications GenAI avec des modifications de code minimales et tirez parti de la puissante plateforme d'analytique et de monitoring de Databricks.

Exigences

astuce

Databricks recommande d'installer la dernière version du SDK TypeScript de MLflow Tracing lors du développement d'applications Node.js avec traçage.

Pour instrumenter vos applications Node.js avec MLflow Tracing, installez les éléments suivants :

• mlflow-tracing depuis le registre npm
• Node.js 14 ou version ultérieure
• Un Workspace Databricks avec accès aux Expérimentations MLflow

Pour le traçage automatique avec OpenAI, vous avez également besoin de :

• mlflow-openai depuis le registre npm

Configurer le SDK

Installer le package

Installez le package à partir du registre npm:

Bash

npm install mlflow-tracing

Créer une Experimentation MLflow

1. Ouvrez votre workspace Databricks.
2. Dans la barre latérale gauche, sous IA/ML , cliquez sur Experimentation .
3. En haut de la page Expérimentations, cliquez sur Applications et agents GenAI .
4. Cliquez sur l'icône à côté du nom de l'expérimentation pour trouver l'ID de l'expérimentation et le noter.

Configurer l’authentification

Choisissez l'une des méthodes d'authentification suivantes :

Environment Variables

1. Dans votre Experimentation MLflow, cliquez sur l’icône > **Enregistrer les traces localement** > cliquez sur **Générer une clé API**.
2. Copiez et exécutez le code généré dans votre terminal :

Bash

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

.env File

1. Dans votre Experimentation MLflow, cliquez sur l’icône > **Enregistrer les traces localement** > cliquez sur **Générer une clé API**.
2. Copiez le code généré dans un fichier .env à la racine de votre projet :

Bash

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

Initialiser le SDK

Dans votre application Node.js, initialisez le SDK avec l'ID d'expérimentation :

TypeScript

import * as mlflow from 'mlflow-tracing';

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

Traçage automatique

Ajoutez une ligne de code pour tracer automatiquement les bibliothèques prises en charge. Le SDK TypeScript de MLflow Tracing prend actuellement en charge le traçage automatique pour le SDK OpenAI.

Pour utiliser le traçage automatique pour OpenAI, installez le mlflow-openai package :

Bash

npm install mlflow-openai

Ensuite, encapsulez le client OpenAI avec la fonction 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?" },
  ],
});

Traçage manuel

Traçage d'une fonction avec l'API trace

L'API trace est utile lorsque vous souhaitez tracer une fonction.

Named function

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

Anonymous function

TypeScript

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

Lors de l'invocation de la fonction tracée, MLflow créera automatiquement un span qui capture :

• Arguments d'entrée
• Valeur de retour
• Informations sur l'exception si levée
• Latence

Capture des appels de fonction imbriqués

Si vous tracez des fonctions imbriquées, MLflow générera une trace avec plusieurs spans, où la structure des spans capture les appels de fonctions imbriquées.

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

La trace se présentera comme suit :

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

Traçage d'une méthode de classe avec l'API @trace

TypeScript version 5.0+ prend en charge les décorateurs. MLflow Tracing prend en charge cette syntaxe pour tracer facilement les méthodes de classe. MLflow créera automatiquement une étendue qui capture :

• Arguments d'entrée
• Valeur de retour
• Informations sur l'exception si levée
• Latence

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

Traçage d'un bloc de code avec l'API withSpan

L'API withSpan est utile lorsque vous souhaitez tracer un bloc de code, et non une fonction.

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

Créer et terminer explicitement une portée

Pour mieux contrôler le cycle de vie d'un span, vous pouvez créer et terminer un span explicitement.

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

Regroupement des traces par utilisateurs et sessions

De nombreuses applications réelles utilisent des sessions pour maintenir des interactions utilisateur multi-tours. D'autre part, les traces sont souvent générées par requête. MLflow prend en charge le regroupement des traces par sessions utilisateur pour vous aider à comprendre le parcours d'un utilisateur final et à identifier les problèmes. Consultez le guide Ajouter du contexte aux traces pour plus de détails.

Exemple d'application Full-stack

Consultez l'exemple complet full-stack pour un exemple complet d'utilisation du SDK TypeScript de MLflow Tracing dans une application Node.js.

Ressources supplémentaires

• Déboguer et observer votre application — Utilisez l'interface utilisateur de trace pour analyser le comportement et les performances de votre application.
• Évaluez la qualité des applications – Exploitez vos traces pour évaluer et améliorer systématiquement la qualité des applications.
• Monitoring de production – Suivez les métriques de qualité en temps réel en production