Google Gemini Decisions API (gemini-decision-1) 아키텍처 해부: 출력 토큰 0개·단일 패스 병렬 채점과 noul·choice·score 설계 경계
2026년 11월 Google이 공개한 Gemini Decisions API(gemini-decision-1)의 단일 프리필 패스(Single Forward Pass) 아키텍처를 분석한다. 262,144 토큰 공유 멀티모달 컨텍스트 위에서 최대 1,000개 독립 질문을 출력 토큰 0개로 동시 평가하는 메커니즘, noul·choice·score 3대 질문 프리미티브의 확률 보정 및 UTF-8 키 정렬·이봉 분포 함정, Interactions API와의 역할 분리 및 로컬 Python 6대 검증을 정리한다.
Google Gemini Decisions API(gemini-decision-1)의 단일 멀티모달 컨텍스트 프리필과 병렬 보정 확률 분기를 상징하는 추상 그래픽 아트워크
AI 애플리케이션이 프로덕션 규모로 커질수록 LLM에게 '긴 문장'을 요구하지 않는 워크로드 비중이 빠르게 커진다. 고객 문의를 어느 담당 큐로 보낼지 라우팅하거나, 에이전트가 호출할 도구를 고르거나, 업로드된 PDF 영수증·사진·통화 녹음이 수십 개의 컴플라이언스 규정을 위반하지 않는지 동시에 검사하는 작업이 대표적이다. 지금까지 개발팀은 이런 닫힌 집합(Closed-Set) 판정 문제를 풀기 위해 일반 생성형 모델에 Structured Outputs(JSON 스키마)를 강제하고 응답 텍스트를 토큰 단위로 디코딩한 뒤 다시 파싱해야 했다. 그러나 이 구조는 질문이 늘어날수록 공유 컨텍스트를 반복 프리필(Prefill)하거나 긴 JSON 출력 토큰 비용과 지연 시간을 그대로 떠안아야 하는 비효율을 낳았다.
Google이 2026년 11월 11일 공개한 Gemini Decisions API와 전용 모델 gemini-decision-1(Google AI Studio 공식 문서)은 이 문제를 모델 아키텍처와 API 계약 수준에서 분리해 해결한다. Decisions API는 텍스트를 한 글자도 생성하지 않는다(total_output_tokens = 0). 대신 텍스트·JSON·이미지·오디오·비디오·PDF로 구성된 최대 262,144 토큰의 공유 입력을 단 한 번의 전방향 패스(Single Forward Pass)로 처리하면서 최대 1,000개의 독립 질문을 병렬 채점해 보정된 확률(Calibrated Probabilities)과 신뢰도(confidence)를 직접 반환한다.
핵심 판단 기준을 먼저 요약하면, Gemini Decisions API 도입 전 엔지니어가 점검해야 할 설계 경계는 세 가지다. 첫째, gemini-decision-1은 생성·요약·JSON 값 추출·인자 포함 Tool Call용 모델이 아니므로 자유 텍스트나 다단계 추론은 기존 Interactions API(generateContent)에 남기고, 사전 라우팅·정책 필터·루브릭 채점 계층만 분리 배치해야 한다. 둘째, 질문 간에는 서로의 답을 참조할 수 없는 완전 병렬 격리 구조이므로 복합 판단은 단일 장문 프롬프트 대신 원자적 noul·choice·score 질문으로 쪼개고 애플리케이션 코드에서 if·임계값으로 조합해야 하며, choice의 UTF-8 바이트 정렬과 noul의 [0.01, 0.99] 클램핑 규칙을 정확히 지켜야 한다. 셋째, 현재 v1beta 전용이며 Context Caching, Batch API, gs:// 직접 경로, YouTube URL, 대화 히스토리(thought/tool_call 블록)를 지원하지 않으므로 반복 입력 캐싱이나 대용량 비동기 배치 파이프라인과는 적용 범위를 명확히 구분해야 한다. 이 글은 2026년 11월 18일 기준 Google 공식 블로그와 Google AI Studio Decisions API 명세를 교차 검증해 정리했으며, 로컬 Python 6대 불변식 검증 스크립트로 요청·확률·비용 경계를 검증했다.
1. 왜 생성형 LLM으로 '판정'을 하면 병목이 생기는가
기존 생성형 LLM 기반 분류·가드레일 파이프라인은 코드 제어 흐름(Control Flow)에 AI 판단을 끼워 넣을 때 세 가지 구조적 마찰을 일으킨다.
- 자기회귀 디코딩(Autoregressive Decoding) 지연과 출력 토큰 비용:
- 단순한
Yes/No나 4지선다 라우팅을 받기 위해서도 모델이 JSON 키와 괄호, 문자열 값을 한 토큰씩 순차 생성해야 한다. 수십~수백 개 정책 규칙을 한 번에 점검하려면 출력 길이가 길어져 꼬리 지연(Tail Latency)이 급증하고, 입력보다 단가가 높은 출력 토큰 비용이 누적된다.
- 공유 컨텍스트 반복 처리 또는 질문 간 간섭(Cross-Question Interference):
- 10,000 토큰짜리 PDF 문서를 100개 규정으로 검증할 때 질문을 100번 호출로 쪼개면 컨텍스트를 100배 중복 프리필하게 된다. 반대로 100개 질문을 한 프롬프트에 묶어 JSON 배열로 출력하게 하면 앞선 질문의 답변이 뒤쪽 질문의 자기회귀 컨텍스트에 영향을 주어 판정 편향이 발생한다.
- 미보정 확률(Uncalibrated Confidence)과 취성 높은 임계값 분기:
- 생성형 모델이 내뱉는
"confidence": 0.9텍스트는 실제 정답률과 일치하지 않는 자기보고 수치인 경우가 많다. 실무에서 '확신도가 0.85 이상이면 자동 처리하고 그 미만이면 사람 검수로 에스컬레이션'하는 안전한 분기 로직을 짜기 어렵다.
2. 생성형 Structured Outputs vs Gemini Decisions API 핵심 경계 비교
애플리케이션 아키텍처에서 기존 Interactions API(generateContent + Structured Outputs)와 gemini-decision-1(Decisions API)을 어떤 기준으로 분리해야 하는지 네 가지 핵심 경계로 정리하면 다음과 같다.
- 텍스트 디코딩 vs 단일 패스 확률 산출: Interactions API는 자연어 설명·요약·구조화 데이터 추출처럼 새로운 토큰을 생성해야 하는 작업에 적합하다. 반면 Decisions API는 이미 코드에 분기 경로와 선택지가 고정되어 있을 때 출력 토큰 0개로 확률 분포만 뽑아내는 결정 엔진이다.
- 질문 간 직렬 문맥 공유 vs 완전 격리 병렬 평가: Decisions API는 한 요청 안의 최대 1,000개 질문을 서로 격리해 채점한다. 모델은 각 질문의
key(예:is_damaged)도 보지 못하므로 반드시instructions필드에 완전한 질문 문장을 적어야 하며, 특정 질문을 추가·삭제해도 다른 질문의 확률은 변하지 않는다.
- 단발 대량 규칙 검사 vs 캐싱·배치 파이프라인: Decisions API는 공유 입력 토큰을 요청당 1회만 과금하고 유료 티어 기준 모달리티(텍스트·이미지·오디오·비디오·PDF) 구분 없이 100만 입력 토큰당 $0.10(무료 티어 무료, 출력 토큰 $0)의 단순한 과금 구조를 갖는다. 단, Context Caching과 Batch API는 미지원이므로 동일 초거대 문서를 매 초 반복 조회하는 워크로드는 컨텍스트 캐싱 지원 모델과 비용을 비교해야 한다.
- 미디어 전달 및 대화 상태 제약: Decisions API는 Files API URI, 공개/서명된 HTTPS URL(최대 15MB), 인라인 Base64(요청당 최대 100MB, PDF 50MB)를 지원하지만
gs://Cloud Storage 직접 URI와 YouTube URL은 차단한다. 또한 멀티턴thought·tool_call·tool_result블록을 받지 않으므로 이전 대화 맥락은 단일 텍스트 블록으로 직렬화해 넘겨야 한다.
| 비교 항목 | 기존 LLM (Interactions API / Structured Outputs) | Gemini Decisions API ( gemini-decision-1) |
| 연산 및 출력 방식 | 자기회귀(Autoregressive) 토큰 순차 디코딩 | 단일 프리필 패스(Single Forward Pass) · 출력 토큰 0개 |
| 공유 입력 및 질문 한도 | 모델별 컨텍스트 한도 내 프롬프트 구성 (출력 길이 제약 존재) | 최대 262,144 토큰 공유 입력 + 최대 1,000개 독립 질문 동시 평가 |
| 응답 스키마 및 확률 보정 | 사용자 정의 JSON 스키마 추출 (텍스트 기반 자기보고 점수) | noul · choice · score 3종 타입 + 보정 확률 및 confidence |
| 질문 간 상호 의존성 | 같은 응답 내 앞선 필드가 뒤 필드 생성에 영향 가능 | 질문 간 완전 격리 (추가·제거 시 타 질문 결과 불변) |
| 지연 시간 및 과금 기준 | 출력 토큰 수에 비례해 지연 증가 · 입력+출력 동시 과금 | 모델 연산 50~100ms / E2E 150~250ms · 입력 $0.10/1M · 출력 $0 |
| 지원 멀티모달 및 미디어 | 텍스트·이미지·오디오·비디오·PDF (YouTube/ gs:// 등 폭넓은 연동) | 텍스트·이미지·오디오·비디오·PDF (단, Files API / HTTPS / Base64만 허용) |
| 미지원 및 제외 기능 | 범용 기능 지원 (단, 고정 선택지 대량 확률화에는 비효율) | Context Caching · Batch API · gs:// · YouTube · Function Calling · 자유 텍스트 생성 미지원 |
3. Gemini Decisions API 아키텍처와 3대 프리미티브 심층 분석
Google Gemini Decisions API(gemini-decision-1) 단일 패스 아키텍처: 공유 멀티모달 입력, 병렬 격리 평가, noul·choice·score 3대 질문 프리미티브 및 코드 레벨 제어 흐름 경계
3.1 noul · choice · score 3대 질문 프리미티브와 응답 구조
google-genai Python SDK v3.2 이상(http_options={"api_version": "v1beta"}) 또는 REST 엔드포인트(POST /v1beta/decisions)는 모든 의사결정을 세 가지 타입으로 정규화한다.
- Yes/No 판정 (
noul): - 명제가 참일 확률
noul을0.01에서0.99사이로 클램핑해 반환하며,confidence = max(noul, 1 - noul)을 함께 제공한다. 선택적으로criteria에true_description과false_description을 지정해 경계 사례(예: 단순 변심 반품 vs 제품 결함 반품)를 명확히 가를 수 있다. - 확률 상한이
0.99이므로 애플리케이션 코드에서if answer.noul > 0.99:처럼 검사하면 영원히 참이 되지 않는 데드 코드가 생긴다. 임계값은 반드시[0.01, 0.99]내부에 설정해야 한다.
- 단일 선택 (
choice): - 2개에서 255개의 고정 후보 중 최적 선택지 1개와 전체 후보의 정규화 확률 분포(합계
1.0), 그리고 1등 선택지 확률과 동일한confidence를 반환한다. choice질문은 어떤 입력이 들어와도 후보 전체에 확률 합1.0을 강제 배분하므로, 후보 중 아무것도 해당하지 않는 입력에서도 특정 후보가 높은 확률을 가질 수 있다. 따라서 별도noul범위 게이트(Scope Check)와 조합하거나"other"같은 포괄 옵션을 두는 설계가 필수적이다.
- 순서형 루브릭 채점 (
score): - 가장 낮은 수준부터 높은 수준까지 정렬된 2~255개(실무 권장 2~10단계) 비어 있지 않은 문자열 배열을
criteria로 받아 0번 인덱스부터 채점한다. - 반환되는
score값은 각 단계 확률에 인덱스 번호를 곱한 기대값(Σ i · P(i))이므로1.12같은 연속 실수로 나온다. 이산 등급이 필요할 때는probabilities에서 최대 확률 키를 고르고legend로 원문을 조회하면 된다.
3.2 실무에서 가장 자주 밟는 3가지 설계 함정 (UTF-8 정렬 · 이봉 분포 · 블록 구분자)
공식 문서의 제약 사항을 자세히 들여다보면, 일반 프롬프트 엔지니어링 감각으로 접근했을 때 프로덕션 버그로 직결되는 세 가지 미묘한 동작이 숨어 있다.
- 함정 1 —
choice옵션 키의 UTF-8 바이트 알파벳순 자동 정렬: Decisions API는 평가 직전criteria딕셔너리의 옵션 키를 UTF-8 바이트 오름차순으로 정렬하며, 완전 동률일 때는 알파벳순으로 앞선 키를 선택한다. 만약 "해당 없음" 옵션을"none_of_the_above"로 지어 맨 뒤에 넣었다고 생각해도, 실제 평가 순서에서는"shipping"이나"technical"보다 앞에 배치된다. 예외 처리용 기본 옵션은"other"처럼 위치 의존성이 없는 키와 명시적 설명을 써야 한다.
- 함정 2 —
score기대값의 이봉 분포(Bimodal Distribution) 착시와 비선형 척도: 3단계 루브릭(0, 1, 2)에서 1단계 확률이 100%일 때와 0단계 50% · 2단계 50%로 모델이 극단적 혼란을 겪을 때 모두 기대score는 정확히1.0이 된다. 그러나 전자는confidence = 1.0이고 후자는confidence = 0.50이다. 또한 배열 인덱스0, 1, 2...를 그대로 가중 평균하므로 1·10·100·1000 같은 지수적 간격을 의도한 루브릭은 기대 점수가 왜곡된다.
- 함정 3 — 인접 텍스트 블록 무구분 결합 및 Key 비가시성:
input배열에 여러text블록을 넘기면 API는 사이에 공백이나 줄바꿈을 자동으로 넣지 않고 그대로 이어 붙인다. JSON 직렬화 블록 사이는 반드시 명시적인"\n"을 포함해야 하며, 모델은questions맵의 키 이름(1~64자 ASCII[A-Za-z0-9_-]+)을 전혀 보지 못하므로instructions만 읽고도 질문 의도가 완결되도록 작성해야 한다.
3.3 코드 레벨 합성 패턴과 안전 필터(HTTP 400) 처리
Decisions API는 모델 내부에서 복잡한 연쇄 추론을 돌리는 대신, 개발자가 원자적 질문들을 병렬로 던지고 반환된 확률을 일반 코드로 조합하는 패턴을 권장한다. 예를 들어 고객 지원 티켓 하나에 대해 is_defect(noul), next_action(choice), churn_risk(score) 세 질문을 1회 호출로 동시 채점한 뒤, if a["is_defect"].noul > 0.9 and a["next_action"].confidence > 0.6: 조건으로 자동 실행과 상담원 에스컬레이션을 결정론적으로 분기한다. 한편 입력이 안전 정책에 걸리면 answers 대신 HTTP 400 Bad Request와 함께 error.code(safety, prohibited_content, blocklist, image_safety, content_blocked)를 반환하므로, 라우팅 레이어에서는 400 안전 차단 예외를 별도 감사 로그 및 기본 격리 큐로 넘기는 방어 코드가 필요하다.
3.4 멀티모달 처리와 의도적 제외 영역
이미지·비디오 블록은 resolution(이미지는 low·medium·high·ultra_high, 비디오는 low·medium·high) 옵션으로 시각 정밀도와 입력 토큰 비용을 조율할 수 있다. 오디오 입력은 별도 STT(음성-텍스트 변환) 전처리 없이 발화 내용과 말투·속도·머뭇거림을 직접 평가하며, PDF는 표·차트·레이아웃을 페이지 이미지 토큰으로 함께 읽는다. 반면 Context Caching, Batch API, Flex/Priority 추론, gs:// 직접 URI, YouTube URL, thought/tool_call 블록은 의도적으로 제외되어 있으므로, 장기 캐시가 필요한 반복 Q&A나 에이전트 도구 인자 생성 워크로드는 Interactions API로 분리해 하이브리드 파이프라인을 구성해야 한다.
4. 로컬 Python 6대 아키텍처 불변식 및 비용·제약 검증 스크립트
아래 verify_gemini_decisions_api.py 스크립트는 외부 API 키나 네트워크 호출 없이 Python 표준 라이브러리만으로 Gemini Decisions API의 6대 핵심 불변식(① 요청 스키마·키 규칙·262,144 토큰 한도 및 gs://·YouTube·thought 차단 경계, ② noul의 [0.01, 0.99] 클램핑 및 도달 불가능 임계값 탐지, ③ choice의 UTF-8 바이트 정렬·알파벳 동률 처리·noul 범위 게이트 결합, ④ score 기대값 계산과 이봉 분포 confidence 판별, ⑤ 질문 간 격리 불변식 및 100개 규칙·10K 토큰 기준 $0.10/1M 비용 절감 계산, ⑥ 워크로드 사전 적합성 감사)을 로컬에서 검증한다.
로컬 실행 결과:
5. 실무 Gemini Decisions API 도입 및 라우팅 설계 체크리스트
워크로드 분리 기준 확정: 에이전트 도구 선택·요청 라우팅·다중 정책 가드레일·루브릭 채점처럼 닫힌 선택지와 보정 확률이 필요한 경로만 gemini-decision-1로 이전하고, 텍스트 생성·요약·JSON 추출·도구 인자 생성은 Interactions API에 유지한다.
noul · choice · score 설계 함정 점검: noul 임계값이 0.99를 넘지 않도록 제한하고, choice에 none_of_the_above 대신 other 또는 별도 noul 범위 게이트를 두며, score 자동 분기 시 기대 점수와 함께 confidence(이봉 분포 여부)를 반드시 검사한다.
질문 키·인접 블록·프롬프트 위생 확인: 모델은 questions 키를 읽지 못하므로 instructions에 완전한 질문을 작성하고, 멀티 블록 input 사이에는 명시적 개행(\n)을 넣으며, 비신뢰 사용자 입력의 프롬프트 인젝션을 대비해 금전·보안 민감 분기는 저신뢰 에스컬레이션 경로를 둔다.
미디어 경로 및 미지원 기능 사전 필터링: gs:// 경로나 YouTube URL은 사전 차단하고 Files API URI, HTTPS URL(15MB 이하), Base64(요청당 100MB / PDF 50MB 이하)로 정규화하며, 멀티턴 이력은 단일 텍스트 블록으로 직렬화한다.
운영 트래픽 기반 임계값 캘리브레이션 및 HTTP 400 안전 예외 처리: confidence 커트라인(예: 0.70~0.85)은 자사 라벨링 데이터를 기준으로 거짓 양성·거짓 음성 비용을 따져 튜닝하고, 안전 필터 차단 시 반환되는 HTTP 400 error.code에 대한 폴백 큐를 구현한다.
6. 참고 자료 및 공식 출처 (2026-11-18 확인)
확인 기준일: November 18, 2026