MLflow Observability

MLflow Observability

MLflow Tracing은 OpenTelemetry를 통해 Vercel AI SDK (the ai package)로 구축된 애플리케이션에 자동 트레이싱을 제공하며, TypeScript 및 JavaScript 앱에 관측성을 제공해요.

사용하면 MLflow는 다음을 기록해요:

  • 프롬프트/메시지와 생성된 응답
  • 지연시간과 호출 계층 구조
  • 토큰 사용량 (프로바이더가 반환할 때)
  • 예외 (Exceptions)

출처: 문서

본문

퀵스타트 (NextJS)

NextJS를 사용한다면 Vercel AI SDK용 MLflow 트레이싱을 활성화하는 것이 꽤 간단해요.

준비된 앱이 없나요? Vercel의 데모 챗봇을 사용해 보세요: https://vercel.com/templates/next.js/ai-chatbot-telemetry

1. MLflow Tracking Server 시작

mlflow server --backend-store-uri sqlite:///mlruns.db --port 5000

Docker Compose로 서버를 시작할 수도 있어요. MLflow Setup Guide를 참고하세요.

2. 환경 변수 구성

이것을 .env.local에 추가해요:

OTEL_EXPORTER_OTLP_ENDPOINT=<your-mlflow-tracking-server-endpoint>
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-mlflow-experiment-id=<your-experiment-id>
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf

로컬 테스트용: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5000.

3. OpenTelemetry 활성화

Vercel OpenTelemetry 통합을 설치해요:

pnpm i @opentelemetry/api @vercel/otel @ai-sdk/otel

프로젝트 루트에 instrumentation.ts를 만들고 OTel 프로바이더 설정과 함께 LegacyOpenTelemetry를 등록해요:

import { registerTelemetry } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';
import { registerOTel } from '@vercel/otel';

registerTelemetry(new LegacyOpenTelemetry());

export async function register() {
  registerOTel({ serviceName: 'next-app' });
}

통합이 등록되면 AI SDK 호출에 대해 텔레메트리가 자동으로 전송돼요:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { prompt } = await req.json();

  const { text } = await generateText({
    model: openai('gpt-6-astra'),
    prompt,
  });

  return new Response(JSON.stringify({ text }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

컨텍스트 전파 같은 고급 옵션은 Vercel OpenTelemetry 문서를 참고하세요.

4. 앱 실행과 trace 보기

NextJS 앱을 시작하고 tracking server 엔드포인트(예: http://localhost:5000)에서 MLflow UI를 열어요. AI SDK 호출에 대한 trace가 구성된 실험에 표시돼요.

기타 Node.js 애플리케이션

다른 Node.js 프레임워크의 경우 OpenTelemetry Node SDK와 OTLP exporter를 수동으로 연결해요.

import { init } from 'mlflow-tracing';
import { registerTelemetry, generateText } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';
import { openai } from '@ai-sdk/openai';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

const sdk = new NodeSDK({
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: '<your-mlflow-tracking-server-endpoint>/v1/traces',
        headers: { 'x-mlflow-experiment-id': '<your-experiment-id>' },
      }),
    ),
  ],
});

sdk.start();
init();
registerTelemetry(new LegacyOpenTelemetry());

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'What is MLflow?',
});

console.log(result.text);
sdk.shutdown();

npx tsx main.ts

스트리밍

스트리밍이 지원돼요. generateText처럼 통합이 등록되면 trace가 자동으로 캡처돼요.

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const stream = await streamText({
  model: openai('gpt-6-astra'),
  prompt: 'Explain vector databases in one paragraph.',
});

for await (const part of stream.textStream) {
  process.stdout.write(part);
}

자동 트레이싱 비활성화

Vercel AI SDK 트레이싱을 비활성화하려면 AI SDK 호출에 telemetry: { isEnabled: false }를 설정해요.

더 알아보기

  • AI SDK용 MLflow Tracing을 설정한 후에는 더 넓은 MLflow GenAI 기능을 활용할 수 있어요:
    • Evaluation: 내장 LLM judge와 데이터셋 관리를 사용해 개발부터 프로덕션까지 GenAI 앱 품질을 체계적으로 측정하고 모니터링.
    • Prompt Management: 버전 관리, 별칭, 계보, 협업을 통해 프롬프트 템플릿을 중앙화해 팀이 프롬프트를 안전하게 재사용·비교.
    • MCP Server: 코딩 에이전트를 MLflow MCP Server와 연결해 MLflow trace와 프로그래밍 방식으로 상호작용하고 LLM 애플리케이션 개선.
  • AI SDK의 트레이싱에 대한 자세한 내용은 텔레메트리 문서를 참고하세요.

더 알아보기 (Learn more)