In this article
The checkpoint and API alias are different identifiers; changing an alias does not change model weights or capabilities.
vLLM’s served-model-name defines the name a client uses in the API. A request with another model value can fail even after the weights loaded correctly. Read /v1/models and compare its identifier with the request before changing CUDA or reinstalling packages.
Keep model identity, endpoint address and request path as separate checks. This makes a routing error easier to distinguish from failed inference.
Separate the checkpoint from the API alias
The checkpoint selects weights and configuration. The API name is an agreement with clients. A readable alias can refer to a particular repository revision without altering its quality or context capacity.
Several names may refer to the same artifact; they do not necessarily mean several independent models were loaded. Preserve the checkpoint and alias separately in the launch record.
Check a minimal launch
The following illustrates the relevant arguments:
vllm serve Qwen/Qwen3-0.6B --served-model-name local-qwen --max-model-len 4096After readiness, query /v1/models at the intended local server. Use local-qwen in the client only if that is what this process advertises. The example does not install vLLM or verify GPU access; those stages must already be checked.
| Identifier | Purpose |
|---|---|
| Checkpoint | Actual weights and configuration |
| API alias | Client’s model value |
| Base address | Server receiving the request |
| Request path | API operation being called |
| Process reference | Confirms which instance answered |
Investigate the client boundary
Capture an anonymised failing request and compare the model field exactly. If a proxy sits between client and vLLM, repeat a short request directly against the local server. Direct success and proxy failure identify another configuration boundary.
Change one condition at a time. A different port can reach an old process, while a new alias can still point to unchanged weights. Do not infer the destination from the style of the returned text.
Do not confuse naming with compatibility
An alias does not add tool support, change prompt templates or make a different model architecture compatible. After correcting identity, validate the required request format and one useful response.
Store checkpoint revision, API name and server address in the pilot record. Repeat listing and generation after an update or restart. That supports a concrete integration check without mistaking a naming issue for insufficient hardware.
Continue with First Verifiable vLLM Launch in Docker on NVIDIA GPUs and vLLM bench serve: Read a Serving Benchmark Result.