PointFive
PointFive
LiteLLM은 프록시 요청 로그를 PointFive로 보내 AI 비용 및 사용량 분석을 할 수 있어요. 로그는 버퍼링되었다가 PointFive API가 배치마다 발급하는 사전 서명된 URL(presigned URL)을 통해 업로드되므로, 프록시는 자체 클라우드 자격 증명을 보유하지 않고 호스팅 위치와 무관하게 그대로 실행돼요.
출처: 문서
본문
개요 (Overview)
| 속성 | 세부 정보 |
|---|---|
| 콜백 이름 | pointfive |
| 목적지 | PointFive, 배치마다 발급되는 사전 서명된 업로드 URL을 통해 |
| 데이터 형식 | gzip 압축 NDJSON, 요청당 한 줄 |
| 업로드 트리거 | 매 flush_interval 초마다, 또는 batch_size 레코드가 큐에 쌓이는 즉시 |
| 인증 | PointFive API 키 |
사전 준비 (Prerequisites)
PointFive 계정과 API 키가 필요해요. PointFive 앱에서 LiteLLM 통합을 추가하세요. 이 콜백이 업로드 URL을 요청할 때 사용하는 키를 발급해요.
설정 (Setup)
환경 변수 (Environment variables)
| 변수 | 필수 | 설명 |
|---|---|---|
| POINTFIVE_API_KEY | 예 | PointFive API 키 |
| POINTFIVE_API_URL | 아니요 | PointFive API 엔드포인트. 기본값 https://api.pointfive.co/api/v1/ingestion |
프록시 설정 (Proxy config)
model_list:
- model_name: gpt-5.6-luna
litellm_params:
model: openai/gpt-5.6-luna
api_key: os.environ/OPENAI_API_KEY
litellm_settings:
callbacks: ["pointfive"]
export POINTFIVE_API_KEY="<your-api-key>"
litellm --config /path/to/config.yaml
UI에서 설정 (Setup on the UI)
config.yaml 대신 admin UI에서 콜백을 활성화할 수 있어요. Settings, 다음 Logging & Alerts를 열고 PointFive를 추가한 후 API 키를 붙여넣으세요. 기본 엔드포인트를 사용하려면 URL 필드는 비워 두세요. Test는 PointFive가 그 키를 수락하는지 물어보고 수락하지 않으면 이유를 보고해요. 이 기능은 프록시 관리자만 사용할 수 있어요. 이 화면에 접근하는 방법은 admin UI 문서를 참조하세요.
배치 튜닝 (Tuning the batching)
모든 설정은 선택 사항이며 pointfive_params 아래에 줄 수 있어요. 비밀값은 os.environ/로 참조할 수 있어요.
litellm_settings:
callbacks: ["pointfive"]
pointfive_params:
api_key: os.environ/POINTFIVE_API_KEY
api_url: https://api.pointfive.co/api/v1/ingestion
batch_size: 1000
flush_interval: 300
max_batch_bytes: 8388608
max_upload_retries: 3
| 설정 | 기본값 | 설명 |
|---|---|---|
| api_key | 미설정 | POINTFIVE_API_KEY로 폴백. 키 없이는 콜백이 시작을 거부 |
| api_url | https://api.pointfive.co/api/v1/ingestion | POINTFIVE_API_URL로 폴백 |
| batch_size | 1000 | 간격이 지나기 전에 플러시를 트리거하는 큐잉된 레코드 수 |
| flush_interval | 300 | 플러시 사이의 초 |
| max_batch_bytes | 8388608 | 업로드 객체당 압축 전 크기 상한. 더 큰 플러시는 여러 객체로 분할 |
| max_upload_retries | 3 | 객체당 시도 횟수, 그 사이 지수 백오프 |
모든 플러시가 적어도 하나의 객체가 되므로, 기본값은 신선함보다 더 적고 큰 업로드를 선택해요.
프롬프트와 응답 제거 (Redacting prompts and responses)
turn_off_message_logging을 설정하면 실패한 요청과 성공한 요청 모두에서 프롬프트와 응답이 업로드되는 것에서 제외돼요. 모델, 토큰 수, 지연 시간, 지출 같은 메타데이터는 여전히 전송돼요.
litellm_settings:
callbacks: ["pointfive"]
pointfive_params:
turn_off_message_logging: true
동작 방식 (How it works)
각 플러시는 큐잉된 레코드를 NDJSON으로 직렬화하고, max_batch_bytes보다 크지 않은 객체로 분할한 뒤, 이벤트 루프에서 각 객체를 gzip으로 압축하고, PUT하기 전에 정확히 그 바이트 크기의 업로드 URL을 PointFive API에 요청해요. 모든 재시도는 새 URL을 요청하므로 만료되었거나 이미 소비된 URL은 재사용되지 않으며, PointFive가 객체 키를 정하므로 프록시는 자체 데이터가 어디에 놓일지 선택하지 않아요.
업로드 URL은 PointFive API에서 오므로, 프록시가 연결하기 전에 다른 외부 공급 목적지처럼 검사돼요. 프라이빗, 루프백, 링크-로컬 주소로 해석되는 호스트는 거부되고 리다이렉트는 절대 따라가지 않아요. 이 검사는 litellm_settings의 user_url_validation과 user_url_allowed_hosts를 존중해요.
전달은 최소 한 번(at-least-once)이에요. 재시도할 가치가 있는 실패는 배치를 다음 플러시까지 큐에 유지하여 이미 도착한 객체를 다시 보낼 수 있으며, 서버가 다시 거부할 리젝션은 그 뒤에 큐잉된 모든 레코드를 차단하는 대신 그 객체를 버려요. 플러시가 큐에 아무것도 없을 때, 콜백은 여전히 살아 있음을 보고하므로 유휴 프록시는 전송을 멈춘 프록시와 구분할 수 있어요.
검증 (Verification)
LITELLM_LOG=DEBUG로 프록시를 실행하고 요청을 보내세요. 각 업로드는 압축된 크기와 도착한 키를 기록해요:
pointfive: uploaded 5182 gzipped bytes to <object-key>
실패는 같은 pointfive: 접두사에 경고나 오류로 기록되며, 배치가 이후 플러시를 위해 유지됐는지 버려졌는지도 포함돼요.
프록시 관리자는 프록시에 연결을 직접 확인하도록 요청할 수도 있어요:
curl -H "Authorization: Bearer $LITEL..._KEY" \
"http://localhost:4000/health/services?service=pointfive"
{"status": "healthy", "message": "PointFive is healthy"}