OpenAI API 배포 체크리스트: Responses API는 시작점이고 eval·rate limit·background부터 잠가야 한다

OpenAI API 데모가 한 번 잘 답했다고 배포 준비가 끝난 것은 아니다. 실제 서비스에서는 모델이 답을 냈는지보다 먼저 봐야 할 것이 있다. 실패한 요청을 어떻게 다시 보낼지, 긴 작업을 어디서 기다릴지, 완료 알림을 믿어도 되는지, 민감한 데이터에서 background mode를 켜도 되는지부터 갈린다.

2026-04-28 기준 OpenAI 공식 문서로 보면 결론은 단순하다. 새 OpenAI API 앱은 Responses API를 기본 출발점으로 두고, 배포 전에 eval, rate limit backoff, long-running task policy, webhook signature, ZDR 경계, tool-loop transport를 따로 잠가야 한다. 데모 프롬프트 3개가 통과한 상태는 launch gate가 아니다.

핵심만 먼저 적으면 이렇다.

• 새 구현은 먼저 Responses API 기준으로 잡는다. OpenAI 문서는 최신 모델 동작, built-in tools, stateful workflow, agent feature의 시작점으로 Responses API를 둔다.
• reasoning.effort와 text.verbosity는 모델을 고른 뒤 남는 운영 레버다. 분류와 라우팅에는 낮게, 진단과 코드 추론에는 높게 잡는다.
• 배포 전에는 eval dataset과 rate limit backoff가 있어야 한다. 실패 요청도 limit에 잡히므로 무한 재시도는 답이 아니다.
• 긴 작업은 background=True와 polling/webhook을 검토한다. 다만 background mode는 response data를 대략 10분 저장하므로 ZDR 요구와 맞지 않는다.
• tool call이 길게 이어지는 agent loop라면 WebSocket을 검토한다. 한 번 묻고 한 번 답하는 흐름이면 HTTP가 더 단순하다.

Responses API는 시작점이다

OpenAI의 deployment checklist는 첫 항목으로 Responses API를 둔다. 이유는 기능 이름보다 운영 면에서 크다. Responses API는 최신 모델 동작, built-in tools, stateful workflow, agent feature가 붙는 중심축이다. 새 앱을 Chat Completions식 단발 호출로만 설계하면 나중에 background, tool loop, response state, built-in tool을 붙일 때 구조를 다시 고치게 된다.

이 말이 모든 기존 코드를 당장 갈아엎으라는 뜻은 아니다. 이미 안정적으로 운영 중인 단순 completion workflow라면 migration 비용을 따져야 한다. 다만 새 제품이나 큰 개편이라면 배포 체크리스트를 Responses API 기준으로 쓰는 편이 낫다. 그래야 이후 항목인 reasoning.effort, prompt_cache_key, background, WebSocket을 같은 request/response 모델 안에서 판단할 수 있다.

reasoning과 verbosity는 모델 선택 뒤에 남는 손잡이다

모델 이름을 정해도 배포 설정은 끝나지 않는다. OpenAI 문서는 reasoning.effort로 모델이 답하기 전에 얼마나 생각할지 정하라고 설명한다. 오늘 문서 기준 gpt-5.5는 none, low, medium, high, xhigh를 지원하고 기본값은 medium이다. 낮은 effort는 extraction, routing, classification, simple rewrite에 맞고, medium/high는 diagnosis, option comparison, planning, code reasoning에 더 맞다. xhigh는 eval에서 추가 지연을 감수할 이유가 확인된 경우로 남기는 편이 안전하다.

text.verbosity도 비슷하다. 제품 화면에서 한 줄 답만 필요한데 매번 긴 설명을 만들면 비용과 지연이 늘어난다. 반대로 코드 원인 분석이나 장애 보고서처럼 근거가 남아야 하는 작업에서 너무 낮게 잡으면 사람이 다시 묻게 된다.

배포 전에는 최소한 업무 유형별 기본값을 나눠야 한다.

workload	먼저 볼 설정	이유
티켓 분류	low reasoning, low verbosity	빠르게 라우팅하고 출력 길이를 줄인다
장애 원인 분석	high reasoning, medium/high verbosity	여러 로그와 원인을 비교해야 한다
코드 수정 계획	medium/high reasoning	작은 수정과 부작용을 같이 봐야 한다
고객-facing 짧은 답변	low/medium verbosity	화면에서 바로 읽히는 길이가 중요하다

여기서 중요한 점은 가장 높은 설정이 기본값이 아니라는 것이다. 높은 effort와 긴 답변은 필요한 곳에만 써야 한다.

eval과 rate limit 없이 데모를 믿으면 안 된다

OpenAI evals 문서는 모델 출력이 정한 style과 content criteria를 만족하는지 테스트하는 절차를 reliable application의 핵심으로 둔다. 데모 prompt 몇 개가 통과한 것과, 대표 dataset에서 통과한 것은 다르다. 특히 모델을 바꾸거나 prompt를 바꿀 때는 이전에 맞던 edge case가 다시 깨질 수 있다.

Rate limit도 같은 층위의 문제다. OpenAI rate limit 문서는 random exponential backoff를 권장하면서도, 실패한 요청이 per-minute limit에 잡힌다고 말한다. 계속 같은 요청을 빠르게 다시 보내면 복구가 아니라 더 큰 실패가 된다.

그래서 배포 전 gate는 이렇게 잡는 편이 현실적이다.

1. 대표 입력 20개라도 먼저 모은다.
2. 정답이 명확한 작업은 string check나 rubric을 둔다.
3. 실패한 요청은 random exponential backoff로 재시도한다.
4. 사용자별 일/주/月 cap이나 manual review 조건을 둔다.
5. model/prompt 변경 전후 eval 결과를 남긴다.

이 항목이 비어 있으면 아직 데모다. 트래픽을 받기 시작하면 같은 문제가 더 비싸게 드러난다.

background는 긴 작업용이지만 ZDR과 충돌한다

긴 reasoning 작업은 HTTP request 하나가 끝날 때까지 붙잡고 있으면 timeout과 연결 끊김에 취약하다. OpenAI background mode 문서는 background=True로 response generation을 비동기로 시작하고, response object를 poll하면서 상태를 확인할 수 있다고 설명한다. 장애 로그 분석, 긴 보고서 생성, code/log inspection처럼 몇 분 걸릴 수 있는 작업에는 이 구조가 더 맞다.

단, background mode는 저장 경계를 바꾼다. 공식 문서는 polling을 위해 response data를 대략 10분 저장하므로 ZDR과 호환되지 않는다고 설명한다. 민감 문서 요약이나 저장 금지 요구가 있는 workflow라면 background를 편의 기능처럼 켜면 안 된다.

간단한 분기점은 이렇다.

조건	선택
몇 분 걸리고 ZDR 요구가 없다	background + polling 또는 webhook
몇 분 걸리지만 저장 금지 요구가 있다	background를 피하고 stateless HTTP와 encrypted reasoning 경계 검토
한 번 묻고 빠르게 답한다	일반 HTTP
완료 알림 뒤 backend action이 있다	webhook signature verification 필수

webhook은 완료 알림보다 검증이 먼저다

OpenAI webhooks 문서는 background response, batch completion, fine-tuning job 같은 event를 HTTP endpoint로 받을 수 있다고 설명한다. 완료 알림을 받으면 polling을 줄일 수 있고, long-running job UI도 깔끔해진다.

하지만 webhook을 backend action의 trigger로 쓴다면 먼저 signature verification을 해야 한다. 공식 문서는 OpenAI에서 온 요청인지 확인하라고 말한다. 예를 들어 background response가 끝났다는 event를 받고 DB row를 업데이트하거나 고객에게 알림을 보내는 구조라면, OPENAI_WEBHOOK_SECRET 같은 signing secret을 서버 환경 변수로 두고 SDK helper나 Standard Webhooks library로 검증해야 한다.

Webhook을 단순 로그로만 보면 optional처럼 보인다. 운영에서는 다르다. 알림이 곧 상태 변경이면, 서명 검증 실패는 상태 변경 실패로 처리해야 한다.

WebSocket은 긴 tool loop에서만 검토한다

OpenAI deployment checklist는 WebSocket mode를 long-running, tool-call-heavy workflow용으로 설명한다. 같은 socket을 유지한 채 previous_response_id와 새 input item만 보내면, 일반 HTTP처럼 매번 새 request를 여는 것보다 tool loop에서 setup 비용을 줄일 수 있다. 문서는 tool call이 20개 이상인 rollout에서 end-to-end가 roughly 40% faster라고 적는다.

그래도 WebSocket이 기본값은 아니다. 공식 문서도 one request, one answer 흐름이면 HTTP를 유지하라고 한다. 한 socket은 한 번에 하나의 in-flight response를 다루므로 병렬 작업은 여러 connection이 필요하고, connection 시간 제한도 고려해야 한다.

실무 기준은 짧다.

• tool call이 거의 없으면 HTTP가 낫다.
• tool call이 길게 이어지면 WebSocket 후보가 된다.
• 병렬 작업이 많으면 connection 수와 failure recovery를 먼저 설계한다.
• WebSocket을 쓰더라도 eval, rate limit backoff, tool failure log는 사라지지 않는다.

로컬 deployment gate 결과

이번 run에서는 OpenAI API를 실제 호출하지 않았다. 대신 공식 문서의 배포 항목을 deterministic gate로 바꿔 배포 후보 5개를 통과시켰다. 기준은 Responses API 사용 여부, eval dataset, reasoning/verbosity 설정, prompt cache key, background polling, webhook signature, rate limit backoff, ZDR 요구, encrypted reasoning, WebSocket, tool search 또는 deferred loading이다.

case	score	gate	recommendation
support-ticket-triage	100	pass	http_eval_cache_rate_gate
incident-rca-report	100	pass	background_polling_webhook_gate
tool-heavy-admin-agent	100	pass	websocket_tool_loop_gate
regulated-contract-summary	100	pass	stateless_encrypted_reasoning_gate
launch-demo-chatbot	38	blocked	block_until_launch_gate_is_fixed

막힌 후보가 흥미롭다. launch-demo-chatbot은 데모 prompt만 통과한 상태였고, Responses API migration, eval dataset, rate limit backoff가 빠져 있었다. 그래서 모델 답변 품질을 재기 전에 launch gate에서 막혔다.

반대로 통과한 후보들은 모두 같은 길을 택하지 않았다. 짧은 티켓 분류는 HTTP + eval + cache + backoff로 충분했다. 긴 RCA 보고서는 background와 webhook이 맞았다. tool call이 28개인 관리자 agent는 WebSocket 후보였다. 저장 경계가 민감한 계약서 요약은 background를 피하고 stateless encrypted reasoning 쪽으로 갔다.

배포 전 10줄 체크리스트

OpenAI API 앱을 배포하기 전에 아래 질문을 먼저 본다.

1. 새 구현을 Responses API 기준으로 잡았는가.
2. 업무 유형별 reasoning.effort 기본값이 있는가.
3. 출력 길이를 text.verbosity로 나눴는가.
4. 대표 입력 dataset과 eval 기준이 있는가.
5. rate limit error에 random exponential backoff와 retry cap이 있는가.
6. 사용자별 usage cap이나 manual review 조건이 있는가.
7. 같은 긴 prefix가 반복되면 prompt_cache_key를 안정적으로 쓰는가.
8. 긴 작업은 background polling이나 webhook으로 상태를 추적하는가.
9. webhook이 backend action을 일으키면 signature verification을 통과해야 하는가.
10. ZDR 요구가 있으면 background mode를 끄고 저장 경계를 다시 확인했는가.

이 중 4번과 5번이 없으면 배포가 아니라 공개 데모에 가깝다. 답변이 한 번 좋았다는 사실보다, 실패했을 때 어떻게 멈추고 다시 시도하는지가 먼저다.

같이 보면 좋은 글

• OpenAI Responses API로 가야 하는 이유와 Assistants API 종료 일정
• OpenAI·Anthropic·LangSmith 문서를 같이 보면: AI 에이전트 eval은 왜 기능 데모보다 먼저 있어야 하나
• OpenAI Computer Use와 Playwright CLI 브라우저 자동화 비교: 화면 판단은 모델, 로그인·첨부·검증은 selector 하네스가 맡는다
• OpenAI Realtime API 연결 기준: 브라우저 음성은 WebRTC, 서버 로직은 WebSocket·sideband로 나눠야 한다

참고 자료

• OpenAI API deployment checklist
• OpenAI Background mode
• OpenAI Webhooks
• OpenAI Working with evals
• OpenAI Rate limits
• OpenAI Latency optimization

실행 로그 첨부

민감정보를 제거한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

• wn114-openai-api-deployment-gate-public.json
• wn114-openai-api-deployment-gate-summary-public.md
• wn114-openai-api-deployment-gate-public.py

wn114-openai-api-deployment-gate-public.json

0.01MB

wn114-openai-api-deployment-gate-summary-public.md

0.00MB

wn114-openai-api-deployment-gate-public.py

0.01MB