서론

Gemini API의 모델 카탈로그(Model Catalog)는 자신도 모르는 사이에 늘어나거나, 프리뷰(Preview) 버전이 교체되기도 합니다.

그래서 models.list로 취득한 모델 목록을 스냅샷(Snapshot)으로 저장하고, 새로 발견된 모델이나 지난번에 에러가 발생했던 모델, 비교를 위한 베이스라인 모델(Baseline Model)을 간단한 테스트 케이스로 평가하는 로컬 도구를 만들었습니다.

평가 결과는 JSON으로 저장하며, 브라우저상의 대시보드(Dashboard)에서 모델별로 비교할 수 있습니다.

참고로, 이 기사에서 다루는 실행 결과는 Gemini API의 무료 티어(Free tier)에서 취득한 것입니다. 무료 티어에서는 할당량(Quota)의 제약을 받기 쉬우므로, 수치는 모델 성능을 확정하기 위한 벤치마크(Benchmark)가 아니라, 도구의 동작 확인 및 추가 검증을 위한 입구로 봐주시기 바랍니다.

만든 것

이번 도구는 주로 다음과 같은 작업을 수행합니다.

• Gemini API의 models.list로부터 모델 목록을 취득합니다.
• config/evaluation.json의 modelNameAllowList로 대상 모델을 압축합니다.
• 이전에 저장한 스냅샷과 비교하여 신규 모델을 감지합니다.
• 신규 모델, 지난 평가에서 errorRate > 0이었던 모델, baselineModels로 지정한 모델을 평가합니다.
• --all 옵션을 붙인 경우, 압축 후의 모든 모델을 평가합니다.
• Score / Latency / Error Rate / New / Evaluated / Decision을 대시보드에 표시합니다.
• 과거 실행(run)을 포함하여, 모델별 최신 평가 결과를 목록화합니다.

실행은 Node.js로 수행합니다.

npm run monitor
npm run serve

직접 실행하는 경우는 다음과 같습니다.

node src/monitor.js
node server.js

API 키 없이 동작 확인을 하고 싶은 경우를 위해 데모 모드(Demo mode)도 준비되어 있습니다.

npm run monitor:demo

처리 흐름

현재의 일반적인 실행 흐름은 대략 다음과 같습니다.

포인트는 신규 모델만을 평가하는 것이 아니라, 일반 실행 시에도 baselineModels를 매번 평가하도록 하고 있다는 점입니다. 이를 통해 새로운 모델이 발견되었을 때, 기존 비교 대상과 동일한 실행(run) 내에서 나란히 배치하기 쉬워집니다.

또한, 직전 실행에서 errorRate > 0이었던 모델은 다음번에도 평가 대상에 포함됩니다. 일시적인 429 또는 503 에러로 실패한 모델을 다음 실행에서 다시 잡아낼 수 있도록 하기 위함입니다.

API 키 관리

API 키는 .env에 둘 수 있도록 했습니다.

GEMINI_API_KEY=your-api-key

코드상에서는 GEMINI_API_KEY 외에도 GOOGLE_API_KEY를 참조하지만, .env.example에서는 GEMINI_API_KEY를 안내하고 있습니다.

.env는 .gitignore에 포함하며, 리포지토리(Repository)에는 .env.example만 올려둡니다.

모델 카탈로그 저장

models.list에서 취득한 모델 정보는 정규화하여 data/models.snapshot.json에 저장합니다.

저장하는 주요 항목은 다음과 같습니다.

{
"name": "models/gemini-2.5-flash",
"id": "gemini-2.5-flash",
...

신규 모델 판정에는 name을 사용합니다. 이전 스냅샷에 존재하지 않는 name이 있으면 신규 모델로 취급합니다.

평가 설정

평가 설정은 config/evaluation.json에 모아두었습니다.

{
"baselineModels": [
"gemini-2.5-pro",
...

baselineModels는 일반 실행 시 매번 평가하는 비교용 모델입니다.

modelNameAllowList는 models.list 결과에서 평가 후보를 압축하기 위한 문자열 배열입니다. 현재 설정에서는 "gemini"를 포함하는 모델이 대상이 됩니다.

evaluationCases에는 각 모델에 던질 평가 케이스를 정의합니다. 현재는 경량 평가로서 다음과 같은 케이스를 사용하고 있습니다.

• 지정한 키를 가진 JSON을 반환할 수 있는가
• 일본어 요약에 기대하는 단어가 포함되어 있는가
• 간단한 추론 문제에 답할 수 있는가

점수(Score)는 단순한 합격/불합격이 아니라, 케이스 내에서 기대치와 얼마나 일치했는지를 0에서 1 사이의 값으로 가집니다.

평가 결과 저장 방식

평가 결과는 data/evaluation-runs.json에 저장합니다.

1회의 실행(run)에는 시작 시각, 종료 시각, 모델별 평균 점수(Score), 평균 레이턴시(Latency), 에러율(Error Rate), 케이스별 상세 정보가 포함됩니다.

에러가 발생한 케이스도 버리지 않고 저장합니다. 예를 들어 API 측에서 429 또는 503 에러가 반환된 경우, 대시보드 상의 에러율(Error Rate)을 통해 상세 메시지를 확인할 수 있습니다.

data/events.json에는 모델 체크, 신규 모델 감지, 재시도 대상 추가, 평가 완료 등의 이벤트를 저장합니다. 대시보드의 타임라인(Timeline)은 이 이벤트 이력을 표시합니다.

대시보드

실제로 무료 티어(Free tier)에서 실행한 결과를 표시한 화면이 다음과 같습니다.

참고로, 이 화면의 수치는 단발성 간이 평가 결과이며, 엄격한 모델 성능 랭킹을 나타내는 것은 아닙니다.

대시보드는 server.js로 실행합니다.

npm run serve

브라우저에서 여는 URL은 다음과 같습니다.

현재 화면은 주로 세 가지 영역으로 구성되어 있습니다.

• Model Comparison
• Timeline
• Model Catalog

Model Comparison

Model Comparison은 최신 실행(run)뿐만 아니라 과거의 실행 결과도 확인합니다.

모델별로 '가장 최신 평가 결과'를 하나씩 추출하여, 현재 models.snapshot.json에 존재하는 모델만 표시합니다. 이를 통해 직전의 통상적인 실행에서 베이스라인(baseline)만 평가했을 경우에도, 과거에 평가 완료된 다른 모델들을 목록에 남겨둘 수 있습니다.

정렬 순서는 다음과 같습니다.

• 점수(Score)가 높은 순
• 점수가 같을 경우 레이턴시(Latency)가 낮은 순
• 이 또한 같을 경우 모델 ID(model id) 문자열 순

New는 최신 실행에서 신규 모델로 평가된 경우에만 표시합니다. --all 실행 시에는 모든 모델을 평가한다는 의미가 강하므로, New는 모두 -로 표시됩니다.

Evaluated는 최신 실행 결과라면 Current, 과거 실행 결과라면 날짜를 표시합니다.

Decision은 화면 측에서 다음 기준에 따라 표시합니다.

• Adopt: 점수(Score)가 85% 이상이고, 에러율(Error Rate)이 0%
• Watch: 점수(Score)가 65% 이상
• Skip: 그 외

랭킹 읽는 법과 한계

이 화면을 Gemini에게 보여주고 리뷰를 요청한 결과, 레이턴시(Latency) 정렬 방식, 동일한 점수를 가진 모델이 여러 개 존재하는 점, 에러가 발생한 모델에도 Watch가 붙는 점에 대해 지적을 받았습니다. 또한, 이번 결과는 무료 플랜에서 실행한 것이므로 할당량(quota)이나 혼잡도의 영향을 받기 쉬운 조건입니다. 이 점들은 모두 이 화면을 '엄격한 모델 순위표'로 취급하지 않기 위해 중요한 관점입니다.

먼저, 레이턴시(Latency)는 이 경량 평가를 1회 실행했을 때의 평균 응답 시간에 불과합니다. 경량 모델보다 다른 모델이 더 빠르게 표시되었다고 해서, 그것만으로 항상 빠르다고 판단할 수는 없습니다. API 측의 혼잡도, 네트워크, 시도 타이밍의 영향을 받기 때문에 성능 비교에 사용하려면 여러 번 실행했을 때의 중앙값(median)이나 분산(variance)도 살펴볼 필요가 있습니다.

또한, 현재의 점수(Score)는 3개의 간이 케이스를 부분 점수를 포함하여 집계한 것입니다. 케이스 수가 적기 때문에 여러 모델이 83%나 92%와 같이 동일한 표시 값을 갖는 일이 충분히 발생할 수 있습니다. 점수가 비슷할 경우, 이 대시보드는 레이턴시(Latency)가 작은 순서대로, 그리고 레이턴시까지 같다면 모델 ID(model id) 순으로 정렬합니다. 이 순위는 채택 결론이 아니라 확인 순서를 부여하기 위한 보조 표시입니다.

에러 처리에도 과제가 있습니다. 현재 판정 방식으로는 점수(Score)가 65% 이상이면 에러율(Error Rate)이 0%가 아니더라도 Watch로 표시됩니다. 따라서 3개 케이스 중 1개 케이스에서 503 에러가 발생한 모델에도 Watch가 표시됩니다.

표시될 수 있습니다. 실제 채택 여부를 판단하기에는 기준이 다소 완만하므로, 에러가 발생한 run을 「평가 보류」로 분류하거나 Error Rate에 따른 강력한 감점을 적용할 여지가 있습니다.

또한, Robotics와 같이 특정 용도에 특화된 것으로 보이는 모델이 범용 모델과 동일한 점수를 받더라도, 이 테스트만으로 동등한 성능이라고 단정할 수는 없습니다. 현재의 평가 케이스는 JSON 출력, 요약, 간단한 추론뿐이며, 로보틱스 용도나 장문 처리 등의 적합성은 측정하고 있지 않기 때문입니다.

이 대시보드의 수치는 모델 카탈로그(Model Catalog)의 변화를 발견하여 추가 검증 후보를 좁히기 위한 초기 관측치로 취급하고, 실제 모델 선정에는 용도에 맞는 평가 케이스와 반복 측정을 추가하는 것이 좋아 보입니다.

Timeline

Timeline에는 최신 이벤트를 최대 8개까지 표시합니다.

예를 들어, 모델 카탈로그 체크, 재시도(retry) 대상 추가, 평가 완료, 에러 등입니다. 실행 후에 어떤 일이 일어났는지 가볍게 추적할 수 있도록 구성했습니다.

Model Catalog

Model Catalog에는 현재 스냅샷에 저장된 모델을 표시합니다.

모델명, ID, input / output token limit, supportedGenerationMethods의 일부를 카드 형식으로 확인할 수 있습니다.

모든 모델을 평가하는 모드

통상적인 실행에서는 평가 대상을 좁혀서 진행합니다.

• 신규 모델
• 최근 run에서 에러가 발생한 모델
• baseline 모델

반면, 현재 가지고 있는 카탈로그 전체를 다시 평가하고 싶을 때는 --all을 사용합니다.

npm run monitor:all

또는 직접 실행합니다.

node src/monitor.js --all

--all에서는 modelNameAllowList로 필터링된 현재의 모든 모델을 평가합니다.

무료 티어(Free tier)의 API 키로 실행할 경우, 모델 수나 케이스 수에 따라 429 에러가 발생하기 쉬우므로 주의가 필요합니다.

실행 중 로그

평가는 시간이 걸리기 때문에, 현재 어떤 모델과 케이스를 평가하고 있는지를 콘솔에 출력합니다.

[1/3] Evaluating gemini-2.5-pro
[1/3] json-schema
OK score=1.00 latency=420ms

에러 발생 시에는 모델명, 케이스 ID, 레이턴시(latency), 에러 메시지를 출력합니다.

ERROR model=gemini-2.5-pro case=json-schema latency=164ms
generateContent failed for gemini-2.5-pro: 503 ...

이 정보는 run의 케이스 상세 정보에도 저장되므로, 나중에 대시보드에서도 확인할 수 있습니다.

실제 API를 통해 발견한 주의점

실제로 Gemini API를 사용해 보니 몇 가지 조정하고 싶은 점들이 보였습니다.

429 quota exceeded

무료 티어나 낮은 할당량(quota) 상태에서는 모든 모델을 평가할 때 429 에러가 발생하기 쉽습니다.

따라서 평소에는 통상 실행을 통해 신규 모델, 재시도 대상, baseline 모델만 평가하고, 필요한 경우에만 --all을 사용하는 방식으로 운영하고 있습니다.

503 high demand

일부 모델에서는 일시적으로 503 에러가 반환될 수 있습니다.

이 경우 모델의 성능이 나쁘다기보다, 평가 시점에 API 측이 혼잡했을 가능성이 있습니다. 그래서 지난번에 errorRate > 0이었던 모델을 다음번에도 평가 대상으로 남기도록 했습니다.

generateContent 미지원 모델

models.list에는 반드시 generateContent에 사용하는 모델만 포함되어 있다고 할 수 없습니다.

현재 구현에서는 modelNameAllowList로 필터링한 모델을 평가 대상으로 삼고 있으므로, 필요에 따라 modelNameAllowList를 조정합니다. 향후에는 supportedGenerationMethods에 generateContent가 포함된 모델만 평가하는 필터를 넣으면 더욱 다루기 쉬워질 것 같습니다.

향후 하고 싶은 일

앞으로는 다음과 같은 부분들을 개선하고 싶습니다.

generateContent

• 대응 모델만 평가 대상으로 설정 - 429 / 503 에 대해 백오프 (Backoff)를 포함한 재시도 (Retry) 로직 추가
• 요청 (Request) 사이에 대기 시간을 넣을 수 있도록 개선
• 여러 번 평가하여 레이턴시 (Latency)의 중앙값 및 편차 표시
• 에러가 발생한 run을 랭킹 판정에서 분리
• 평가 케이스를 늘려 실제 사용 환경에 가까운 비교 수행
• 대시보드에서 평가를 실행할 수 있는 버튼 추가
• run 간의 비교 및 스코어 추이를 볼 수 있도록 개선

요약

Gemini API의 모델 카탈로그 (Model Catalog)는 계속 변화하기 때문에, 수동으로 계속 추적하는 것은 다소 어렵습니다.

이번 사례처럼 모델 목록의 스냅샷 (Snapshot), 신규 탐지, 간이 평가, 이력 저장, 대시보드 표시를 통합해 두면, 새로운 모델을 발견했을 때 초기 판단이 훨씬 수월해집니다.

아직 MVP (Minimum Viable Product) 단계이지만, 일반 실행과 --all을 분리함으로써 평상시의 가벼운 모니터링과 필요할 때의 전체 평가를 구분하여 사용할 수 있게 되었습니다.

Discussion