OpenAI Decisions API 사용 가이드: 개발자를 위한 실용적인 안내서

만약 당신의 앱이 대규모 언어 모델(LLM)에게 예/아니오 질문을 한다면, 아마 이런 경험을 해봤을 겁니다. 깔끔한 라벨링 결과를 요청했는데, 모델은 단락으로 답하고, 결국 코드베이스 어딘가에서 정규 표현식(regex)이 "I believe this does constitute a refund request."라는 문구에서 "refund"라는 단어를 끄집어내려고 시도하는 식입니다. 월요일에는 작동합니다. 금요일쯤 되면 모델은 수다쟁이가 되어, 정규 표현식은 놓치고, 지원 티켓은 잘못된 대기열로 가게 됩니다.

10월 6일, OpenAI는 개발자들에게 다른 형태의 답변을 제공하는 공개 베타를 선보였습니다. 바로 Decisions API입니다. 이는 새로운 엔드포인트인 POST /v1/decisions이며, 산문(prose) 대신 타입이 지정된 판결(typed verdicts)을 반환합니다. 파싱할 단락도 없고, 억지로 유도할 JSON 모드도 없습니다. 오직 확률, 선택지, 또는 점수만 있습니다. 이것은 실용적인 가이드입니다: 이 엔드포인트가 무엇을 하는지, 비용은 얼마인지, 어디에 진정으로 도움이 되는지, 그리고 조용히 당신에게 남겨두는 보정(calibration) 작업이 무엇인지를 다룹니다.

Decisions API란 실제로 무엇인가

그 아이디어는 의도적으로 좁습니다. 증거(입력)와 하나 이상의 질문을 보내면, API가 각 질문에 대해 고정된 형태의 답변을 합니다. 세 가지 질문 유형이 존재합니다:

• Predicate — 예/아니오 조건으로, 0과 1 사이의 확률로 답변됩니다. "이 사진은 눈에 보이는 제품 손상을 보여주는가?"

• Choice — 당신이 정의한 고정된 후보 답변 세트로, 승리하는 선택지, 옵션별 확률, 그리고 신뢰도 값으로 답변됩니다. "어떤 부서가 이 티켓을 소유하고 있는가?"

• Score — 당신이 정의한 순서화된 루브릭(rubric)으로, 레벨 전반에 걸친 확률 가중 평균과 신뢰도로 답변됩니다. "이 사건은 얼마나 심각한가?"

거절(refusal)은 별도의 답변 유형입니다. 낮은 점수나 당신의 폴백 카테고리가 아닙니다. 10월 중순 기준으로 이 API는 공개 베타이며, gpt-6-luna가 유일하게 지원되는 모델이고, OpenAI는 일반 사용 가능 시점(general availability)이 "몇 주 안에"라고 예상한다고 밝히고 있습니다. 이것은 기대치이지 날짜가 아닙니다.

5분 만에 경험하는 첫 번째 결정

API의 형태를 가장 빠르게 체감할 수 있는 방법은 지원 라우팅 호출입니다. curl을 사용하여 다음과 같이 할 수 있습니다:

Python에서는 호출이 OpenAI가 발표한 가이드와 동일합니다 (SDK 표면은 여전히 베타이며 변경될 수 있습니다):

from openai import OpenAI

client = OpenAI()
...

응답에는 질문에 부여한 이름 아래 각 답변이 담기므로, 단일 요청으로 같은 입력(예: 큐와 심각도)에 대해 여러 독립적인 질문을 할 수 있으며, 분석해야 할 문단 대신 깔끔한 목록을 받게 됩니다.

값을 읽기 전에 거부 처리하기

대부분의 튜토리얼이 건너뛰는 부분이자 프로덕션에서 문제가 되는 부분이 바로 모델이 질문을 거부할 수 있다는 점입니다. 거부는 자체 답변 유형으로 도착하며, 확률(probability), 선택(choice) 또는 점수(score)를 다루기 전에 코드가 이를 분기 처리해야 합니다. 작은 라우팅 헬퍼가 정책을 명시적으로 만듭니다:

REVIEW = "manual_review"

...