SpecBundle 사용법

SpecBundle 사용법 (SpecBundle Usage)

SpecBundle은 오픈소스 커뮤니티와 산업 파트너(Ant Group, Meituan, Nex-AGI, EigenAI)가 함께 주도하는 이니셔티브로, 주류 오픈소스 LLM용 고성능·프로덕션급 EAGLE3 드래프트 모델 가중치를 제공해 추측 디코딩을 민주화하는 것을 목표로 합니다. 이 가이드는 SpecBundle 모델로 SGLang 서버를 시작하고 벤치마크하는 방법을 다룹니다.

출처: 문서

본문

SpecBundle에 대하여 (About SpecBundle)

추측 디코딩, 특히 EAGLE3는 강력한 이론적 보장과 함께 토큰 수용률·종단 간 추론 속도의 일관된 경험적 개선을 제공합니다. 그러나 이러한 발전에도 불구하고, 오픈소스 생태계에서 추측 디코딩(특히 EAGLE3)의 채택은 주로 세 가지 핵심 요인 때문에 제한적입니다.

1. 프로덕션 준비된 훈련 인프라 부족: 기존 추측 디코딩 툴체인은 대부분 연구 프로토타입이라 시스템 수준 최적화가 제한적이고 다양한 아키텍처·대규모 모델에 대한 지원이 부족합니다.
2. 고품질 드래프트 모델 희소성: 효과적인 추측 디코딩은 강력한 드래프트 모델에 의존하지만, 공개된 EAGLE3 호환 체크포인트는 극히 제한적이며 주로 원저작자에게서 나옵니다.
3. 기존 드래프트의 훈련 규모 부족: 대부분의 가용 드래프트 모델은 작거나 선별된 데이터셋으로 훈련되어 현대 LLM 훈련에 사용되는 크고 다양한 말뭉치에 일반화하지 못하며, 낮은 토큰 수용률과 감소된 실용적 속도 향상을 초래합니다.

SpecBundle은 이러한 한계에 대한 직접적인 대응입니다. 오픈소스 커뮤니티와 Ant Group, Meituan, Nex-AGI, EigenAI를 포함한 산업 파트너가 함께 주도하는 SpecBundle은 주류 오픈소스 LLM용 고성능·프로덕션급 EAGLE3 드래프트 모델 가중치를 제공해 추측 디코딩을 민주화하는 것을 목표로 하는 첫 오픈 이니셔티브입니다. 이 이니셔티브는 여러 규모·아키텍처를 통해 SpecForge 프레임워크의 견고성도 검증합니다.

설치 (Installation)

git clone https://github.com/sgl-project/SpecForge.git

사용법 (Usage)

SpecBundle 모델로 SGLang 서버 시작 (Launch SGLang Server with SpecBundle models)

다음 명령으로 SpecBundle 모델과 함께 SGLang 서버를 시작할 수 있습니다. 메모리 문제가 발생하면 --tp, --ep, --mem-fraction-static 인자를 추가하세요.

python3 -m sglang.launch_server \
    --model <target-model-path> \
    --speculative-algorithm EAGLE3 \
    --speculative-draft-model-path <draft-model-path> \
    --speculative-num-steps 3 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 4

예:

SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python3 -m sglang.launch_server \
    --model Qwen/Qwen3-30B-A3B-Instruct-2507 \
    --speculative-algorithm EAGLE3 \
    --speculative-draft-model-path lmsys/SGLang-EAGLE3-Qwen3-30B-A3B-Instruct-2507-SpecForge-Nex \
    --speculative-num-steps 3 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 4 \
    --tp 4

SpecBundle로 추측 디코딩 드래프트 모델 성능 비교 (Use SpecBundle to compare the performance)

SpecBundle 드래프트 모델의 성능을 평가하는 벤치마크 스위트를 여기에서 제공합니다.

예시 (Example):

1. SGLang 서버 시작

SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python3 -m sglang.launch_server \
    --model Qwen/Qwen3-30B-A3B-Instruct-2507 \
    --speculative-algorithm EAGLE3 \
    --speculative-draft-model-path lmsys/SGLang-EAGLE3-Qwen3-30B-A3B-Instruct-2507-SpecForge-Nex \
    --speculative-num-steps 3 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 4 \
    --tp 4

2. 벤치마크 스위트로 SpecBundle 드래프트 모델 성능 평가

bench_eagle3.py는 SGLang 서버 프로세스와 벤치마킹 프로세스를 동시에 시작하는 것을 도와줍니다. 이렇게 하면 SGLang 서버를 수동으로 시작할 필요가 없으며, 이 스크립트는 서로 다른 추측 디코딩 설정에서 SGLang 시작을 자동으로 처리합니다. 중요한 인자 몇 가지:

• --model-path: 대상 모델 경로.
• --speculative-draft-model-path: 드래프트 모델 경로.
• --port: SGLang 서버를 시작할 포트.
• --trust-remote-code: 원격 코드 신뢰.
• --mem-fraction-static: 정적 메모리 비율.
• --tp-size: 텐서 병렬 크기.
• --attention-backend: 어텐션 백엔드.
• --config-list: 테스트할 추측 디코딩 설정 목록, 형식은 <batch-size>,<num-steps>,<topk>,<num-draft-tokens>.
• --benchmark-list: 테스트할 벤치마크 목록, 형식은 <benchmark-name>:<num-prompts>:<subset>.

cd SpecForge/benchmarks
python bench_eagle3.py \
    --model-path Qwen/Qwen3-30B-A3B-Instruct-2507 \
    --port 30000 \
    --config-list 1,3,1,4 \
    --benchmark-list mtbench:5 gsm8k:100 \
    --skip-launch-server

대화형 명령 생성기 (Interactive Command Generator): 아래 설정 선택기를 사용해 모델과 벤치마크에 적합한 테스트 명령을 자동으로 생성하세요.

{
  "mtbench": [
    {
      "batch_size": 1,
      "steps": null,
      "topk": null,
      "num_draft_tokens": null,
      "metrics": [
        {
          "latency": 12.232808108034078,
          "output_throughput": 319.71399906382845,
          "accept_length": 2.170366259711432,
          "accuracy": null,
          "num_questions": 5,
          "num_valid_predictions": 0,
          "categorical_performance": null
        }
      ],
      "num_samples": 5
    }
  ],
  "gsm8k": [
    {
      "batch_size": 1,
      "steps": null,
      "topk": null,
      "num_draft_tokens": null,
      "metrics": [
        {
          "latency": 37.42077191895805,
          "output_throughput": 373.6160234823207,
          "accept_length": 2.643410852713178,
          "accuracy": 0.96,
          "num_questions": 100,
          "num_valid_predictions": 100,
          "categorical_performance": null
        }
      ],
      "num_samples": 100
    }
  ]
}