# PR #56414 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Docs] Add Nebius Serverless AI deployment guide
- 合并时间：2026-09-11 14:58
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/56414

---

# 执行摘要

- 一句话：新增 Nebius Serverless AI 单卡部署 vLLM 指南
- 推荐动作：值得精读程度：中低。纯文档 PR 不需要逐行评审，但有三处设计值得借鉴：(1) 用镜像 digest + 模型 revision + CLI 版本三重固定来保证可复现，这套写法可以直接复用到其他平台指南；(2) 把「RUNNING 不等于模型加载完成」「公共 URL 必须唯一」等踩坑经验写成可执行断言和等待条件，而不是含糊提示；(3) 对 stop/start 与删除的语义、成本与持久化边界做了明确交代。建议维护者在合入后续跟进：为这类指南建立 digest/revision 过期检查或更新 checklist（例如随 vLLM 发版同步更新 pinned digest），并考虑在 CI 中至少对 shell 片段做语法或 dry-run 校验。另外要留意该分支名带 `codex/` 前缀、PR body 结构化程度很高，文档由 AI 辅助起草，但作者确实在真实 Nebius 环境完成了验证，评审时可优先核对示例参数与平台约束的准确性。

# 功能与动机

PR body 的 Purpose 写明目标是「Add a single-GPU deployment guide for running vLLM on Nebius Serverless AI Endpoints」，即让 Nebius Serverless AI 的用户有一条可直接复制的 vLLM 自托管路径。指南开头主动划清边界：Endpoint 会一直运行到被停止或删除，示例使用常规 GPU 实例，「does not configure autoscaling or automatic scale-to-zero」。文档还专门解释了重启语义——「Starting again can require fresh capacity and new image/model downloads; do not rely on the container disk as persistent storage」，说明动机不只是「贴一份命令」，而是把容量、镜像 / 模型下载、token 混淆、RUNNING 不等于模型加载完成这些线上最容易踩的坑前置写清楚。关联 Issue 为空，属于第三方平台侧主动贡献的生态文档。

# 实现拆解

1. **新增单页指南，复用自动导航**：唯一改动是新增 `docs/deployment/frameworks/nebius.md`（148 行新增、0 删除）。页面放在既有的 `docs/deployment/frameworks/` 目录下，PR body 说明「The page uses existing automatic deployment navigation and links the Nebius cookbook」，因此没有改动 mkdocs 配置或导航文件。章节顺序为 Prerequisites → Create the Endpoint → Check readiness → Send a chat request → Stop or delete the Endpoint → Troubleshooting。

2. **可复现性优先的参数固定**：指南把环境变量集中导出，包括 `PROJECT_ID`、`SUBNET_ID`、随机生成的 `ENDPOINT_NAME`（`openssl rand -hex 6`）与 `AUTH_TOKEN`、`MODEL_ID=Qwen/Qwen3-0.6B`、`MODEL_REVISION=c1899de...`，以及镜像引用 `vllm/vllm-openai@sha256:89c1d062...`（用 digest 而非 tag）。同时注明测试所用版本：Nebius CLI `0.12.265`、`gpu-l40s-a` 平台、`1gpu-8vcpu-32gb` 预设，并提示换镜像时要核对 CUDA/ 驱动与该平台的兼容性。

3. **鉴权与网络边界的显式取舍**：`nebius ai endpoint create` 使用 `--auth token --token "$AUTH_TOKEN"`，且只暴露一个端口 `--container-port 8000/http`，文档解释这是 Nebius token 鉴权的约束（「requires exactly one HTTP port」），因此没有再叠加 vLLM 自带的 API key。配套要求包括 `--public=false`、`--preemptible=false`、`--retries 1`，并强调 Endpoint token 与 Nebius CLI 控制面凭证是两套东西、子网内访问需限制可信客户端，最后给出「不带 token 请求应返回 HTTP 401 或 403」的反向验证。

4. **就绪判定与入口 URL 选择**：指南要求先 `nebius ai endpoint get` / `logs --tail 100 --timestamps` 观察状态，再用 `jq -er` 从 `status.public_endpoints` 中筛出恰好一个 `https://` 入口（长度不为 1 则 `error("Expected one HTTPS URL")`），并去掉尾部斜杠。随后明确「`RUNNING` alone does not establish that the model has finished loading」，必须等 `/health` 成功且 `/v1/models` 列出 `Qwen/Qwen3-0.6B` 才能发 chat 请求；等待期间应看日志而不是重复创建 Endpoint。

5. **请求示例与生命周期 / 成本说明**：chat 示例包含 `chat_template_kwargs.enable_thinking=false` 并注明这是 Qwen 专用选项、不是通用参数；流式示例要求 `curl -N` 且不要管道给 `jq`，成功流以 `data: [DONE]` 收尾；OpenAI 兼容客户端以 `${ENDPOINT_URL}/v1` 为 base URL。生命周期部分说明 stop 是同步的、需确认 `STOPPED`，重新 start 可能重新申请容量与下载，删除后要确认 get 返回 `NotFound`，并提醒关闭终端、中断请求都不会停止 Endpoint，挂载存储另计费。

6. **排障表与验证配套**：Troubleshooting 表覆盖 6 类症状——`PROVISIONING`/`NotEnoughResources`（配额与容量是两件事）、`RUNNING` 但 502/503（模型下载与引擎日志、子网 egress、端口绑定）、401/403（用 Endpoint token 而非控制面 token）、CUDA/OOM（镜像与驱动兼容性、显存与上下文长度）、model not found（校验 ID 与 revision）、流式中断（不应自动重放为新一轮生成）。测试侧无任何源码 / 测试 / 配置 /CI 改动，作者在 PR body Test Result 中给出人工验证证据：两次冷启动、缺失 / 错误 token 拒绝、chat、SSE 增量与终态 DONE、curl 与 OpenAI client 3.12.0、并发、stop/start 复测、失败处理与删除，并清理了 5 个测试 Endpoint。

关键文件：
- `docs/deployment/frameworks/nebius.md`（模块 部署文档；类别 docs；类型 documentation）: 唯一改动文件：新增 Nebius Serverless AI 单卡部署指南，148 行全部为新增内容，覆盖创建 Endpoint、token 鉴权、就绪判定、chat/ 流式请求、stop/start 与清理、故障排查表，并固定镜像 digest 与模型 revision 保证可复现。

关键符号：未识别

## 关键源码片段

### `docs/deployment/frameworks/nebius.md`

唯一改动文件：新增 Nebius Serverless AI 单卡部署指南，148 行全部为新增内容，覆盖创建 Endpoint、token 鉴权、就绪判定、chat/ 流式请求、stop/start 与清理、故障排查表，并固定镜像 digest 与模型 revision 保证可复现。

下面的两个片段来自指南中最核心的两段：先创建 Endpoint（版本全部锁死、鉴权与端口约束一次说清），再验证就绪与鉴权是否真的生效。

```bash
# 环境准备：项目 / 子网 / 随机 Endpoint 名与入口 token
# Endpoint 名称带随机后缀，避免与既有资源重名；名字要保留好，创建超时后靠它找回 Endpoint
export PROJECT_ID="<project-id>"
export SUBNET_ID="<subnet-id>"
export ENDPOINT_NAME="vllm-qwen-$(openssl rand -hex 6)"
export AUTH_TOKEN="$(openssl rand -hex 32)"   # Endpoint 入口 token，与 Nebius CLI 控制面凭证是两套东西
export MODEL_ID="Qwen/Qwen3-0.6B"
# 模型与 tokenizer 共用同一个 revision，保证权重与分词器一致、结果可复现
export MODEL_REVISION="c1899de289a04d12100db370d81485cdf75e47ca"
# vllm/vllm-openai:v0.19.1 对应的 Linux/amd64 镜像 digest；写 digest 而不是 tag，避免镜像漂移
export VLLM_IMAGE="vllm/vllm-openai@sha256:89c1d0629d377daa3f7f369cbea6167a7b48ea89aaacd12555e2b0b2f7f740d3"

# --container-command vllm + --args "serve ..." 等价于本地执行 vllm serve
# --auth token 要求恰好暴露一个 HTTP 端口，因此这里只用 8000/http，也没有叠加 vLLM 自带 API key
# --public=false 表示不申请公网 VM IP，仍然可以走 managed HTTPS 入口；子网仍需能出网下载镜像与模型
nebius ai endpoint create \
  --parent-id "$PROJECT_ID" \
  --subnet-id "$SUBNET_ID" \
  --name "$ENDPOINT_NAME" \
  --image "$VLLM_IMAGE" \
  --container-command vllm \
  --args "serve $MODEL_ID --revision $MODEL_REVISION --tokenizer-revision $MODEL_REVISION --host 0.0.0.0 --port 8000 --tensor-parallel-size 1 --max-model-len 4096 --gpu-memory-utilization 0.8" \
  --platform gpu-l40s-a \
  --preset 1gpu-8vcpu-32gb \
  --container-port 8000/http \
  --auth token --token "$AUTH_TOKEN" \
  --disk-size 250Gi --shm-size 16Gi \
  --public=false --preemptible=false \
  --retries 1

```

```bash
# 选 URL：断言 public_endpoints 中恰好有一个 https 入口，多于或少于一个都直接报错
# 这能挡住 ENDPOINT 仍在 STARTING 时 ingress 返回 404 的情况，并保留 scheme
ENDPOINT_URL="$(nebius ai endpoint get "$ENDPOINT_ID" --format json \
  | jq -er '[.status.public_endpoints[]? | select(startswith("https://"))]
            | if length == 1 then .[0] else error("Expected one HTTPS URL") end')"
export ENDPOINT_URL="${ENDPOINT_URL%/}"

# 就绪判定：RUNNING 只说明控制面在跑，必须等 /health 成功且 /v1/models 能列出模型
curl --fail-with-body --silent --show-error --max-time 10 \
  "$ENDPOINT_URL/health" -H "Authorization: Bearer $AUTH_TOKEN"
curl --fail-with-body --silent --show-error --max-time 10 \
  "$ENDPOINT_URL/v1/models" -H "Authorization: Bearer $AUTH_TOKEN" | jq

# 反向验证：不带 token 应当被拒绝，期望 HTTP 401 或 403
# 这一步是为了确认 Endpoint 没有意外接受匿名推理请求
curl --silent --show-error --max-time 10 --output /dev/null \
  --write-out '%{http_code}\n' "$ENDPOINT_URL/v1/models"

```

# 评论区精华

本 PR 几乎没有实质性的 review 交锋，3 条 comments 全部来自 bot：mergify 给出 ReadTheDocs 预览链接，github-actions 给出欢迎 /CI 授权提示，review 侧只有 claude[bot] 的一条说明——「This pull request is from a fork — automated review is disabled」，即该文档未经自动化审查。唯一的人类评审是 maintainer ywang96 的批准：「Thanks for adopting vLLM at Nebius!」，没有提出任何修改请求。因此本次讨论的「精华」主要来自 PR body 自身的验证证据与文档里的取舍表述：作者把 RUNNING ≠ 模型就绪、Endpoint token 与控制面凭证分离、stop/start 可能要重新拉容量与镜像等经验写进正文，等价于用文档回答了通常会在 review 里被追问的问题（怎么确认服务真正可用、失败时怎么清理、密钥怎么管）。

- Fork PR 关闭自动化 review (other): 无人请求补充自动 review，维护者以人工批准放行；文档类改动被视为低风险。
- 维护者对第三方平台适配文档的态度 (documentation): 维护者欢迎外部平台贡献部署指南，本 PR 无需返工即合入。
- 文档类改动的验证标准 (testing): 以真实环境端到端验证替代自动化测试，评审接受该证据，未要求补充 CI 校验。

# 风险与影响

- 风险：
 1. **版本与 digest 漂移**：指南把 `vllm/vllm-openai@sha256:89c1d062...`、`MODEL_REVISION=c1899de...`、Nebius CLI `0.12.265`、平台 / 预设 `gpu-l40s-a` 与 `1gpu-8vcpu-32gb` 全部写死，一旦 vLLM 发布新版本或 Nebius 下架该平台 / 预设，复制文档会失败，而文档没有注明更新责任人或过期检查机制。
 2. **缺少自动化校验**：没有测试或 CI 改动，docs 构建只校验文档引用与格式（PR body 也提到在排除 API 文档时会出现无关引用告警），shell 片段、`jq -er` 表达式、请求 JSON 都不会被执行，命令何时失效只能由读者发现。
 3. **示例参数被当成默认值**：`--tensor-parallel-size 1 --max-model-len 4096 --gpu-memory-utilization 0.8 --disk-size 250Gi --shm-size 16Gi` 是针对 Qwen3-0.6B + 单张 L40S 的可跑通配置；用户直接照搬到更大模型或更长上下文会 OOM，文档只在排障表里提示「check the model's memory requirements and maximum context length」。
 4. **密钥处理偏弱**：`export AUTH_TOKEN=...` 会进入 shell 历史与进程环境，指南虽然提示可使用 Nebius secret environment variables 并在清理步骤 `unset AUTH_TOKEN`，但示例本身没有走 secret 管理；好的一面是强调了 token 不可分享、`--public=false` 与 401/403 反例校验。
 5. **入口语义依赖外部行为**：URL 出现于 `STARTING` 阶段会返回 404、公共 URL 数量必须恰好为 1 等假设都来自作者实测，没有 Nebius 官方契约背书，平台侧行为变化会静默让文档失真。
 - 影响：对用户：想要在 Nebius Serverless AI 上自托管 vLLM 的用户获得一条「从创建到清理」的可复制路径，能提前规避入口 404、token 混淆、把 RUNNING 当就绪、误以为重启保留磁盘等高频问题，属于降低首次上手成本的文档收益。对系统：零影响，不触碰任何运行时代码路径、配置默认值或依赖，不改变部署产物。对团队与生态：`docs/deployment/frameworks/` 的第三方平台矩阵继续扩张，外部平台的部署支持成本从「答疑」转为「维护文档」，但维护成本也会随之转移到版本更新（digest、CLI 版本、平台 / 预设）。影响程度整体偏低（纯文档、单文件、无运行时代码），但对外可见性中等——页面自动进入 deployment 导航，且已通过 ReadTheDocs 预览与渲染检查。
 - 风险标记：版本与镜像 digest 易过期 , 文档命令无自动化校验 , 示例参数被误当默认值 , 密钥以环境变量示例给出 , 外部平台行为假设未获官方背书

# 关联脉络

- PR #56286 [Docs]: quote variable-bearing wheel URLs: 同为纯文档 PR（只改 docs 内容、无运行时代码变更），可用于对照 vLLM 对文档类改动的评审尺度与合并节奏；两者都涉及「用户复制粘贴命令 /URL 会出错」这类可用性问题。
- PR #56379 [EC] Automatically enable embedding inputs on EC/KV consumers: 同属部署形态多样化这条线：本 PR 面向 Serverless Endpoint 的单卡托管部署，该 PR 面向 EC/KV 消费者侧的自动配置，都反映 vLLM 正在适配更多外部部署拓扑。