Instrumentieren Sie Node.js-Anwendungen mit MLflow-Tracing

Das TypeScript SDK von MLflow bietet MLflow-Ablaufverfolgungsfunktionen in TypeScript- und JavaScript-Anwendungen. Fügen Sie Ihren GenAI-Anwendungen produktionsfähige Observability mit minimalen Codeänderungen hinzu und nutzen Sie die leistungsstarke Analyse- und Überwachungsplattform von Databricks.

Anforderungen

Um Ihre Node.js Anwendungen mit MLflow-Ablaufverfolgung zu instrumentieren, installieren Sie Folgendes:

• mlflow-tracing aus dem npm-Repository
• Node.js 14 oder höher
• Ein Databricks-Arbeitsbereich mit Zugriff auf MLflow-Experimente

Für die automatische Ablaufverfolgung mit OpenAI benötigen Sie außerdem Folgendes:

• mlflow-openai aus dem npm-Repository

Einrichten des SDK

Installiere das Paket

Installieren Sie das Paket aus der npm-Registrierung:

npm install mlflow-tracing

Erstellen eines MLflow-Experiments

1. Öffnen Sie Ihren Databricks-Arbeitsbereich.
2. Klicken Sie in der linken Randleiste unter AI/ML auf "Experimente".
3. Klicken Sie oben auf der Seite "Experimente" auf GenAI-Apps und -Agents.
4. Klicken Sie auf das neben dem Namen des Experiments, um die Experiment-ID zu finden und sie nach unten zu notieren.

Konfigurieren der Authentifizierung

Wählen Sie eine der folgenden Authentifizierungsmethoden aus:

Umgebungsvariablen

1. Klicken Sie in Ihrem MLflow-Experiment auf das Wählen Sie > und klicken Sie anschließend auf API-Schlüssel generieren.
2. Kopieren Sie den generierten Code in Ihrem Terminal, und führen Sie diesen aus:

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

env-Datei

1. Klicken Sie in Ihrem MLflow-Experiment auf das Wählen Sie > und klicken Sie anschließend auf API-Schlüssel generieren.
2. Kopieren Sie den generierten Code in eine .env Datei im Projektstamm:

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

Initialisieren des SDK

Initialisieren Sie in Ihrer Node.js-Anwendung das SDK mit der Experiment-ID:

import * as mlflow from 'mlflow-tracing';

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

Automatische Nachverfolgung

Fügen Sie eine Codezeile hinzu, um unterstützte Bibliotheken automatisch nachverfolgen zu können. Das MLflow Tracing TypeScript SDK unterstützt derzeit das automatische Tracing für das OpenAI SDK.

Um die automatische Ablaufverfolgung für OpenAI zu verwenden, installieren Sie das mlflow-openai Paket:

npm install mlflow-openai

Schließen Sie dann den OpenAI-Client mit der tracedOpenAI Funktion um:

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

Manuelle Nachverfolgung

Nachverfolgen einer Funktion mit der trace API

Die trace API ist nützlich, wenn Sie eine Funktion nachverfolgen möchten.

Benannte Funktion

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

Anonyme Funktion

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

Beim Aufruf der nachverfolgten Funktion erstellt MLflow automatisch eine Spanne, die Folgendes erfasst:

• Eingabeargumente
• Rückgabewert
• Ausnahmeinformationen, wenn ausgelöst
• Latenz

Erfassen geschachtelter Funktionsaufrufe

Wenn Sie geschachtelte Funktionen nachverfolgen, generiert MLflow eine Trace mit mehreren Spans, die die Struktur der Spans erfasst und die geschachtelten Funktionsaufrufe wiedergibt.

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

Die Ablaufverfolgung sieht wie folgt aus:

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

Verfolgen einer Klassenmethode mit der @trace API

TypeScript Version 5.0+ unterstützt Dekoratoren. Die MLflow-Ablaufverfolgung unterstützt diese Syntax, um Klassenmethoden einfach zu verfolgen. MLflow erstellt automatisch einen Abschnitt, der Folgendes erfasst:

• Eingabeargumente
• Rückgabewert
• Ausnahmeinformationen, wenn ausgelöst
• Latenz

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

Verfolgen eines Codeblocks mit der withSpan API

Die withSpan API ist nützlich, wenn Sie einen Codeblock nachverfolgen möchten, nicht eine Funktion.

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

Explizites Erstellen und Beenden eines Spans

Um mehr Kontrolle über den Lebenszyklus einer Spanne zu erhalten, können Sie einen Span explizit erstellen und beenden.

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

Gruppieren von Ablaufverfolgungen nach Benutzern und Sitzungen

Viele echte Anwendungen verwenden Sitzungen, um mehrfache Benutzerinteraktionen aufrechtzuerhalten. Andererseits werden Traces oft pro Anforderung generiert. MLflow unterstützt das Gruppieren von Ablaufverfolgungen nach Benutzersitzungen, um Die Reise eines Endbenutzers zu verstehen und Probleme zu identifizieren. Weitere Details finden Sie im Leitfaden zum Hinzufügen von Kontext zu Ablaufverfolgungen .

Vollständige Beispielanwendung

Sehen Sie sich das Vollständige Stapelbeispiel an, um ein vollständiges Beispiel für die Verwendung des MLflow Tracing TypeScript SDK in einer Node.js-Anwendung zu finden.

Nächste Schritte

Weitere Informationen finden Sie auf den folgenden Seiten:

• Debuggen und Beobachten Ihrer App – Verwenden Sie die Ablaufverfolgungs-UI, um das Verhalten und die Leistung Ihrer Anwendung zu analysieren.
• App-Qualität bewerten – Nutzen Sie Ihre Traces, um die App-Qualität systematisch zu bewerten und zu verbessern.
• Produktionsüberwachung – Nachverfolgen von Qualitätsmetriken in Echtzeit in der Produktion