Patronus 관측성

Patronus AI 는 LLM 시스템의 성능을 평가·모니터링·개선하기 위한 엔드투엔드 시스템을 제공해, 개발자가 AI 제품을 안전하고 자신 있게 출시할 수 있게 해줘요. 더 알아보기 여기.

AI SDK로 빌드할 때 OpenTelemetry(OTEL) 트레이스를 Patronus로 직접 스트리밍하고, 모든 생성(generation)을 풍부한 자동 평가와 함께 짝지을 수 있어요.

출처: 문서

본문

설정 (Setup)

1. OpenTelemetry

Patronus는 완전 관리형 OTEL 엔드포인트를 제공해요. OTLP exporter를 그쪽을 가리키도록 구성하고 API 키를 전달하면 끝이에요 — Patronus가 LLM 스팬을 탐색·평가할 수 있는 프롬프트/응답 레코드로 자동 변환해줘요.

환경 변수 (권장)

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.patronus.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="x-api-key:<PATRO...EY>"

`@vercel/otel` 사용

import { registerOTel } from '@vercel/otel';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { registerTelemetry } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';

export function register() {
  registerOTel({
    serviceName: 'next-app',
    additionalSpanProcessors: [
      new BatchSpanProcessor(
        new OTLPTraceExporter({
          url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
          headers: {
            'x-api-key': process.env.PATRONUS_API_KEY!,
          },
        }),
      ),
    ],
  });
}

registerTelemetry(new LegacyOpenTelemetry());

참고: HTTP 대신 gRPC가 필요하면 exporter를 @opentelemetry/exporter-trace-otlp-grpc로 바꾸고 https://otel.patronus.ai:4317을 사용하세요.

2. 통합 등록 및 텔레메트리 활성화

@ai-sdk/otel을 설치하고 instrumentation.ts에 registerTelemetry를 추가하면 텔레메트리가 자동으로 캡처돼요. 메타데이터를 붙이려면 telemetry를 전달하세요:

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

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'Write a haiku about spring.',
  telemetry: {
    functionId: 'spring-haiku', // 스팬 이름
    metadata: {
      userId: 'user-123', // 커스텀 속성은 Patronus UI에 표시됨
    },
  },
});

metadata 안의 모든 속성은 OTEL 속성이 되고 Patronus가 필터링용으로 인덱싱해요.

예시 — 트레이싱과 자동 평가 (Example — tracing and automated evaluation)

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

export async function POST(req: Request) {
  const body = await req.json();
  const tracer = trace.getTracer('next-app');

  return await tracer.startActiveSpan('chat-evaluate', async span => {
    try {
      /* 1️⃣ 답변 생성 */
      const answer = await generateText({
        model: openai('gpt-6-astra'),
        prompt: body.prompt,
        telemetry: { functionId: 'chat' },
      });

      /* 2️⃣ 같은 트레이스 안에서 Patronus 평가 실행 */
      await fetch('https://api.patronus.ai/v1/evaluate', {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.PATRONUS_API_KEY!,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          evaluators: [
            { evaluator: 'lynx', criteria: 'patronus:hallucination' },
          ],
          evaluated_model_input: body.prompt,
          evaluated_model_output: answer.text,
          trace_id: span.spanContext().traceId,
          span_id: span.spanContext().spanId,
        }),
      });

      return new Response(answer.text);
    } finally {
      span.end();
    }
  });
}

결과: 루트 HTTP 요청, LLM 생성 스팬, 평가 스팬을 포함하는 단일 트레이스 — 모두 Patronus에서 볼 수 있고 환각(hallucination) 점수가 붙어요.

트레이싱 후 (Once you've traced)

에이전트를 추적하고 있다면 Patronus의 AI 어시스턴트 Percival이 오류 분석과 프롬프트 최적화를 도와줘요. 더 알아보기 여기
Patronus에서 로그와 트레이스를 보고 알림용 웹훅을 구성해 프로덕션 모니터링·경보를 설정하세요. 더 알아보기 여기

리소스 (Resources)

더 알아보기 (Learn more)

Vercel AI SDK 텔레메트리 문서

전체 사이트맵

Patronus 관측성