Tokenflood

Tokenflood는 특정 프롬프트 및 응답 데이터가 필요 없이 임의의 부하 프로파일을 실행할 수 있는, 명령어 조정형 LLM용 부하 테스트 도구입니다.
원하는 프롬프트 길이, 접두사 길이(prefix lengths), 출력 길이(output lengths), 요청 속도(request rates)를 정의하면, tokenflood가 이 워크로드를 시뮬레이션합니다.

Tokenflood는 다양한 제공업체(providers), 하드웨어, 양자화(quantizations), 또는 프롬프트를 사용할 때 지연 시간(latency)이 어떻게 변하는지 쉽게 탐색할 수 있게 해줍니다.

일반 사용 시나리오
- 예시: 잠재적인 프롬프트 최적화 효과 평가
- 예시: 사람들이 언제부터 지연 시간을 훔치기 시작하는지 알아내기
전문 서비스
설치(Installation)
빠른 시작(Quick Start)
구성(Configuration)
결과 시각화(Visualizing Results)
토큰 계산(Counting tokens)
휴리스틱 부하 테스트 설명(Heuristic Load Testing Explained)
안전(Safety)

일반 사용 시나리오

자체 호스팅 LLM의 부하 테스트.
모델, 하드웨어, 양자화 및 프롬프트 최적화가 지연 시간, 처리량(throughput), 비용에 미치는 영향 평가.
데이터를 전송하기 전에, 로드 유형별로 호스팅된 LLM 제공업체의 일일 지연 시간 변화를 평가.

이 그래프에서는 네 가지 프롬프트 구성을 비교합니다.
파란색 선은 약 3000개의 입력 토큰, 1000개의 접두사(prefix) 토큰, 그리고 200개의 출력 토큰을 가진 기본 모델 Gemma4-26B-A4B를 나타냅니다.
녹색 선은 동일한 모델이지만, 접두사 섹션이 1000개 대신 2000개로 더 길게 설정된 경우를 나타내며, 예를 들어 정적(static) 부분이 모두 시작 부분에 오도록 프롬프트를 재배열하여 달성할 수 있습니다.
빨간색 선은 동일한 모델이지만, 출력 토큰을 120개로 줄인 경우를 나타냅니다. 이는 모델에게 간결하게 작성하도록 지시하거나 과도하게 생각하지 않도록 요청하는 방식으로 하거나, 구조화된 출력 형식(structured output format)을 조정함으로써 달성할 수 있습니다.
마지막으로, 회색 선은 두 가지 최적화를 모두 결합한 것으로, 이들이 상호 보완적이며 둘 다 추구할 가치가 있음을 보여줍니다.

전반적으로 합리적인 최적화만으로도 매우 의미 있는 지연 시간(latency) 개선을 확인할 수 있습니다. Tokenflood를 사용하면 코드베이스나 인프라에 변경 사항을 구현하기 전에 프롬프트 매개변수 또는 모델 개선을 위한 가치 있는 목표를 찾을 수 있습니다.

예시 2: 사람들이 언제 당신의 지연 시간을 훔치기 시작하는지 알아내기

대규모 제공업체(large providers)에 대한 부하 테스트는 그들의 데이터센터가 거대한 공유 자원이기 때문에 실제로 큰 의미가 없습니다. 한 회사나 사용자가 이들에게 미치는 영향이 크지 않더라도, 이러한 공유 자원은 일일 비즈니스 시간과 일치하는 경우가 많은, 하루 중 지연 시간 변화(intraday latency variations)를 겪습니다.

Tokenflood는 또한 관찰 테스트를 사용하여 실제 운영 환경에 배포하기 전에 이러한 패턴을 평가할 수 있도록 합니다.

🛠️ 전문 서비스 (Professional Services) 🛠️

다음과 같은 전문 지원이 필요하다면

LLM의 정확도(accuracy), 지연 시간(latency), 처리량(throughput), 또는 비용 최적화
사용 사례에 맞게 오픈 모델 파인튜닝(fine-tune)
LLM 관찰 가능성(observability) 개선
사용자 지정 AI 시스템 설계 및 구축

[email protected] 또는 linkedin에서 언제든지 연락 주십시오.

설치 (Installation)

pip install tokenflood

빠른 시작 (Quick Start)

빠른 시작을 위해, vllm이 설치되어 있는지 확인하고 작은 모델을 서빙하세요:

pip install vllm
vllm serve HuggingFaceTB/SmolLM-135M-Instruct --enable-prompt-tokens-details

그 후, 기본 설정 파일을 생성하고 첫 실행을 수행합니다:

# 이 명령어는 tiny 시작 파일들: load_test.yml, observation.yml 및 endpoint.yml을 생성합니다.
tokenflood init
# 그 후에 해당 파일들을 검사한 다음, 부하 테스트를 수행할 수 있습니다.
...

설정 (Configuration)

부하 테스트 사양 (Load Test Specs)

부하 테스트 사양을 사용하면 실행하고자 하는 부하 테스트를 정의합니다. 각 테스트는 초당 요청 수가 다른 여러 단계(phases)를 가질 수 있습니다. 모든 단계는 동일한 길이와 전송되는 부하의 유형을 공유합니다.

tokenflood init을 호출할 때 생성되는 부하 테스트 사양은 다음과 같습니다:

type: load_test
name: starter
requests_per_second_phases: # 다른 요청률을 가진 단계를 정의합니다
...

관찰 사양 (Observation Specs)

관찰 사양을 사용하면 엔드포인트에 대한 더 긴 실행 시간의 관찰을 정의할 수 있습니다. 몇 시간에 걸친 총 관찰 길이와 분 단위의 폴링 간격은 물론, 특정 시점에 얼마나 많은 양의 어떤 유형의 요청을 보낼지 정의할 수 있습니다. 이는 하루 동안 LLM 제공업체의 지연 시간을 관찰하는 데 유용합니다.

tokenflood init을 실행하여 생성되는 관찰 사양은 다음과 같습니다:

type: observation
name: starter
duration_hours: 1.0             # 총 테스트 길이: 1시간
...

엔드포인트 사양 (Endpoint Specs)

엔드포인트 사양 파일을 사용하면 테스트의 대상을 결정할 수 있습니다. Tokenflood는 내부적으로 litellm을 사용하며, litellm이 지원하는 모든 제공업체(providers)를 지원합니다.

여기서 빠른 시작(quick start)에서 가져온 예시 엔드포인트 스펙 파일이 있습니다:

provider: hosted_vllm
model: HuggingFaceTB/SmolLM-135M-Instruct
base_url: http://127.0.0.1:8000/v1
...

매개변수 설명:

provider: litellm에서 사용하는 제공업체(provider) 매개변수로, 다양한 제공업체가 다른 API를 가지고 있기 때문에 엔드포인트와 정확하게 상호 작용하는 방법을 결정하는 데 사용됩니다.
model: 주어진 엔드포인트에서 사용할 특정 모델입니다.
base_url: 자체 호스팅하거나 제공업체의 특정 지역에 있는 엔드포인트를 사용하는 경우 중요합니다.
api_key_env_var: API 키로 사용할 환경 변수 이름입니다. 이를 지정하면, AZURE_KEY_FRANKFURT와 AZURE_KEY_LONDON처럼 다른 지역의 동일한 제공업체에 대한 여러 API 키를 환경 파일 변경 없이 관리할 수 있습니다.
deployment: azure와 같은 일부 제공업체에서 필수입니다.
extra_headers: 특정 제공업체에서 모델을 선택하는 데 유용할 수 있습니다 (예: sagemaker 추론 구성 요소).
extra_body: 채팅 템플릿 kwargs를 추가하는 데 유용할 수 있습니다 (예: 추론 비활성화).

Tokenflood는 이 모든 매개변수를 litellm의 completion 호출로 전달합니다. 더 자세히 알아보고 싶다면 litellm completion 호출 공식 문서를 참고하세요.

엔드포인트 예시

자체 호스팅 VLLM

provider: hosted_vllm
model: meta-llama/Llama-3.1-8B-Instruct
base_url: http://127.0.0.1:8000/v1

Openai

provider: openai
model: gpt-4o-mini

환경 변수: OPENAI_API_KEY

Bedrock

provider: bedrock
model: anthropic.claude-3-sonnet-20240229-v1:0

환경 변수: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME

AWS Sagemaker Inference Endpoints

provider: sagemaker_chat
model: your-sagemaker-endpoint

환경 변수: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME

Azure

provider: azure
deployment: gpt-4o
model: gpt-4o
...

환경 변수: AZURE_API_KEY

Gemini

provider: gemini
model: gemini-2.5-flash-lite-preview-09-2025

환경 변수: GEMINI_API_KEY

Anthropic

provider: anthropic
model: claude-3-5-sonnet-20240620

환경 변수: ANTHROPIC_API_KEY

결과 시각화 (Visualizing Results)

Tokenflood는 결과를 시각화하고 여러 실행 및 지표를 비교할 수 있는 내장 프런트엔드를 제공합니다. 로드 테스트를 시작한 것과 같은 작업 디렉토리에서 tokenflood viz를 실행하세요.

이 공개 huggingface space를 확인하여 gradio 프런트엔드를 살펴볼 수 있습니다.

토큰 개수 세기 (Counting tokens)

Tokenflood는 또한 기존 프롬프트의 토큰을 계산하는 내장 기능을 제공하여 토큰 개수를 어디서부터 시작해야 할지 아이디어를 얻을 수 있게 합니다. 이 토큰 카운팅은 텍스트 기반 및 채팅 기반 프롬프트뿐만 아니라 API 기반 및 로컬 토큰화도 지원합니다.

텍스트 기반 프롬프트의 로컬 토큰화를 다음과 같이 실행할 수 있습니다:

tokenflood count -f text prompt1.txt prompt2.txt promptN.txt --tokenizer Qwen/Qwen3.5-35B-A3B

또는 채팅 기반 형식으로 다음과 같이 사용할 수 있습니다:

tokenflood count -f chat prompts.jsonl --tokenizer Qwen/Qwen3.5-35B-A3B-FP8

채팅 기반 및 텍스트 기반 프롬프트 모두 여러 파일을 지정할 수 있도록 합니다.

API 기반 토큰화는 openai, anthropic, gemini, azure, bedrock, vertex ai 모델에서 사용할 수 있습니다. 다음과 같이 사용할 수 있습니다:

tokenflood count -f chat prompts.jsonl --endpoint my_endpoint_spec.yml

여기서 my_endpoint_spec.yml은 지원되는 제공업체 중 하나에 대한 표준 tokenflood 엔드포인트 사양입니다.

토큰 개수 세기 결과로, 프롬프트의 입력 및 출력 토큰에 대한 최소/평균/최대값과 모든 제공된 프롬프트가 공유하는 가장 긴 접두사(prefix)를 받게 됩니다.

휴리스틱 로드 테스트 (Heuristic Load Testing)

Tokenflood는 테스트를 실행하는 데 특정 프롬프트 데이터가 필요하지 않습니다. 대신, 프롬프트와 작업에 대한 메타데이터만 있으면 됩니다: 프롬프트 길이, 접두사 길이, 그리고 출력 길이입니다. 모든 값은 토큰 단위로 계산됩니다. 이를 통해 다양한 구성과 부하에 대한 신속한 테스트가 가능합니다. 로드 유형에서 토큰 수를 변경하는 것은 시스템의 구현을 조정하고 프롬프트를 재관찰해야 하는 것과는 달리 단 몇 초 만에 이루어집니다. 또한, 모든 모델과 구성에 걸쳐 정확히 원하는 출력 프로필을 얻도록 보장할 수 있어, 이들 간의 직접적인 비교가 가능합니다.

작동 방식

Tokenflood는 대부분의 토크나이저에서 단일 토큰에 해당하는 문자열 세트를 사용합니다. 예를 들어, 공백과 대문자 같은 형태입니다. 이 단일 토큰 문자열 세트에서 샘플링하여 Tokenflood는 입력 프롬프트를 생성합니다. 정의된 접두사 길이는 무작위가 아닙니다. 마지막으로, 일반적으로 긴 답변을 생성하는 작업이 추가됩니다. 생성에 대한 최대 완료 토큰(maximum completion tokens) 설정과 결합하여, Tokenflood는 원하는 출력 길이를 달성합니다.

작동 원리

이러한 유형의 휴리스틱 테스트는 신뢰할 수 있는 데이터를 생성하는데, 이는 비추론형 LLM(non-reasoning LLM)의 처리 시간이 오직 입력과 출력의 길이 및 관련된 캐싱 메커니즘에만 의존하기 때문입니다.

휴리스틱의 실패 사례

휴리스틱 부하 테스트는 특정 모델에 대해 원하는 토큰 수를 완벽하게 달성하지 못할 위험을 안고 있습니다. 만약 이런 일이 발생하면, Tokenflood는 요청이 예상 입력 또는 출력 토큰 길이에서 10% 이상 벗어날 경우 실행 중에 경고를 표시합니다. 시각화 프론트엔드에서도 절대적 및 상대적 토큰 오류를 보여줍니다.

[!IMPORTANT]
접두사(prefix) 길이를 지정할 수 있지만, 접두사가 사용될지 여부는 특정 엔드포인트와 그 구성에 따라 달라집니다. OpenAI와 같은 일부 제공업체는 전체 프롬프트 길이가 1024 토큰을 초과해야만 접두사 캐싱(prefix caching) 사용을 시작합니다. 또한, litellm이 항상 접두사 캐싱 사용량을 기록하는 것은 아닌 것 같습니다. vllm을 추론 서버로 사용할 때는 접두사 토큰을 올바르게 측정하기 위해 --enable-prompt-tokens-details를 지정해야 합니다.

🚨 안전(Safety) 🚨

tokenflood를 잘못 구성하여 사용하면 높은 토큰 지출이 발생할 수 있습니다. 예상치 못한 문제를 방지하기 위해 tokenflood에는 추가적인 안전 장치가 마련되어 있습니다:

tokenflood는 항상 테스트 시작을 확인하도록 요청합니다.
API 키 오구성 등으로 웜업(warm-up) 요청에 실패하는 경우, 실행을 시작하지 않습니다.
tokenflood는 마지막 30개 요청의 오류율이 30%를 초과하면 실행을 종료합니다.

🤝 기여(Contributing)

기여를 환영합니다!
새로운 기능을 추가하거나, 버그를 수정하거나, 문서를 개선하고 싶다면:

레포지토리를 포크(Fork)하세요.
개발 종속성(dev dependencies)을 포함하여 설치하세요:
```
poetry install --all-groups
```
1
2
기능 브랜치(feature branch)를 생성하세요:
```
git checkout -b feature/my-improvement
```
1
2
변경 사항을 적용하고, 해당되는 경우 테스트를 추가하세요.
모든 것이 작동하는지 확인하기 위해 로컬에서 린팅(linting) 및 테스트를 실행하세요:
```
make lint
make test
```
1
2
3
개선 사항에 대한 명확한 설명을 담아 풀 리퀘스트(pull request)를 제출하세요.

만약 주요 변경 사항(예: 새로운 테스트 유형 또는 제공업체 통합)을 계획한다면, 먼저 이슈(issue)를 열어 논의하는 것이 좋습니다.

Show HN: Tokenflood – 명령어 조정형(instruction-tuned) LLMs에 임의 부하 시뮬레이션

요약

핵심 포인트