kyush/kyush-llm-router

Fork 0

Kyush 1dae7e6719 feat(docs): benchmark

2026-03-25 17:38:51 +09:00

5.5 KiB

Raw Permalink Blame History

Benchmarks

server/benchmarks 는 라우터를 거치지 않는 direct 요청과 라우터를 통과하는 route 요청의 응답 시간과 처리량을 비교하는 CLI 벤치마크 도구다.

엔트리 포인트는 server/benchmarks/index.ts 이고, 루트에서 pnpm run bench, 서버 패키지에서 pnpm run bench 로 실행할 수 있다.

What It Measures

Small Payload: 짧은 POST /v1/chat/completions
Large Payload: 긴 메시지 목록이 포함된 POST /v1/chat/completions
Models Endpoint: GET /v1/models
Real Backend: --backend real 일 때만 추가되는 실제 OpenAI 호환 백엔드용 POST /v1/chat/completions

각 시나리오마다 direct, route 두 경로를 모두 실행하고 아래 지표를 계산한다.

평균 응답 시간
최소/최대 응답 시간
p50, p95, p99
성공/실패 수
처리량(req/s)
route 대비 direct 오버헤드(%)

Commands

루트에서 실행:

pnpm run bench

서버 패키지에서 직접 실행:

cd server
pnpm run bench

기본값은 아래와 같다.

동시 요청 수: 10
총 요청 수: 100
워밍업 요청 수: 5
백엔드 타입: mock

CLI Options

pnpm run bench -- --concurrent 20 --requests 200 --warmup 10
pnpm run bench -- --backend real --backend-url https://api.example.com/v1 --backend-key YOUR_KEY
pnpm run bench -- --output ./benchmark-results.json

지원 옵션:

-c, --concurrent <number>: 동시 요청 수
-r, --requests <number>: 전체 요청 수
-w, --warmup <number>: 워밍업 요청 수
-b, --backend <mock|real>: 대상 백엔드 타입
-u, --backend-url <url>: 실제 백엔드 URL. real 모드에서 필수
-k, --backend-key <key>: 실제 백엔드 API 키. direct 호출과 라우터의 백엔드 인증에 사용
-o, --output <file>: 결과를 JSON으로 저장

real 모드에서는 --backend-url 이 반드시 필요하다. URL 끝의 /v1 과 trailing slash 는 내부에서 제거한 뒤 엔드포인트를 다시 붙인다.

Modes

Mock Backend

mock 모드는 테스트용 mock 서버와 라우터 서버를 둘 다 띄운다.

mock 백엔드: 동적 포트
라우터: http://localhost:3099
DB에 benchmark-backend, benchmark-user 를 준비
사용자와 백엔드 사이 권한을 자동 생성

실행 예시:

pnpm run bench -- --backend mock

Real Backend

real 모드는 direct 요청은 실제 OpenAI 호환 API로 보내고, route 요청은 로컬 라우터를 통해 같은 백엔드로 보낸다.

라우터: http://localhost:3099
DB에 real-backend, benchmark-user 를 준비
사용자의 백엔드 접근 권한을 자동 생성
Real Backend 시나리오의 모델명은 REAL_MODEL 환경 변수를 우선 사용하고, 없으면 default-model 을 사용

실행 예시:

REAL_MODEL=gpt-4o-mini pnpm run bench -- --backend real --backend-url https://api.openai.com/v1 --backend-key $OPENAI_API_KEY

PowerShell 예시:

$env:REAL_MODEL="gpt-4o-mini"
pnpm run bench -- --backend real --backend-url https://api.openai.com/v1 --backend-key $env:OPENAI_API_KEY

Execution Flow

벤치마크 실행 시 내부 동작은 대략 아래 순서다.

라우터 서버를 3099 포트로 기동한다.
mock 모드면 mock 백엔드를 추가로 띄운다.
벤치마크용 사용자, 백엔드, 권한을 DB에 생성 또는 갱신한다.
각 시나리오에 대해 warmup 요청을 먼저 보낸다.
같은 payload 로 direct 요청과 route 요청을 각각 실행한다.
결과를 집계해 표 형태로 출력하고, --output 이 있으면 JSON으로 저장한다.
프로세스 종료 전에 mock 서버와 라우터 서버를 닫는다.

Output

콘솔에는 시나리오별로 Direct, Route 두 행이 출력된다.

Success: 성공 수 / 전체 요청 수
Avg, Min, Max, P50, P95, P99: 밀리초 단위 응답 시간
Errors: 실패한 요청 수
Req/s: 성공 요청 기준 처리량
Overhead: (route.avg - direct.avg) / direct.avg * 100

JSON 출력 예시:

{
  "timestamp": "2025-01-01T00:00:00.000Z",
  "results": [
    {
      "scenario": "Small Payload",
      "mode": "direct",
      "totalRequests": 100,
      "successfulRequests": 100,
      "avgResponseTime": 12.34,
      "minResponseTime": 10,
      "maxResponseTime": 20,
      "p50ResponseTime": 12,
      "p95ResponseTime": 18,
      "p99ResponseTime": 20,
      "errors": 0,
      "throughput": 83.33,
      "totalDuration": 1200
    }
  ]
}

Notes And Caveats

이 도구는 DB 레코드를 일시적으로 사용한다. benchmark-user, benchmark-backend, real-backend 가 없으면 생성하고, 있으면 재사용하거나 갱신한다.
서버 소켓은 정리하지만 벤치마크용 사용자/백엔드 레코드는 종료 시 삭제하지 않는다.
요청 타임아웃은 요청당 30초다.
통계의 totalDuration 은 전체 테스트 벽시계 시간이 아니라 성공 요청 중 최대 응답 시간으로 계산된다. 따라서 Req/s 는 절대적인 부하테스트 처리량보다는 상대 비교 지표로 보는 편이 맞다.
GET /v1/models 시나리오는 인증과 라우팅 오버헤드를 보기 좋지만, 실제 모델 추론 비용은 포함하지 않는다.
real 모드 결과는 외부 API 상태, 네트워크 지연, rate limit 영향까지 포함한다.

5.5 KiB Raw Permalink Blame History