요약 (TL;DR): 이 가이드는 개발자와 코딩 에이전트가 Apache 2.0 라이선스를 따르는 오픈 소스 AI 평가 플랫폼인 Quantiles를 사용하여 로컬에서 AI 평가를 빠르게 실행, 분석 및 비교하는 방법을 보여줍니다. 이 포스트 전반에 걸쳐 SimpleQA Verified 벤치마크를 예시로 사용하여, 명령어를 따라 하고, 평가 결과를 검토하며, 동일한 워크플로우를 위해 자신만의 모델을 구성할 수 있도록 안내합니다.

AI 평가를 실행하는 것은 모델에 프롬프트 (Prompt)를 보내는 것만큼 간단한 경우가 거의 없습니다. 개발자는 "시스템이 개선되었는가?"라는 기본적인 질문에 답하기 전에 데이터셋 (Datasets), 모델 API (Model APIs), 점수 산정 로직 (Scoring logic), 결과 저장 (Result storage) 및 비교 도구 (Comparison tooling)를 연결해야 합니다. 이러한 요소들이 스크립트, 노트북 (Notebooks), 로그 (Logs)에 흩어져 있으면, 매번 다시 실행할 때마다 재현하고 진단하기가 더 어려워집니다. 점수 하나만으로는 모델이 변경된 것인지, 아니면 데이터셋, 프롬프트, 스코어러 (Scorer) 또는 샘플 세트 (Sample set)가 함께 변경된 것인지 밝혀낼 수 없습니다.

퀵스타트: 예시 벤치마크 실행

Quantiles CLI는 명령줄에서 qt로 호출됩니다. 간단한 curl ... | bash 명령어를 통해 X86-64 및 Arm64 시스템의 macOS와 Linux를 지원합니다. 먼저, 이를 사용하여 CLI를 설치하세요:

curl -fsSL https://cli.quantiles.io/install.sh | bash

인터넷에서 직접 가져온 코드를 실행하고 싶지 않다면, 먼저 install.sh 소스 코드를 확인하십시오.

다음으로, 단일 명령어를 사용하여 내장된 벤치마크를 처음부터 끝까지 실행해 보겠습니다. SimpleQA Verified는 Google DeepMind와 Google Research가 제작한 1,000개의 프롬프트로 구성된 벤치마크입니다. 이 벤치마크는 OpenAI의 SimpleQA 벤치마크에서 질문을 재선별하여 잘못된 레이블(incorrect labels), 주제 편향(topical bias), 중복 질문, 모호한 출처 근거와 같은 문제들을 줄였습니다. 각 예시에는 problem에 포함된 짧은 사실적 질문, 참조 answer, 주제 및 답변 유형 메타데이터, 그리고 지원 URL이 포함되어 있습니다.

사용 요금이 발생하지 않는 내장 Quantiles 데모 모델을 사용하여 simpleqa-verified를 실행하려면 다음 명령어를 사용하십시오:

qt run simpleqa-verified

데모 모델의 결과는 출력이 무작위로 생성되기 때문에 평가 워크플로우(workflow)를 보여주기 위한 목적으로만 제공됩니다. 본인의 모델로 평가를 실행하려면 설정(configuration) 섹션을 참조하십시오.

현재 Quantiles 통합 기능은 Google의 공식 데이터셋을 포크(fork)한 quantiles/simpleqa-verified 데이터셋에서 problem 및 answer 컬럼을 읽어옵니다. 해당 벤치마크의 저작권은 원작자에게 있습니다.

위의 qt run 명령어는 fastembed를 기반으로 하는 로컬 임베딩 모델(embedding model)을 사용하여 각 응답과 참조 답변을 임베딩(embedding)한 다음, 코사인 유사도(cosine similarity)를 사용하여 두 값을 비교합니다. 그런 다음 샘플 수준의 유사도 점수를 기록하고 점수 분포를 집계합니다. 이 흐름은 LLM 제공업체를 사용하지 않고도 데이터셋 로딩, 샘플 실행, 점수 산정, 집계, 그리고 평가 메타데이터 및 지표(metrics) 저장을 연습합니다. 이는 벤치마크의 공식 GPT-4.1 자동 평가기(autorater)를 재현하는 것이 아니므로, 결과로 나온 유사도 지표를 SimpleQA Verified 모델의 성능으로 보고하지는 않습니다.

LLM을 평가할 준비가 되면, 상세한 설정 지침을 위해 아래의 모델 설정(model configuration) 문서를 참조하십시오.

Quantiles는 모든 샘플이 평가된 후 집계 지표(aggregate metrics)를 계산하여 표시하며, 평가 이름, 상태, 타임스탬프(timestamps), 소요 시간(duration), 워크플로 입력 및 출력(workflow input and output), 에러 상태(error state), 그리고 집계 지표를 보고합니다.

$ qt run simpleqa-verified

Created run 1
...

샘플 수준 결과 검사 및 분석

완료된 각 평가는 고유의 run_id를 보고합니다. 만약 ID가 더 이상 보이지 않는다면, 다음 명령어를 사용하여 이전 실행(runs) 목록과 해당 ID들을 나열할 수 있습니다:

qt list

특정 실행에 대한 샘플 수준의 세부 정보를 표시하려면 다음 명령어를 사용하십시오. 여기서 run_id 1은 위에서 완료된 SimpleQA Verified 평가를 의미합니다.

qt show 1 --json

--json 플래그를 사용하면 샘플 수준의 결과와 실행 세부 정보를 구조화된 기계 판독 가능(machine-readable) 출력으로 가져올 수 있습니다. JSON 문서는 run, metrics, samples라는 세 가지 최상위 필드를 가집니다. 기록된 단계(step)에 따라, 샘플에는 단계 키(step key), 상태(status), 입력 해시(input hash), 타임스탬프(timestamps), 저장된 출력(stored output), 에러(error) 및 관련 지표(associated metrics)가 포함될 수 있습니다.

두 개의 벤치마크 실행 비교

프롬프트(prompts), 데이터셋(datasets), 코드(code), 인프라(infrastructure), 그리고 모델 자체의 변경을 포함하여 많은 시스템 변경 사항이 모델의 동작에 영향을 미칠 수 있습니다. 두 번의 실행을 비교하면 변경 사항의 효과를 측정하고 검사할 수 있습니다.

simpleqa-verified 평가를 두 번째로 실행하고 두 실행의 ID를 모두 유지하십시오:

qt run simpleqa-verified

이 예시에서, 두 개의 SimpleQA Verified 실행은 run_id 값으로 1과 2를 가집니다:

qt compare 1 2

Comparing runs 1 and 2
                       Run 1              Run 2              Delta
Eval                   simpleqa-verified  simpleqa-verified  SAME
...

qt compare는 확인된 입력(input), 출력(output), 단계(step) 또는 집계 메트릭(aggregate metric) 중 하나라도 다를 경우 상태 코드 1로 종료되고, 실행 결과가 일치할 경우 0으로 종료됩니다. 이는 스크립트나 CI 작업에 유용할 수 있습니다. 하지만 중요한 점은, 상태 코드 1이

아래의 quantiles.toml 설정은 OpenAI 모델을 사용하여 처음 10개의 SimpleQA Verified 샘플을 실행합니다:

[benchmarks.simpleqa-verified]
samples = 10
model = "openai:gpt-5.6-luna"

전체 데이터셋에 대해 평가를 실행하려는 경우 설정에서 samples 키를 생략하세요.

다음 명령어를 실행하면 Quantiles가 일치하는 벤치마크(benchmark) 섹션을 자동으로 로드합니다:

qt run simpleqa-verified

모델을 선택하고 API 키를 설정하세요

Quantiles는 현재 네 가지 모델 제공자(model provider) 접두사(prefix)를 지원합니다. 접두사 이후의 텍스트를 제공자의 모델 ID (model ID)로 전달하므로, 사용 가능한 모델은 제공자의 현재 카탈로그 및 사용자의 계정 권한에 따라 달라집니다. 아래 리포지토리(repository) 예제들은 현재의 설정 형식에서 작동하는 식별자(identifiers)를 보여줍니다.

지원되는 제공자 및 모델 ID 형식

Cloudflare는 OpenAI의 gpt-oss, Llama, Mistral, Gemma, DeepSeek, Qwen, GLM과 같은 제품군(families)의 모델을 포함합니다. 가용성 및 액세스 권한은 Quantiles와 무관하게 변경될 수 있으므로, Cloudflare 모델 카탈로그를 사용하여 정확한 모델 ID를 선택하세요.

API 키를 quantiles.toml, --input JSON 및 소스 제어(source control)에 포함하지 마세요. Quantiles는 환경 변수(environment variables)에서 제공자 자격 증명(credentials)을 읽으므로, 선택한 제공자에 대해 표에 나열된 변수를 설정하세요.

아래의 OpenAI 예제의 경우, qt 명령어를 실행할 동일한 터미널 세션에서 키를 내보내기(export) 하세요:

export OPENAI_API_KEY="<your-openai-api-key>"

모델을 설정 파일로 전달하든 --input 플래그(flag)로 전달하든 자격 증명(credentials)은 동일한 방식으로 구성됩니다.

평가 워크플로를 위한 코딩 에이전트 사용

Quantiles는 Codex나 Claude Code와 같은 코딩 에이전트(coding agents)가 qt CLI를 사용하여 평가를 실행하고, 샘플 수준의 결과(sample-level results)를 검사하며, 실행 결과(runs)를 비교하고, 중단된 작업을 복구할 수 있도록 재사용 가능한 지침을 제공하는 오픈 소스 에이전트 스킬 (open-source agent skill)을 제공합니다. 에이전트가 Quantiles 설정과 로컬 실행 기록(local run history)을 찾을 수 있도록 프로젝트 루트(project root)에서 에이전트를 실행하세요.

먼저, 코딩 에이전트에게 스킬을 설치하도록 요청하세요:

Please install the Quantiles skill at github.com/quantiles-evals/skill

그 다음, 에이전트에게 데모 모델로 SimpleQA Verified 벤치마크를 실행하도록 프롬프트(prompt)를 입력하세요:

Run the simpleqa-verified benchmark and summarize the results.

모델을 평가할 준비가 되면, 다음 프롬프트의 플레이스홀더(placeholder)를 교체하고 모델 설정이 올바른지 확인하기 위해 작은 스모크 테스트(smoke test)를 실행하세요:

Run 10 samples of the simpleqa-verified benchmark using <model provider and model_id>. Confirm that the required provider credentials are available without showing their values; if they are not, stop and tell me what is missing. When finished, summarize the results. Do not run the evaluation until I confirm.

비교 가능한 두 번의 실행 결과가 확보되면, 에이전트에게 변경 사항을 분석하도록 요청하세요:

Compare the two most recent runs for 'simpleqa-verified'. Summarize the aggregate metrics, sample-level results, failures, and any notable errors. Identify the highest-impact issues to review first, and recommend specific next steps.

한계점 및 재현성 (Limitations and reproducibility)

• 내장된 데모 모델은 시드(seed)가 설정되지 않은 무작위 텍스트를 생성합니다. 실행 ID(Run IDs), 타이밍, 응답 및 유사도 값은 실행할 때마다 달라지며, 이러한 결과 중 어느 것도 모델 품질의 증거로 해석해서는 안 됩니다.
• SimpleQA Verified는 웹 검색이나 외부 도구 없이 생성된 답변을 테스트하도록 설계되었습니다. 모델을 평가할 때는 의도한 작업을 측정할 수 있도록 도구 액세스(tool access)를 비활성화하십시오. 코딩 에이전트(coding agent)가 평가 워크플로우를 조율할 수는 있지만, 벤치마크 질문에 답하기 위해 도구를 사용해서는 안 됩니다.
• 새로운 데이터셋을 사용하는 첫 번째 실행은 데이터셋 메타데이터 및 캐시되지 않은 행을 로드하기 위해 네트워크 액세스가 필요합니다. qt CLI는 기본 Hugging Face 리비전(revision)을 사용하므로, 엄격한 재현이 중요한 경우 설정 파일에 데이터셋 저장소(repository), 구성(configuration), 분할(split) 및 리비전을 반드시 기록하십시오.
• 모델 평가는 외부 서비스로 프롬프트(prompt)를 전송하며 사용 요금이 발생할 수 있습니다. 제공업체(provider)의 가용성 및 동작은 Quantiles와 무관하게 변경될 수 있습니다.

결론 (Conclusion)

Quantiles 스택은 AI 평가를 실행, 분석, 비교 및 재현하기 위한 구조화된 로컬 우선(local-first) 시스템을 제공합니다. 내장된 데모 모델을 사용하여 워크플로우가 올바르게 구성되었는지 확인한 다음, 고정된 구성(fixed configuration)을 가진 지원되는 제공업체(예: OpenAI 또는 Anthropic)의 모델로 전환하여 실제 모델 동작을 일관되게 평가할 수 있습니다. 평가 실행, 결과 분석, 실행 비교가 모두 동일한 CLI를 사용하므로, 전체 프로세스를 선호하는 코딩 에이전트를 통해 수행할 수 있습니다.

다른 사람들이 단일 명령으로 실행할 수 있도록 귀하의 벤치마크를 Quantiles에 포함하고 싶다면, Quantiles 이슈 트래커를 통해 요청을 제출하십시오.

문서 및 참고 문헌 (Documentation and references)