OpenAI Cookbook: Responses API로 실행별 지출 한도 컨트롤러 만들기
리퀘오 운영팀
이 글은 OpenAI Cookbook에 실린 OpenAI의 글을 한국어로 옮긴 것이다. Responses API로 에이전트를 운영하면서 한 작업(run)마다 예산을 두고, 다음 모델 요청을 보낼 여력이 있는지 미리 판단하고 싶은 개발자에게 도움이 된다.
1. 왜 실행별 예산이 필요한가
Responses API를 쓰는 에이전트는 한 작업을 끝내기 위해 모델을 여러 번 호출할 수 있다. 조직·프로젝트 지출 한도는 전체 사용량을 덮을 뿐, 지금 이 작업이 다음 요청을 감당할 수 있는지는 알려주지 않는다. 그래서 실행마다 자체 예산을 두고, 요청 전에 입력 토큰을 세고 응답이 낼 수 있는 최대 비용을 미리 확보한 뒤, 응답이 오면 실제 비용을 기록하고 남은 금액을 예산으로 되돌리는 방식을 쓴다. 요청이 잔액을 넘길 것 같으면 보내기 전에 멈춘다.
예시로 지원 티켓 #4821에 0.02달러 예산을 준다. 첫 응답에 0.01달러가 들고, 다음 응답은 최대 0.0146달러가 들 수 있다. 남은 돈이 0.01달러뿐이므로 애플리케이션은 여기서 멈춘다.
이 컨트롤러는 기본 처리 등급에서 동기·비스트리밍 Responses API 요청을 다룬다. 예산은 모델 토큰 비용만 포함하며 호스팅 도구 등 다른 비용은 제외한다. 글에 나오는 가격, 토큰 수, 모델 이름, 한도는 모두 예시로 만든 값이며 실제 OpenAI 가격이나 모델 한도, 최종 청구서를 보장하지 않는다.
2. 요청 비용 추정하기
예시 가격은 100만 토큰당 달러 기준이다. 일반 입력 4.00, 캐시 입력 2.00, 캐시 쓰기 8.00, 출력 20.00이다. 요청당 입력 10,000토큰, 출력 250토큰으로 한도를 둔다. 이 수치도 실제 모델 한도가 아닌 예시 설정이다. 캐시 쓰기 가격은 선택한 모델이 캐시 쓰기를 별도로 청구할 때만 적용된다.
티켓 #4821은 입력 1,200토큰을 쓴다. 응답 비용을 과소평가하지 않으려면 모든 입력 토큰이 가장 비싼 입력 가격을 쓴다고 가정한다. 여기서는 별도 청구되는 캐시 쓰기가 가장 비싸다.
(1,200 x $8.00 + 250 x $20.00) / 1,000,000 = $0.0146
달러 금액을 정확히 유지하려면 Python 내장 Fraction 타입을 쓴다. 실제 요청 전에 모델, 기본 처리 등급, 토큰 한도, 가격을 확인한다. verified_at 날짜는 가격을 확인한 시점을 기록할 뿐 여전히 유효하다는 뜻은 아니다. 최신 API 가격과 모델 문서를 참고한다.
3. 모델과 가격 정의하기
Python 3.12 이상과 openai>=2.28.0이 필요하다. 모델, 기본 처리 등급, 토큰 가격, 요청 한도를 함께 설정한다. API가 response.model에 그대로 돌려주는 고정 모델 ID를 쓴다. 이 예시는 모델 별칭을 지원하지 않는다. cache_write_usd_per_million은 모델이 캐시 쓰기를 별도 청구하지 않을 때만 None으로 둔다. 예시 가격은 오프라인 클라이언트에서만 동작한다.
RateCard 데이터 클래스는 모델과 처리 등급이 비어 있지 않은 문자열인지, 처리 등급이 default인지, 가격이 양의 정확한 달러 금액인지 검증한다. 예시 전용·미검증 상태를 표시하는 필드도 둔다.
4. 실행 예산 추적하기
RunBudget은 이미 쓴 돈과 임시로 확보한 돈을 추적한다. 잠금(lock)은 같은 Python 프로세스 안에서 두 요청이 같은 자금을 중복 확보하지 못하게 한다. 캐시 쓰기에 별도 가격이 있으면 응답에 캐시 쓰기 토큰 수가 포함되어야 한다.
BudgetExceeded와 UncertainCharge 예외를 두고, RunBudget은 maximum, spent, pending, blocked, 확보 내역, 잠금을 필드로 가진다. ensure_active는 최소 필요 금액을 확인하고, reserve는 금액을 확보한 뒤 핸들을 돌려준다. 예산이 모자라면 BudgetExceeded를 던진다. settle은 확보했던 금액을 풀고 실제 비용을 기록하는데, 실제 비용이 확보액보다 크면 실행을 막고 UncertainCharge를 던진다. actual_cost는 응답의 사용량으로 일반 입력·캐시 입력·캐시 쓰기·출력 비용을 나눠 계산하며, 사용량이 빠졌거나 합계가 맞지 않거나 설정 한도를 넘으면 UncertainCharge를 던진다.
5. 요청 전에 예산 확인하기
토큰을 세는 요청과 응답을 생성하는 요청에는 같은 model과 input을 쓴다. 지침, 도구 스키마, 이미지, 파일, 대화 기록도 입력 토큰을 쓴다. 이런 요소를 더하면 두 요청에 같은 지원 필드를 넘긴다. max_output_tokens, service_tier, store는 응답 요청에만 보낸다.
response_with_budget 함수는 프롬프트가 비어 있지 않은 문자열인지, 예시 허용 값이 불리언인지 확인한다. 가격이 예시 전용이거나 미검증이면 명시적으로 허용하고 오프라인 클라이언트일 때만 통과시킨다. 클라이언트는 max_retries=0으로 초기화해야 한다. 그다음 최대 출력 비용만큼 예산이 남아 있는지 확인하고, 입력 토큰을 세어 설정 한도를 넘으면 BudgetExceeded를 던진다. 입력 가격 중 가장 비싼 값으로 입력 비용을 계산하고, 최대 출력 비용을 더해 예산을 확보한 뒤 요청을 보낸다.
response_with_budget은 response.output_text와 response.output을 포함한 전체 응답을 돌려준다. API가 설정한 모델과 처리 등급을 썼는지도 확인한다. 요청이 중단되거나 비용을 확정할 수 없으면 실행은 영구히 멈추고 확보한 예산은 풀리지 않는다. 불완전한 응답이 사용량을 보고하면 그 비용을 기록하고 실행은 계속 차단한다.
실제 클라이언트를 쓰려면 from openai import OpenAI로 불러오고 최신 가격을 확인한 뒤 OPENAI_API_KEY를 설정한다. 그리고 client = OpenAI(max_retries=0, timeout=60.0)으로 만든다. 클라이언트가 타임아웃돼도 요청이 계속 실행될 수 있으므로 확보한 예산은 그대로 둔다.
6. 예시: 지원 티켓에 예산 두기
티켓 #4821의 첫 응답은 입력 1,200토큰을 보고한다. 캐시 400, 별도 청구 캐시 쓰기 500, 나머지 300은 일반 입력이다. 출력은 200토큰이다.
(300 x $4.00 + 400 x $2.00 + 500 x $8.00 + 200 x $20.00) / 1,000,000 = $0.0100
첫 응답에 0.01달러가 들어 0.01달러가 남는다. 다음 응답은 0.0146달러가 들 수 있으므로 컨트롤러는 다음 모델 요청을 보내기 전에 멈춘다.
전체 코드는 원문에 있다. 원문의 코드 블록 세 개와 오프라인 예시를 순서대로 controller.py로 저장하고, SDK를 설치한 뒤 실행한다.
python -m pip install "openai>=2.28.0"
python controller.py
티켓과 주문은 가상이며 오프라인 클라이언트는 네트워크 요청을 보내지 않는다. OfflineClient는 model_calls를 세고, count는 입력 1,200토큰을 돌려주며, create는 모델 호출 수를 늘리고 완료된 응답과 사용량 세부 정보를 돌려준다. 메인 블록은 0.02달러 예산으로 첫 응답을 받아 출력하고, 두 번째 응답을 시도하다 BudgetExceeded를 잡아 중단 메시지를 출력한다.
실행하면 다음 내용이 차례로 출력된다.
- 첫 응답 문장: 주문 ORD-42가 발송되어 금요일에 도착할 예정이라는 안내
- 티켓 #4821이 다음 단계에서 예산을 넘기게 되어 멈췄다는 메시지
- 지출(Spent) $0.01, 확보 중(Reserved) $0
- 모델 호출 수(Model calls) 1회
7. 한도와 기타 비용
일반 입력, 캐시 입력, 별도 청구 캐시 쓰기, 출력은 각각 한 번만 센다. 모델이 캐시 쓰기를 별도 청구하지 않으면 캐시되지 않은 입력을 일반 요금으로 계산한다. 예상치 못한 양의 캐시 쓰기 수치는 실행을 멈춘다. 모델의 프롬프트 캐싱 안내를 확인한다. 추론 토큰은 이미 출력 합계에 포함되어 있다.
잠금은 Python 프로세스 하나만 보호한다. 여러 워커가 예산을 공유하면 확인과 확보를 한 번의 연산으로 처리하는 공유 저장소를 써서 같은 돈을 중복 확보하지 못하게 한다. 요청의 최종 비용을 알 수 없으면 그 실행을 포기하고 확보한 예산은 그대로 둔다. 재시도를 켜기 전에 Python SDK의 재시도 동작을 검토한다.
호스팅 도구는 별도 비용을 더할 수 있다. 예를 들어 웹 검색은 호출마다, 그리고 관련 모델 토큰에 대해 비용을 청구할 수 있다. 예산은 저장, 기본이 아닌 처리 등급, 지역별 가격, 장문 컨텍스트 요금, 스트리밍, 백그라운드 요청, 서버 관리형 에이전트 실행, 계정별 비용도 제외한다. 백그라운드 요청은 처음에 queued나 in_progress를 돌려줄 수 있어 최종 사용량 추적에 별도 규칙이 필요하다. store=False로 설정해도 데이터 무보존(Zero Data Retention)이 보장되지는 않으니 데이터 제어 문서를 확인한다.
프로젝트 지출 한도는 프로젝트 전체 지출을 덮으며 즉시 적용되지 않을 수 있다. 알림은 요청을 멈추지 않는다. Costs API 참조는 일별 합계를 보여줄 뿐, 한 작업이 다음 요청을 감당할 수 있는지는 알려주지 않는다.
여러분은 에이전트 실행 예산을 어떤 방식으로 관리하고 계신가요? 경험을 댓글로 나눠 주세요.
---
출처: OpenAI Cookbook 「Responses API로 실행별 지출 컨트롤러 구축하기」 (OpenAI)
https://developers.openai.com/cookbook/articles/per_run_spending_controller_responses_api
저작권 고지(라이선스가 요구하는 원문 표기): Copyright (c) 2025 OpenAI · MIT 라이선스 https://github.com/openai/openai-cookbook/blob/main/LICENSE
변경 사항: 리퀘오 운영팀이 2026-11-11에 한국어로 번역하고 일부 축약·재구성했습니다. 원문 작성자가 이 번역을 보증하지 않습니다.
도움돼요 0 로그인하면 누를 수 있습니다. 로그인하면 저장하고 새 답글 알림을 받을 수 있습니다.