스마트 라우팅 시작하기
하나의 Route model ID로 요청하고, BizRouter가 요청 조건과 운영 목표에 맞는 실제 Model·Provider를 선택하도록 설정합니다. 이 문서에서 완료할 작업 기본 Route의 운영 목표를 정하고 자동 라우팅을 적용합니다. 선택 결과를 먼저 검증하고 싶은 경우에만 자동 라우팅 시뮬레이션을 사용합니다.
준비 사항
Route 설정은 Organization owner가 수행하고, 호출은 서비스 API key로 수행합니다. Organization에서 사용할 실제 Model이 활성화되어 있어야 합니다. 서비스 API key가 실제 후보 Model을 호출할 수 있어야 합니다. 사용할 Provider가 실제 요청을 처리할 수 있는 상태여야 합니다. 시뮬레이션을 사용할 때는 모델 선택 결과를 만들 검증 요청이 필요합니다. 스마트 라우팅 설정 열기 설정과 라우팅 분석 메뉴는 Organization owner에게만 표시됩니다.
핵심 개념
설정 화면의 용어와 API 요청 값을 먼저 구분하십시오. 용어 의미 Route 독립적인 운영 목표와 분석 설정을 가진 가상 API model 현재 응답 Model 자동 라우팅 시뮬레이션에서 실제 응답을 생성하는 비교 기준 Model 자동 라우팅 시뮬레이션 현재 응답 Model은 유지하면서 자동 선택 결과만 로그에 기록하는 선택형 검증 기능 자동 라우팅 요청별로 선택한 Model·Provider를 실제 호출하는 단계
Route model ID
기본 Route와 용도별 사용자 Route를 합해 최대 10개까지 만들 수 있습니다. 종류 API 요청의 model 수명주기 기본 Route bizrouter/route 항상 존재하며 삭제할 수 없음 사용자 Route bizrouter/route/<slug> 비활성 상태로 생성되며 이름 수정·삭제 가능 사용자 Route의 slug는 1–40자의 영문 소문자, 숫자, hyphen만 허용되며 생성 후 변경할 수 없습니다. default, route, auto, manual, smart는 예약된 값입니다. 최대 10개 제한에는 기본 Route가 포함됩니다.
기본 Route 설정
시뮬레이션 없이 바로 적용하거나, 현재 응답 Model을 유지한 채 추천 결과를 먼저 검증할 수 있습니다.
기본 Route 설정 · 자동 라우팅 사용
시뮬레이션 사용 을 체크하지 않습니다. 운영 목표와 프로바이더·모델 제한을 정합니다. Route API 사용 을 켜고 저장합니다.
기본 Route 설정 · 추천 결과를 먼저 검증
시뮬레이션 사용 을 체크합니다. 기준 응답 Model을 선택하고 Route API 사용 을 켠 뒤 저장합니다. 검증 요청을 보내 실제 응답과 추천 결과를 비교합니다. 검증이 끝나면 체크를 해제하고 저장합니다. 시뮬레이션은 선택 사항이며 실제 응답 Model을 바꾸지 않습니다 자동 라우팅이 추천한 Model·Provider는 호출하지 않고 로그에만 기록합니다. 이 단계의 응답 품질과 생성 비용은 현재 응답 Model 기준입니다. 내부 요청 분석 비용(요청당 약 ₩0.3)은 별도로 발생할 수 있습니다.
검증 요청 보내기
Route를 저장한 후 모델 테스트 화면이나 API에서 실제 요청을 보낼 수 있습니다. 모델 테스트 화면에서 바로 검증 모델 테스트에서 모델 추가 선택 을 누른 뒤 Smart Routing 그룹의 Route를 선택하십시오. 활성화된 기본 Route와 사용자 Route만 표시됩니다. 응답 상단에서는 실제 응답 Model과 시뮬레이션 추천 Model·Provider를 구분해 확인할 수 있습니다. 기본 Route 사용자 Route Responses API 이 요청의 응답은 현재 응답 Model이 생성합니다. 자동 선택 추천은 실제로 호출되지 않고 라우팅 분석에만 기록됩니다. 사용자 Route 예제의 support 는 생성한 slug로 바꾸십시오. 지원 endpoint Route model ID는 POST /v1/chat/completions , POST /v1/responses , POST /v1/messages 에서 지원됩니다. Responses API는 OpenAI Model·Provider 후보만 사용하며 fallback 재시도를 지원하지 않습니다. Messages API(Claude Code·Agent SDK 클라이언트)는 전체 후보를 사용하며 fallback 재시도를 지원하지 않습니다. Route를 임의의 Model로 대체하지 않습니다 Route가 비활성화되었거나 요청 조건·API Key scope·Route의 프로바이더·모델 제한을 모두 만족하는 후보가 없으면 요청이 실패합니다. Chat Completions의 fallback도 재시도 가능한 일부 Provider 오류에서만 동작하며 성공을 보장하지 않습니다. 실패 원인과 후보 제외 사유는 라우팅 분석에서 확인하십시오.
응답에서 선택 결과와 원가 확인
Route 요청의 응답만으로 실제 선택된 Model·Provider와 확정 비용을 확인할 수 있습니다. Messages 응답 body의 model 에는 실제 선택된 BizRouter Model code가 반환됩니다. Chat Completions와 Messages 스마트 라우팅 요청에는 실제 Model code와 Provider가 응답 헤더로 함께 내려옵니다. 확정 KRW 비용은 usage.cost 로 제공됩니다. 스트리밍에서도 마지막 usage 청크에 동일하게 포함되므로, 요청마다 실제 Model이 달라지는 Route에서도 단가를 역산할 필요 없이 응답 값을 그대로 정산에 사용할 수 있습니다. 두 헤더는 스트리밍과 비스트리밍 모두에서 제공됩니다.
시뮬레이션 사용 시 체크리스트
Route가 활성화되고 시뮬레이션 변경사항이 저장되었는지 확인 검증 요청이 라우팅 분석에 기록되었는지 확인 여러 Route를 비교할 때 로그 탭의 전체 라우팅 설정에서 결과를 함께 확인 서비스 API key가 스마트 라우팅에서 사용할 Model을 허용하는지 확인 시뮬레이션에서 후보 제외 사유와 예상치 못한 Provider 선택 확인 이미지, tool calling, JSON output 등 실제 요청 유형으로 검증 Responses API 사용 시 OpenAI 후보가 남아 있는지 확인 시뮬레이션 사용 체크를 해제한 뒤 저장했는지 확인 자동 라우팅 저장 후 Route별 성공률, latency, 비용과 fallback 모니터링