故障排查与常见问题
先看运行时对自身的报告。对于你自己启动的运行时：
curl -s localhost:8100/health
curl -s localhost:8100/v1/models
对于路由器托管的运行时，查看路由器的指标和日志：
curl -s localhost:9190/metrics | grep '^vsr_model_runtime'
vsr_model_runtime_ready{deployment="..."} 1 表示该 deployment 可以作答。
路由器日志会列出每个托管运行时进程以及它停止的原因。
信号从不匹配
很可能是模型还没就绪，或者它的答案到得太晚。
-
查看该 deployment 的
vsr_model_runtime_ready。它为0时，使用它的每个信号都为未知，不会匹配。 -
按
reason查看vsr_model_runtime_unknown_answers_total。timeout表示答案晚于信号的timeout_ms：调大它，或改用更小的模型或 GPU。unavailable表示运行时未就绪或不可达。overloaded表示它的队列已满。 -
打开调试并发送同样的文本，读取
x-vsr-matched-*响应头：curl -s -D - -o /dev/null localhost:8899/v1/chat/completions \-H 'content-type: application/json' -H 'x-vsr-debug: true' \-d '{"model": "auto", "messages": [{"role": "user", "content": "your text"}]}'
运行时一直处于 loading 或 warming
- 首次启动： 模型正在下载，大模型需要几分钟。路由器日志和
GET /health会显示当前阶段。 - 没有网络： 运行时从 Hugging Face Hub 下载。离线时，先把模型复制到缓存中，或把
artifact指向本地副本。 - CPU 上长时间处于
warming： 自检会让模型跑几次请求。大型决策模型在 CPU 上很慢； 请使用 GPU 或vllm-sr/Decision-2.0-Kai-0.6B。 loading且原因中有 "retrying after ..."： 模型因可能自行消失的原因加载失败，例如 GPU 被占用、可用内存不足或下载中断。运行时最多重试五次，首次等待 5 秒，之后每次加倍，期间同一进程中的其他模型照常服务（--load-attempts、--load-retry-seconds）。包损坏或自检失败会立即报告failed。
运行时报告 failed
GET /v1/models 会给出每个模型失败的原因。由路由器运行模型时，路由器日志会带有同样的原因，例如
model runtime is not ready: model @domain_classifier failed to load: ...。
路由器运行的某个运行时进程中所有模型都加载失败时，路由器会重启该进程（首次等待 1 秒，之后最长间隔 60 秒），
因此 GPU 被占用、磁盘已满这类暂时性原因消除后，模型会自行恢复。与仍在服务的模型同处一个进程的模型加载失败时，由运行时自己重试，该进程会继续运行。重试三次仍然失败的任务模型会让路由器无法启动。常见原因：
| 原因提示 | 处理方法 |
|---|---|
| a file hash does not match | 下载已损坏或仓库发生了变化。从缓存中删除该模型后重新启动。 |
| a revision is required | 非内置仓库需要用 40 位 commit 设置 revision。 |
| access denied, gated or private | 用 hf auth login 登录，或为有访问权限的账号设置 HF_TOKEN。Vela 2.0 是私有预览。 |
| does not fit, out of memory | 换用更小的模型、显存更大的 GPU，或给该模型单独的 process。 |
| device not available | 指定的 GPU 不存在，或已安装的 PyTorch 不支持它。使用 device: auto，或安装正确的 PyTorch 版本。 |
| built without LAPACK | 该模型在 CPU 上需要 LAPACK，而当前的 PyTorch（ROCm 镜像中的版本）没有。把模型放到 GPU 上（device: rocm:0），或用 CPU 镜像运行 CPU 上的模型。运行时不会重试。 |
| no family recognizes the package | 不支持该模型的架构。见选择模型。 |
| a licence must be accepted | 该模型的许可证限制了使用。确认你可以使用后，传入 --accept-licence <id>。 |
同一进程中一个模型失败时，该进程中的其他模型继续提供服务。
已就绪模型的自检显示 unverified
GET /v1/models 在 golden 下给出每个模型的自检结果。matched 表示它的回答与该类设备上发布版的回答一致。
unverified 表示模型可以提供服务，但运行时无法担保这一点：
- 没有
reason，且golden.reference为空： 该设备没有发布版的回答，例如非内置模型，或没有验证记录的 GPU（CUDA）。 运行时只检查了回答格式正确，且每次运行都相同。 reason以kernel choices not applied开头： 在 AMD Instinct MI300X 和 MI325X GPU 上，Decision 2.0 和 Vela 2.0 使用发布时用 FLA 0.5.2 记录的内核配置运行，因此每个进程给出相同的回答。这些配置无法在当前环境运行时，模型仍会加载， 日志会写... runs without its recorded kernel choices: ...，它的回答可能与发布版不同。
reason 提示 | 处理方法 |
|---|---|
FLA is not installed | 安装 fla-core==0.5.2，或使用自带它的路由器 ROCm 镜像。 |
they were recorded with FLA 0.5.2, not ... | 安装 fla-core==0.5.2。 |
failed to import | 修复 FLA 安装；消息中给出了具体错误。 |
has no autotuned kernel ... | 安装 fla-core==0.5.2。 |
--autotune-cache 会在重启之间保留已编译的内核，但不能代替记录的配置。
路由器拒绝配置
| 消息提到 | 处理方法 |
|---|---|
removed model execution fields、candle、ort、openvino、precision、variant、use_mmbert_32k、use_nli、polarity_guard | 运行 vllm-sr config migrate。见迁移。 |
| a binding does not match the model | 模型的标签、头、维度与该功能所需不同，或输入上限更小。绑定为该功能训练的模型，或修改 input。 |
artifact must be a Hub repository ID or an absolute package path | Hub 模型用 owner/name，本地副本用绝对路径。 |
revision must be a 40-hex commit | 使用完整的 commit 哈希，而不是分支或标签。 |
长输入被拒绝
任务 deployment 会拒绝超过 input.max_tokens 的输入，而不是悄悄截断。
把 max_tokens 调大到模型上限，或选择其他策略：
global:
model_catalog:
deployments:
vela-pii:
provider: model_runtime
artifact: vllm-sr/Vela-1.0-Encoder-307M-PII
input:
max_tokens: 32768
overflow: window
truncate 保留文本开头。window 用相互重叠的窗口读取全文并合并结果，PII 和安全扫描应使用它，以免漏检。
路由器无法访问挂载的运行时
- 除非用
--host 0.0.0.0启动，运行时只监听127.0.0.1。 - 在容器内部，
localhost指容器自身。请使用宿主机地址、Docker 网络名或 Kubernetes Service。 - 从路由器所在的机器执行
curl <endpoint>/health必须有响应。
请求比预期慢
- 查看运行时
/metrics上的vllm_sr_runtime_request_duration_seconds和vllm_sr_runtime_queue_duration_seconds。排队时间长说明模型已饱 和：增加 GPU、改用更小的模型或另起一个进程。 - 在 CPU 上，同一进程中的模型共享 CPU 线程。用
--threads指定你能分给运行时的核数来启动它。 - GPU 上的决策模型可以使用
shared_context或batching；见 Profiles。
常见问题
需要 GPU 吗？ 不需要。所有内置任务模型以及较小的决策模型都能在 CPU 上运行。
运行时会把我的数据发到别处吗？ 不会。它只从 Hugging Face Hub 下载模型文件，从不把请求文本发出去。 它不记录请求文本，指标中也不包含请求内容。
可以使用非内置的模型吗？ 可以，只要架构受支持：提供带 revision 的 Hub 仓库，或本地绝对路径。
对于它不认识的模型，运行时会计算并报告其身份。
从 Hub 加载模型安全吗？ 运行时从不执行模型仓库中附带的代码，并会在加载前对照固定的哈希校验内置模型的每个文件。
多个路由器可以共享一个运行时吗？ 可以。启动一次，并给每个路由器配置同一个 endpoint。
一个运行时可以提供多个模型吗？ 可以。给 vllm-sr serve 传入多个模型，或让路由器把它的 deployment 分组到进程中。
更换 embedding 模型后，我缓存和存储的向量会怎样？ 它们与新向量隔离，不会被复用。 见更换 embedding 模型时重新向量化。
模型存放在哪里？ 你自己启动的运行时存放在 Hugging Face 缓存（HF_HUB_CACHE）中，
托管运行时存放在路由器的模型目录下；见参考。