Spend 정책
Spend 정책
조직 전반의 LLM 사용량에 비용 한도를 설정하고 프로바이더에 도달하기 전에 통제 불능 지출을 방지하는 방법을 알려드릴게요.
참고: LLM Gateway는 베타 상태입니다.
spend 정책은 특정 범위(조직, 워크스페이스, API 키, 또는 사용자)에 대해 시간 창(월별, 주별, 일별, 시간별)에 걸친 비용 캡을 정의합니다. LLM Gateway는 지출을 실시간으로 추적하며 지출을 캡 너머로 밀어낼 요청을 차단하고 402 응답을 반환합니다:
API Error: 402 request blocked by gateway policies: R&D Spend Cap
차단된 요청은 정책 위반이 메타데이터로 기록된 채 LangSmith에 트레이싱되어 정확히 무엇이 차단되었고 왜인지 볼 수 있습니다.
출처: 문서
본문
정책 차원
Spend 정책은 가장 넓은 범위에서 가장 구체적인 범위로 평가됩니다. 일치하는 모든 정책이 확인되고, 하나라도 차단을 반환하면 요청이 거부됩니다. 기본값(모든 워크스페이스, 사용자, API 키에 블랭킷 spend 캡 적용) 또는 세분화 정책(개별 한도 또는 엔티티 그룹의 한도)으로 설정할 수 있습니다.
| Scope | What it caps | Example |
|---|---|---|
| Organization | Total spend across all workspaces in the org | "The entire org cannot spend more than $10,000/month on LLM calls" |
| Workspace | Total spend within a single workspace or group of workspaces | "The workspaces related to R&D cannot spend more than $2,000/month" |
| API key | Spend by a single API key or group of API keys (maps to a service or agent) | "The customer support agent keys cannot spend more than $500/month cumulatively" |
| User | Spend by a single user or group of users (resolved from the API key's identity) | "No individual developer can spend more than $50/day" |
충돌 해결
기본적으로 LLM Gateway는 가장 넓은 범위를 먼저 평가합니다. 세분화 정책이 적용되면 가장 제한적인 정책이 이깁니다. 더 좁은 범위는 한도를 조일 수만 있고, 느슨하게 할 수는 없습니다. 조직 수준 정책이 지출을 월 $10,000로 캡하고 워크스페이스 수준 정책이 $15,000/월로 캡하면 $10,000 조직 캡이 여전히 적용됩니다.
기본값 vs 세분화 정책
Spend 정책에는 두 가지 측면이 있습니다:
- 차원의 합계(sum across a dimension): 해당 범위의 총 캡. 예: "이 워크스페이스의 총 지출은 월 $5,000를 초과할 수 없습니다."
- 차원의 각 구성원에 대한 기본값: 재정의되지 않는 한 범위 내의 모든 API 키 또는 사용자에게 적용되는 기본 한도. 예: "이 워크스페이스의 각 API 키는 월 $200 기본 캡을 받습니다." 개별 API 키는 특정 한도를 높이는 추가 정책을 받을 수 있지만, 어떤 정책도 더 넓은 범위에서 설정된 캡을 느슨하게 할 수 없습니다.
시간 창
| Window | Resets | Use case |
|---|---|---|
| Monthly | 매월 1일 | 예산 정렬, 전반적인 비용 제어 |
| Weekly | 매주 월요일 자정 UTC | 주간 예산 |
| Daily | 자정 UTC | 단일일 비용 급증 방지(예: 밤새 재시도 루프에 빠진 코딩 에이전트) |
| Hourly | 매시 정각 | 통제 불능 에이전트를 빠르게 잡기 |
같은 범위에 여러 시간 창을 적용할 수 있습니다. 예를 들어 워크스페이스는 월 $5,000 캡과 일 $500 캡을 모두 가질 수 있습니다. 둘 다 독립적으로 시행됩니다.
Spend 정책 만들기
경고: 정책 생성·관리에는
organization:manage권한이 필요합니다. 전체 권한 분석은 트레이스, Engine, 접근 제어를 참고하세요.
- LLM Gateway로 이동해 Cost Controls를 선택합니다.
- Create spend limit을 클릭합니다.
- 범위(조직, 워크스페이스, API 키, 사용자)를 선택합니다.
- (선택) 기본적으로 모든 사용자에게 동일한 기본 한도를 독립적으로 적용하려면 Separate limits by custom header를 선택하고 헤더 이름을 입력해 각 커스텀 헤더 값에 독립적으로 적용합니다.
- 시간 창(월별, 주별, 일별, 시간별)을 설정합니다.
- USD로 spend 캡을 설정합니다.
- Create spend limit을 클릭합니다.
정책은 즉시 적용됩니다. 게이트웨이는 모든 들어오는 요청에서 1초 미만의 시행 지연 시간으로 평가합니다.
spend 정책은 커스텀 요청 헤더를 사용해 하나의 API 키 아래에서 각 최종 고객에게 독립적인 캡을 줄 수도 있습니다. 자세한 내용은 고객별 정책을 참고하세요.
지출 보기
지출 가시성 대시보드는 실시간 비용 롤업을 보여주므로 한도에 도달하기 전에 LLM 예산이 어디로 가는지 이해할 수 있습니다.
게이트웨이 설정 페이지에서 각 정책이 캡에 대해 얼마나 지출했는지 볼 수 있습니다.
LangSmith Engine과의 통합
spend 정책이 요청을 차단하면 위반이 트레이스의 메타데이터로 기록됩니다. 이러한 위반은 LangSmith Engine에서 이슈로 표면화되며, 이슈에서 트레이스로 클릭스루해 에이전트가 한도에 도달했을 때 무엇을 하고 있었는지 이해할 수 있습니다.
이것은 차단된 요청이 진짜 비용 문제(재시도 루프의 코딩 에이전트)인지, 아니면 조정이 필요한 정책(캡을 넘어 성장한 정당한 워크로드)인지 진단하는 데 유용합니다.