Braintrust

Braintrust는 AI 제품을 위한 평가, 로깅, 프롬프트 플레이그라운드부터 데이터 관리까지 제공해요. LiteLLM 통화를 Braintrust에 로깅하고 메타데이터로 스팬을 커스터마이징하는 방법을 알려드릴게요.

출처: 문서

본문

빠른 시작 (Quick Start)

# uv add braintrust
import litellm
import os

# set env
os.environ["BRAINTRUST_API_KEY"] = ""
os.environ["BRAINTRUST_API_BASE"] = "https://api.braintrustdata.com/v1"
os.environ['OPENAI_API_KEY']=""

# set braintrust as a callback, litellm will send the data to braintrust
litellm.callbacks = ["braintrust"]

# openai call
response = litellm.completion(
  model="gpt-5.6-luna",
  messages=[
    {"role": "user", "content": "Hi 👋 - i'm openai"}
  ]
)

OpenAI 프록시 사용 (OpenAI Proxy Usage)

환경 변수에 키 추가

BRAINTRUST_API_KEY=""
BRAINTRUST_API_BASE="https://api.braintrustdata.com/v1"

callbacks에 braintrust 추가

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

litellm_settings:
  callbacks: ["braintrust"]

테스트해 보세요!

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-D '{
    "model": "groq-llama3",
    "messages": [
        { "role": "system", "content": "Use your tools smartly"},
        { "role": "user", "content": "What time is it now? Use your tool"}
    ]
}'

고급 — Project ID 또는 이름 전달 (Advanced - pass Project ID or name)

트레이스가 올바른 Braintrust 프로젝트에 기록되도록 project_id 또는 project_name을 포함하는 것이 좋아요.

사용자 지정 스팬 이름 (Custom Span Names)

metadata에 span_name을 전달해 Braintrust 로깅의 스팬 이름을 커스터마이징할 수 있어요. 기본값은 서버 스팬 이름이 "Chat Completion"으로 설정돼요.

사용자 지정 스팬 속성 (Custom Span Attributes)

metadata에 span_id, root_span_id, span_parents를 전달해 Braintrust 로깅의 스팬 ID, 루트 스팬 이름, 스팬 부모를 커스터마이징할 수 있어요. span_parents는 쉼표로 연결된 스팬 ID 목록 문자열이어야 해요.

SDK:

response = litellm.completion(
  model="gpt-5.6-luna",
  messages=[
    {"role": "user", "content": "Hi 👋 - i'm openai"}
  ],
  metadata={
    "project_id": "1234",
    # passing project_name will try to find a project with that name, or create one if it doesn't exist
    # if both project_id and project_name are passed, project_id will be used
    # "project_name": "my-special-project",
    # custom span name for this operation (default: "Chat Completion")
    "span_name": "User Greeting Handler"
  }
)

참고: SDK 사용 시 여기에 다른 metadata도 포함할 수 있어요.

response = litellm.completion(
  model="gpt-5.6-luna",
  messages=[
    {"role": "user", "content": "Hi 👋 - i'm openai"}
  ],
  metadata={
    "project_id": "1234",
    "span_name": "Custom Operation",
    "item1": "an item",
    "item2": "another item"
  }
)

Curl:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-D '{
    "model": "groq-llama3",
    "messages": [
        { "role": "system", "content": "Use your tools smartly"},
        { "role": "user", "content": "What time is it now? Use your tool"}
    ],
    "metadata": {
        "project_id": "my-special-project",
        "span_name": "Tool Usage Request"
    }
}'

OpenAI SDK:

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

# request sent to model set on litellm proxy, `litellm --model`
response = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages = [
        {
            "role": "user",
            "content": "this is a test request, write a short poem"
        }
    ],
    extra_body={ # pass in any provider-specific param, if not supported by openai, https://docs.litellm.ai/docs/completion/input#provider-specific-params
        "metadata": { # 👈 use for logging additional params (e.g. to braintrust)
            "project_id": "my-special-project",
            "span_name": "Poetry Generation"
        }
    }
)

print(response)

더 많은 예시는 여기 클릭을 참고해 주세요.

BRAINTRUST_API_BASE를 사용해 자체 호스팅 Braintrust 데이터 플레인을 가리킬 수 있어요. 자세한 내용은 여기에서 읽어보세요.

전체 API 스펙 (Full API Spec)

braintrust 요청의 metadata에 전달할 수 있는 모든 값이에요.

braintrust_* — 프록시 요청 헤더 에서 메타데이터를 추가하는 경우, braintrust_로 시작하는 모든 메타데이터 필드는 로깅 요청에 metadata로 전달돼요. SDK를 사용한다면 평소처럼 메타데이터를 전달하면 돼요(예: metadata={"project_name": "my-test-project", "item1": "an item", "item2": "another item"}).
project_id — braintrust 호출의 프로젝트 ID를 설정해요. 기본값은 litellm.
project_name — braintrust 호출의 프로젝트 이름을 설정해요. 그 이름의 프로젝트를 찾거나 없으면 생성하려 시도해요. project_id와 project_name을 모두 전달하면 project_id가 사용돼요.
span_name — 작업의 사용자 지정 스팬 이름을 설정해요. 기본값은 "Chat Completion". 앱에서 다양한 작업 유형에 더 설명적인 이름을 붙일 때 사용하세요(예: "User Query", "Document Summary", "Code Generation").

더 알아보기 (Learn more)

Braintrust — 평가·로깅·프롬프트 관리 플랫폼