agentperf-local

agentperf-local은 AI 에이전트를 구동하는 속도를 측정합니다. 기록된 에이전트 대화를 OpenAI와 호환되는 모델 서버에 재현(replays)하여 처리량(throughput)과 지연 시간(latency)을 보고합니다. 각 요청에는 실제 에이전트가 하는 것처럼 지금까지의 전체 대화 내용이 포함됩니다. 이는 출력 품질은 측정하지 않고 속도만을 측정합니다.

이미 운영 중인 서버를 벤치마크할 수도 있고, 지정된 모델을 다운로드하여 서버를 시작하고 직접 벤치마킹할 수도 있습니다.

빠른 시작 (Quick start)

uv가 필요합니다. 만약 Python 3.12가 없다면 이를 가져와 설치해 줍니다. Docker와 Rust는 선택 사항입니다. macOS, Linux, Windows를 지원합니다. Windows의 경우, 관리형 실행(managed runs)에는 NVIDIA GPU와 llama.cpp가 필요하며, vLLM과 SGLang은 Linux에서만 실행됩니다.

또한, 이미 OpenAI와 호환되는 API를 사용하여 실행 중인 모델 서버(예: llama.cpp, LM Studio, vLLM, SGLang 또는 Ollama)나 도구가 시작할 수 있는 서빙 프레임워크가 필요합니다. 번들된 레시피는 각 레시피가 고정하는 정확한 버전의 llama.cpp(PATH에 있는 llama-server), NVIDIA GPU용 vLLM 또는 SGLang, 또는 Apple Silicon용 Splash를 사용합니다. 이 도구는 프레임워크를 설치하지 않습니다.
agentperf-local deployment-options --profile-id <id>를 실행하면 해당 장치에서 어떤 프레임워크로 레시피를 서비스할 수 있는지 확인할 수 있습니다.

uv tool install agentperf-local
agentperf-local

설치 없이 사용하려면 uvx agentperf-local을 실행하세요. pipx install agentperf-local도 작동합니다.

소스 코드를 체크아웃하여 작업하는 경우:

git clone https://github.com/ArtificialAnalysis/aa-agentperf-local.git
cd aa-agentperf-local
uv sync
...

아래 예제들은 체크아웃 상태에서 uv run agentperf-local을 사용하는 경우입니다. 도구를 설치했다면, uv run을 생략하세요.

TUI(Textual User Interface)를 사용하면 모델 선택, 설정 구성 및 실행 과정을 안내받을 수 있습니다. 화살표 키는 이동, Enter는 계속 진행, Escape는 뒤로 가기, ?는 도움말 열기, q는 종료입니다. 플래그를 사용하여 설정을 미리 채우려면 agentperf-local tui를 사용하세요. TEXTUAL_TUI.md를 참조하십시오.

TUI 없이 실행하려면, 카탈로그 프로필과 설치된 프레임워크를 선택하세요:

uv run agentperf-local managed-run \
  --profile-id qwen38-27b-q4-k-m \
  --framework llama-cpp \
...

managed-run은 고정된 모델을 Hugging Face 캐시에 다운로드하고, 모든 파일의 SHA-256을 확인하며, localhost에서 서버를 시작하고, 리플레이를 실행한 다음, 서버를 중지합니다. 이 도구가 실행할 수 있는 모든 레시피는 recipes/에 있는 YAML 파일이며, 모델별로 하드웨어별로 분류되어 있습니다.

qwen38-27b-splash-dflash 레시피는 Splash에서 작동합니다.
이는 Apple Silicon(M3 이상, macOS 26.4 이상)용 Inco AI의 Metal 엔진입니다.
brew install incoai/tap/splash로 설치할 수 있습니다. 이 레시피는 Splash 1.2.1을 고정하며, incoai/Qwen3.8-27B-Splash 패키지를 커밋별로 사용합니다. managed-run은 패키지 자체를 다운로드하고 검증한 다음, 해당 스냅샷에서 Splash 서버를 시작하므로 Splash는 절대 더 새로운 버전을 해결하지 않습니다. Splash 1.2.1은 도구(tools)가 있는 요청에 대해 ignore_eos를 준수하므로 이 레시피는 exact 정책을 실행합니다. 그 KV 캐시는 항상 8비트입니다:

uv run agentperf-local managed-run \
  --profile-id qwen38-27b-splash-dflash \
  --framework splash \
...

기본 실행 (The default run)

기본 리플레이는 agentperf-default-v1입니다. 이는 168 모델 턴을 가진 8개의 기록된 에이전트 작업으로 구성됩니다. 이 작업은 모든 턴이 기록된 토큰 수를 생성하는 exact 출력 정책을 사용합니다. 이것이 비교 가능한 실행(comparable run)입니다.

--replay aa-mini-v1는 6턴의 합성 리플레이를 선택합니다. 이는 빠른 설치 확인용이며, 그 결과는 비교할 수 없습니다.

컨텍스트 요구 사항 (Context requirement)

전체 실행을 위해서는 배치 크기(batch size) 1에서 65,536 토큰의 컨텍스트가 필요합니다. 모든 카탈로그 프로파일은 이 컨텍스트로 실행됩니다. 131,072 토큰처럼 더 많은 것을 제공하는 연결된 서버도 전체로 간주됩니다.

기본 리플레이의 가장 큰 턴은 약 58,000 토큰이 필요하므로, 오직 전체인 65,536에서만 실행됩니다. 만약 장치에 이것을 담을 수 없다면, 8,192 토큰이 필요한 aa-mini-v1로 여전히 설정을 확인할 수 있습니다:

uv run agentperf-local managed-run \
  --profile-id gemma4-12b-it-q4-0 \
  --framework llama-cpp \
...

TUI에서는 uv run agentperf-local tui --replay aa-mini-v1로 시작하고 설정(Setup) 화면에서 더 작은 컨텍스트를 선택하세요. 65,536 토큰 미만의 실행은 reduced: true로 표시되며 전체 컨텍스트 결과와 비교할 수 없습니다.

연결된 서버의 경우, 해당 도구는 실행 시작 시 컨텍스트를 읽습니다:
llama.cpp의 meta.n_ctx, vLLM 및 SGLang의 max_model_len, 또는
Splash 상태 엔드포인트의 maximum_context_tokens입니다. 이 중 어느 것도 보고하지 않는 서버는 비교 불가로 기록됩니다.

연결된 서버

이미 실행한 서버를 대상으로 run을 지정하세요:

uv run agentperf-local run \
  --base-url http://127.0.0.1:8080/v1 \
  --model served-model \
...

서버의 기본 URL과 보고하는 모델 이름을 사용하세요:

exact 정책은 OpenAI API에 포함되지 않는 ignore_eos를 전송합니다.
리플레이 전에, run과 managed-run은 서버가 이를 준수하는지 확인합니다. 만약 그렇지 않다면, 중단하고 플래그를 변경하라고 이름 붙입니다. TUI는 대신 recorded 정책으로 전환되고 그렇게 알려줍니다.

Ollama는 ignore_eos를 준수할 수 없습니다. 이 도구는 실행 전에 Ollama를 감지하고 경고합니다. 그러면 해당 실행은 모델이 자체적으로 멈추도록 허용하고, 종단 간 지연 시간(end-to-end latency)을 정규화된 추정치로 보고하는 recorded 정책을 사용합니다. 그 결과는 exact 실행과 직접 비교할 수 없습니다.

API 키를 전송하려면 환경 변수에 넣고 해당 변수 이름을 --api-key-env와 함께 전달하세요. 어떤 플래그도 실제 키 값을 받지 않습니다.

실제 도구 호출

기본적으로 리플레이는 턴(turn) 사이의 도구 시간을 건너뜁니다. run --tool-mode fixed_delay는 각 턴 후에 기록된 도구 시간만큼 대기합니다. run --tool-mode live는 기록된 셸 명령을 Docker 컨테이너에서 실행하므로 도구 시간이 실제입니다.
이 모드는 선택 사항이며 Docker와 사전 구축된 이미지가 필요합니다. 빌드 스크립트는 소스 체크아웃에 있습니다. 이들은 bash 스크립트이므로 Windows에서는 Git Bash 또는 WSL에서 실행하세요:

scripts/install-swebench-validation.sh   # arm64 호스트 전용, 1회만
scripts/build-default-containers.sh

...

보안 주의사항:

• 기록된 명령어는 신뢰할 수 없는 입력입니다. Docker가 위험을 줄여주지만 보안 경계는 아닙니다.
• Docker 데몬에 대한 접근은 대부분의 호스트에서 root 권한과 동일합니다.
• 컨테이너는 기본적으로 네트워크가 없지만, 리플레이 매니페스트(replay manifest)를 통해 요청할 수 있습니다. --live-network none을 전달하여 네트워크가 없도록 강제하세요.
• 작업 공간(task workspace)은 읽기/쓰기로 마운트됩니다. --live-workspace-root를 전달하지 않으면 출력 디렉토리 아래에 위치합니다.
• 스크립트는 서드파티 이미지를 가져오거나 빌드하고 GitHub에서 SWE-bench 하네스(harness)를 클론합니다.

Rust 클라이언트 (실험적)

기본 클라이언트는 Python입니다. 선택적인 Rust 클라이언트는 Python 외부에서 타이밍을 기록합니다. Rust 툴체인이 필요합니다:

uv sync --extra rust
uv run agentperf-local tui --client rust

도구가 설치되어 있다면, 대신 uv tool install 'agentperf-local[rust]'를 사용하세요. 일반적인 uv sync는 확장 기능을 다시 제거합니다. 두 클라이언트 모두 동일한 메트릭을 생성합니다.

결과 제출(Submitting results)

제출은 선택 사항이며, 요청하지 않는 한 아무것도 업로드되지 않습니다. prepare-submission이 제출 파일을 빌드하고, submit이 이를 전송하며, submission-status가 이를 다시 읽어옵니다. 시작한 서버에서 실행하려면 run --attached-server FILE이 필요합니다. Artificial Analysis에 무엇이 전송되는지에 대한 자세한 내용은 SUBMITTING.md를 참조하세요.

명령어(Commands)

결과(Results)

실행 시 새 디렉토리가 생성됩니다:

results/my-server/
├── turns.jsonl
├── tasks.json
...

summary.json에는 헤드라인 수치, 즉 초당 출력 토큰(output tokens per second)과 중앙값 및 p95 첫 번째 토큰 시간(first-token) 및 턴 시간(turn times)이 저장됩니다. 이 파일은 마지막에 작성되므로, 실행 중 오류가 발생하면 요약 정보가 없습니다. 관리형 실행(managed run)의 경우 서버 로그와 배포 기록도 함께 작성됩니다. FORMATS.md에서 각 파일에 대해 설명합니다.

결과는 비공개입니다. 여기에는 경로, 모델 레이블, 오류가 포함될 수 있습니다. 실행을 시작하면 기록된 프롬프트가 모델 서버로 전송되므로, 원격 URL은 해당 내용을 사용자의 기기 밖으로 보냅니다.

개발(Development)

make lint        # ruff check, ruff format --check, ty check
make test        # pytest
make test-rust   # Rust 코어 테스트

CI는 이러한 검사 및 Python과 Rust 클라이언트의 동등성 테스트를 수행합니다. 전체 목록과 코드 규칙은 AGENTS.md를 참조하십시오.

문서(Documentation)

• Recipes: 관리형 실행 레시피 및 추가 레시피 작성 방법 안내.
• Textual TUI: 옵션, 키, 화면 구성.
• Architecture: 측정 규칙, 증거 경계(evidence boundary), 패키지 레이아웃.
• Data formats: 입력, 출력 및 스키마.
• Submitting: 업로드할 내용과 사용 방법 안내.

agentperf-local은 Artificial Analysis에서 구축하고 유지 관리합니다. 코드는 Apache-2.0 라이선스 하에 배포됩니다. Artificial Analysis 이름과 로고는 코드 라이선스의 적용을 받지 않습니다.