vLLM TT 플러그인은 LLM 서빙에 Tenstorrent 가속기 도입
TL;DR
vLLM TT 플러그인은 vLLM 서빙 스택에 Tenstorrent 가속기 지원을 추가하며, 동일한 OpenAI 호환 API를 유지하면서 메시지 기반 스케줄러, 장치 내 샘플링, 단일 프로세스 레인 데이터 병렬 설계를 도입합니다.
TT 플러그인 개요
이 플러그인은 TT-Metal의 ttnn 패키지가 임포트 가능한 경우 자동으로 활성화되는 트리 외부 플랫폼 모듈로 배포됩니다. 클라이언트 코드나 요청 형식에 대한 변경이 필요 없으며, OpenAI 호환 API는 그대로 작동합니다.
지원되는 모델 패밀리
플러그인은 Tenstorrent 기반 아키텍처를 TT 접두사로 등록합니다. 모델 선택은 모델 이름이 아니라 아키텍처 기반으로 이루어지며, 하나의 등록으로 여러 릴리스를 커버할 수 있습니다. 현재 지원 목록은 다음과 같습니다:
| 모델 패밀리 | TT 아키텍처 클래스 |
|---|---|
| Llama 3.1 / 3.2 / 3.3 | TTLlamaForCausalLM |
| Llama 3.2 Vision | TTMllamaForConditionalGeneration |
| Qwen 2.5 / Qwen 3 | TTQwen2ForCausalLM, TTQwen3ForCausalLM |
| Qwen 3.5 / 3.6 | TTQwen3_5ForConditionalGeneration |
| Qwen 2.5‑VL / 3‑VL | TTQwen2_5_VLForConditionalGeneration, TTQwen3VLForConditionalGeneration |
| Mistral / Mistral 3 | TTMistralForCausalLM, TTMistral3ForConditionalGeneration |
| Gemma 3 | TTGemma3ForConditionalGeneration |
| Gemma 4 | TTGemma4ForCausalLM, TTGemma4ForConditionalGeneration, TTGemma4UnifiedForConditionalGeneration |
| DeepSeek V3 | TTDeepseekV3ForCausalLM |
| GPT‑OSS 20B / 120B | TTGptOssForCausalLM |
Llama 3.2 Vision, Qwen‑VL, Qwen 3.6, Mistral 3, Gemma 3과 같은 멀티모달 모델은 이미 플러그인을 통해 서빙되고 있습니다.
아키텍처 중심 등록
플러그인은 모델 코드를 포함하지 않으며, 단지 아키텍처 이름을 등록할 뿐입니다. 실제 구현은 TT-Metal 내부에 있으며, 각 클래스는 수작업으로 작성된 TTNN 모델을 래핑합니다. 등록은 아키텍처 기반으로 이루어지므로, 하나의 클래스가 여러 모델 릴리스를 지원할 수 있습니다 (예: TTQwen3_5ForConditionalGeneration은 Qwen/Qwen3.6-27B를 지원합니다).
사용자 정의 모델은 플러그인 소스를 수정하지 않고도 EXTRA_MODELS_DIR를 vllm_metadata.json과 어댑터 클래스를 포함한 디렉터리로 지정함으로써 추가할 수 있습니다. TT_VLLM_BUILTIN_MODELS=0을 설정하면 레지스트리가 사용자 제공 모델만으로 제한됩니다.
Tenstorrent 메시 vs. GPU 형태의 추론 스택
Tenstorrent 하드웨어는 네트워크(예: n150, n300, QuietBox, Galaxy)를 통해 연결된 코어와 칩의 메시입니다. 프로그램은 고정된 메시 형태에 대해 컴파일되며, 칩 간 데이터 이동은 호스트 측 컬렉티브 명령이 아니라 컴파일된 트레이스에 고정됩니다.
이 컴파일 모델의 주요 결과:
- 텐서 병렬 또는 파이프라인 병렬 랭크 없음 – 메시 프로그램이 병렬성을 직접 인코딩합니다.
MESH_DEVICE=TG플래그는 일반적인--tensor‑parallel-size인수를 대체하며, 플러그인은-tp/-pp를 거부합니다. - 스텝의 세부 수준은 전체 추적 프로그램 – 각 스텝은 고정된 배치 형태에 대한 캡처된 트레이스를 재생하므로, 동일한 배치는 비동일한 배치보다 훨씬 저렴합니다.
- 장치 내 샘플링이 가능 – 메시 프로그램은 선택된 토큰을 직접 반환할 수 있어 호스트 측 로짓 전송이 제거됩니다.
이러한 차이는 vLLM의 플러그인 인터페이스에 상당한 적응이 필요했습니다.
플러그인 통합 포인트
vLLM 하드웨어 플러그인 메커니즘(2025년 5월 도입)은 두 가지 진입점을 제공합니다:
| 진입점 그룹 | 이름 | 대상 |
|---|---|---|
vllm.platform_plugins |
tt |
vllm_tt_plugin.entrypoints:platform_plugin |
vllm.general_plugins |
tt_model_registry |
vllm_tt_plugin.entrypoints:register |
platform_plugin()은 ttnn이 임포트 가능한 경우에만 TTPlatform 인스턴스를 반환하여 순수 CUDA 환경에서 오작동을 방지합니다.
플러그인은 vLLM의 확장 포인트를 통해 Tenstorrent 전용 런타임 클래스를 교체합니다:
| vLLM 설정 필드 | TT 구현 |
|---|---|
parallel_config.worker_cls |
vllm_tt_plugin.worker.TTWorker |
scheduler_config.scheduler_cls |
vllm_tt_plugin.scheduler.TTScheduler 또는 vllm_tt_plugin.lane_scheduler.TTLaneCoordinator |
장치별 옵션은 vLLM의 일반적인 --additional-config 네임스페이스를 통해 전달되며, 예를 들어:
--additional-config.tt.sample_on_device_mode all
--additional-config.tt.fabric_config FABRIC_1D_RING
Tenstorrent 전용 코드는 vLLM 커널에 존재하지 않으며, 업스트림 릴리스와의 향후 호환성을 보장합니다.
단계 기반 스케줄링
vLLM의 토큰 예산 스케줄러와 달리, Tenstorrent 경로는 각 스케줄링 스텝을 다음 세 가지 동일한 결과 중 하나로 제한합니다:
- prefill-only
- decode-only
- empty
혼합 prefill 및 decode 배치는 허용되지 않습니다. 긴 프롬프트는 여러 개의 prefill-only 스텝으로 분할되며, 다른 요청이 진행되도록 decode-only 스텝이 교차 배치됩니다. 이 설계는 컴파일된 메시 프로그램에 필수적인 트레이스 안정성을 유지합니다.
단계 분할이 가져오는 이점
- 각 스텝 형상에 대해 단일 컴파일된 트레이스를 재사용할 수 있습니다.
- 대규모 GPU 풀에서 사용되는 "분리된 서빙" 패턴을 단일 엔진 내에서 적용합니다.
비용
- decode 요청은 각 prefill 청크를 기다려야 하며, 스텝 수준의 지연이 발생합니다.
- 스케줄러는 스텝 간에 모드를 전환해야 하며, 소량의 정책 오버헤드가 발생합니다.
이 설계는 확장 가능하며, 필요 시 향후 버전에서 혼합 형상 트레이스를 캡처할 수 있습니다.
Galaxy에서 단일 프로세스 레인 데이터 병렬성
Galaxy(32칩 메시)는 일부 모델을 전체 메시를 아우르는 단일 실행 프로그램으로 실행합니다. 메시 제출이 하나뿐이므로 전통적인 다중 프로세스 데이터 병렬성은 적용할 수 없습니다.
해결책은 프로세스 내 레인 DP입니다:
TTLaneCoordinator는 기본적으로 네 개의 레인마다 하나의TTScheduler를 생성합니다.- 각 레인은 자체 대기/실행 큐, KV 캐시, 블록 ID 공간을 유지합니다.
- 요청은 가장 적은 부하를 가진 레인에 할당되며, 그 레인에 고정됩니다.
- 각 스텝에서 조정기는 모든 레인에 대해 공유 모드(_prefill 또는 decode)를 선택합니다. 작업이 없는 레인은 빈 슬라이스를 기여합니다.
- 병합된 배치는 한 번 장치로 전송되며, 결과는 내부적으로 레인으로 분할됩니다.
이로써 이전 다중 프로세스 시도에서 발생했던 비용이 큰 프로세스 간 산란/수집을 제거합니다.
예외 케이스
prefill 스텝에서 KV 압박으로 인해 0개의 토큰이 허용되는 경우, 다른 레인에 decode 작업이 있는 경우, 데드락을 피하기 위해 decode 모드로 재시도됩니다.
사용자용 플래그
일반적인 vLLM 플래그가 재사용됩니다:
MESH_DEVICE=TG \
TT_LLAMA_TEXT_VER=llama3_70b_galaxy \
VLLM_RPC_TIMEOUT=900000 \
python examples/server_example_tt.py \
--model "meta-llama/Llama-3.3-70B-Instruct" \
--data_parallel_size 4 \
--max_num_seqs 8 \
--async-scheduling \
--additional-config.tt.dispatch_core_axis col \
--additional-config.tt.sample_on_device_mode all \
--additional-config.tt.fabric_config FABRIC_1D_RING \
--additional-config.tt.worker_l1_size 1344544 \
--additional-config.tt.trace_region_size 220000000
--data_parallel_size 4는 이제 네 개의 프로세스 내 레인을 생성하며, 각 레인은 --max_num_seqs 요청을 처리할 수 있습니다.
장치 내 샘플링과 자동 백업
sample_on_device_mode가 설정되면 메시 프로그램이 토큰 선택을 수행하고 토큰을 직접 반환합니다. 배치가 장치가 표현할 수 없는 기능(예: 로그확률, 패널티, 사용자 정의 로짓 프로세서 등)을 요구하는 경우, 플러그인은 해당 배치에 대해 vLLM의 호스트 측 샘플러로 백업합니다. always_compat_sampling 플래그는 디버깅을 위해 호스트 측 샘플링을 강제합니다.
비동기 디코딩 오버랩
플러그인은 디코딩/호스트 오버랩을 제공하지만, 별도의 장치 실행 스레드가 아니라 비동기 호스트 읽기로만 제공됩니다:
- 블로킹 없이 디코딩 작업을 제출합니다 (
read_from_device=False). - 비차단 호스트 읽기 시작합니다 (
async_read=True). - 결과 이벤트를 저장합니다.
- 최종화 시점에
ttnn.event_synchronize()로 동기화한 후 호스트 텐서로 변환합니다.
깊이 2의 인플라이트 큐를 통해 호스트는 스텝 N+1을 스케줄링할 수 있으며, 스텝 N의 읽기 작업이 여전히 진행 중일 수 있습니다. 오버랩은 안정된 형상, 장치 내 샘플링, 구조화된 출력 추적 없이 유지됩니다. prefill은 여전히 동기적입니다.
현재 제한 사항
플러그인은 구성 설정을 조기에 검증하고 지원되지 않는 조합을 거부합니다:
- 텐서 병렬 및 파이프라인 병렬은 vLLM 랭크가 아니라 메시 형태로 표현됩니다.
- 사전 추측 디코딩, LoRA, 프롬프트 로그확률은 아직 지원되지 않습니다.
- 접두사 캐싱은 해당 기능을 선언한 모델에서만 가능합니다.
- 비동기 디코딩 오버랩은 모델이 해당 기능을 선언해야 합니다.
- 표준 다중 프로세스 DP는 MoE 모델을 지원하지 않으며, 대신 레인-DP가 사용됩니다.
- 다중 호스트 서빙은 아직 구현되지 않았습니다.
이러한 제한은 현재 TT-Metal 런타임 및 모델 구현의 한계이며, 하드웨어 자체의 강제 제약은 아닙니다.
시작하기
공식 가이드에 따라 TT-Metal을 설치합니다.
플러그인을 복제하고 설치합니다:
git clone https://github.com/tenstorrent/vllm-tt-plugin.git cd vllm-tt-plugin source docs/install-vllm-tt.sh스크립트는 TT-Metal 환경 내부에서 버전 0.26.0 기반으로 vLLM을 빌드합니다.
모델을 서빙합니다:
MESH_DEVICE=T3K VLLM_RPC_TIMEOUT=100000 python examples/server_example_tt.pyOpenAI 호환 클라이언트를 통해 쿼리합니다. 예:
curl http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{"model": "meta-llama/Llama-3.1-70B-Instruct", "prompt": "San Francisco is a", "max_tokens": 32}'
로드맵
- 더 많은 모델 패밀리에 대해 비동기 디코딩 지원 확장
- 추가 모델에 대해 접두사 캐싱 및 레인-DP RoPE 처리 활성화
- 메시 측 드래프트/검증 파이프라인 안정화 후 사전 추측 디코딩 구현
- 단일 머신을 초과해 확장하기 위한 다중 호스트 서빙 추가
감사의 말
이 플러그인은 Ascend 팀이 기여한 vLLM 플랫폼 플러그인 메커니즘과 Spyre 팀의 플러그인 스케줄러 설계를 기반으로 합니다. 메시 아키텍처에 적합한 확장 포인트를 유지해 주신 vLLM 유지보수 팀에게 감사드립니다.
기여자: Viktor Puš, Tomasz Cheda, Sanjar Adylov, Salar Hosseini. 레인-DP 사용자 인터페이스 및 우선 순위 모델 패밀리에 대한 피드백은 GitHub 이슈 또는 vLLM Slack을 통해 환영합니다.