D. 서버리스

GPU를 띄우지 않고 LLM만 쓰는 경로. 키 발급 시점에 예산이 선불 차감되고, 호출할 때마다 원장을 건드리지 않는다.

선행 A. 온보딩. 팀에 크레딧이 있어야 한다.

돈이 움직이는 시점

Org Admin 키 발급 ──▶ 팀 크레딧에서 예산만큼 즉시 차감 (serverless_purchase)
사용자 호출        ──▶ 키의 used만 올라간다. 원장 차감 없음
Org Admin 폐기     ──▶ 잔여(예산 − 사용)를 팀 크레딧으로 환원 (serverless_refund)

키 예산은 미리 사둔 지갑이다. 발급하는 순간 팀 잔여에서 빠져나가고, 호출은 그 지갑에서 쓴다. 폐기하면 안 쓴 만큼 돌아온다.

---

S-24 키 발급에서 첫 호출까지

Org Admin → 사용자 · 6분 · 선행 S-06

절차 — Org Admin

1. 서버리스에서 + 키 발급 을 누른다.
2. 팀, 키 이름(alias), 예산(C), 허용 모델, TPM·RPM 한도를 넣는다.
3. 발급한다.

절차 — 사용자 4. 서버리스 화면에 수령 대기 배지가 뜬 것을 본다. 5. 키 수령 을 누른다. 6. 표시된 전체 키를 복사해 안전한 곳에 둔다. 이 화면에서만 보인다. 7. 아래 명령으로 호출한다.

curl $VOLTRA_GATEWAY/v1/chat/completions \
  -H "Authorization: Bearer sk-voltra-…" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"안녕"}]}'

게이트웨이 주소는 배포마다 다르다. 실제 주소는 서버리스 화면의 호출 예시에 채워져 나온다.

기대

• ✅ 발급 즉시 팀 잔여가 예산만큼 줄어든다.
• ✅ 응답 안내에 예산 n C가 팀 크레딧에서 선불 차감되었습니다가 있다.
• ✅ Org Admin에게는 비밀 키가 표시되지 않는다. 목록에도 마스킹만 보인다.
• ✅ 팀에 서버리스 API 키가 준비되었습니다 알림이 간다.
• ✅ 수령 순간 상태가 active가 되고 전체 키가 1회만 표시된다.
• ✅ 호출이 200으로 돌아오고 usage에 토큰 수가 있다.
• ✅ 호출 후 키의 사용/예산 게이지가 올라간다.
• ✅ 팀 잔여는 호출로 변하지 않는다. 이미 발급 때 빠졌다.
• ✅ 감사 로그에 llm_key.issue와 llm_key.claim이 남는다.

키를 잃어버렸다면 다시 볼 방법이 없다. 폐기하고 새로 발급받는다. 폐기 시 잔여 예산은 환원되므로 손해는 없다.

관련 서버리스 키 관리 · 서버리스 LLM

---

S-25 키 예산 증액·감액

Org Admin · 3분 · 선행 S-24

절차

1. 키 행의 수정을 누른다.
2. 예산을 올려 저장한다.
3. 다시 열어 예산을 내려 저장한다.

기대

• ✅ 증액: 차액이 팀 크레딧에서 추가 차감된다(serverless_purchase).
• ✅ 감액: 차액이 팀 크레딧으로 환원된다(serverless_refund).
• ✅ 팀 잔여가 즉시 반영된다.
• ✅ 예산이 오르면 blocked였던 키가 다시 호출 가능해진다.

실패 경로

시도	결과
이미 쓴 금액보다 낮게 감액	budget_below_used. 사용분(n C) 아래로는 감액할 수 없습니다
폐기된 키 수정	already_revoked

환원 상한은 구매액 − 기환원액이다. 이 상한 때문에 감액을 반복해도 넣은 것보다 많이 돌려받을 수 없다. 크레딧이 생성되는 경로를 원천 차단한 것이다.

관련 서버리스 키 관리

---

S-26 키 폐기와 환원

Org Admin · 3분 · 선행 S-24

전제 예산의 일부만 쓴 활성 키가 있다.

절차

1. 키 행의 폐기 를 누른다.
2. 확인한다.
3. 사용자 쪽에서 같은 키로 호출해 본다.

기대

• ✅ 응답에 환원액이 나온다: 잔여 예산 n C가 팀 크레딧으로 환원되었습니다.
• ✅ 환원액 = 예산 − 사용액. 쓴 만큼은 돌아오지 않는다.
• ✅ 팀 잔여가 그만큼 늘어난다.
• ✅ 폐기 즉시 그 키의 호출이 401 invalid_api_key로 거부된다.
• ✅ 감사 로그에 llm_key.revoke가 환원액과 함께 남는다.

즉시 차단되는 이유 게이트웨이는 키 정보를 Redis에 2초만 캐시한다. 폐기 시 그 캐시를 직접 지우므로 다음 호출부터 바로 막힌다.

두 번 폐기하면 already_revoked로 거부된다. 환원이 두 번 일어나지 않는다.

관련 서버리스 키 관리

---

S-27 팀 예산을 넘는 키 발급 시도

Org Admin · 2분 · 선행 S-24

절차 팀 잔여보다 큰 예산으로 키를 발급한다.

기대

• ✅ insufficient_credit으로 거부된다: 팀 크레딧이 부족하여 키 예산(n C)을 구매할 수 없습니다.
• ✅ 키가 활성화되지 않는다.
• ✅ 팀 잔여가 그대로다.

연관 — 팀 예산 감액 제약 이미 발급한 키의 예산 합계 아래로 팀 예산을 내리려 하면 budget_below_key_sum으로 거부된다. 발급된 키가 무효가 되는 상황을 막는다.

같은 이름으로 다시 발급하면 새 키가 생기지 않고 기존 키를 재사용한다. 응답만 유실된 재시도가 이중 차감되지 않게 한 것이다. 다만 예산이 다르면 alias_budget_mismatch로 거부된다. 폐기 후 재발급하거나 수정해야 한다.

관련 서버리스 키 관리 · 팀 생애주기

---

S-28 예산 소진 후 호출

사용자 · 5분 · 선행 S-24

절차

1. 예산이 작은 키(예: 1 C)를 받는다.
2. 예산을 다 쓸 때까지 반복 호출한다.

기대

• ✅ 소진되면 429 budget_exceeded로 거부된다: 키 예산이 소진되어 호출이 거부되었습니다. 조직 어드민에게 예산 증액을 요청하십시오.
• ✅ 키 상태가 blocked가 된다.
• ✅ 잔액이 음수가 되지 않는다.
• ✅ Org Admin이 예산을 올리면 즉시 다시 호출된다.

소진 직전 동작 잔여가 예산의 일정 비율 아래로 내려가면 max_tokens가 256으로 제한된다. 마지막 한 번의 큰 요청이 예산을 넘겨 쓰는 것을 막는다.

동시 호출도 막힌다 호출 전에 Redis에서 예상 최대 비용을 원자적으로 선점한다. 여러 요청이 같은 잔여 값을 보고 동시에 통과하는 상황이 생기지 않는다. 선점이 예산을 넘으면 되돌리고 budget_exceeded로 거부한다.

속도 제한 RPM·TPM을 넘기면 429 rate_limit_exceeded가 온다. 예산과는 별개 게이트다.

관련 서버리스 LLM

---

S-29 폐기된 키로 호출

사용자 · 1분 · 선행 S-26

절차 폐기된 키로 호출한다.

기대

• ✅ 401 invalid_api_key: 폐기되었거나 존재하지 않는 키입니다.
• ✅ 존재하지 않는 키도 같은 응답이다. 어떤 키가 실재하는지 알려주지 않는다.
• ✅ Authorization 헤더가 없거나 Bearer sk-로 시작하지 않으면 같은 401이다.

팀이 잠긴 경우는 다르다 크레딧 소진으로 팀이 잠기면 403 team_locked가 온다: 팀이 잠겨 있습니다 (크레딧 소진). GPU·서버리스 호출이 차단됩니다. 키는 멀쩡하지만 팀이 막힌 상태다(S-31).

관련 서버리스 LLM

---

S-30 접근 없는 모델 호출

사용자 · 1분 · 선행 S-24

키마다 쓸 수 있는 모델이 정해져 있다.

절차

1. GET /v1/models로 이 키가 쓸 수 있는 모델을 확인한다.
2. 목록에 없는 모델로 호출한다.

기대

• ✅ 404 model_not_found: 이 키로 접근할 수 없는 모델입니다: {모델}. 모델 접근 요청이 필요합니다.
• ✅ /v1/models에는 허용된 모델만 나온다.
• ✅ 단가가 등록되지 않은 모델도 model_not_found로 막힌다. 값을 모르는 채 과금하지 않는다.

해결 모델 접근 요청을 보내면 Org Admin이 처리한다. 승인되면 키 설정에 모델이 추가되고 바로 쓸 수 있다.

관련 서버리스 LLM · 요청함

---

게이트 순서

호출 하나가 통과해야 하는 관문이다. 위에서부터 순서대로 검사한다.

#	관문	실패 시
1	키가 실재하고 폐기되지 않았는가	401 invalid_api_key
2	팀이 잠기지 않았는가	403 team_locked
3	키 예산이 남았는가	429 budget_exceeded
4	이 키로 그 모델을 쓸 수 있는가	404 model_not_found
5	RPM·TPM 안인가	429 rate_limit_exceeded
6	잔여로 이 요청의 최대 비용을 감당하는가	429 budget_exceeded
7	예산 원자 선점에 성공했는가	429 budget_exceeded

업스트림 호출이 실패하면 6~7에서 선점한 금액이 되돌아온다. 실패한 호출로 예산이 줄지 않는다.

이 묶음이 끝나면

발급·수령·호출·증감액·폐기·환원과 모든 차단 경로를 본 것이다.

다음: E. 한도와 차단 — 막혀야 할 때 정말 막히는지.