모델 액세스 그룹 예산

모델 액세스 그룹 예산 (Model Access Group Budgets)

모델 액세스 그룹에 하나의 공유 예산을 줘요. 그룹의 모델에 도달하는 모든 키가 같은 풀에서 끌어가므로, 모델 계층 하나가 각 키에 별도 예산을 두는 대신 단일 월별 허용량을 가질 수 있어요.

관심 있는 지출이 특정 호출자가 아니라 모델에 속할 때 이 예산을 사용해요. 조직 전체가 공유하는 "프리미엄" 계층, 비싼 reasoning 모델 풀, 누가 evals를 돌리든 상한을 두고 싶은 평가 그룹 같은 경우예요.

출처: 문서

본문

사전 요구사항 (Pre-Requisites)

그룹 예산 설정하기

1. 모델을 액세스 그룹에 넣기

config.yaml 또는 /model/new를 통해 배포에 model_info.access_groups를 추가해요.

model_list:
  - model_name: premium-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
    model_info:
      access_groups: ["premium"]

curl -X POST 'http://0.0.0.0:4000/model/new' \
     -H "Authorization: Bearer ***" \
     -H 'Content-Type: application/json' \
     -d '{
           "model_name": "premium-sonnet",
           "litellm_params": {"model": "anthropic/claude-sonnet-5", "api_key": "os.environ/ANTHROPIC_API_KEY"},
           "model_info": {"access_groups": ["premium"]}
         }'

2. 그룹의 예산 설정

curl -X PUT 'http://0.0.0.0:4000/access_group/premium/budget' \
     -H "Authorization: Bearer ***" \
     -H 'Content-Type: application/json' \
     -d '{
           "max_budget": 500.0,
           "budget_duration": "30d"
         }'

파라미터	타입	필수	설명
max_budget	float	아니요	그룹의 공유 지출이 여기에 도달하면 요청을 거부
soft_budget	float	아니요	도달 시 알림 발생. 요청은 여전히 성공
budget_duration	string	아니요	그룹 지출이 리셋되는 주기 (`"1d"`, `"7d"`, `"30d"`, ...)
budget_id	string	아니요	새로 만들지 않고 기존 예산 연결

이 중 하나 이상이 필요해요. 호출은 멱등이므로 다시 보내도 두 번째를 쌓지 않고 그룹의 예산을 교체해요.

3. 키에 그룹 부여

키는 models 목록에서 그룹 이름을 지정해야 해요. 그 부여가 키의 지출을 풀에 묶는 것이에요.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
     -H "Authorization: Bearer ***" \
     -H 'Content-Type: application/json' \
     -d '{
           "models": ["premium"]
         }'

팀, 프로젝트, 조직, 멤버별 팀 범위도 같은 방식이에요. 그룹을 부여한 허용 목록이 무엇이든 그것이 집계됩니다.

4. 테스트

풀을 소진할 때까지 그 키로 그룹의 모델을 호출해요.

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
     -H "Authorization: Bearer ***" \
     -H 'Content-Type: application/json' \
     -d '{
           "model": "premium-sonnet",
           "messages": [{"role": "user", "content": "Hello"}]
         }'

그룹 지출이 max_budget에 도달하면 그룹에 도달할 수 있는 모든 키가 거부됩니다. 자체적으로 아무것도 쓴 적 없는 키도요.

{
  "error": {
    "message": "Budget has been exceeded! Model access group=premium Current cost: 500.12, Max budget: 500.0",
    "type": "budget_exceeded",
    "param": null,
    "code": "429"
  }
}

예산 읽기·지우기

풀과 그것에 대해 사용된 지출 읽기:

curl -X GET 'http://0.0.0.0:4000/access_group/premium/budget' \
     -H "Authorization: Bearer ***"

{
  "access_group": "premium",
  "spend": 245.5,
  "budget": {
    "budget_id": "f56842f7-78d7-4816-847d-b016af57df4c",
    "max_budget": 500.0,
    "soft_budget": null,
    "budget_duration": "30d",
    "budget_reset_at": "2026-09-28T00:00:00Z"
  }
}

예산을 지워도 그룹과 모델은 그대로 남아요.

curl -X DELETE 'http://0.0.0.0:4000/access_group/premium/budget' \
     -H "Authorization: Bearer ***"

{
  "access_group": "premium",
  "budget_deleted": true,
  "message": "Budget for access group 'premium' deleted successfully"
}

어떤 요청이 풀에서 끌어가는가

두 가지가 모두 참일 때 요청이 그룹에 청구됩니다. 그룹이 호출되는 모델을 서빙하고, 호출자가 그룹을 이름으로 부여받은 경우예요. 두 번째 조건을 주의 깊게 보세요.

그룹 이름을 지정하지 않는 허용 목록은 청구할 것을 지정하지 않으므로 절대 풀에서 끌어가지 않아요. 여기에는 models: []나 models: ["*"]를 가진 키, all-proxy-models가 부여된 키, openai/* 같은 와일드카드가 부여된 키가 포함됩니다. 호출하는 모델이 예산 그룹에 속하더라도요. 그런 키는 모델을 계속 호출할 수 있으며, 지출은 그룹 예산 대신 키·사용자·팀·조직 예산에 착륙해요.

그래서 관리자 키나 무제한 키는 그룹 예산에 막히지 않아요. 호출자 세트에 대해 그룹의 상한이 진짜 천장이 되기를 원한다면 와일드카드가 아니라 그 호출자들에게 그룹 자체를 부여하세요.

하나 이상 적용되면 여러 그룹이 전부 청구됩니다. premium과 eval 둘 다 부여받고 둘 다에 속하는 모델을 호출하는 키는 각 풀에서 요청 비용을 별도로 끌어가며, 어느 풀이라도 소진되면 요청이 거부돼요.

더 알아보기 (Learn more)

모델 액세스 그룹

모델 액세스 그룹 예산