Helicone

Helicone

Helicone은 사용량, 지출, 지연 시간 등에 대한 핵심 인사이트를 제공하는 오픈소스 관측성 플랫폼이에요. LiteLLM과 Helicone을 연동해 모든 프로바이더의 응답을 로깅하는 방법을 알려드릴게요.

출처: 문서

본문

tip — 커뮤니티에서 유지 관리되는 통합이에요. 버그를 발견하면 이슈를 만들어 주세요: https://github.com/BerriAI/litellm

Helicone은 사용량, 지출, 지연 시간 등에 대한 핵심 인사이트를 제공하는 오픈소스 관측성 플랫폼이에요.

빠른 시작 (Quick Start)

Python SDK:

단 한 줄의 코드로 모든 프로바이더의 응답을 Helicone에 즉시 로깅할 수 있어요:

import os
from litellm import completion

## Set env variables
os.environ["HELICONE_API_KEY"] = "your-helicone-key"

# OpenAI call
response = completion(
    model="helicone/gpt-5.6-luna",
    messages=[{"role": "user", "content": "Hi 👋 - I'm OpenAI"}],
)

print(response)

LiteLLM Proxy:

LiteLLM 프록시 구성에 Helicone을 추가해 주세요:

config.yaml:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

# Add Helicone callback
litellm_settings:
  success_callback: ["helicone"]

# Set Helicone API key
environment_variables:
  HELICONE_API_KEY: "your-helicone-key"

프록시 시작:

litellm --config config.yaml

통합 방법 (Integration Methods)

LiteLLM과 Helicone을 통합하는 두 가지 주요 접근 방식이 있어요.

1. 프로바이더로 사용: Helicone으로 지원되는 모든 모델의 요청을 로깅
2. 콜백 사용: 어떤 프로바이더를 사용하면서도 Helicone에 로깅

지원되는 LLM 프로바이더 (Supported LLM Providers)

Helicone은 모든 주요 LLM 프로바이더에 걸쳐 요청을 로깅할 수 있어요:

• OpenAI
• Azure
• Anthropic
• Gemini
• Groq
• Cohere
• Replicate
• 그 외 더 많음

방법 1: Helicone을 프로바이더로 사용 (Using Helicone as a Provider)

Helicone의 AI 게이트웨이는 캐싱, 속도 제한, LLM 보안 등 고급 기능을 제공해요.

Helicone을 기본 URL로 설정하고 인증 헤더를 전달해 주세요:

import os
import litellm
from litellm import completion

os.environ["HELICONE_API_KEY"] = ""  # your Helicone API key

messages = [{"content": "What is the capital of France?", "role": "user"}]

# Helicone call - routes through Helicone gateway to any model
response = completion(
    model="helicone/gpt-5.6-luna", # or any 100+ models
    messages=messages
)

print(response)

고급 사용법 (Advanced Usage)

Helicone 헤더를 사용해 요청에 사용자 지정 메타데이터와 속성을 추가할 수 있어요. 몇 가지 예시예요:

litellm.metadata = {
    "Helicone-User-Id": "user-abc",  # Specify the user making the request
    "Helicone-Property-App": "web",  # Custom property to add additional information
    "Helicone-Property-Custom": "any-value",  # Add any custom property
    "Helicone-Prompt-Id": "prompt-supreme-court",  # Assign an ID to associate this prompt with future versions
    "Helicone-Cache-Enabled": "true",  # Enable caching of responses
    "Cache-Control": "max-age=3600",  # Set cache limit to 1 hour
    "Helicone-RateLimit-Policy": "10;w=60;s=user",  # Set rate limit policy
    "Helicone-Retry-Enabled": "true",  # Enable retry mechanism
    "helicone-retry-num": "3",  # Set number of retries
    "helicone-retry-factor": "2",  # Set exponential backoff factor
    "Helicone-Model-Override": "gpt-5.6-luna",  # Override the model used for cost calculation
    "Helicone-Session-Id": "session-abc-123",  # Set session ID for tracking
    "Helicone-Session-Path": "parent-trace/child-trace",  # Set session path for hierarchical tracking
    "Helicone-Omit-Response": "false",  # Include response in logging (default behavior)
    "Helicone-Omit-Request": "false",  # Include request in logging (default behavior)
    "Helicone-LLM-Security-Enabled": "true",  # Enable LLM security features
    "Helicone-Moderations-Enabled": "true",  # Enable content moderation
}

캐싱과 속도 제한 (Caching and Rate Limiting)

캐싱을 활성화하고 속도 제한 정책을 설정해 주세요:

litellm.metadata = {
    "Helicone-Cache-Enabled": "true",  # Enable caching of responses
    "Cache-Control": "max-age=3600",  # Set cache limit to 1 hour
    "Helicone-RateLimit-Policy": "100;w=3600;s=user",  # Set rate limit policy
}

방법 2: 콜백 사용 (Using Callbacks)

어떤 LLM 프로바이더를 직접 사용하면서도 Helicone에 요청을 로깅해요.

Python SDK:

import os
import litellm
from litellm import completion

## Set env variables
os.environ["HELICONE_API_KEY"] = "your-helicone-key"
os.environ["OPENAI_API_KEY"] = "your-openai-key"
# os.environ["HELICONE_API_BASE"] = "" # [OPTIONAL] defaults to `https://api.helicone.ai`

# Set callbacks
litellm.success_callback = ["helicone"]

# OpenAI call
response = completion(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hi 👋 - I'm OpenAI"}],
)

print(response)

config.yaml:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

# Add Helicone logging
litellm_settings:
  success_callback: ["helicone"]

# Environment variables
environment_variables:
  HELICONE_API_KEY: "your-helicone-key"
  OPENAI_API_KEY: "your-openai-key"
  ANTHROPIC_API_KEY: "your-anthropic-key"

프록시 시작:

litellm --config config.yaml

프록시에 요청 보내기:

import openai

client = openai.OpenAI(
    api_key="anything",  # proxy doesn't require real API key
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",  # This gets logged to Helicone
    messages=[{"role": "user", "content": "Hello!"}]
)

세션 추적 및 트레이싱 (Session Tracking and Tracing)

세션 ID와 경로를 사용해 다단계·에이전트 LLM 상호작용을 추적해요.

Python SDK:

import os
import litellm
from litellm import completion

os.environ["HELICONE_API_KEY"] = ""  # your Helicone API key

messages = [{"content": "What is the capital of France?", "role": "user"}]

response = completion(
    model="helicone/gpt-5.6-terra",
    messages=messages,
    metadata={
        "Helicone-Session-Id": "session-abc-123",
        "Helicone-Session-Path": "parent-trace/child-trace",
    }
)

print(response)

LiteLLM Proxy:

import openai

client = openai.OpenAI(
    api_key="anything",
    base_url="http://localhost:4000"
)

# First request in session
response1 = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "Helicone-Session-Id": "session-abc-123",
        "Helicone-Session-Path": "conversation/greeting"
    }
)

# Follow-up request in same session
response2 = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Tell me more"}],
    extra_headers={
        "Helicone-Session-Id": "session-abc-123",
        "Helicone-Session-Path": "conversation/follow-up"
    }
)

• Helicone-Session-Id: 관련 요청을 묶는 세션의 고유 식별자
• Helicone-Session-Path: 부모/자식 트레이스를 나타내는 계층적 경로(예: "parent/child")

재시도 및 폴백 메커니즘 (Retry and Fallback Mechanisms)

Python SDK:

import litellm

litellm.api_base = "https://ai-gateway.helicone.ai/"
litellm.metadata = {
    "Helicone-Retry-Enabled": "true",
    "helicone-retry-num": "3",
    "helicone-retry-factor": "2",
}

response = litellm.completion(
    model="helicone/gpt-5.6-luna/openai,claude-sonnet-5/anthropic", # Try OpenAI first, then fallback to Anthropic, then continue with other models
    messages=[{"role": "user", "content": "Hello"}]
)

config.yaml:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
      api_base: "https://oai.hconeai.com/v1"

default_litellm_params:
  headers:
    Helicone-Auth: "Bearer ${HELICONE_API_KEY}"
    Helicone-Retry-Enabled: "true"
    helicone-retry-num: "3"
    helicone-retry-factor: "2"
    Helicone-Fallbacks: '["gpt-5.6-luna", "gpt-5.6-terra"]'

environment_variables:
  HELICONE_API_KEY: "your-helicone-key"
  OPENAI_API_KEY: "your-openai-key"

지원 헤더 — 지원되는 Helicone 헤더 전체 목록과 설명은 Helicone 문서를 참고해 주세요. 이 헤더들과 metadata 옵션을 사용하면 LLM 사용량을 더 자세히 확인하고, 성능을 최적화하며, Helicone과 LiteLLM으로 AI 워크플로를 더 잘 관리할 수 있어요.

더 알아보기 (Learn more)

• Helicone — 오픈소스 관측성 플랫폼
• Helicone 문서 — AI 게이트웨이 고급 기능