TL;DR

이 저장소는 논문 'Agent-as-a-Router'의 공식 재현 구현과 CodeRouterBench 벤치마크, 체크인된 출력, 그리고 데모를 포함해 코딩 과제에서 모델 라우팅을 실험하고 재생할 수 있도록 구성되어 있다. ACRouter는 후보 모델 목록과 저비용 우선 체인을 사용해 각 모델 호출 뒤에 검증기를 적용하고 실패 시 더 강력한 모델로 에스컬레이션하는 정책을 통해 성능과 비용의 균형을 관리한다. 공개 OOD176 매트릭스와 가격 정보를 포함해 비용 대비 성능 통계를 산출할 수 있으며 오프라인 재현 모드는 API 키 없이 논문 실험을 반복할 수 있게 설계되어 있다.

주요 기능

• 코딩 과제를 후보 모델 목록에 순차적으로 또는 정책에 따라 전달해 최종 응답을 선택하는 라우팅 파이프라인을 포함한다. 이 파이프라인은 모델 호출 함수와 검증기 콜백을 결합해 검증 실패 시 에스컬레이션을 수행하도록 설계되어 있다. 오프라인 재현 모드에서는 API 키 없이 체크인된 출력과 매트릭스를 사용해 동일한 실험을 반복할 수 있다.
• 공개 벤치마크 CodeRouterBench와 OOD176 재현 매트릭스를 번들링해 논문 성능을 비교할 수 있는 데이터와 기준 표를 제공한다. 데이터에는 ID 및 OOD 태스크와 모델별 결과가 CSV·JSONL 형식으로 포함되어 있고 가격 테이블도 함께 제공되어 비용 계산이 가능하다. 출력은 outputs/ 디렉터리에 기록되어 체크인된 레퍼런스 결과와 비교 가능하게 유지된다.
• 런타임 통합용 데모와 어댑터를 제공해 기존 Claude Code·Codex 기반 워크플로에 라우터를 붙일 수 있다. claude-code-router 및 cc-switch 통합은 게이트웨이 혹은 프록시 수준에서 라우팅 결정을 실행하도록 구현되어 있다. 사용자는 제공되는 템플릿을 수정해 자체 프로바이더와 모델 이름을 연결할 수 있다.
• 설정 기반 파이프라인과 스크립트가 포함되어 있어 이미 수집된 태스크-모델 결과로 평가 파이프라인을 실행할 수 있다. run_pipeline.py는 tasks.jsonl과 model_results.jsonl을 입력으로 받아 성능 및 비용 통계를 생성한다. 이 구성형 접근은 기존 실험 결과를 새로운 라우팅 정책으로 재평가할 때 유용하다.
• 옵션으로 Hugging Face에서 제공하는 훈련된 라우터 어댑터를 내려받아 로컬 재생에서 사용하는 구성이 준비되어 있다. download_hf_assets 스크립트는 최소 파일만 내려받는 --minimal 플래그와 라우터 모델 포함 여부를 제어하는 플래그를 제공한다. 이 방식으로 로컬에서 재현 실험을 수행할 때 외부 API 호출을 최소화할 수 있다.

어떻게 동작하는가

라우터는 후보 모델 목록과 저비용 우선 체인을 입력으로 받아 각 모델을 순차적으로 또는 정책에 따라 호출하는 방식으로 동작한다. 각 모델 호출 뒤에 검증기를 실행해 기준을 만족하지 못하면 다음 후보로 에스컬레이션하는 루프를 수행하며 비용과 성능 지표를 결합해 선택 결정을 내린다. 오프라인 재현은 사전 계산된 매트릭스와 모델 결과 파일을 사용해 동일한 라우팅 결정을 재생하고 성능·비용 통계를 산출하는 방식으로 구현되어 있다.

해결 문제

코딩 과제에서 단일 백엔드 모델로 인한 비용 낭비 또는 불충분한 성능 문제를 완화하는 것이 핵심 목표이다. 라우터는 저비용 모델로 먼저 시도하고 검증 실패 시 더 강력한 모델로 순차적으로 에스컬레이션해 비용 대비 성능을 개선하는 정책을 제공한다. 또한 논문 재현과 비교 가능한 벤치마크를 함께 제공해 연구 결과의 반복성과 검증 가능성을 확보한다.

차별점

• 공식 재현 구현과 체크인된 레퍼런스 출력, 그리고 CodeRouterBench 데이터셋을 함께 제공해 논문 결과를 로컬에서 재생할 수 있다는 점이 주요 차별점이다. outputs/ 디렉터리에 예시 결과를 포함해 재현 파이프라인이 참조 가능한 상태로 유지되어 있다. 이 점은 단순한 연구 코드가 아니라 실험 재생성을 염두에 둔 배포라는 측면에서 가치가 있다.
• 성능-비용 트레이드오프를 라우팅 정책의 일차 목표로 삼아 라우터 설계에 비용 테이블과 매트릭스 기반 의사결정이 통합되어 있다는 점이 차별화 요소이다. README와 데이터에 포함된 model_pricing.json을 통해 USD 기반 비용 계산이 가능한 점이 실무 적용에 직접적인 이점을 제공한다. 따라서 단순 성능 최적화가 아니라 비용 통제 요건이 있는 환경에서 유용하다.
• Claude Code·Codex·Opencode 같은 상용 또는 로컬 CLI 백엔드를 바로 연결할 수 있는 런타임 통합 예시와 템플릿을 제공해 실제 워크플로에 빠르게 적용할 수 있다. claude-code-router와 cc-switch 같은 하위 디렉터리는 게이트웨이 또는 프록시 수준에서 라우팅을 실행하도록 설계되어 통합 난이도를 낮춘다. 이로 인해 연구용 재현에서 실무용 파이프라인으로 전환하기가 용이하다.

사용 사례

• 여러 성능·가격 특성을 가진 모델을 조합해 코딩 자동화 파이프라인의 비용을 줄이고자 할 때 유용하다. 라우터는 저비용 모델을 우선 적용하고 검증 실패 시 고성능 모델로 에스컬레이션해 총비용을 통제하면서 성공률을 개선한다. 조직이 모델 호출 비용과 응답 품질 사이에서 정책화된 결정을 필요로 할 때 이 레포의 구현을 적용할 수 있다.
• 연구자가 논문에 보고된 Agent-as-a-Router 결과를 로컬에서 재현하고자 할 때 이 저장소의 데이터와 스크립트를 활용할 수 있다. 제공된 OOD176 및 ID 매트릭스와 체크인된 출력은 논문 표를 동일한 방식으로 재생성하는 데 필요한 자료를 포함하고 있다. 재현 결과는 논문 비교와 추가 실험 설계의 출발점으로 사용 가능하다.
• 로컬 개발 환경에서 Claude Code·Codex·Opencode 같은 CLI 기반 모델을 조합해 자동화된 문제 해결 워크플로를 만들 때 데모 템플릿을 곧바로 적용할 수 있다. demos 디렉터리에는 API 기반 샘플과 상용 CLI 라우터 예시가 있어 실제 프로젝트에 맞춰 모델 목록과 검증기만 교체하면 동작하는 구성이 제공된다. 이 접근은 테스트 기반 자동 수리나 코드 패치 자동화 같은 실무 시나리오에 적합하다.

시작하기

기본 설치 절차는 conda 환경 생성 후 종속성을 설치하고 유닛테스트를 실행하는 흐름으로 진행된다. README에서 제시된 핵심 명령은 conda create -n acrouter python=3.11 -y, python -m pip install -r requirements.txt, python -m pip install -e . 그리고 python -m unittest discover -s tests 이다. 이 명령들은 오프라인 재현을 위한 환경 준비부터 설치 검증까지 필요한 최소 단계로 구성되어 있어 로컬에서 바로 실험 재생을 시작할 수 있다.

요구사항

• Python 3.11 런타임을 요구한다.
• conda 기반 환경 생성이 권장되며 pip를 통한 패키지 설치가 포함된다.
• 오프라인 재현은 추가 API 키 불필요하지만, 상용 백엔드를 연결하려면 해당 프로바이더의 자격증명이 필요하다.

벤치마크