옴니라우트 오토 콤보 예산 설정 가이드

요청 한 번이 예산을 넘었는데도 가장 싼 모델로 계속 실행되고 있다면, 기본 회귀 설정만 믿고 있는 상태입니다.

가장 빠른 해결책은 후보 모델을 먼저 허용 목록으로 줄인 뒤 요청 예산과 strict 차단을 함께 설정하고, 비생산 클라이언트 하나에서 초과·장애·무후보 결과를 모두 확인하는 것입니다. 옴니라우트 오토 콤보는 기본 cheapest 회귀가 남아 있으면 상한을 넘는 후보로 이어질 수 있습니다. 공식 오토 콤보 문서도 cheapest를 이전 동작으로, strict를 초과 시 HTTP 402로 종료하는 방식으로 구분합니다.

이 글은 옴니라우트 오토 콤보로 한 번의 에이전트 요청 비용을 통제하려는 개발자를 위한 안내입니다. 여러 코딩 도구에 같은 라우팅 규칙을 적용하려는 플랫폼 엔지니어와, 로컬 게이트웨이를 상시 온라인 환경으로 옮기려는 원격 팀에도 적합합니다.

예산 객체와 실패 정책

먼저 예산을 세 가지로 나눠 기록해야 합니다. 서로 다른 계층을 하나의 숫자로 관리하면 초과 원인을 찾기 어렵습니다.

공식 API 문서 기준으로 비용 예산은 키에 일간, 주간, 월간 한도를 둘 수 있고, 토큰 한도는 모델·공급자·전체 범위로 구분할 수 있습니다. 여러 토큰 한도가 동시에 맞으면 가장 엄격한 한도가 적용됩니다. 예산 및 토큰 한도 API 문서를 설정 전에 확인해야 합니다.

실패 정책은 다음 중 하나로 결정합니다.

• 차단: 비용 통제가 최우선인 운영 에이전트에 적합합니다.
• 강등: 작업을 계속해야 하지만 결과 품질 저하를 감수할 수 있을 때 사용합니다.
• 알림: 내부 테스트나 비용 관찰 단계에서 사용합니다.

예산 민감한 생산 에이전트라면 차단을 기본값으로 두고, 개발용 에이전트만 강등을 허용하는 편이 안전합니다. 후보 목록에는 자격 증명이 검증되고 기본 요청이 성공한 모델만 넣습니다. 긴 문맥, 도구 호출, 코드 작성처럼 작업별 한계도 함께 적습니다.

후보 모델 구성과 비용 경계

오토 콤보는 연결된 후보를 실시간으로 모아 건강 상태와 비용, 지연 시간, 쿼터 등을 기준으로 선택합니다. 공식 위키의 가상 후보 생성 흐름도 활성 연결, 유효한 자격 증명, 모델 목록과 가격 정보를 확인한 뒤 후보를 만든다고 설명합니다. 오토 콤보 후보 생성 구조를 보면 새 연결이 후보 풀에 자동으로 들어갈 수 있다는 점도 확인할 수 있습니다.

그러나 자동 후보 확장은 편리함과 비용 통제 사이에 긴장을 만듭니다. 새 공급자를 연결한 뒤 auto를 그대로 사용하면 기존에 검토하지 않은 모델이 선택 대상에 들어갈 수 있기 때문입니다.

후보를 구성할 때는 모델 수를 늘리는 것보다 대체 관계를 명확히 하는 편이 중요합니다. 가장 싼 모델이 코드 수정에는 적합하지 않을 수 있고, 빠른 모델이 긴 작업에서 반복 실패할 수도 있습니다. auto/cheap은 비용 최적화용 선택이지만 strict 예산 통제와 같은 기능은 아닙니다. 오토 변형과 모드 설명에서도 cheap와 strict가 서로 다른 역할로 설명됩니다.

주의: 문서의 필드 이름과 기본 동작은 릴리스에 따라 바뀔 수 있습니다. 설정을 복사하기 전에 사용 중인 버전의 문서와 코드 스키마를 함께 대조해야 합니다.

요청 예산과 strict 설정

요청별 제어는 저장된 조합 설정과 호출 헤더를 나눠 생각하면 쉽습니다. 저장 설정은 기본 정책이고, 헤더는 한 번의 호출에만 적용하는 예외 규칙입니다. 공식 릴리스 기록에는 X-OmniRoute-Mode가 선택 모드를 바꾸고 X-OmniRoute-Budget가 요청별 비용 상한을 정한다고 나와 있습니다. 공식 릴리스 기록에서 사용 중인 버전의 변경 내역과 설정 변경 여부를 함께 확인해야 합니다.

아래 값은 실제 비밀 정보가 아닌 자리 표시자입니다.

curl -sS <OMNIROUTE_ENDPOINT>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AGENT_API_KEY>" \
  -H "X-OmniRoute-Mode: <MODE>" \
  -H "X-OmniRoute-Budget: <REQUEST_BUDGET>" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "<TEST_PROMPT>"}
    ]
  }'

예상 결과는 세 가지로 나눠 기록합니다.

엄격 모드는 “가장 싼 후보를 선택하라”가 아니라 “상한을 넘는 후보는 선택하지 말라”는 의미입니다. 따라서 모델 가격표가 오래됐거나 입력·출력 토큰 비용 계산이 누락되면 strict도 잘못된 판단을 할 수 있습니다. 비용 추적은 요청 로그와 가격표를 함께 갱신해야 합니다.

키 단위 비용 예산은 요청별 상한의 대체물이 아닙니다. 예를 들어 팀 월간 한도는 남아 있어도 한 번의 긴 코드 작업이 허용 범위를 넘을 수 있습니다. 반대로 요청 상한이 낮아도 여러 사용자가 동시에 호출하면 주기별 한도에 먼저 도달할 수 있습니다.

초과와 공급 장애 검증

설정 저장 후 바로 팀에 공유하지 말고 네 가지 실패를 순서대로 재현합니다.

첫째, 모든 후보의 예상 비용이 요청 상한보다 높도록 테스트 조건을 만듭니다. strict라면 요청이 실행되지 않고 HTTP 402가 반환되어야 합니다. cheapest라면 더 싼 후보로 계속 진행할 수 있으므로, 실제 비용 제한이 필요한 환경에서 이 결과를 통과로 처리하면 안 됩니다.

둘째, 첫 번째 공급자의 자격 증명을 임시로 무효화합니다. 후보가 남아 있으면 다른 후보로 넘어가는지 확인하고, 인증 오류가 반복 재시도로 증폭되지 않는지 살핍니다.

셋째, 공급자 연결을 비활성화하거나 모델을 사용할 수 없게 만듭니다. 후보가 하나도 없을 때는 성공 응답을 기대하지 말고, 명확한 오류와 라우팅 설명이 남는지 확인해야 합니다.

넷째, 제한 응답을 의도적으로 발생시킵니다. 키별 토큰 한도에 도달하면 공식 문서상 HTTP 429가 반환될 수 있으므로, 이 응답을 비용 초과인 HTTP 402와 같은 유형으로 처리하지 않아야 합니다.

각 테스트에서는 요청 식별자, 설정 버전, 후보 목록, 최종 모델, 회귀 횟수, 응답 상태와 오류 본문을 저장합니다. “왜 이 모델이 선택됐는가”를 확인하려면 최종 모델만 저장해서는 부족합니다. 후보가 제외된 이유와 적용된 모드, 예산, 건강 상태까지 남겨야 합니다.

첫 에이전트 연결과 재시도 차단

첫 연결 대상은 생산 계정이 아닌 별도 테스트 클라이언트로 정합니다. 클로드 코드나 커서처럼 서로 다른 클라이언트는 기본 주소, 인증 방식, 스트리밍 처리와 재시도 방식이 다를 수 있습니다. 따라서 라우터가 예산을 막았더라도 클라이언트가 같은 요청을 다시 보내면 비용 정책이 우회된 것처럼 보일 수 있습니다.

다음 순서로 확인합니다.

1. <TEST_AGENT_NAME> 전용 API 키를 만듭니다.
2. 기본 모델을 auto 또는 검증한 조합 식별자로 지정합니다.
3. 엔드포인트와 키를 환경 변수 또는 비밀 저장소에 넣습니다.
4. 일반 응답과 스트리밍 응답을 각각 실행합니다.
5. 도구 호출, 긴 작업, 오류 응답에서 클라이언트 재시도를 관찰합니다.
6. 요청 로그의 식별자와 에이전트 화면의 결과를 대조합니다.

테스트 클라이언트의 재시도 횟수가 라우터의 예산 실패 정책보다 높으면, 사용자에게 한 번만 실패한 것처럼 보여도 내부에서는 여러 요청이 발생할 수 있습니다. HTTP 402와 HTTP 429를 자동 재시도 대상에서 제외하고, 사람이 다시 실행할지 결정하도록 만드는 편이 좋습니다.

팀 회귀와 운영 점수

첫 주에는 모든 팀원을 동시에 연결하지 않고 클라이언트나 구성원 단위로 확대합니다. 점수는 단순 성공률 하나로 정하지 않습니다.

비용 경고는 요청별 상한과 별도로 둡니다. 키 단위의 일간·주간·월간 한도는 팀의 총량을 보는 계층이고, 요청별 상한은 개별 작업의 폭주를 막는 계층입니다. 예산 상태 조회와 토큰 한도 조회를 주기적으로 수집하면 구성원별 편차도 확인할 수 있습니다.

장기 유지와 빠른 회귀

모델 가격, 공급자 상태, 자격 증명 만료, 쿼터 정책은 바뀔 수 있습니다. 과거에 가장 저렴했던 후보가 계속 최선이라는 보장은 없습니다. 오토 콤보 구조상 후보 점수에는 비용뿐 아니라 지연 시간, 건강 상태, 남은 쿼터와 작업 적합성도 영향을 줄 수 있습니다.

운영팀은 다음 변경이 생길 때마다 네 가지 실패 테스트를 다시 실행해야 합니다.

• 모델 가격표 변경
• 새 공급자 또는 새 계정 추가
• API 키 교체와 만료
• 오토 콤보 버전 업데이트

설정 파일에는 budgetFallback, 허용 후보 목록, 적용 모드, 담당자, 마지막 검증 결과를 함께 기록합니다. 즉시 회귀할 수 있도록 이전 설정을 보관하고, 팀 공유 전에는 비생산 클라이언트에서 먼저 이전 버전으로 돌아가는 절차도 확인합니다.

현재 방식이 각 에이전트에 공급자 키를 따로 넣는 구조라면 비용 추적이 분산되고, 초과 요청의 원인을 찾기 어렵고, 장애 때마다 클라이언트별 재설정이 필요합니다. 단일 로컬 게이트웨이에만 의존하면 원격 구성원이 접근하기 어렵고, 컴퓨터가 꺼졌을 때 라우팅도 중단됩니다. 여러 구성원이 같은 규칙을 써야 한다면 클라우드 맥 대여 환경이나 맥 가상 서버 가격과 운영 방식을 비교해 상시 온라인 환경으로 옮기는 편이 관리상 유리할 수 있습니다. 다만 장기간 고정 부하가 크거나 물리 장치 연결이 필수라면 직접 서버를 운영하는 편이 더 적합합니다.

처음부터 전체 팀을 이전하기보다는 비생산 에이전트 하나로 예산 초과, 공급 장애, 자격 증명 오류, 무후보 상태를 재현하는 것이 안전합니다. 이후 원격 구성원이 공유할 규칙이 필요할 때 Zilmac의 맥 지원 안내를 확인하고, 지속 온라인 게이트웨이 구성과 클라우드 맥 운영을 함께 검토하면 됩니다.

• 오픈라우터 에이피아이 요금과 주요 모델 비교로 라우팅 비용 가늠하기
• 클로드 코드 맥스 요금과 개발 기능을 살펴보며 예산 상한 정하기