Skypool Token
Token online
Sign up
DocsvLLM

vLLM 本地模型准备

Provider Agent 接入 vLLM OpenAI-compatible 服务前，安装、启动模型、设置上下文窗口和验证可用性的操作说明。

Updated:

什么时候需要看这页

如果你的 Provider 节点准备用 vLLM 承接推理任务，先按这页把 vLLM 服务和模型实例启动起来。vLLM 暴露的是 OpenAI-compatible 接口，和 Ollama 的 /api 接口不同；Provider Agent 侧需要使用 --api-format vllm。

Token 供应示例里的模型名，例如 qwen3.6:35b、gemma4:26b，是启动 Provider Agent 时使用的平台模型代码。vLLM 本身加载的是 Hugging Face 模型 ID 或本地模型目录；控制台展示的“模型名称”用于下载和启动模型，“模型 ID”用于 vLLM 对外暴露的 OpenAI-compatible 模型标识和 Provider Agent 的 --runtime-model-id。

适用系统和特点

vLLM 主要面向 Linux 服务器和 GPU 推理。官方文档的常规 GPU 路径以 Linux、Python 3.10 到 3.13、NVIDIA CUDA 或 AMD ROCm 为主。

主要优点：

  • 吞吐和并发能力强，适合长期在线的 Provider 节点
  • 支持 OpenAI-compatible /v1/models、/v1/chat/completions 等接口
  • 支持 PagedAttention、连续批处理、prefix caching、chunked prefill 和多 GPU 并行
  • 支持 Hugging Face 模型 ID、本地模型目录和多种量化格式

主要限制：

  • 安装和驱动环境比 Ollama 更复杂，需要关注 CUDA、ROCm、PyTorch、显存和并行度
  • 一次 vllm serve 通常服务一个主模型，多个模型一般需要多个进程或额外路由
  • --max-model-len 不能让模型突破自身训练或配置支持的上下文上限

安装 vLLM

NVIDIA CUDA 环境推荐使用 uv 创建独立环境：

Bash
uv venv --python 3.12 --seedsource .venv/bin/activateuv pip install vllm --torch-backend=auto

AMD ROCm 环境需要使用 ROCm wheel 源，具体版本以 vLLM 官方安装页为准：

Bash
uv venv --python 3.12 --seedsource .venv/bin/activateuv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/

也可以直接使用官方 OpenAI-compatible Docker 镜像：

Bash
docker run --runtime nvidia --gpus all \  -v ~/.cache/huggingface:/root/.cache/huggingface \  --env "HF_TOKEN=$HF_TOKEN" \  -p 8000:8000 \  --ipc=host \  vllm/vllm-openai:latest \  --model Qwen/Qwen3.6-35B-A3B \  --max-model-len 262144

如果模型需要 Hugging Face 鉴权，先设置 HF_TOKEN。首次启动时，vLLM 会把模型下载到 Hugging Face 缓存目录。

准备模型名

vLLM 的 --model 接收 Hugging Face 模型 ID 或本地路径，不接收 Ollama 风格的 name:tag 作为下载目标。

实际使用时，先打开 Provider API 密钥页，在 Token 供应示例中选择目标模型和 vLLM 推理框架，然后分别点击“复制模型名称”和“复制模型 ID”。模型名称用于 vllm serve 的下载来源；模型 ID 是 /v1/models、验证请求里的 model，也是 Provider Agent 的 --runtime-model-id / PROVIDER_AGENT_RUNTIME_MODEL_ID。

常见对应关系可以这样理解，最终以页面里“模型名称 / 模型 ID”显示的值为准：

Token 供应示例模型名vLLM 模型名称vLLM 模型 ID说明
qwen3.6:35bQwen/Qwen3.6-35B-A3BQwen/Qwen3.6-35B-A3B模型卡标注原生 262144 tokens，适合作为长上下文示例
gemma4:26bgoogle/gemma-4-26B-A4B-itgoogle/gemma-4-26B-A4B-it具体 checkpoint 以你实际下载和平台配置为准

vLLM 默认会用 --model 的值作为服务侧模型名。一般保持这个名字即可：

Bash
vllm serve Qwen/Qwen3.6-35B-A3B \  --max-model-len 262144 \  --host 0.0.0.0 \  --port 8000

如果你确实需要使用 --served-model-name 覆盖返回名称，也应设置为上表中的 vLLM 模型 ID，例如 Qwen/Qwen3.6-35B-A3B，不要设置成 Ollama 风格的 qwen3.6:35b。Provider Agent 的 --runtime-model-id 需要和这个服务侧模型 ID 一致。

设置上下文窗口

vLLM 对应的上下文字段是 max_model_len，命令行参数是 --max-model-len。这个值要根据目标模型要求的“上下文窗口”大小设置，不能默认所有模型都写成同一个数字。下面示例里的 262144 只适用于明确支持 256K 上下文窗口的模型；如果模型要求 128K，则应设置为 131072。

Bash
vllm serve Qwen/Qwen3.6-35B-A3B \  --served-model-name Qwen/Qwen3.6-35B-A3B \  --max-model-len 262144 \  --dtype auto \  --host 0.0.0.0 \  --port 8000 \  --api-key runtime-...

需要多 GPU 时，按机器情况增加 tensor parallel：

Bash
vllm serve Qwen/Qwen3.6-35B-A3B \  --served-model-name Qwen/Qwen3.6-35B-A3B \  --max-model-len 262144 \  --tensor-parallel-size 4 \  --host 0.0.0.0 \  --port 8000

注意：

  • --max-model-len 是 prompt 和输出合计的上下文长度
  • OpenAI 请求体里的 max_tokens 只是本次最多生成多少 token，不是上下文窗口
  • 如果模型配置本身不支持目标上下文窗口大小，强行设置可能报错、质量下降或显存溢出
  • 如果启动时 OOM，先降低 --max-model-len、降低并发、调整量化或增加 GPU 并行

验证 vLLM 服务

如果启动时配置了 --api-key runtime-...，验证时也要带上 Authorization header。

查看模型列表：

Bash
curl http://127.0.0.1:8000/v1/models \  -H "Authorization: Bearer runtime-..."

做一次非流式推理：

Bash
curl http://127.0.0.1:8000/v1/chat/completions \  -H "Authorization: Bearer runtime-..." \  -H "Content-Type: application/json" \  --data-raw '{    "model": "Qwen/Qwen3.6-35B-A3B",    "messages": [      {        "role": "user",        "content": "用一句中文回复：vLLM 服务可用。"      }    ],    "max_tokens": 64,    "temperature": 0  }'

如果没有配置 --api-key，删掉 Authorization 这一行即可。

启动 Provider Agent

vLLM 服务可用后，再启动 Provider Agent：

Bash
./token-provider-agent preflight start \  --model qwen3.6:35b \  --base-url http://127.0.0.1:8000 \  --api-format vllm \  --runtime-model-id Qwen/Qwen3.6-35B-A3B \  --runtime-api-key runtime-...

预检通过后正式启动：

Bash
./token-provider-agent start \  --api-key stp-... \  --model qwen3.6:35b \  --base-url http://127.0.0.1:8000 \  --api-format vllm \  --runtime-model-id Qwen/Qwen3.6-35B-A3B \  --runtime-api-key runtime-...

如果 vLLM 没有启用推理框架 API Key，可以省略 --runtime-api-key。

参考链接