커스텀 프로퍼티

커스텀 프로퍼티 (Custom Properties)

AI 애플리케이션을 운영하다 보면 요청을 프로젝트·기능·워크플로 단계 같은 다양한 기준으로 나눠 분석하고 싶어져요. 커스텀 프로퍼티는 LLM 요청에 메타데이터를 태그로 달아서, 사용자·기능별 비용 분석이나 구간별 성능 추적을 가능하게 해 줘요. 요청에 헤더 몇 개만 추가하면 대시보드에서 그 기준으로 필터링하거나 집계할 수 있어요.

출처: Helicone 공식 문서 — Custom Properties

왜 커스텀 프로퍼티인가요

  • 단위 경제성 추적 — 사용자·대화·기능별 비용을 계산해 애플리케이션 수익성을 파악할 수 있어요.
  • 복잡한 워크플로 디버깅 — 다단계 AI 프로세스의 관련 요청을 묶어 문제를 찾기 쉽게 해 줘요.
  • 구간별 성능 분석 — 사용자 유형·기능·환경별로 지연 시간과 비용을 비교해요.

시작하기

헤더로 커스텀 프로퍼티를 추가해요.

  1. 헤더 이름 정의 — Helicone-Property-[Name] 형식으로, Name이 커스텀 프로퍼티 이름이에요.
  2. 값 정의 — 값은 이 프로퍼티에 대한 라벨 문자열이에요.
from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gateway.helicone.ai",
    api_key=os.getenv("HELICONE_API_KEY"),
    default_headers={
        "Helicone-Property-Conversation": "support_issue_2",
        "Helicone-Property-App": "mobile",
        "Helicone-Property-Environment": "production",
    }
)

cURL로는 https://ai-gateway.helicone.ai/chat/completions에 인증 헤더와 함께 각 프로퍼티 헤더를 실어 보내면 돼요. LangChain을 쓴다면 ChatOpenAI에 openai_api_base="https://ai-gateway.helicone.ai"와 default_headers를 지정해 같은 방식으로 태그를 달 수 있어요.

동작 방식

커스텀 프로퍼티는 각 요청에 붙는 메타데이터로, 다음이 가능하게 해 줘요.

  • 대시보드에서 어떤 프로퍼티로든 요청 필터링
  • 프로퍼티별로 비용·메트릭 집계
  • 커스텀 차원으로 데이터 내보내기
  • 프로퍼티 값 기반 알림 설정

사용 사례

환경·배포 추적 — Helicone-Property-Environment: production/staging/development, Helicone-Property-Version: v2.1.0, Helicone-Property-Region: us-east-1처럼 헤더를 달면 환경별·버전별 성능과 비용을 비교할 수 있어요. Python에서는 extra_headers로 요청마다 다르게 지정할 수 있어요.

고객 지원 봇 — 티켓 ID(Helicone-Property-TicketId: TICKET-12345), 카테고리, 우선순위, 채널 프로퍼티를 함께 달면 티켓별 비용을 추적하고 우선순위 상향 여부를 분석할 수 있어요.

설정 참고

헤더 설명
Helicone-Property-[Name] 추적하려는 임의의 커스텀 메타데이터. [Name]을 프로퍼티 이름으로 치환. 예: Helicone-Property-Environment: staging
Helicone-User-Id 사용자 추적용 특별 예약 프로퍼티. 사용자별 비용·사용량 분석 활성화. 예: Helicone-User-Id: user-123

요청 이후 프로퍼티 갱신

REST API로 요청 완료 후에도 프로퍼티를 갱신할 수 있어요.

// Get the request ID from the response
const { data, response } = await client.chat.completions
  .create({ /* your request */ })
  .withResponse();

const requestId = response.headers.get("helicone-id");

// Update properties via API
await fetch(`https://api.helicone.ai/v1/request/${requestId}/property`, {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${HELICONE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Environment": "production",
    "PostProcessed": "true"
  })
});

응답 헤더의 helicone-id로 요청 ID를 얻은 뒤, PUT https://api.helicone.ai/v1/request/{requestId}/property 엔드포인트로 갱신해요.

쿼리로 커스텀 프로퍼티 검색

커스텀 프로퍼티를 단 요청은 Query API로 필터링·조회할 수 있어요.

중요: 커스텀 프로퍼티로 필터링할 때는 반드시 properties 필터를 request_response_rmt 객체 안에 감싸야 해요. 이 래퍼를 생략하면 데이터가 있어도 빈 결과가 돌아와요.

curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer ***" \
  --data '{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "Environment": {
          "equals": "production"
        }
      }
    }
  },
  "limit": 100
}'

여러 프로퍼티를 조합하려면 left/right와 operator: "and"(또는 or)로 트리 구조를 만들면 돼요. 예를 들어 Environment=production 이면서 App=mobile 인 요청을 찾으려면 두 필터를 AND로 묶어요. 프로퍼티 필터와 날짜 범위(request_created_at: { "gte": "2024-01-01T00:00:00Z" }) 같은 다른 조건도 같은 방식으로 조합할 수 있어요.

오답 예시(래퍼 없음): filter의 최상위에 properties를 직접 쓰면 빈 결과가 나와요. 항상 request_response_rmt.properties 구조를 써야 해요.

더 알아보기