docs: add note around model name consistency (#205)

Signed-off-by: bitliu <[email protected]>

Author: Xunzhuo

website/docs/getting-started/configuration.md

@@ -141,7 +141,7 @@ vllm_endpoints:
     address: "127.0.0.1"  # Your server IP - MUST be IP address format
     port: 8000                # Your server port
     models:
-      - "llama2-7b"          # Model name
+      - "llama2-7b"          # Model name - must match vLLM --served-model-name
     weight: 1                 # Load balancing weight
 ```
 
@@ -176,13 +176,30 @@ address: "127.0.0.1/api"      # ❌ Remove path, use IP only
 address: "127.0.0.1:8080"     # ❌ Use separate 'port' field
 ```
 
+#### Model Name Consistency
+
+The model names in the `models` array must **exactly match** the `--served-model-name` parameter used when starting your vLLM server:
+
+```bash
+# vLLM server command:
+vllm serve meta-llama/Llama-2-7b-hf --served-model-name llama2-7b
+
+# config.yaml must use the same name:
+vllm_endpoints:
+  - models: ["llama2-7b"]  # ✅ Matches --served-model-name
+
+model_config:
+  "llama2-7b":             # ✅ Matches --served-model-name
+    # ... configuration
+```
+
 ### Model Settings
 
 Configure model-specific settings:
 
 ```yaml
 model_config:
-  "llama2-7b":
+  "llama2-7b":              # Must match the model name in vllm_endpoints
     pii_policy:
       allow_by_default: true    # Allow PII by default
       pii_types_allowed: ["EMAIL_ADDRESS", "PERSON"]

website/docs/getting-started/installation.md

@@ -130,6 +130,25 @@ The `address` field **must** contain a valid IP address (IPv4 or IPv6). Domain n
 - `"http://127.0.0.1"` → Remove protocol prefix
 - `"127.0.0.1:8080"` → Use separate `port` field
 
+**⚠️ Important: Model Name Consistency**
+
+The model name in your configuration **must exactly match** the `--served-model-name` parameter used when starting your vLLM server:
+
+```bash
+# When starting vLLM server:
+vllm serve microsoft/phi-4 --port 11434 --served-model-name your-model-name
+
+# The config.yaml must use the same name:
+vllm_endpoints:
+  - models: ["your-model-name"]  # ✅ Must match --served-model-name
+
+model_config:
+  "your-model-name":             # ✅ Must match --served-model-name
+    # ... configuration
+```
+
+If these names don't match, the router won't be able to route requests to your model.
+
 The default configuration includes example endpoints that you should update for your setup.
 
 ## Running the Router

website/docs/getting-started/reasoning.md

@@ -34,7 +34,7 @@ vllm_endpoints:
   - name: "endpoint1"
     address: "127.0.0.1"
     port: 8000
-    models: ["deepseek-v31", "qwen3-30b", "openai/gpt-oss-20b"]
+    models: ["deepseek-v31", "qwen3-30b", "openai/gpt-oss-20b"]  # Must match --served-model-name
     weight: 1
 
 # Reasoning family configurations (how to express reasoning for a family)

website/docs/training/model-performance-eval.md

@@ -59,6 +59,29 @@ see code in [/src/training/model_eval](https://github.com/vllm-project/semantic-
   pip install -r requirements.txt
   ```
 
+**⚠️ Critical Configuration Requirement:**
+
+The `--served-model-name` parameter in your vLLM command **must exactly match** the model names in your `config/config.yaml`:
+
+```yaml
+# config/config.yaml must match the --served-model-name values above
+vllm_endpoints:
+  - name: "endpoint1"
+    address: "127.0.0.1"
+    port: 11434
+    models: ["phi4"]          # ✅ Matches --served_model_name phi4
+  - name: "endpoint2"
+    address: "127.0.0.1"
+    port: 11435
+    models: ["qwen3-0.6B"]    # ✅ Matches --served_model_name qwen3-0.6B
+
+model_config:
+  "phi4":                     # ✅ Matches --served_model_name phi4
+    # ... configuration
+  "qwen3-0.6B":               # ✅ Matches --served_model_name qwen3-0.6B
+    # ... configuration
+```
+
 **Optional tip:**
 
 - Ensure your `config/config.yaml` includes your deployed model names under `vllm_endpoints[].models` and any pricing/policy under `model_config` if you plan to use the generated config directly.