装完 ollama 跑得好好的,换 llama.cpp 编译过不了;vllm 起服务端口通了,客户端却一直超时。多数人第一反应是换模型或者重装,白折腾半天。这篇按「装没装上、服务起没起、请求通不通」三层往下走,每层给可执行的检查动作,让你在十分钟内知道该改哪一格。
装完 ollama 跑得好好的,换 llama.cpp 编译过不了;vllm 起服务端口通了,客户端却一直超时。多数人第一反应是换模型、重装、再换个量化版本,白折腾半天。这事儿麻烦在:三个工具报的错看着都像「模型有问题」,实际卡的位置完全不同。
下面这套顺序按三层往下走——装没装上、服务起没起、请求通不通。每层给一条最小复现命令和判断标准,目标是十分钟内知道该改哪一格,而不是把能跑的东西改坏。卡住超过半小时再考虑换路验证,别在原地反复重启。
先别改配置,把「卡在哪一层」确定下来
三个工具的故障可以粗分成四层:包装不上、模型拉不下来、服务起不来、请求连不通。层与层之间别混着改,因为它们的报错长得像。举个最常见的误判:vllm 客户端超时,有人去重装 CUDA,其实服务早就起来了,只是客户端 base_url 填的是容器里的 localhost。
- 用一条最小命令复现ollama 用 ollama run 一个本地已有的模型;llama.cpp 用 llama-cli 直接跑一个现成 gguf;vllm 起服务后用 curl 打一次健康检查接口。三条命令跑一遍,哪条先挂就锁在哪层。
- 只修挂掉的那一层挂在哪层改哪层,别顺手把温度、上下文、并行度全调一遍。改完再跑同一条最小命令,确认这一层过了再往上走。
- 横向对比同一个模型换到另一个工具里跑一次。ollama 能跑、llama.cpp 报错,说明问题在框架适配或文件格式,模型权重本身没坏。
判断标准很简单:最小命令能过、换个工具也过,那问题就出在你没检查到的配置项上。这条横向验证花的时间最少,能砍掉一大半「重装一遍」的冲动操作。
装不上这一类:报错在编译和依赖,不在推理
编译报错和 import 报错都发生在加载权重之前,这类问题跟模型大小、量化格式基本无关。看到报错里出现编译器、链接器或者 Python 模块名,就先别怀疑模型。
- llama.cpp 卡在 cmake 阶段,先看是缺 CUDA 工具链还是显卡驱动版本对不上,用 nvcc 和驱动查询命令各确认一次,不要直接换分支重来
- vllm 装完 import 报错,多半是 torch 版本和 vllm 要求的版本错位,按它官方安装说明对齐版本,pip 和 conda 别混着装
- ollama 装完没服务,先查是不是装了第三方封装或旧版本,用系统服务状态命令确认进程到底起没起
- 编译通过但运行时报找不到动态库,这是安装路径没进环境变量,不是模型问题
模型拉不下来:先分清是下载失败还是格式不认
下载失败和格式不认的表现很像,处理方向完全不同。前者是网络和权限,后者是文件本身。用一条区分动作:把报错全文看一眼,出现解析失败、超时、404 这类词,归下载;出现不认识的格式、魔数不对、张量名缺失,归格式。
- ollama 报拉取失败,用 ollama list 看有没有半截记录,再看日志里的地址是解析失败还是连接超时
- llama.cpp 报不认识的 gguf,通常是量化版本不被当前构建支持或文件被截断,换官方发布的 gguf 试一次就能区分
- vllm 报权重格式不支持,先确认它认的是 safetensors 还是 huggingface 目录结构,gguf 要走另一条加载路径
- 文件权限问题会被伪装成格式错误,确认运行用户对模型目录有读权限
不适用的情况也得说清楚:内网离线环境,所有下载类报错都要先排除网络策略和代理,再看工具本身。这时候换模型、换量化版本全是白费。
服务起不来:显存、参数、端口三处挨个看
先分清「进程退出」和「进程活着但请求没响应」。前者是起不来,查显存、参数、端口;后者是连通问题,下一节再说。很多人把这两种混成一种,结果去改了根本没问题的启动参数。
- 看启动日志头几行先找 OOM 还是精度不支持。显存不足是最常见的起不来原因,日志里一般会明确写出来。
- 按最小配置起一次vllm 的上下文长度、张量并行度这类参数填大了会直接起不来,先用最小配置跑通,再加回去。llama.cpp 同理,先减 GPU 层数。
- 确认端口和监听地址端口被占用和监听地址写错是两个问题。前者换端口,后者改绑定地址;用端口占用查询命令确认是哪种。
判断标准:进程退出就是起不来,进程活着但请求打过去没反应,属于下一层的连通问题。别在启动参数上浪费时间。
请求连不通:地址、鉴权、协议格式对不上
这一层的坑最多,也最容易误判成服务坏了。先用 curl 直接打健康检查接口,能通就说明服务没问题,问题在客户端配置。curl 都不通,才回头查服务层。
- 容器访问宿主机
- localhost 指向容器自己,要换成宿主地址或者走同一 Docker 网络
- OpenAI 兼容路径
- base_url 和结束路径要分开填,差一个前缀就是 404 而不是报错
- 鉴权
- 先确认这个工具本身要不要 API key,别照搬别家的配置直接贴
- 超时
- curl 加长超时再试一次,区分是没响应还是响应慢
实际用下来,客户端超时十有八九是地址填错。把 curl 命令和客户端配置并排放,逐字符对一遍地址,比读十遍文档快。
一张对照表:同样的症状,三个工具该看哪
| 症状 | ollama | llama.cpp | vllm |
|---|---|---|---|
| 编译或依赖报错 | 基本不编译,查服务状态 | 看 CUDA 工具链和 cmake | 看 torch 版本是否对齐 |
| 模型加载失败 | 看拉取日志和文件完整性 | 先验 gguf 完整性和量化版本 | 先验目录结构和权重格式 |
| 起服务时 OOM | 换更小的量化版本 | 减 GPU 层数 | 调小上下文和并行度 |
| 请求超时 | 先本机 curl 再换地址 | 先本机 curl 再换地址 | 先本机 curl 再换地址 |
表格里最后一行的三格一样,不是偷懒:连通问题的排查动作在三个工具里是共通的,先本机 curl,再换局域网地址,最后才怀疑客户端代码。想对照各家工具的实际推理解码速度,可以到 /tools/speed-test 跑一次,比自己拼参数快。
排查顺序里最省时间的一步:先把日志找对
很多人只看终端输出的第一屏就下结论。实际上 ollama 的权限和端口问题只写在服务日志里,终端静悄悄;llama.cpp 的报错往往在加载完文件之后那几行。先把日志找对,能省掉一大半瞎猜。
- ollama 看服务日志而不是只看终端,系统服务方式安装的日志在系统日志里
- vllm 启动报错优先看最后几十行,前面多是正常加载信息,别被刷屏劝退
- llama.cpp 报错集中在加载完文件之后,别只看第一屏就断定是模型坏了
- 每改一处就记一行,改了什么、结果如何;不记的话问题会越修越多
卡住超过半小时,换一条路验证
原地反复重启是最耗时间的做法。卡满半小时就停手,换一条路验证:同一个模型换一个工具跑,能跑通说明是原工具配置问题,不是模型坏了;把服务起在最小配置上先跑通一次请求,再逐步加回参数。
还有一条容易忽略的动作:量响应时间。curl 加一个计时参数,看是连不上还是连上了但回得慢。这两种处理方向完全相反,一个查网络和端口,一个查显存和并发。判断不适用的情况:生产环境排障要先保住服务,切流量、留日志,别在原地重启。
排查不是把所有参数试一遍,是先把问题锁到一层,再只动那一层里的一个格子。下一步想先确认手上的中转站和各家官方接口在这个模型上的实际表现,去站内的中转站可信度检测和价格追踪页面对一遍当时的数字,比对着报错反复试快。→
常见问题
三个工具都装了,同一个模型只有 ollama 能跑,是模型坏了吗?
多半不是。能在一个工具里跑通,说明模型文件本身可用,问题在另外两个工具的加载方式或参数上。先确认它们认的格式对不对,再查显存和上下文设置,别急着重新下载模型。
vllm 启动没报错,但客户端一直超时,怎么定位?
先在服务器本机用 curl 打一次接口。本机能通说明服务正常,问题在地址、端口映射或容器网络;本机也不通再看启动日志是不是只加载到一半。两种情况的修法完全不同。
llama.cpp 编译总失败,要换别的部署方式吗?
先看报错是缺编译工具还是显卡驱动版本不匹配,这类问题有明确的修法。编译阶段失败跟模型和推理完全无关,换工具反而把变量变多了。
显存不足的报错,三个工具的解法一样吗?
方向一致但参数不同。vllm 主要调上下文长度和并行度,llama.cpp 调卸载到 GPU 的层数,ollama 换更小的量化版本或减小并发。先确认是哪一项把显存吃掉的。
怎么判断问题出在模型还是框架?
同一份权重要是能在另一个工具里跑通,问题就在框架侧。反过来三个工具都在加载阶段报错,才值得去验证文件完整性和格式。