Helicone Observability

Helicone은 AI 애플리케이션을 모니터링, 분석, 최적화하도록 돕는 오픈소스 LLM 관측성 플랫폼이에요. 내장 관측성은 모든 요청을 자동으로 추적해 추가 계측 없이도 성능, 비용, 사용자 행동, 모델 사용량에 대한 포괄적인 인사이트를 제공해요.

출처: 문서

본문

설정

Helicone 프로바이더는 @helicone/ai-sdk-provider 패키지에서 사용할 수 있어요. 다음과 같이 설치해요:

npm install @helicone/ai-sdk-provider

Helicone 설정하기:

helicone.ai에서 Helicone 계정을 만들어요.
Helicone Dashboard에서 API 키를 받아요.
API 키를 환경 변수로 설정해요:
```
HELICONE_API_KEY=your-helicone-api-key
```

애플리케이션에서 Helicone을 사용해요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

// Use the provider with any supported model: https://helicone.ai/models
const result = await generateText({
  model: helicone('claude-4.5-haiku'),
  prompt: 'Hello world',
});

console.log(result.text);

끝이에요! 이제 요청이 자동 관측성과 함께 Helicone을 통해 로그되고 모니터링돼요.

→ Helicone AI Gateway에 대해 더 알아보기

주요 관측성 기능

Helicone은 추가 계측 없이도 AI 애플리케이션에 대한 포괄적인 관측성을 제공해요:

자동 요청 추적

모든 요청이 전체 요청/응답 데이터와 함께 자동으로 로그돼요.
지연시간, 토큰, 비용, 모델 성능을 실시간으로 추적해요.
OpenTelemetry 설정이나 추가 구성이 필요 없어요.

분석 대시보드

모든 AI 요청에 걸친 지표(비용, 지연시간, 토큰 사용량, 오류율)를 확인해요.
사용자, 세션, 모델 또는 커스텀 속성별로 필터링해요.
성능 병목 지점을 파악하고 모델 선택을 최적화해요.

사용자 및 세션 분석

개별 사용자 행동과 사용 패턴을 추적해요.
세션 추적으로 대화 흐름을 모니터링해요.
사용자 참여와 기능 채택을 분석해요.

비용 모니터링

요청, 사용자, 기능, 모델별 실시간 비용 추적.
예산 알림과 비용 최적화 인사이트.
서로 다른 모델과 프로바이더 간 비용 비교.

디버깅 및 문제 해결

모든 호출에 대한 전체 요청/응답 로깅.
상세 컨텍스트와 함께하는 오류 추적.
문제를 빠르게 파악하기 위한 검색 및 필터.

→ Helicone 관측성에 대해 더 알아보기

관측성 구성

사용자 추적

개별 사용자 행동을 추적하고 애플리케이션 전반의 사용 패턴을 분석해요. 가장 활발한 사용자가 누구인지 이해하고, 파워 유저를 식별하며, 사용자별 비용을 모니터링하는 데 도움이 돼요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

const result = await generateText({
  model: helicone('gpt-6-luna', {
    extraBody: {
      helicone: {
        userId: '[email protected]',
      },
    },
  }),
  prompt: 'Hello world',
});

추적할 수 있는 것:

사용자별 총 요청 수
사용자별 비용
사용자별 평균 지연시간
사용자 세그먼트별 가장 흔한 사용 사례

→ 사용자 메트릭에 대해 더 알아보기

커스텀 속성

구조화된 메타데이터를 추가해 기능, 환경 또는 기타 임의 차원으로 요청을 세분하고 분석해요. 이는 분석 대시보드에서 강력한 필터링과 인사이트를 가능하게 해요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

const result = await generateText({
  model: helicone('gpt-6-luna', {
    extraBody: {
      helicone: {
        properties: {
          feature: 'translation',
          source: 'mobile-app',
          language: 'French',
          environment: 'production',
        },
      },
    },
  }),
  prompt: 'Translate this text to French',
});

커스텀 속성의 사용 사례:

서로 다른 기능이나 환경 간 성능 비교하기
제품 영역이나 고객 등급별 비용 추적하기
가장 많은 AI 사용을 이끄는 기능 파악하기
실험에 태그를 붙여 다른 프롬프트나 모델 A/B 테스트하기

→ 커스텀 속성에 대해 더 알아보기

세션 추적

관련 요청을 세션으로 묶어 대화 흐름과 다중 턴 상호작용을 분석해요. 사용자 여정을 이해하고 복잡한 대화를 디버깅하는 데 필수적이에요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

const result = await generateText({
  model: helicone('gpt-6-luna', {
    extraBody: {
      helicone: {
        sessionId: 'convo-123',
        sessionName: 'Travel Planning',
        sessionPath: '/chats/travel',
      },
    },
  }),
  prompt: 'Tell me more about that',
});

세션 추적 이점:

단일 타임라인에서 전체 대화 기록 보기
세션/대화별 총 비용 계산
세션 기간과 메시지 수 측정
다중 턴 대화에서 사용자가 이탈하는 지점 파악
전체 대화 흐름을 재생해 문제 디버깅

→ 세션에 대해 더 알아보기

고급 관측성 기능

태그와 조직화

태그를 추가해 분석 대시보드에서 요청을 조직화하고 필터링해요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

const result = await generateText({
  model: helicone('gpt-6-luna', {
    extraBody: {
      helicone: {
        tags: ['customer-support', 'urgent'],
        properties: {
          ticketId: 'TICKET-789',
          priority: 'high',
          department: 'support',
        },
      },
    },
  }),
  prompt: 'Help resolve this customer issue',
});

태그 인사이트:

태그별로 요청 필터링 및 그룹화
서로 다른 카테고리 간 성능 추적
태그가 달린 요청의 패턴 파악
특정 태그를 중심으로 커스텀 대시보드 구축

→ Helicone 기능에 대해 더 알아보기

스트리밍 응답 추적

첫 토큰까지의 시간과 총 스트리밍 기간을 포함해 스트리밍 응답을 완전한 관측성으로 모니터링해요:

import { createHelicone } from '@helicone/ai-sdk-provider';
import { streamText } from 'ai';

const helicone = createHelicone({
  apiKey: proces...KEY,
});

const result = await streamText({
  model: helicone('gpt-6-luna', {
    extraBody: {
      helicone: {
        userId: '[email protected]',
        sessionId: 'stream-session-123',
        tags: ['streaming', 'content-generation'],
      },
    },
  }),
  prompt: 'Write a short story about AI',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

추적되는 스트리밍 메트릭:

첫 토큰까지의 시간 (TTFT)
총 스트리밍 기간
초당 토큰 수
스트림에도 적용되는 완전한 요청/응답 로깅
실시간 애플리케이션을 위한 사용자 경험 메트릭
스트리밍된 응답에도 추적되는 모든 메타데이터 (세션, 사용자, 태그)

자료

더 알아보기 (Learn more)

출처 문서: Helicone Observability