vllm-encyclopedia

name	vllm-encyclopedia
description	vLLM documentation-first workflow for vLLM-specific questions, troubleshooting, command planning, OpenAI-compatible serving behavior, model-loading/runtime behavior, scheduler/prefix-caching/chunked-prefill semantics, quantization and kernel-path checks, multimodal/tool-calling and Responses/OpenAI surface review, build/install/source-tree work, and diagnostics when the actual product/runtime layer is vLLM. Use when the request is clearly about vLLM itself: the `vllm` Python package/CLI, `vllm serve`, `vllm.entrypoints.openai.api_server`, OpenAI-compatible endpoints implemented by vLLM, engine arguments, cache/scheduler behavior, tensor-parallel/pipeline-parallel/expert-parallel settings, paged attention, prefix caching, chunked prefill, speculative decoding, structured outputs, tool calling, reasoning parsers, model support, quantization backends, flash-attention/FlashInfer/XFormers/Triton/kernel selection, or vLLM source build/runtime behavior where vLLM-specific semantics matter. Do not use for generic LLM prompting, generic OpenAI API usage divorced from vLLM, generic CUDA/Linux/PyTorch administration, or model-quality discussions unless the actual issue is specifically about vLLM behavior or configuration.
metadata	{"openclaw":{"emoji":"🧠","homepage":"https://docs.vllm.ai/en/latest/"}}

vLLM Encyclopedia

Overview

Use a docs-first workflow for vLLM work. Prefer the official vLLM documentation at https://docs.vllm.ai/en/latest/, consult cached local copies under .vLLM-Encyclopedia/ before re-fetching, and record useful authoritative excerpts plus environment-specific operational learnings so future work gets faster, safer, and more grounded.

This skill is for the vLLM product/runtime layer. It should trigger for real vLLM serving, engine, OpenAI-surface, build, kernel-selection, model-loading, and operational questions — not for generic LLM prompting, generic PyTorch/CUDA administration, or model-evaluation talk unless vLLM-specific behavior is actually the thing being debugged or discussed.

Workflow

1. Classify the task

   • Decide whether the task is a vLLM question, troubleshooting task, command-planning task, serving/API review, engine/runtime review, source-build task, or live operational task.
   • Use this skill when the request is specifically about vLLM product behavior, the vLLM CLI/Python package, vLLM OpenAI-compatible serving, engine arguments, scheduler/cache/runtime semantics, quantization/kernel/backend selection, or vLLM source build/runtime behavior.
   • Do not use this skill for generic prompt engineering, generic OpenAI API usage unrelated to vLLM, generic CUDA/Linux/PyTorch administration, or pure model-quality discussion unless the vLLM layer is specifically in play.

2. Check local cache first

   • Use .vLLM-Encyclopedia/ as the local knowledge/cache root.
   • Check these locations first when relevant:
     • .vLLM-Encyclopedia/docs/docs.vllm.ai/en/latest/...
     • .vLLM-Encyclopedia/notes/components/...
     • .vLLM-Encyclopedia/notes/patterns/...
     • .vLLM-Encyclopedia/inventory/...
   • If a cached page or note already answers the question well enough, use it.

3. Consult authoritative vLLM docs before answering or acting

   • Before answering direct or indirect vLLM questions that depend on exact CLI/argument behavior, OpenAI-surface semantics, engine/runtime flags, scheduler/cache behavior, model-support boundaries, quantization/backend support, or version-sensitive details, consult the official docs unless the answer is already well-supported by the local cache.
   • Before performing direct vLLM build/config/serving work, consult the relevant docs first when:
     • the exact flag/entrypoint/endpoint path matters
     • serving or runtime semantics are easy to misremember
     • the action could affect model loading, runtime stability, scheduler behavior, structured outputs/tool-calling behavior, cache behavior, parallelism settings, quantization selection, or production reachability
   • If the real issue is generic CUDA/PyTorch/Linux breakage rather than vLLM behavior, do not stretch this skill beyond the vLLM layer.
   • Do not improvise high-impact vLLM answers from memory when the docs are easy to check.

4. Cache consulted docs locally

   • When you consult a vLLM docs page, save a normalized cache copy under .vLLM-Encyclopedia/docs/docs.vllm.ai/en/latest/....
   • Mirror the official docs path structure as much as practical.
   • Cache only pages actually consulted; do not try to mirror the whole docs site eagerly.
   • Use scripts/cache_doc.py when appropriate.

5. Separate authoritative documentation from local observations

   • Store official-doc-derived material under .vLLM-Encyclopedia/docs/....
   • Store environment-specific operational knowledge under:
     • .vLLM-Encyclopedia/notes/components/
     • .vLLM-Encyclopedia/notes/patterns/
     • .vLLM-Encyclopedia/inventory/
   • Distinguish clearly between:
     • authoritative documented behavior
     • observed project/environment state
     • inferred best-practice guidance

6. Record useful local learnings

   • After useful live work, save durable notes such as:
     • deployment layout and endpoint inventory
     • recurring model-load/runtime/debugging patterns
     • backend/kernel-selection or quantization gotchas
     • OpenAI-surface/Responses/tool-calling behavior notes
     • build/source-tree conventions and safe/unsafe operational boundaries
   • Prefer concise durable notes over re-learning the same vLLM details later.

Live Work Rules

• Treat official vLLM docs lookup as the default preflight for non-trivial vLLM work.
• Prefer read/inspect first when entering an unfamiliar vLLM serving/build/runtime area.
• Treat model loading, quantization/backend choice, scheduler/cache behavior, tensor/pipeline/expert parallel settings, structured outputs/tool-calling/Responses behavior, source builds, and production serving endpoints as high-sensitivity areas.
• When uncertainty remains after checking cache + docs, say so and avoid bluffing.
• When answering a question, mention when useful whether the answer comes from cached official docs, a fresh official docs lookup, or live observed environment state.

Data Root

Use this workspace-local root for cache and notes:

• .vLLM-Encyclopedia/

Expected structure:

• .vLLM-Encyclopedia/docs/docs.vllm.ai/en/latest/...
• .vLLM-Encyclopedia/notes/components/...
• .vLLM-Encyclopedia/notes/patterns/...
• .vLLM-Encyclopedia/inventory/...

Use scripts/init_workspace.py to create or repair the expected directory structure.

Note Destinations

• Component-specific observations → .vLLM-Encyclopedia/notes/components/<component-name>.md
• Reusable vLLM patterns/gotchas → .vLLM-Encyclopedia/notes/patterns/<topic>.md
• Environment-wide deployment/access info → .vLLM-Encyclopedia/inventory/*.md
• Cached official docs → .vLLM-Encyclopedia/docs/docs.vllm.ai/en/latest/...

Secrets / Sensitive Data

• Do not store plaintext credentials, API keys, session tokens, private URLs, recovery codes, or other secrets in the encyclopedia notes/inventory tree.
• If a note needs to mention access details, keep it high-level and redact or omit secret material.
• Treat these workspace notes as operational memory, not as a secrets vault.

Resources

• scripts/init_workspace.py — create or repair the .vLLM-Encyclopedia/ directory tree.
• scripts/cache_doc.py — fetch and cache a consulted official vLLM docs page under .vLLM-Encyclopedia/docs/....
• references/workflow.md — detailed operating workflow and evidence-handling rules.
• references/cache-layout.md — canonical .vLLM-Encyclopedia/ directory structure.
• references/topic-map.md — useful vLLM topic groupings for faster authoritative lookup.

Good Outcomes

• Answer a vLLM question using cached or freshly checked official docs instead of guesswork.
• Inspect a live vLLM deployment or source tree after checking the relevant docs and record any new local operational knowledge.
• Build a growing local vLLM knowledge cache that makes later work faster, safer, and more grounded.
• Turn one-off vLLM discoveries into durable notes so future work does not rediscover them from scratch.

Avoid

• Answering vLLM-specific questions purely from memory when docs are easy to consult.
• Treating local observed deployment behavior as if it were guaranteed authoritative vLLM behavior.
• Dumping large amounts of low-value docs into the workspace without a reason.
• Writing environment-specific observations into the official-doc cache tree.
• Confusing generic OpenAI API, generic CUDA/PyTorch admin, or generic model-quality issues with vLLM-specific behavior when the actual vLLM layer is not the thing that matters.