How to Deploy LingBot-Map to Production: Interactive Streaming and Batch Rendering Guide

Deploy LingBot-Map to production by installing PyTorch 2.8.0 with CUDA 12.8, downloading the pre-trained checkpoint, and launching either the interactive Viser server (demo.py) for real-time streaming or the batch renderer (demo_render/batch_demo.py) for offline video generation.

LingBot-Map is a feed-forward 3D foundation model maintained by Robbyant that reconstructs scenes from streaming image streams. Production deployment involves three layers: the Model & Inference Engine (lingbot_map/models/gct_base.py), Pre-processing & Utilities (lingbot_map/utils/), and Serving & Rendering (demo.py and demo_render/batch_demo.py). This guide provides the exact commands and configurations to deploy lingbot-map to production on a fresh server.

Environment Setup and Dependencies

Production deployment requires an isolated Python environment with specific CUDA and PyTorch versions to ensure compatibility with NVIDIA Kaolin and FlashInfer.

Install Python and PyTorch

Create a dedicated Conda environment using Python 3.10. The repository explicitly recommends PyTorch 2.8.0 with CUDA 12.8 because NVIDIA Kaolin (required by the batch renderer) provides pre-built wheels for this combination.

# Create and activate isolated environment

conda create -n lingbot-map-prod python=3.10 -y
conda activate lingbot-map-prod

# Install PyTorch 2.8.0 with CUDA 12.8 support

pip install torch==2.8.0 torchvision==0.23.0 \
    --index-url https://download.pytorch.org/whl/cu128

# Install LingBot-Map in editable mode

pip install -e .

Install FlashInfer and Optional Extras

FlashInfer provides the high-performance paged KV-cache attention implementation used by the Geometric Context Transformer (GCT) in lingbot_map/models/gct_base.py.

# Install FlashInfer (recommended backend)

pip install --index-url https://pypi.org/simple flashinfer-python

# Optional: Install JIT cache for faster first-run compilation

pip install flashinfer-jit-cache -f https://flashinfer.ai/whl/cu128/flashinfer-jit-cache/

# Optional: Install visualization and rendering dependencies

pip install -e ".[vis,render]"

The [vis,render] extras include Open3D, PyYAML, and onnxruntime-gpu, which power the sky-masking utilities in lingbot_map/vis/sky_segmentation.py and the pose encoding helpers in lingbot_map/utils/rotation.py.

Download Pre-Trained Model Checkpoints

LingBot-Map offers three public checkpoints hosted on Hugging Face. For production stability with long sequences, download the "long" checkpoint (approximately 2 GB).

# Create checkpoint directory and download

mkdir -p /opt/lingbot-map/checkpoints
wget https://huggingface.co/robbyant/lingbot-map/resolve/main/lingbot-map-long.pt \
    -O /opt/lingbot-map/checkpoints/lingbot-map-long.pt

This checkpoint is optimized for the paged KV-cache attention mechanism and supports streaming inference beyond the base model's training range when combined with windowed processing modes.

Production Deployment Modes

Choose between two production-ready entry points based on your use case: real-time interactive streaming or offline batch processing.

Interactive Streaming Service (Viser UI)

Use demo.py to launch a browser-based Viser viewer for real-time SLAM dashboards, remote robotics, or AR previews. This mode continuously updates a point-cloud visualization as new frames arrive.

Key Production Flags:

• --mask_sky – Enables automatic sky removal using the ONNX segmentation model in lingbot_map/vis/sky_segmentation.py
• --keyframe_interval N – Stores every N-th frame in KV-cache to reduce memory footprint for long streams
• --use_flashinfer – Forces the FlashInfer backend instead of native PyTorch SDPA
• --offload_to_cpu – Moves per-frame predictions to CPU RAM to stay within GPU memory limits (enabled by default)

Production Command:

python demo.py \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --image_folder /data/stream/images \
    --port 8080 \
    --mask_sky \
    --keyframe_interval 2 \
    --use_flashinfer \
    --offload_to_cpu

Access the interface at http://localhost:8080 or configure the host IP for remote access. The server provides live camera trajectory visualization and point-cloud updates.

Offline Batch Rendering (Headless MP4)

Use demo_render/batch_demo.py for generating final videos, marketing content, or processing massive datasets without interactive monitoring. This mode compiles CUDA extensions (voxel_morton_ext and frustum_cull_ext) automatically on first run.

Critical Flags for Long Sequences:

• --mode windowed – Enables sliding-window inference required for sequences longer than the 320-frame RoPE training limit
• --window_size 128 – Allocates 128 KV-cache slots per window (including 8 scale frames)
• --overlap_keyframes 8 – Shares 8 keyframes between adjacent windows to maintain pose continuity
• --sky_mask_dir – Caches computed sky masks to avoid reprocessing

Production Command:

python demo_render/batch_demo.py \
    --video_path /data/batch/input_video.mp4 \
    --output_folder /data/batch/results \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --config demo_render/config/indoor.yaml \
    --mode windowed \
    --window_size 128 \
    --keyframe_interval 10 \
    --overlap_keyframes 8 \
    --mask_sky \
    --sky_mask_dir /data/batch/sky_masks \
    --sky_mask_visualization_dir /data/batch/sky_viz \
    --camera_vis default \
    --keyframes_only_points \
    --frame_tag \
    --frame_tag_position top_right \
    --save_predictions

The --save_predictions flag persists per-frame NPZ files for downstream analytics, while --camera_vis default overlays the trajectory on the output MP4.

Production Readiness Checklist

Before handling live traffic, verify these production requirements:

1. Hardware Verification – Ensure GPU devices have at least 8 GB VRAM. FlashInfer works on any recent CUDA-compatible GPU, but larger batch sizes require proportional memory increases.

2. Service Daemon Configuration – Wrap your chosen entry point with a process manager to ensure automatic restart on failure. A minimal systemd service for the Viser UI looks like this:

[Unit]
Description=LingBot-Map interactive service
After=network.target

[Service]
Type=simple
User=lingbot
WorkingDirectory=/opt/lingbot-map
ExecStart=/opt/conda/envs/lingbot-map-prod/bin/python demo.py \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --image_folder /data/live_stream \
    --port 8080 \
    --mask_sky \
    --keyframe_interval 2 \
    --use_flashinfer
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

3. Network Security – Expose the Viser port (default 8080) behind an NGINX reverse proxy with SSL termination when serving external traffic.

4. Persistent Storage – Mount checkpoints at /opt/lingbot-map and configure sky_mask_dir on high-speed SSD storage to prevent I/O bottlenecks during batch processing.

5. Monitoring Integration – Import the logging utilities from benchmark/benchmark/utils/logging.py to capture structured logs, and monitor GPU memory using nvidia-smi to detect memory leaks during long streaming sessions.

Containerized Deployment (Optional)

For containerized environments, use nvidia/cuda:12.8.1-cudnn8-runtime-ubuntu22.04 as the base image. Execute the environment setup steps (1-5) inside the Dockerfile, then set the CMD to launch either demo.py or demo_render/batch_demo.py with your production flags. Ensure the container runtime provides GPU access (--gpus all) and mounts the checkpoint volumes.

Summary

• Environment: Deploy using Python 3.10, PyTorch 2.8.0, and CUDA 12.8 to ensure compatibility with NVIDIA Kaolin and FlashInfer.
• Model: Download the "long" checkpoint (2 GB) from Hugging Face for optimal long-sequence performance.
• Interactive Mode: Use demo.py with --use_flashinfer and --keyframe_interval for real-time Viser streaming on port 8080.
• Batch Mode: Use demo_render/batch_demo.py with --mode windowed and --window_size 128 to process videos exceeding 320 frames.
• Stability: Implement systemd services, persistent checkpoint storage, and GPU monitoring for production reliability.

Frequently Asked Questions

What are the minimum GPU requirements to deploy LingBot-Map to production?

You need a CUDA-compatible GPU with at least 8 GB of VRAM. The FlashInfer backend operates efficiently within this constraint, though enabling --offload_to_cpu or increasing --keyframe_interval allows you to process longer sequences on memory-constrained hardware.

Can I use a PyTorch version newer than 2.8.0?

You can use newer PyTorch versions for the interactive demo.py server, but the batch renderer (demo_render/batch_demo.py) specifically requires PyTorch 2.8.0 because NVIDIA Kaolin ships pre-built wheels only for that version. Using a newer version forces Kaolin to compile from source, significantly increasing deployment time.

How do I handle video sequences longer than 320 frames?

Use the windowed inference mode by passing --mode windowed to demo_render/batch_demo.py. Set --window_size 128 (matching your GPU memory) and --overlap_keyframes 8 to maintain pose continuity between windows. This configuration overrides the default RoPE positional encoding limits.

Is FlashInfer mandatory for production deployment?

FlashInfer is not strictly required but highly recommended. Without it, the system automatically falls back to native PyTorch SDPA (Scaled Dot-Product Attention). However, FlashInfer's paged KV-cache implementation in lingbot_map/models/gct_base.py provides significantly higher throughput for streaming applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}