[Docs] Rewrite the preload (ipc_cache) guide and add Docker/Kubernetes usage

docs/cli/README.md

@@ -291,10 +291,7 @@ See [vllm run-batch](./run-batch.md) for the full reference of all available arg
 
 ## preload
 
-Launch weight cache daemons (one per GPU) that hold the post-quantized,
-TP-sharded weights in GPU memory and serve CUDA IPC handles to vLLM engines
-over a Unix domain socket. Restarting engines then map the weights via
-zero-copy IPC instead of reloading from disk, enabling fast engine restarts.
+Launch weight cache daemons, one per GPU, that hold the post-quantized, TP-sharded weights in GPU memory and serve CUDA IPC handles to vLLM engines over a Unix domain socket. A restarting engine maps the weights instead of loading them from disk.
 
 ```bash
 # Launch one daemon per GPU
@@ -305,16 +302,16 @@ vllm serve meta-llama/Llama-3.2-1B-Instruct --tensor-parallel-size 4 \
     --load-format ipc_cache
 ```
 
-The daemon accepts the standard engine arguments (model, dtype, quantization,
-tensor-parallel-size, ...) plus `--weight-cache-socket-dir` to override the
-directory holding the per-GPU Unix sockets, and `--weight-cache-master-port` /
-`--weight-cache-draft-master-port` to pin the daemon rendezvous ports for
-multi-node and speculative-decoding setups. Tensor, expert and data
-parallelism are supported; pipeline parallelism is rejected at launch.
+The daemon accepts the standard engine arguments, which must match the engine's, plus:
 
-See [Preload](../features/preload.md) for how it works, cache modes, and
-limitations, and [vllm preload](./preload.md) for the full reference of all
-available arguments.
+- `--weight-cache-socket-dir` sets the directory holding the per-GPU Unix sockets. It is required when the daemon and the engine run in different containers.
+- `--weight-cache-health-port` and `--weight-cache-health-host` expose a `/health` readiness endpoint for Docker health checks and Kubernetes probes.
+- `--weight-cache-master-port` and `--weight-cache-draft-master-port` set the daemons' own rendezvous ports in multi-node setups.
+- `--seed-listen-host`, `--seed-listen-port`, `--seed-source-host`, `--seed-source-port` and `--seed-token` seed a new multi-rank replica's FlashInfer autotune cache from a running one over an authenticated TCP channel, so it can skip tuning.
+
+Tensor, pipeline, expert and data parallelism are supported. On Hopper and newer GPUs with FlashInfer installed, the daemons also run the FlashInfer autotune pass before they report ready. Pass `--disable-flashinfer-autotune` to skip it.
+
+See [Preload](../features/preload.md) for how it works, cache modes, Docker and Kubernetes deployment, and troubleshooting, and [vllm preload](./preload.md) for the full reference of all available arguments.
 
 ## More Help
 

docs/configuration/optimization.md

@@ -18,10 +18,11 @@ For more information, see the [optimization level documentation](../design/optim
 
 ## Faster Startup
 
-Beyond the optimization levels, three mechanisms reduce time-to-first-token on repeated boots of the same (model, config, hardware) combination:
+Beyond the optimization levels, four mechanisms reduce time-to-first-token on repeated boots of the same (model, config, hardware) combination:
 
 - **Reuse the compile cache.** vLLM persists `torch.compile` artifacts under `VLLM_CACHE_ROOT` (default `~/.cache/vllm`), and the cache directory can be copied between machines or baked into a container image; see the [torch.compile design doc](../design/torch_compile.md). Set `VLLM_FORCE_AOT_LOAD=1` to fail loudly instead of silently recompiling when the cache misses (any change to the model, config, relevant `VLLM_*` environment variables, torch build, or GPU model invalidates it).
 - **Skip memory profiling with `--kv-cache-memory`.** On startup, vLLM logs the exact `--kv-cache-memory` value that reproduces the current allocation. Passing it back on the next boot skips the memory-profiling measurement and the CUDA-graph memory estimation pass. Note that this has performance implications: the KV cache is sized to exactly the given value instead of being measured, so a conservative value caps batch concurrency (and therefore throughput), while an optimistic one fails at allocation time. The value is only valid on the same GPU with the same initial free memory; if a boot OOMs after hardware or co-tenant changes, remove the flag to re-profile.
+- **Keep the weights in GPU memory across engine restarts with [preload](../features/preload.md).** A `vllm preload` daemon per GPU holds the post-processed weights, and an engine started with `--load-format ipc_cache` maps them via CUDA IPC instead of reloading from disk. On Hopper and newer GPUs the daemon also runs the FlashInfer autotune pass at preload time, so the engine skips it too.
 - **Serve without CUDA graphs using `--enforce-eager`.** Skips both compilation and CUDA-graph capture for the fastest possible startup, at the cost of steady-state decode performance. Useful for development loops and for measuring how much of a boot is compile/capture.
 
 ## Preemption

docs/deployment/docker.md

@@ -49,6 +49,39 @@ docker run --rm --gpus all \
 See [Faster Startup](../configuration/optimization.md#faster-startup) for the
 mechanism and for what invalidates the cache.
 
+## Keep model weights in GPU memory across engine restarts
+
+Restarting the `vllm serve` container reloads the model from disk. The [preload](../features/preload.md) feature keeps the weights in a long-lived weight cache daemon container, and a restarted engine container maps them through CUDA IPC:
+
+```bash
+# Long-lived daemon: holds the weights.
+docker run -d --name vllm-weight-cache \
+    --gpus all --ipc=host --pid=host \
+    -v ~/.cache/huggingface:/root/.cache/huggingface \
+    -v vllm-weight-cache:/run/vllm-weight-cache \
+    -e VLLM_FLASHINFER_AUTOTUNE_CACHE_DIR=/run/vllm-weight-cache/autotune \
+    --health-cmd "curl -sf http://localhost:8001/health || exit 1" \
+    --health-interval 10s --health-start-period 10m \
+    --entrypoint vllm \
+    vllm/vllm-openai:latest \
+    preload --model meta-llama/Llama-3.1-8B-Instruct \
+        --weight-cache-socket-dir /run/vllm-weight-cache/sockets \
+        --weight-cache-health-port 8001
+
+# Engine: restarted by Docker, loads from the daemon.
+docker run -d --name vllm \
+    --gpus all --ipc=host --pid=host --restart always \
+    -v ~/.cache/huggingface:/root/.cache/huggingface \
+    -v vllm-weight-cache:/run/vllm-weight-cache \
+    -e VLLM_FLASHINFER_AUTOTUNE_CACHE_DIR=/run/vllm-weight-cache/autotune \
+    -p 8000:8000 \
+    vllm/vllm-openai:latest \
+    meta-llama/Llama-3.1-8B-Instruct --load-format ipc_cache \
+    --model-loader-extra-config '{"socket_dir": "/run/vllm-weight-cache/sockets", "fallback": false}'
+```
+
+Both containers must share the IPC and PID namespaces, the volume holding the sockets and the autotune cache, the GPUs, the user, the image tag and the engine arguments. See [Preload: Docker](../features/preload.md#docker) for the reason behind each requirement, how to share the namespaces between the two containers only, a Docker Compose version and the Kubernetes pattern.
+
 ## Run as a non-root user
 
 The CUDA `vllm/vllm-openai` image runs as root by default for backward