搜 fastgpt 本地部署的人,多半已经装到一半卡住了:容器起来了但页面打不开,或者模型填进去一直报错。这篇不带你敲命令,先把「你手上有什么、它需要什么、对不上会死在哪」这三件事拆开,配一份跑之前就能自查的清单。看完你应该知道自己到底缺的是镜像、端口还是模型那一侧的地址。
搜 fastgpt 本地部署的人,十有八九不是卡在 FastGPT 本身,而是卡在它周围的那些东西上:容器起来了页面打不开,模型填进去一直报鉴权失败,知识库上传完停在处理中不动。这些现象看着都像 FastGPT 的毛病,其实各有各的源头。
这篇不带你敲命令,先把你手上有什么、它需要什么、对不上会死在哪这三件事拆开。看完你至少能判断出,自己缺的是镜像、端口,还是模型那一侧的地址填错了。
先别急着拉镜像,把三件事对清楚
FastGPT 本身是个应用层,它不负责跑模型。模型要么来自你自己机器上的推理服务,要么来自外部接口。这一点没想清楚,后面所有报错都会指向空处——你以为在调 FastGPT 的配置,其实问题在模型那侧压根没起来。
还有一件常被忽略的事:这台机器到底是拿来做「跑应用」还是「连跑模型」。两件事挤在一台机器上,内存和显存会互相抢,部署当天往往看不出问题,用两天就开始卡。要省事就分开,要么应用在本机、模型走外部接口,要么模型单独一台。
- 把要接的模型路径提前写下来:本机推理服务给的是内网地址加端口,外部接口给的是完整地址加密钥,这两类填法不一样,别等报错了再猜
- 确认容器网络能不能访问到宿主机,本地用 localhost 在容器里基本不通,这是第一次部署最高频的误填
- 想清楚对话模型和向量模型分别用哪个,只填前者,知识库一定卡住
环境自查清单:按顺序过一遍,过不去的先别往下走
这份清单是给「跑起来之前」用的。顺序别乱,前一项没过就往下走,后面出的错会混在一起,排查成本翻倍。
- 容器运行时先单独验一遍引擎版本太旧会出现镜像能拉下来但起不来的情况。别在 FastGPT 目录里试,找个空目录跑一个最简单的镜像,能正常起来再回来。
- 看一眼端口谁在占应用、数据库、向量库都要端口。本地如果已经跑过别的服务,最容易撞的就是同一段常用端口。起来前先查一遍监听列表,撞了就换,别硬上。
- 算一下磁盘和内存够不够知识库类应用吃的是磁盘和内存,不是一时半会的 CPU。磁盘写满的表现往往很隐蔽——上传成功但检索不到,很容易误判成模型问题。
- 确认容器能出网也能回连宿主机外部接口模式要能出网,本机模型模式要能从容器里访问到宿主机那条地址。两个方向分开测,别混着看。
模型那一侧怎么接,决定你是十分钟跑通还是折腾一晚
模型接入这块,最大的坑不是填错,是不知道该填什么。先分清两种模式:本机推理服务,要确认服务对外监听的不是只有本机回环地址,以及容器网络能访问到宿主机的那条地址;外部接口模式更省事,但地址是否带版本路径、密钥放在请求头还是查询参数,这两处填反了会一直提示鉴权失败。
| 接入方式 | 要确认的点 | 填错后的典型表现 |
|---|---|---|
| 本机推理服务 | 监听地址不是仅回环、容器能访问宿主机 | 连接超时、一直转圈 |
| 外部接口 | 地址是否含版本路径、密钥放请求头还是参数 | 鉴权失败、401 类报错 |
| 对话模型 | 角色填对、能单独回一句话 | 对话没反应 |
| 向量模型 | 单独配置、上传后能走完处理 | 知识库一直停在处理中 |
接上之后先做一次最小验证:不要一上来就建知识库。先让对话跑通一句,能回话说明链路对了,剩下的才是检索环节的问题。这个顺序能帮你把故障范围砍掉一半。
跑起来之后,真正该盯的几处
应用日志和向量库日志分开看,这一步能一次分清是应用没连上,还是数据处理失败。很多人一报错就去翻 FastGPT 的配置,其实日志早写了答案,只是没分文件看。
知识库处理慢不等于坏了。先确认文件解析和向量化两段分别有没有报错,再判断是不是模型那侧超时。解析卡住和向量化卡住,处理方式完全不同。
- 把这次的端口、地址、模型角色记成一张小表,换机器或升级镜像时照表核对,比重新回忆快得多
- 自己或小团队用,别急着上复杂编排,先保证单机重启后还能起来
- 要对比不同接入方式的成本和延迟,到 /price-watch 核对当时的数字,别凭印象选
说白了,本地部署的难点从来不在那几条命令,而在你对「手上有什么」的盘点够不够清楚。盘点清楚了,装起来就是顺水推舟;盘不清楚,每一步都像在猜。
下一步如果你正在几家中转或接入方式之间做选择,去 /sites 对照各家当前的支持范围和接入说明,再回来看这份清单,能少走一轮弯路。→常见问题
FastGPT 本地部署是不是必须自己有显卡?
不一定。它本身是应用层,模型可以走外部接口,这时对显卡没有要求,压力在网络和额度上。只有当你打算把模型也放在同一台机器上跑,才需要按模型规模去算显存。想先分清两条路的代价,可以对照站内 /models/deploy 的测算口径。
容器起来了但网页打不开,一般先查哪里?
先分两层:容器是不是真的在运行,以及宿主机的端口有没有映射出来。很多时候容器状态是正常的,只是访问的端口和映射的端口不是同一个。确认完再看应用日志里有没有连数据库失败的信息,那属于另一类问题,别混在一起改。
本地模型接上了,知识库却一直处理不完,是什么情况?
多数是向量模型那一格没配或配错,应用能对话说明对话模型通了,但知识库检索走的是另一条链路。先确认向量模型有独立配置并且能返回结果,再看文件解析有没有报错。两块分开验证,比反复重装快。