오프라인 배치 추론 레퍼런스 (Offline Batched Inference)

vLLM을 자체 코드 안에서 쓰고 싶다면 LLM 클래스가 바로 그 입구예요. 서버를 띄우지 않고도 여러 프롬프트를 배치로 묶어 한 번에 생성할 수 있어서, 고정된 입력 집합을 처리하거나 전처리/후처리를 코드로 직접 제어할 때 특히 편리해요.

출처: Offline Inference

모델 유형

vLLM의 모델은 크게 두 종류로 나뉘어요.

생성형 모델(Generative Models) — 텍스트 완성이나 채팅 응답을 만들어내는 모델(예: LLaMA, Qwen, DeepSeek). 이런 모델에는 LLM.generate()와 LLM.chat()을 써요.
Pooling 모델 — 내용을 생성하지 않고 주로 분류·검색(임베딩) 용도로 쓰는 모델(예: bge-m3, Qwen3 Reranker).

생성형 API

LLM.generate — 주어진 입력 프롬프트에 대한 완성문을 생성해요.
LLM.chat — 채팅 대화에 대한 응답을 생성해요.

비동기 큐(Asynchronous Queue) API

LLM.enqueue — 완료를 기다리지 않고 프롬프트를 생성 큐에 넣어요.
LLM.enqueue_chat — 채팅 대화를 기다리지 않고 큐에 넣어요.
LLM.wait_for_completion — 큐에 넣은 모든 요청이 끝날 때까지 기다렸다가 결과를 돌려줘요.

Pooling API

LLM.classify — 분류 모델에만 적용돼요.
LLM.embed — 임베딩 모델에만 적용돼요.
LLM.score — 스코어 모델(크로스 인코더·바이 인코더·late-interaction)에 적용돼요.
LLM.encode — 모든 pooling 모델에 적용돼요.

프로파일링 API

LLM.start_profile — 선택적인 커스텀 트레이스 접두사와 함께 프로파일링을 시작해요.
LLM.stop_profile — 진행 중인 프로파일링 세션을 멈춰요.

슬립 모드 API

LLM.sleep — 엔진을 슬립 모드로 전환해요.
LLM.wake_up — 엔진을 슬립 모드에서 깨워요.

캐시 관리 API

LLM.reset_mm_cache — 멀티모달 캐시를 초기화해요.
LLM.reset_prefix_cache — 프리픽스 캐시를 초기화해요.

메트릭 API

LLM.get_metrics — Prometheus에서 집계된 메트릭 스냅샷을 돌려줘요.

가중치 전송 API (RL 학습)

LLM.init_weight_transfer_engine — RL 학습을 위한 가중치 전송 엔진을 초기화해요.
LLM.start_weight_update — 새 가중치 업데이트 주기를 시작해요.
LLM.update_weights — 모델 가중치를 갱신해요.
LLM.finish_weight_update — 현재 가중치 업데이트 주기를 마무리해요.
LLM.update_weight_version — 모델 가중치는 갱신하지 않고 버전만 설정해요.
LLM.get_weight_version — 가장 최근에 커밋된 가중치 버전을 돌려줘요.

추가 API

LLM.collective_rpc — 모든 워커에서 메서드나 콜러블을 집합적으로 실행해요.
LLM.apply_model — 각 워커 안의 모델에 함수를 직접 적용해요.

Ray Data LLM API

Ray Data LLM은 vLLM을 내부 엔진으로 쓰는 오프라인 추론의 또 다른 API예요. 대규모·GPU 효율 추론을 쉽게 만드는 기능이 몇 가지 추가돼 있어요.

스트리밍 실행 — 클러스터 총 메모리를 넘는 데이터셋도 스트리밍으로 처리해요.
자동 샤딩·로드 밸런싱·오토스케일링 — Ray 클러스터에 작업을 분산시키고 내장된 장애 허용을 제공해요.
연속 배치 — vLLM 레플리카를 포화 상태로 유지해 GPU 활용을 극대화해요.
병렬 처리 — 텐서·파이프라인 병렬을 투명하게 지원해 멀티 GPU 추론을 효율화해요.
파일·오브젝트 스토리지 — 대부분의 인기 파일 포맷과 클라우드 오브젝트 스토리지 읽기/쓰기를 지원해요.
코드 변경 없이 확장 — 워크로드를 코드 수정 없이 키울 수 있어요.

간단한 예시를 보면 이런 식이에요. ray.data에서 아이템 몇 개를 출발점 삼아 build_llm_processor로 전처리·후처리 로직을 입힌 뒤, 데이터셋에 적용하고 parquet로 저장해요.

import ray  # Requires ray>=2.44.1
from ray.data.llm import vLLMEngineProcessorConfig, build_llm_processor

config = vLLMEngineProcessorConfig(model_source="unsloth/Llama-3.2-1B-Instruct")
processor = build_llm_processor(
    config,
    preprocess=lambda row: {
        "messages": [
            {"role": "system", "content": "You are a bot that completes unfinished haikus."},
            {"role": "user", "content": row["item"]},
        ],
        "sampling_params": {"temperature": 0.3, "max_tokens": 250},
    },
    postprocess=lambda row: {"answer": row["generated_text"]},
)

ds = ray.data.from_items(["An old silent pond..."])
ds = processor(ds)
ds.write_parquet("local:///tmp/data/")

핵심 포인트

오프라인 추론은 서버 없이 LLM 클래스로 배치를 직접 처리하는 방식이라, 배치 파이프라인·전처리 자동화에 잘 맞아요.
모델 유형에 따라 쓰는 메서드가 달라지니, 생성형이면 generate/chat, pooling이면 classify/embed/score/encode를 골라야 해요.
대용량·GPU 효율 추론이 필요하다면 Ray Data LLM API가 스트리밍과 자동 스케일링을 더해줘요.