LingBot World
LingBot World
LingBot World는 실시간 카메라 제어 비디오 월드 모델입니다. 라이브 인과 세션을 유지하고, 청크 사이에 프롬프트·카메라 이벤트를 적용하며, DiT/VAE 상태를 재사용하고, 제한된 클립을 완성한 후 반환하는 대신 디코딩된 프레임을 스트리밍합니다.
출처: 문서
본문
<DiffusionModelTags tags={["realtime", "world model", "continuous video", "camera control", "causal KV cache"]} />
1. 모델 소개 (Model Introduction)
LingBot World는 실시간 카메라 제어 비디오 월드 모델입니다. 라이브 인과 세션을 유지하고, 청크 사이에 프롬프트·카메라 이벤트를 적용하며, DiT/VAE 상태를 재사용하고, 제한된 클립을 완성한 후 반환하는 대신 디코딩된 프레임을 스트리밍합니다.
대화형 탐색과 연속 제어에 선택하고, 일회성 시네마틱 생성에는 선택하지 마세요. 인과 창은 긴 세션을 실용적으로 만들지만 오프라인 Wan이나 LTX 파이프라인에서 가능한 전역 양방향 컨텍스트를 포기합니다. 따라서 세션 상태와 캐시 정책이 서빙 계약의 일부가 됩니다.
2. 배포 (Deployment)
sglang serve \
--model-path robbyant/lingbot-world-fast-diffusers \
--pipeline-class-name LingBotWorldCausalDMDPipeline \
--num-gpus 4 \
--ulysses-degree 4 \
--dit-cpu-offload false \
--text-encoder-cpu-offload false
선택적 KV 캐시 압축 (Optional KV-Cache Compression)
장기 실행 세션은 양자화 가이드에 설명된 대로 quant-videogen을 설치하고 서버 명령에 --kv-cache-quant int4를 추가해 완료된 인과 KV-캐시 청크에 대해 손실 int4 PRQ 압축을 활성화할 수 있습니다. 현재 및 가장 최근 완료된 청크는 BF16으로 유지됩니다. 알고리즘, 튜닝 옵션, 측정된 메모리-지연 트레이드오프, 지원 한계는 인과 KV-캐시 양자화를 참조하세요.
3. Realtime WebUI
가벼운 로컬 WebUI는 지연, 프레임 전송, 카메라 제어 동작을 검증하는 데 유용합니다.
python -m http.server 18080 -d python/sglang/multimodal_gen/apps/realtime_webui
http://127.0.0.1:18080을 열고 사용:
ws://127.0.0.1:30000/v1/realtime_video/generate
4. HTTP 및 WebSocket API
LingBot World는 realtime 비디오 WebSocket 엔드포인트를 사용합니다. 서버는 하나의 라이브 세션을 유지하고, 한 번에 하나의 청크를 생성하며, 생성이 실행되는 동안 런타임 제어 이벤트를 받습니다.
엔드포인트 (Endpoints)
| API | 방식 (Method) | 목적 (Purpose) | 참고 (Notes) |
|---|---|---|---|
/v1/models |
GET |
세션을 열기 전에 서빙되는 모델 id 조회. | WebUI는 서버가 모델 메타데이터를 노출할 때 모델 필드를 채우는 데 사용. |
/v1/realtime_video/generate |
WebSocket |
하나의 realtime LingBot 세션을 만들고 생성된 비디오 청크를 스트리밍. | 첫 클라이언트 메시지는 MessagePack으로 인코딩된 init 메시지여야 함. |
init 메시지
WebSocket이 열린 직후 이 MessagePack 맵을 보내세요.
| 파라미터 (Parameter) | 타입 (Type) | 필수 (Required) | 의미 (Meaning) |
|---|---|---|---|
type |
string | Yes | "init"이어야 함. |
model |
string | No | 모델 id. 비워 두면 서빙 모델 사용. |
prompt |
string | Yes | 초기 장면과 동작 스타일용 텍스트 프롬프트. |
first_frame |
bytes 또는 string | Yes | 초기 레퍼런스 이미지. WebUI/클라이언트에서 바이트를 보내거나 서버가 읽을 수 있는 이미지 경로/문자열을 보냄. |
size |
string | Yes | 생성 크기 WIDTHxHEIGHT. 예: 832x480. |
fps |
number | Yes | 생성 스트림의 대상 재생 FPS. |
num_frames |
integer | Yes | 생성 청크당 프레임 수. LingBot은 chunked causal 생성을 사용하므로 청크당 지연과 큐 크기를 제어. |
seed |
integer | No | 결정적 샘플링용 랜덤 시드. |
num_inference_steps |
integer | No | 청크당 디노이즈 스텝. 생략 시 LingBot 기본값 4. |
guidance_scale |
number | No | Classifier-free guidance 스케일. Realtime LingBot은 보통 1 사용. |
negative_prompt |
string | No | 디퓨전 파이프라인에 전달되는 네거티브 프롬프트. |
quality |
"lossless", "extra-high", "high" |
No | lossless는 FP32 VAE 디코드를 유지. extra-high는 FP32 디코드를 유지하고 적격 요청-게이트 커널 융합만 활성화. high는 그 융합을 포함하고 검증된 BF16 디코드 경로로 청크당 지연을 낮춤. |
max_chunks |
integer | No | 이 청크 수 후 중지. 연속 세션에는 생략. |
realtime_causal_sink_size |
integer | No | 인과 어텐션 창에 유지하는 sink 프레임/토큰 수. |
realtime_causal_kv_cache_num_frames |
integer | No | 인과 KV 캐시 창에 유지하는 최근 프레임 수. |
realtime_output_format |
"webp", "jpeg", "raw" |
No | 프리뷰/출력 전송. webp·jpeg는 인코딩된 프리뷰 프레임 전송, raw는 원시 RGB 전송, 생략 시 무손실 delta-gzip RGB. |
output_compression |
integer | No | webp 또는 jpeg용 프리뷰 품질. 1에서 100까지. |
enable_upscaling |
boolean | No | 프레임 디코드 후 서버 측 슈퍼 레졸루션 활성화. |
upscaling_scale |
integer | No | 슈퍼 레졸루션 배율. 현재 기본값은 업스케일링 활성화 시 4. |
upscaling_model_path |
string | No | 선택적 Real-ESRGAN 모델 경로. |
enable_frame_interpolation |
boolean | No | 프레임 인터폴레이션 활성화. 실제 생성 FPS를 측정할 때는 비활성화 유지. |
frame_interpolation_exp |
integer | No | 인터폴레이션 배율 지수. 1은 2x 프레임. |
frame_interpolation_scale |
number | No | 인터폴레이션용 RIFE 내부 배율. |
frame_interpolation_model_path |
string | No | 선택적 RIFE 모델 경로. |
condition_inputs.camera_actions |
list[list[string]] |
No | 초기 스크립트 카메라 동작. 프레임당 하나의 동작 리스트. |
런타임 event 메시지
init 후 MessagePack 이벤트 맵을 보내 라이브 세션을 업데이트합니다.
| 파라미터 (Parameter) | 타입 (Type) | 필수 (Required) | 의미 (Meaning) |
|---|---|---|---|
type |
string | Yes | "event"이어야 함. |
kind |
"prompt" 또는 "camera_actions" |
Yes | 런타임 이벤트 종류. |
payload |
string 또는 object/list | Yes | prompt는 비어 있지 않은 문자열. camera_actions는 스크립트 list[list[string]] 또는 state-mode 페이로드. |
event_id |
integer | No | 클라이언트 시퀀스 id. 서버는 이벤트가 샘플링된 후 청크/프레임 메타데이터에 이를 반향. |
camera_actions는 두 가지 페이로드 모드를 지원합니다:
| 모드 (Mode) | 페이로드 형태 (Payload shape) | 의미 (Meaning) |
|---|---|---|
| Script | list[list[string]] |
다가오는 청크가 소비하는 고정 프레임별 동작 시퀀스. |
| State | { "mode": "state", "transitions": [{"actions": [...], "client_ts_ms": ...}] } |
키보드 또는 UI 컨트롤의 라이브 제어 상태 전환. |
지원되는 LingBot 동작 토큰: 카메라 이동 w, a, s, d와 보기 컨트롤 i, j, k, l.
서버 메시지
| 메시지 (Message) | 페이로드 (Payload) | 의미 (Meaning) |
|---|---|---|
frame_batch |
payload 바이트가 있는 MessagePack 맵 |
프레임 한 배치. 맵은 chunk_index, num_frames, content_type, encoding, width, height, 프레임 배치 메타데이터를 포함. |
chunk_stats |
MessagePack 맵 | 청크별 타이밍·전송 메트릭: scheduler_forward_ms, raw_payload_build_ms, chunk_total_ms, num_frames, ws_payload_bytes. |
error |
MessagePack 맵 | 서버 측 검증 또는 생성 오류. |
최소 클라이언트 스케치
import msgspec.msgpack
import websocket
ws = websocket.create_connection("ws://127.0.0.1:30000/v1/realtime_video/generate")
ws.send_binary(msgspec.msgpack.encode({
"type": "init",
"prompt": "A quiet rainy London alley, stable camera motion.",
"first_frame": open("reference.jpg", "rb").read(),
"size": "832x480",
"fps": 25,
"num_frames": 9,
"num_inference_steps": 4,
"guidance_scale": 1,
"realtime_output_format": "webp",
"output_compression": 95,
}))
ws.send_binary(msgspec.msgpack.encode({
"type": "event",
"kind": "camera_actions",
"event_id": 1,
"payload": {"mode": "state", "transitions": [{"actions": ["w"], "client_ts_ms": 0}]},
}))
5. 일관성 (Consistency)
LingBot World는 일관성 검사에 raw-frame websocket GT와 청크별 지연 가드를 사용합니다.
6. 참고 (Notes)
- 대화형 세션에는 realtime 엔드포인트를 사용하세요:
/v1/realtime_video/generate. - 대화형 테스트에는 WebP 프리뷰 전송을 선호하고, 일관성 검사에는 raw-frame 전송을 사용하세요.
- 장기 실행 세션은 인과 캐시, 조건 샘플링, VAE 디코드 동작을 바꾸기 전에 raw-frame 일관성으로 검증해야 합니다.