同时装过这三样的人大概都遇到过:模型下好了、命令敲对了,结果一句报错看不出是哪里错。多数时候不是模型坏了,是你没先分清卡在下载、加载、服务还是接口这一层。这篇给一个从外往里收的排查顺序,三边通用,照着走能省掉大半重装。
同时装过 ollama、vllm、llama.cpp 的人大概都有这种经历:模型下好了,命令也照着文档敲了,屏幕上蹦出一行报错,看不出是哪里错。第一反应是重装,重装完还是那行字。多数时候模型本身没毛病,是你没先分清它卡在下载、加载、服务还是接口这一层,一急就从头再来一遍,时间全花在同一个坑里。
这篇给一套从外往里收的排查顺序,三家通用。核心思路很朴素:先定位层级,再动手。定位错了,后面做什么都是白费。顺带说一句,这套顺序也有它管不上的情况,最后一节单独讲。
先别急着装,先确认卡在哪一层
把整条链路拆成四层:模型文件在不在本地、进程有没有起来、端口通不通、客户端请求格式对不对。这四层是从里往外的,报错落在哪一层,就往哪一层查,别跨层猜。判断方法土但有效——看日志最后一行写的是模型名还是端口号。写模型名,卡在第一层;写端口号,直接往第三层去。
三家的日志位置不一样,翻错文件是常见误判。ollama 要看服务日志,不是你敲 pull 那个终端的输出;vllm 看启动时 uvicorn 打印的那一大段;llama.cpp 最直接,终端 stderr 就是它的日志。找不到日志就去翻你启动服务的那个窗口,别去翻客户端那边的记录。
| 现象 | 最可能卡在 | 先去查 |
|---|---|---|
| 日志末尾反复出现模型名 | 第一层:文件 | 文件是否齐全、大小是否对得上 |
| 进程起了但请求没反应 | 第三层:端口 | 绑定地址和端口号 |
| 直接返回鉴权失败 | 第四层:接口 | 请求头里有没有带 key |
| 加载阶段就崩 | 第二层:参数 | 显存和并行度是否超出 |
| 容器外访问不了 | 第三层:端口 | 服务是否只听本机 |
模型下不下来和跑不起来,是两件事
这两件事经常被混成一件。ollama pull 卡住,绝大多数情况跟显存无关,是镜像源和网络的事,你去调 num_gpu 纯属南辕北辙。llama.cpp 要自己拿 GGUF 文件,路径写错时报的是文件找不到,不是模型不支持,这两种报错长得像,处理方式完全不同。
vllm 更认 Hugging Face 那种目录结构。权重缺 index 文件、分片少一个,它都会在加载阶段报失败。所以进下一层之前,先老老实实 ls 一遍目录,看该有的文件齐不齐、单个文件大小对不对得上。能看见文件、大小合理,才算过了这一层。
- 拉取卡住先换源或换网络时段,别急着动显存参数
- GGUF 文件确认路径写到文件名那一级,不是只写到目录
- 权重目录里 index 和全部分片都要在,缺一个都会加载失败
- 文件大小和发布页标注的对一下,明显偏小就是没下完
参数填错一格,报错能绕一大圈
显存相关的报错,先算账再动手。参数量乘量化位宽,再留出上下文缓存的空间,超过卡容量就会在加载阶段炸。这时候换小一档量化,通常比调参数快得多。我见过有人为了跑起来把并行度一路往下调,结果模型能载入了,吞吐惨不忍睹——方向从一开始就错了。
vllm 的并行度和张量分片数要和卡数对上,填大了直接起不来,填小了浪费卡。ollama 的 num_gpu 填过头,会把一部分层卸载回内存,速度掉得莫名其妙,报错都不给你。这类参数别背,去站内按自己的卡和模型算一遍更省事。
- 先确认卡数用系统自带工具看实际可用的卡有几张,别按机器标称算
- 按卡数定并行度和分片vllm 的这两个数要能整除对上,填完重启看启动日志有没有报错
- 算显存余量参数量乘量化位宽,再留出上下文缓存,超了就先降一档量化
- 验证服务能稳定起来、跑一次推理不崩,才算这一层过了
服务起来了但调不通,查地址和鉴权
服务进程活着、日志没报错,客户端还是调不通,问题基本在地址和鉴权上。ollama 默认只听本机,容器里或者局域网访问要先改绑定地址,改完必须重启服务才生效——改完不重启然后继续排查,是白费功夫的典型。
vllm 启动时如果设了 key,客户端没带就会返回鉴权失败。这种报错看着像模型拒绝请求,其实是请求头里少了个字段,去客户端配置里补上就行。llama.cpp 的 server 默认端口和别家不一样,配置文件从别处粘过来,端口对不上是常事,先核对端口再怀疑模型。
什么情况下这套顺序不管用
得说清楚,逐层排查不是万能的。报错明确指向驱动或 CUDA 版本不匹配时,先解决环境问题,一层层往下查没有意义,环境不对,哪层都不通。模型本身是私有格式、或者框架还没适配的架构,换哪个框架都一样,这时候该回去看模型发布页的支持说明,而不是继续折腾参数。
还有一种容易被忽略:单机能跑通,不代表生产能扛。并发、限流、长上下文这些压力下的表现,得单独压测,用单机排查的结论去推生产环境,容易翻车。真到上生产前,去站内做一轮压力相关的检测更靠谱。
下一步按自己的卡和模型把参数算一遍,比对着报错猜快得多;具体数值到站内对照页面核对当时的数字。→常见问题
三个都装过,还老是搞混哪个是哪个,有简单办法吗
按角色分:ollama 是打包好的开箱即用服务,llama.cpp 是轻量底层实现、吃 GGUF,vllm 是面向并发吞吐的服务端框架。同一台机器上只留一个在跑,端口各自记下来,别同时开。
明明显存够,为什么还是加载失败
先看量化格式和框架是否匹配,GGUF 给 llama.cpp 和 ollama,vllm 更认 Hugging Face 权重格式。再看上下文长度设得是否过大,预留的缓存也算在显存里,具体容量到 /models/deploy 按自己的卡核一遍。
报错信息看不懂,第一步该做什么
把报错最后一行抄出来,看里面出现的是模型名、路径还是端口号,对应到四层里的某一层。然后只查那一层,不要边改参数边重装,一次只动一个变量,不然改好了也不知道是哪一下起的作用。