Articleaws.amazon.com·2026년 11월 13일·0

Route coding agent requests to the right model on Amazon Bedrock with NVIDIA NeMo Switchyard

Quick Summary

AWS CDK로 Amazon Bedrock 기반 LiteLLM·NVIDIA NeMo Switchyard 게이트웨이를 배포하고, 코딩 에이전트의 모델 라우팅을 테스트 통과 작업당 비용으로 평가하는 비프로덕션 샘플을 소개한다.

Route coding agent requests to the right model on Amazon Bedrock with NVIDIA NeMo Switchyard 관련 대표 이미지

🖼️ 인포그래픽

Route coding agent requests to the right model on Amazon Bedrock with NVIDIA NeMo Switchyard 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

Route coding agent requests to the right model on Amazon Bedrock with NVIDIA NeMo Switchyard의 핵심 내용을 4단계로 요약한 인포그래픽
Route coding agent requests to the right model on Amazon Bedrock with NVIDIA NeMo Switchyard 핵심 내용을 4단계로 압축한 4컷 인포그래픽

💡 한 줄 요약

AWS CDK로 Amazon Bedrock 기반 LiteLLM·NVIDIA NeMo Switchyard 게이트웨이를 배포하고, 코딩 에이전트의 모델 라우팅을 테스트 통과 작업당 비용으로 평가하는 비프로덕션 샘플을 소개한다.

📌 핵심 요약

  • Claude Code와 OpenAI Codex CLI 같은 코딩 에이전트의 작업 비용은 토큰 가격뿐 아니라 호출 횟수, 대화 기록 재전송, 재시도와 미완료 시도에 좌우되므로, 전체 실행 비용을 테스트 통과 실행 수로 나눈 작업당 비용으로 라우팅을 평가해야 한다.
  • NVIDIA NeMo Switchyard의 실험적 LiteLLM 통합은 최근 도구 활동과 결과로 정확히 두 후보 중 하나를 고르는 Stage와, 최소 두 후보에 선택적 가중치를 적용하는 Random을 지원한다. 두 전략 모두 판정용 모델을 호출하지 않으며, 중간 모델 호출이 필요한 Task·Composite는 지원하지 않는다.
  • 샘플은 LiteLLM과 Switchyard 플러그인을 AWS Fargate 기반 Amazon ECS의 프라이빗 서브넷에서 실행하고, AWS WAF·Application Load Balancer·공유 게이트웨이 키로 접근을 제어한다. 모델 호출은 작업 IAM 역할과 VPC 인터페이스 엔드포인트를 통해 Amazon Bedrock Converse 또는 ConverseStream API로 전달된다.
  • 기본 모델 쌍은 Claude Opus 5.5와 NVIDIA Nemotron 3 Super 120B이며, switchyard 라우팅 그룹과 두 단일 모델 기준 그룹을 같은 배포에 구성한다. Stage는 고성능 모델을 먼저, 효율형 모델을 두 번째로 선언하고 전체 대화 기록을 받아야 하며, efficient_first와 recent_window = 3 설정에서는 판단이 불명확하거나 도구 결과가 없는 요청에 Nemotron 3 Super를 사용한다.
  • 샘플은 데모·평가용 switchyard-server 0.3.0과 LiteLLM v1.102.0을 사용하며 비프로덕션 계정에서 검증해야 한다. 자격 증명을 litellm.yaml에 넣으면 안 되고, global. 추론 프로필의 전 세계 지원 리전 처리 가능성과 파생 IAM 정책을 검토해야 한다. 제공된 본문에는 비용·통과율 측정 결과가 없다.

🧩 주요 포인트

  1. 미완료 시도의 비용까지 포함하는 작업당 비용 → 저렴한 토큰 단가가 실제 작업 비용 절감으로 이어지는지 통과율과 함께 판단하는 기준이 된다.
  2. switchyard와 두 단일 모델 기준 그룹의 병행 구성 → 동일 배포에서 라우팅의 비용·통과율을 각 모델 단독 사용과 비교할 수 있지만, 제공된 본문만으로 우열은 확정할 수 없다.
  3. Stage의 전체 대화 기록·후보 순서 의존성과 global. 추론 프로필의 처리 위치 범위 → 클라이언트의 기록 전달 방식, 모델 설정, 데이터 처리 위치 제약이 적용 가능성을 좌우한다.

🧠 상세 정리

1. 토큰 가격보다 해결된 작업당 비용을 봐야 하는 이유

Claude Code와 OpenAI Codex CLI 같은 코딩 에이전트는 개발자가 변경을 요청하면 파일을 읽고 코드를 수정하며 테스트를 실행하는 작업 단위로 움직이고, 하나의 작업에 필요한 모델 호출은 몇 차례에서 수십 차례까지 달라질 수 있다. 전체 비용에는 토큰 단가뿐 아니라 모델이 요구하는 턴 수, 매번 다시 전달하는 대화 기록의 양, 재시도 횟수가 영향을 주며, 끝내 완료되지 않은 시도에도 비용이 발생한다. 따라서 원문은 모든 실행 비용의 합을 테스트를 통과한 실행 수로 나눈 ‘해결된 작업당 비용’을 라우팅 평가 기준으로 제안한다. NVIDIA NeMo Switchyard는 에이전트가 각 요청을 처리할 모델을 선택하도록 돕는 오픈 소스 라이브러리로, 사용자가 후보 모델과 선택 전략을 정의한다. 이 접근의 핵심은 요청 하나의 가격을 낮추는 데서 평가를 끝내지 않고, 실제로 작업을 해결하는 데 지출한 비용을 비교하는 것이다.

2. 지원 전략과 샘플의 실험적 성격

Switchyard의 LiteLLM 통합은 최근 요청 기록의 도구 활동과 결과를 읽어 정확히 두 후보 중 하나를 고르는 Stage와, 최소 두 후보에서 선택적 가중치로 트래픽을 분배하는 Random을 지원한다. 두 전략 모두 판정용 모델을 호출하지 않으며, 중간 모델 호출이 필요한 분류기 기반 Task·Composite 전략은 이 통합에서 지원하지 않는다. 소개된 샘플은 AWS CDK로 LiteLLM과 Switchyard 라우팅 플러그인을 AWS 계정에 배포하고, Amazon Bedrock 모델을 호출하며, 벤치마크 실행기로 라우팅 그룹과 단일 모델 기준 그룹을 비교하도록 구성되어 있다. 설치 대상은 crates.io의 switchyard-server 0.3.0과 공개 LiteLLM v1.102.0 이미지이며, NVIDIA는 해당 서버 버전을 데모·평가용 구성 요소로 문서화하고 있다. 원문은 통합 자체가 실험적이어서 설정과 API가 릴리스 사이에 바뀔 수 있다고 밝히고, 비프로덕션 계정에서 테스트하며 배포 전 조직의 보안·법무 요구사항을 검토하도록 안내한다.

3. 요청 수신부터 Amazon Bedrock 응답까지의 흐름

코딩 에이전트는 model 필드를 switchyard로 지정한 OpenAI 호환 요청을 보내고, Authorization 헤더에 공유 게이트웨이 키를 전달하며, 소유한 호스트 이름의 HTTPS 엔드포인트로 접속한다. Route 53 호스팅 영역을 사용하는 경우 이름은 로드 밸런서로 해석되고, ACM 인증서가 HTTPS를 제공하며, 허용한 IPv4 CIDR 범위와 AWS WAF의 IP 평판·알려진 악성 입력·IP별 요청 제한 규칙이 접근을 제한한다. Application Load Balancer는 /v1/chat/completions, /v1/models, /health/liveliness만 프라이빗 서브넷의 ECS 작업으로 전달하고 나머지 경로에는 404를 반환한다. AWS Fargate에서 실행되는 단일 컨테이너의 LiteLLM은 키를 검증하고 플러그인으로 모델을 선택한 뒤, 작업 IAM 역할의 자격 증명을 사용해 VPC의 Amazon Bedrock Runtime 인터페이스 엔드포인트를 거쳐 Converse 또는 ConverseStream API를 호출한다. 응답이나 토큰 스트림은 LiteLLM과 로드 밸런서를 통해 반환되며, 실제 응답 모델은 x-litellm-model-name 헤더에 표시되고 응답 본문의 model 필드는 switchyard로 유지된다.

4. 운영 구성과 실행 전제조건

LiteLLM은 컨테이너의 4000번 포트에서 수신하고 작업 보안 그룹은 로드 밸런서의 접근만 허용하며, 경로 허용 목록은 관리 UI·API 문서·키 관리 경로를 외부에서 접근할 수 없게 한다. Amazon ECR은 게이트웨이 이미지를 보관하고 AWS Secrets Manager는 게이트웨이 키의 기반 비밀 값을 생성하며, 컨테이너는 시작할 때 sk- 접두사를 붙인다. 작업 정의로 전달한 LITELLM_CONFIG_TEXT와 SWITCHYARD_CONFIG_TEXT는 시작 스크립트가 /tmp 파일로 기록하고, 로그는 /<stack name>/litellm CloudWatch 로그 그룹에 30일간 보관되며 Container Insights가 지표를 수집한다. VPC는 두 가용 영역에 걸치지만 NAT 게이트웨이는 하나이며, 이미지 가져오기와 다른 AWS 서비스 접근에 필요한 아웃바운드 연결을 제공한다. 실행에는 Claude Opus 5.5와 NVIDIA Nemotron 3 Super 120B 접근 권한이 있는 비프로덕션 AWS 계정, 자격 증명과 명시적 리전이 설정된 AWS CLI v2 및 CDK 부트스트랩 환경, Node.js 20 이상·npm·BuildKit 지원 Docker·Python 3.11 이상이 필요하다. 이 모델 쌍은 미국 동부 버지니아 북부에서 테스트되었으므로 다른 리전에서는 모델 가용성과 도구 호출 지원을 확인해야 하며, HTTPS에는 소유한 호스트 이름과 공개 Route 53 호스팅 영역 또는 배포 리전의 ACM 인증서가 필요하지만 짧은 일반 HTTP 테스트에는 둘 다 필요하지 않다.

5. 라우팅 모델 그룹과 단일 모델 비교 기준 구성

샘플은 profiles/ 아래 배포 프로필마다 모델과 게이트웨이 설정을 담는 litellm.yaml과 선택 동작을 정하는 switchyard.toml을 짝으로 관리한다. Stage 프로필에서는 Claude Opus 5.5와 NVIDIA Nemotron 3 Super 120B가 같은 model_name인 switchyard를 공유하므로, 클라이언트는 하나의 공개 모델 이름을 사용하고 실제 후보 선택은 Switchyard에 맡긴다. Stage는 선언 순서로 역할을 해석하기 때문에 고성능 모델을 첫 번째, 비용이 낮은 효율형 모델을 두 번째에 두어야 한다. 별도의 claude-opus-5-5와 nemotron-super-3-120b 그룹은 각각 자기 모델로만 응답하는 기준 그룹이며, 같은 배포 안에서 라우팅 그룹의 비용과 통과율을 각 모델 단독 사용과 비교할 수 있게 한다. 이미지에 등록된 switchyard_gateway.configured.ROUTING_PLUGIN 래퍼는 후보가 하나인 그룹을 그대로 통과시키고, 고유 후보가 둘 이상인 그룹에 Switchyard를 적용하며, 모델 선택과 지원되는 요청 변경을 모두 수행하도록 두 곳에 등록된다. 모든 모델 경로는 bedrock/converse/<id> 형식을 사용하도록 검증되고, LiteLLM의 600초 요청 제한은 로드 밸런서의 10분 유휴 제한과 맞춰져 있다.

6. 자격 증명·파생 권한·처리 위치의 주의점

litellm.yaml에는 자격 증명을 저장하지 않고, LiteLLM은 환경 변수에서 게이트웨이 키를 읽으며 AWS 자격 증명은 작업 IAM 역할로 공급받는다. 스택이 litellm.yaml 전체를 작업 정의와 AWS CloudFormation 템플릿에 평문으로 복사하기 때문에, litellm_params 아래에 aws_access_key_id, aws_secret_access_key, api_key 같은 값을 넣으면 안 된다고 원문은 명시한다. 스택은 이 파일의 모델 설정에서 Amazon Bedrock 권한도 도출하며, 전역 교차 리전 추론 프로필의 기반 모델 리소스에는 리전 와일드카드와 끝부분 와일드카드가 들어가 같은 접두사의 다른 모델 ID까지 일치할 수 있으므로 배포 전에 파생 정책을 검토해야 한다. Claude 모델 ID의 global. 접두사는 전역 교차 리전 추론 프로필을 뜻하고, Amazon Bedrock은 지원되는 전 세계 상용 AWS 리전에서 해당 요청을 처리할 수 있어 처리 위치가 중요하면 지리적 프로필이나 리전 내 모델 ID를 사용해야 한다. Nemotron 3 Super는 nvidia.nemotron-super-3-120b라는 리전 내 모델 ID를 사용하며, 샘플은 테스트를 위해 이를 다른 모델로 바꿀 수 있다고 설명한다.

7. Stage의 기록 기반 선택과 기본 설정

기본 profiles/stage/switchyard.toml은 algorithm = "stage", picker = "efficient_first", confidence_threshold = 0.5, recent_window = 3, only_on_wrong_signal_escalation = true를 설정한다. Stage는 요청 기록의 도구 활동과 실행 결과를 근거로 두 후보 중 하나를 선택하므로 에이전트가 전체 대화 기록을 보내야 하고, 이 프로필은 가장 최근 도구 결과 세 개를 살핀다. efficient_first는 기록의 신호만으로 판단하기 어려우면 효율형 후보를 선호한다는 뜻이며, 도구 결과가 아직 없는 새 요청은 Nemotron 3 Super로 전달된다. confidence_threshold는 Stage가 점수를 매기는 실행 신호에 적용하는 0부터 1 사이의 신뢰도 기준이고, only_on_wrong_signal_escalation은 선택적으로 추가할 상향 전환 메모의 시점을 제어하는 Switchyard 기본값이지만 샘플에는 메모가 설정되어 있지 않다. Stage는 escalation_note·deescalation_note와 capable_system_prompt·efficient_system_prompt도 선택적으로 받을 수 있으나, 기본 프로필은 이 인계 메모와 모델 계층별 시스템 프롬프트를 모두 지정하지 않는다.

8. Random 비교 실험과 제공된 근거의 범위

profiles/random/의 Random 프로필은 Stage와 같은 모델을 사용하면서 algorithm = "random"과 weights = [0.5, 0.5]를 지정해 가중치 기반 A/B 비교에 활용할 수 있도록 한다. 가중치는 선언 순서에 따른 고유 후보마다 하나씩 대응하며, 이 예시는 두 후보에 같은 가중치를 부여한다. Random이 최소 두 후보를 대상으로 가중치에 따라 선택하는 것과 달리, Stage는 정확히 두 후보를 대상으로 요청 기록의 도구 활동과 결과를 읽어 선택한다. 원문이 제시하는 평가 방향은 라우팅 그룹과 단일 모델 기준 그룹의 전체 실행 비용 및 테스트 통과 수를 측정해, 자기 작업 부하에서 해결된 작업당 비용을 비교하는 것이다. 다만 제공된 본문은 Random 설정 설명 도중에 끝나며 실제 배포·시험·벤치마크의 후속 절차나 측정된 비용·통과율은 포함하지 않으므로, 어느 전략이나 모델 조합이 더 경제적인지는 이 자료만으로 결론 내릴 수 없다.

🧾 핵심 주장 / 시사점

  • 효율형 모델의 낮은 호출 비용이 더 많은 턴이나 재시도로 상쇄될 수 있으므로, 라우팅의 경제성은 실패한 시도까지 포함한 작업 전체의 비용과 성공 여부를 함께 봐야 드러난다.
  • Stage의 선택에는 클라이언트가 전달하는 도구 실행 기록이 직접 사용된다. 따라서 전체 대화 기록 전달과 후보 선언 순서는 라우팅 동작을 결정하는 기능적 조건이다.
  • Amazon Bedrock 호출이 VPC 엔드포인트를 거쳐 AWS 네트워크에 머무는 것과 global. 추론 프로필의 처리 리전 범위는 서로 다른 조건이므로, 네트워크 경로만으로 데이터 처리 위치를 판단할 수 없다.

✅ 액션 아이템

  • switchyard와 두 단일 모델 기준 그룹의 전체 실행 비용 및 테스트 통과 수를 비교해 작업당 비용과 통과율을 평가한다.
  • Stage 적용 시 전체 대화 기록 전달과 고성능·효율형 후보 순서를 확인하고, efficient_first와 recent_window = 3의 선택 동작을 검증한다.
  • 비프로덕션 계정에서 switchyard-server 0.3.0·LiteLLM v1.102.0을 검증하고, litellm.yaml의 자격 증명 제외 여부와 파생 IAM 정책 및 global. 추론 프로필의 처리 위치 제약을 검토한다.

❓ 열린 질문

  • 실제 작업 부하에서 switchyard는 Claude Opus 5.5와 NVIDIA Nemotron 3 Super 120B의 단일 모델 기준 그룹보다 작업당 비용을 낮추면서 어느 수준의 통과율을 보이는가?
  • Stage가 요구하는 전체 대화 기록을 전달할 수 있으며, efficient_first와 recent_window = 3 설정은 해당 작업 부하에서 어떤 모델 선택으로 이어지는가?
  • global. 추론 프로필의 전 세계 지원 리전 처리 가능성과 파생 IAM 정책은 적용 환경의 데이터 처리 위치 제약에 부합하는가?

관련 문서

공통 태그와 주제 흐름을 기준으로 같이 보면 좋은 문서를 이어서 제안합니다.