diff --git a/README.md b/README.md
index d5e1644..c06440c 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,12 @@ make lint      # ruff check .
 
 For local vLLM inference (NVIDIA GPU, CUDA 12.8, ≥ 24 GB VRAM):
 
+```bash
+uv sync --extra vllm
+```
+
+vLLM is an optional extra so the base install resolves on macOS / non-CUDA hosts. If you don't use `uv`:
+
 ```bash
 uv pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128
 ```
diff --git a/pyproject.toml b/pyproject.toml
index 8113e31..933ef7b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -20,12 +20,14 @@ dependencies = [
     "transformers>=4.40.0",
     "sentence-transformers>=5.2.3",
     "torch>=2.10.0",
-    "vllm==0.17.0",
     "openai>=2.24.0",
     "anthropic>=0.75.0",
     "google-genai>=1.0.0",
     "pyarrow>=16.0.0",
 ]
 
+[project.optional-dependencies]
+vllm = ["vllm==0.17.0"]
+
 [tool.pytest.ini_options]
 pythonpath = ["."]
diff --git a/uv.lock b/uv.lock
index 22da3ac..815ac79 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2703,6 +2703,10 @@ dependencies = [
     { name = "torch" },
     { name = "tqdm" },
     { name = "transformers" },
+]
+
+[package.optional-dependencies]
+vllm = [
     { name = "vllm" },
 ]
 
@@ -2727,8 +2731,9 @@ requires-dist = [
     { name = "torch", specifier = ">=2.10.0" },
     { name = "tqdm", specifier = ">=4.67.3" },
     { name = "transformers", specifier = ">=4.40.0" },
-    { name = "vllm", specifier = "==0.17.0" },
+    { name = "vllm", marker = "extra == 'vllm'", specifier = "==0.17.0" },
 ]
+provides-extras = ["vllm"]
 
 [[package]]
 name = "sse-starlette"