ai-本地大模型部署工具怎么排查?先看卡在哪一层,别急着重装

模型与算力

按「装没装上、认没认到卡、模型跑不跑得动、连不连得上」四层顺序排查本地大模型部署工具的问题,给出每层的判断依据和该动的那个配置项。

本地部署最气人的不是报错,是没报错但用不了:模型拉下来了却一直在 CPU 上爬,服务起来了浏览器连不上,接口地址填了对方回 404。这时候多数人的第一反应是卸载重装,结果折腾两小时回到原点。这篇不讲工具怎么装,只讲出问题以后按什么顺序查、每一步看什么、看到什么就停手别往下改。

先分清卡在哪一层,再决定动哪

本地大模型装不上,最常见的反应是删环境、重装驱动、换个工具再来一遍。折腾一晚上,问题还在原地。麻烦的地方在于:你其实不知道它坏在哪一层,所以每次动手都是碰运气。

我建议先把故障拆成四层,从上往下走。第一层,工具本身装没装上;第二层,加速卡认没认到;第三层,模型跑不跑得动;第四层,外部连不连得进来。顺序不能跳,跳层就是白忙。

层要确认的事过了的标志
一、工具层命令行里能不能找到这个工具敲命令能列出模型清单
二、硬件层显卡型号和显存有没有被识别日志里打出显卡型号和显存数字
三、推理层模型能不能真的算出字输入一句话能出字
四、接入层别的程序能不能连进来本机或局域网请求能拿到返回

判断办法很土,但比看文档快。命令行能列出模型,第一层就过了;日志里出现显卡型号和显存,第二层就过了;随便输入一句话能出字,第三层就过了。三层都过、外面还是连不上,才轮到第四层去查端口和地址。

  • 只改一个变量:一次只动一个地方,改完立刻回到那一层验证,别一边改环境变量一边重装驱动
  • 先看日志再动手:报错信息里已经写了卡在哪一层,很多人不看就先去重装
  • 别用重装当排查:重装会把现场清掉,问题复现不了,下次还得再来一遍
  • 每层留个记录:哪条命令、什么输出算通过,写下来,下次直接照着走

这套顺序不适用的情况也有:如果你连工具都没装成功,那第一层就直接卡死了,后面三层不用看;反过来,如果你只是想让局域网里另一台机器连过来,前三层都正常,那就别去碰驱动,直接查第四层的监听地址和防火墙。

第二层最容易误判:装上了不等于用上了

这一段最坑。工具跑起来了,界面也开了,模型也加载了,看着一切正常——结果一查日志,写着回退到 CPU 推理,或者显存分配是 0。很多人第一反应是「装坏了,重装一遍」。别急。这种字样基本不是工具的问题,是加速卡压根没被它看见。重装十遍,它还是看不见。

先把「进程能不能看到卡」这件事单独拎出来查,别和模型加载混在一起。宿主机上跑个最简单的设备查询,记下结果;再用同样的方式进到工具所在的运行环境里查一遍。两次结果不一样,那就是隔离层的问题,跟工具本身没关系。

  1. 宿主机先查一遍在宿主机直接跑加速卡的设备查询命令,确认驱动正常、卡在列表里、没有报错。这一步不通,后面全都白搭。
  2. 进到工具的实际运行环境再查如果工具跑在容器里,就进容器查同样的东西。注意是进工具真正所在的那个容器,不是随便开一个镜像。
  3. 对比两边结果容器里查不到卡、宿主机查得到,说明缺的是容器启动时的设备透传参数,不是装错了包。补齐启动参数重启容器,再查一次确认卡出现在列表里。
  4. 多卡机器确认跑的是哪张在工具配置里显式指定设备编号,别让它自己挑。跑起来后再查一次占用情况,看真正吃显存的是不是你指定的那张。
现象大概率卡在哪先做什么
日志出现回退到 CPU 的字样加速卡没被进程看见宿主机和容器各查一次设备列表,对比差异
显存分配显示为 0同上,或配置里设备编号写错显式指定设备编号后重启,再查占用
容器里查不到卡启动参数缺设备透传检查容器启动配置里的设备相关参数
多卡机器占用落在意料外的卡上工具默认挑了核显或最小显存那张配置里锁定编号,核对实际占用
驱动版本和运行库对不上运行环境层先对齐宿主机驱动与容器内运行库,再谈工具

还有一种误判:显存明明够,但一批并发上来就爆。这不一定是部署工具的问题,而是量化档位和并发数没对上。同一张卡,量化档位越激进,单实例占用越小,能同时跑的请求越多;反过来留的余量越少,越容易被突发流量打穿。这个对应关系不建议拍脑袋,去站内 /models/deploy 按你选的量化档位估一遍,把并发上限压到估算值以下再压测。什么情况下不适用?如果你的请求长度波动特别大,估算值只能当起点,实际还得靠压测调。

模型跑不动,先算账再改参数

模型加载半天没动静,或者跑起来一个字一个字往外蹦,很多人第一反应是重装、换版本、怀疑驱动。先别动。八成不是装坏了,是显存预算不够。显存不够有两种表现,认错了就会走弯路。

  • 直接报错:加载时提示内存分配失败,或者进程被杀掉,这种好认,日志里能翻到关键词
  • 悄悄降级:不报错,但工具把一部分层丢到系统内存里,速度慢得你以为卡死,风扇也不怎么转,这种最容易被误判成「工具不行」
  • 还有一种介于两者之间:能跑,但一提问就卡几秒才出第一个字,通常是上下文一开大,预算就被吃光了
现象大概率原因先动哪里
加载就报分配失败参数量或量化档位超出显存把量化档位降一档,或换更小的参数档
能跑但出字极慢部分层被放到内存,或上下文开太大先看上下文长度,再确认有没有溢出到内存
第一个字要等很久上下文吃预算,或并发数开多了把上下文调小,并行数先设成一
跑一会儿才崩常驻显存加并发叠加超了降低并行数,留出余量

动手改之前先算一遍账。参数量乘上量化档位对应的每参数字节数,再留一部分给上下文和运行开销,估出来的数跟显卡实际可用显存比一比。这一步不用精确到小数点,能看出「差一点」还是「差一倍」就够了。各量化档位大概占多少,去 模型资料库(/models) 对照着看当时的说明,别背数字。

  1. 估显存按参数量和量化档位算个粗略占用,加上上下文长度的开销,跟可用显存对比,判断是超了一点还是超了很多
  2. 先降上下文把上下文长度砍一半再测。很多情况是长度把预算吃光,模型本身并不大,改完立刻能跑就说明判断对了
  3. 一次只改一项上下文、并行数、常驻显存这几项,一次只动一个,其余保持不动,否则分不清是谁起的作用
  4. 用同一句话复测固定一句长度适中的提问,记录出字速度和第一个字的等待时间,改完再跑同一句,对比才有意义

什么时候这套算法不适用?如果你的机器本来就吃紧,比如同时开着别的推理服务或者显存被别的进程占着,估出来的数会偏乐观。先确认没有别的进程在抢显存,再谈参数怎么调。工具本身的默认值也可能偏激进,去 工具目录(/tools) 看对应工具的说明页,比盲目试参数快。

服务起来了连不上,八成是地址和端口填错

服务在终端里跑起来、日志也显示在监听,结果浏览器一打开就是连接被拒或者转圈到超时——这种时候先别急着删容器重装。重装一次要重拉镜像、重下权重,花的时间够你把地址核对三遍。真正的问题经常不在服务本身,而在「谁在听、听哪个地址、对面填的是哪个地址」这三件事上。

先分清两种现象,它俩的排查方向完全不一样。本机能打开、换一台机器就打不开,说明服务活着,是监听地址或者网络可达性的问题;本机都打不开,那才轮到看进程、看端口有没有真的起来。很多人一上来就去翻防火墙规则,其实服务如果只绑在回环地址上,防火墙开得再宽也没用,因为外面根本没人应答。

回环地址
只在本机内部可用的地址,别的机器发过来的请求到不了这里,服务绑它等于只对本机开放。
监听地址
服务启动时决定自己从哪个网卡收请求,绑回环还是绑全部网卡,决定了局域网能不能连上。
容器里的本机
容器内的回环指向容器自己,不是宿主机,填它基本等于指向一个空房间。
根地址与完整路径
根地址只到域名和端口,完整路径还要带版本段和接口名,上层应用要哪个得看它的文档说明。
现象更可能的原因先查什么
本机能开,同事的电脑打不开服务只绑了回环地址启动参数或配置里的监听地址有没有写成全部网卡
本机也打不开,连接被拒进程没起来或端口没占上日志最后几行、端口有没有在监听
容器里连宿主机服务失败把回环当成了宿主机换成宿主机在容器网络里的可达地址
请求有响应但返回 404路径拼错,少了版本段核对对方要的是根地址还是完整接口路径
一直转圈最后超时地址不通或端口被挡先在本机用同一地址自测一遍
  1. 先在本机自测同一地址别用 localhost 试通就算完,换成你准备给别人的那个地址再访问一次。本机用对外地址能通、别人不通,问题就在网络或监听范围。
  2. 看监听地址而不是看防火墙查服务启动参数和配置文件里的绑定项,确认是只绑回环还是绑了全部网卡。改完重启,再用同一地址从另一台机器访问验证。
  3. 容器场景换掉回环容器里访问宿主机服务,把地址换成容器网络里宿主机的可达地址,宿主机侧的服务也要绑到能被容器访问的网卡上,两边都改才算通。
  4. 填接口地址时对齐路径先确认上层应用要根地址还是带版本段的完整路径,再照着填。填错的典型表现是能连上但返回 404,不是超时,别把它当成网络问题去查。

还有一种容易误判的情况:改完监听地址重启了服务,但上层应用里缓存的还是旧地址,或者配置写在了另一个环境变量文件里没生效。这时候现象会看起来「改了没用」,实际是改的那份没被读到。改完先确认进程读的是哪份配置,再谈通不通。至于各家服务默认绑哪个地址、接口路径怎么拼,站内资料库里有对应条目,到 /models 里按服务名查当时的说明,比凭印象填靠谱。

什么时候该停手别再折腾

排查最怕的不是卡住,是明明卡住了还觉得自己再调一个参数就能过。同一个报错在两小时内出现三次以上,基本可以判定:你手上的信息量已经不够了,继续拧参数只是拿运气赌。这时候最该做的是把日志原文整段抄出来——注意是原文,不是你脑补后的转述——拿去搜。很多人失败就失败在这:搜的是「显存不够怎么办」,而日志里其实写的是某个算子不支持、某个库加载失败,方向一开始就偏了。

  • 同一个错误反复出现三次以上:停手,抄原文,去搜报错的关键那半句
  • 每改一个参数就变一个新错误:说明你在盲试,先回头确认最小链路
  • 折腾超过半天还没有一句像样的输出:别叠加功能了,先保底
  • 日志里出现驱动、编译、算子相关的字样:多半不是配置问题,别在配置文件里绕圈

最小链路跑通的意义在于你有了一个能回退的基线。多模态、知识库、多模型挂载这些东西,每加一层都会引入新的失败点,加之前先把手头这版能跑的配置原样留一份——配置文件、启动命令、用到的模型文件路径,抄到一个文本里存着。加挂了之后出了问题,回到这份基线,你至少知道是哪一步弄坏的。没有基线,一旦叠加失败,你连「原来那样是怎么跑起来的」都说不清。

换工具之前,先问自己一句:是工具不行,还是我这台的卡就不够。这两件事长得像,处理方式完全相反。工具不行,换一个可能就过了;卡不够,换哪个工具都一样,因为瓶颈在硬件,不在软件。区别方法不难:看日志是报资源类错误(显存、内存、算力相关),还是报依赖和兼容类错误。前者换工具白搭,后者才值得换。

现象更可能是哪一层该不该换工具
报错集中在显存、内存、算力不足硬件资源层不该,换工具也一样卡
报错集中在库版本、依赖冲突、编译失败软件环境层可以换,但先试隔离环境
模型能加载但输出乱、截断、胡言参数或量化层不该,先调参数和量化设置
客户端连不上、接口对不上接入层可以换客户端,不动模型

这张表不是让你对号入座就完事,它只是帮你把「该往哪个方向使劲」定下来。真要核对具体模型对硬件的要求、各家工具的支持范围,去站内的模型资料库和部署工具目录看当时的说明,别凭印象判断。判断标准摆在那儿,比反复重装省时间。

常见问题

部署工具报错之后,第一件事该做什么?

先看日志最后十行,别急着重装。日志里会写清楚是找不到模型文件、显存分配失败还是端口被占,这三种的处理方式完全不同。重装只是把问题推迟一遍,原来的配置和模型缓存还在原地,问题会原样再来。

为什么模型能在命令行出字,接了客户端就没反应?

多半卡在第四层,也就是地址和路径。客户端要的接口格式、有没有版本号前缀、端口对不对,三样里错一样就连不上。先在同一个网络位置用最笨的方式请求一次,确认服务对外可达,再去改客户端配置。

显存明明够,速度还是慢得离谱怎么办?

先确认卡真的在干活,不少情况下工具压根没用上加速卡,只是在 CPU 上跑。再看上下文长度是不是设得远超实际需要,以及模型是不是每隔一会儿就卸载重载。这三项排查完还慢,才是真的算力不够。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。