简介面向希望将智能问答系统私有化落地的开发者与课程学习者这套示例项目以 Gradio 搭建交互界面结合 FAISS 向量检索与 Sentence-Transformers 文本嵌入演示文件上传、知识库构建与对话问答的完整链路帮助理解本地部署中模型调用、文档检索和前端交互的衔接方式。压缩包共 18 个文件约 336KB主体为 Python 源码、txt 配置说明与 yaml 环境定义另含 whl 依赖包、sh 安装脚本及 docx、xlsx、pdf 等示例资料和证书文件便于直接运行或替换自有文档。已有 140 人浏览学习适合作为入门级项目骨架。读者可获得可运行的问答助理代码结构、多版本迭代脚本、依赖清单与参考文档用于二次开发、课程实验或小型知识库检索场景并据此掌握向量库构建、文本嵌入与界面集成的实践要点。1. 先别急着拉权重ChatGLM 私有化智能问答助理的安装场景与版本坑本地部署私有化智能问答助理最容易被低估的不是 ChatGLM 权重有多大而是版本配对。很多机器学习项目在演示机上能跑换到内网机器上就变成显卡能用、模型加载失败或者知识库问答答非所问。安装前先把 Python、CUDA、PyTorch、量化依赖四件事对齐比后面改十次配置都省时间。这套环境适合想把人工智能问答能力放进本地、又希望资料留在自己机器上的个人开发者和中小团队。我见过最常见的翻车不是模型下载慢而是先装了一堆依赖最后发现 Python 3.11 和旧版 ChatGLM 自定义模块对不上或者 PyTorch 装成了 CPU 版torch.cuda.is_available()一路返回False。所以这篇安装笔记从环境清单开始按驱动、Python 环境、权重目录、服务配置、验证请求的顺序往下走每一步都给出可抄的命令和失败时该看的地方。2. 装前定环境ChatGLM 助理在 Python 3.10 下的硬件与版本矩阵2.1 硬件与系统基线显存、内存、磁盘怎么估ChatGLM 系权重常见有 6B 级和更大参数版本资源包内实际放的是哪一档要以权重目录里的config.json和说明文件为准。下面按 6B 级模型做估算方便你先判断机器能不能装如果你拿到的是更大参数版本显存和内存按比例往上加不要拿同一套参数硬套。CPU 也能跑但问答延迟会明显拉长适合验证流程不适合多人同时用。使用场景显存建议内存建议磁盘余量说明单机验证、短问答8GB 以上16GB 以上20GB 以上可用 8bit 量化降显存日常个人使用12GB 以上32GB 更稳30GB 以上FP16 更省心量化更省显存小团队内网服务16GB 以上32GB 以上50GB 以上要留日志、知识库和并发余量纯 CPU 验证无强制16GB 以上20GB 以上速度慢先关知识库跑基础问答系统层面我一般先看三件事显卡驱动能不能被nvidia-smi认出来系统里有没有和 PyTorch 对得上的 CUDA 运行库磁盘是不是挂在空间足够的分区上。权重文件动辄十几个 GB放在根分区很容易装到一半报No space left on device。另外知识库目录和日志目录最好提前分开后面排查“模型答得慢”还是“检索拖得慢”会清楚很多。提示显存估算不要只看权重体积。加载 tokenizer、生成长文本、并发请求都会额外占用显存按表里的建议留 2GB 到 4GB 余量更保险。2.2 Python、CUDA、PyTorch 的版本取舍这套环境我建议用 Python 3.10 做基线。原因不是 3.10 有什么特殊能力而是 ChatGLM 相关依赖、量化库、Web 服务依赖在这个版本上踩坑概率低Python 3.11 和 3.12 不是不能跑但旧版权重里的自定义模块、cpm_kernels一类依赖容易在 wheel 上卡住。新手先别追新版本装通之后再考虑升级这是最省时间的做法。组件建议基线检查方式取舍说明Python3.10python3 --version兼容旧版 ChatGLM 依赖更省心显卡驱动能支持所选 CUDAnvidia-smi驱动太旧时先升级驱动CUDA11.8 或 12.1 常见基线nvcc --version以 PyTorch wheel 匹配为准PyTorch与 CUDA 对应的 2.xtorch.version.cuda不要混装 CPU 版和 GPU 版transformers4.30 以上常见pip show transformers太旧会缺自定义模型加载参数量化依赖按需装 bitsandbytespython -c import bitsandbytes只在 GPU 量化时必要CUDA 这里有个反直觉点nvcc --version显示的不是唯一标准PyTorch wheel 自带 CUDA 运行库时系统没装完整 CUDA Toolkit 也能跑。真正要看的是torch.cuda.is_available()和torch.version.cuda。所以安装顺序应该是先确定 PyTorch 用哪个 CUDA 版本的 wheel再反推驱动是否满足而不是先把系统 CUDA 升到最新最后发现 PyTorch 装错索引。2.3 权重与依赖清单资源包该包含哪些文件拿到私有化智能问答助理的资源包后先别急着执行启动脚本。我会先核对目录权重目录、依赖清单、服务入口、配置文件、知识库样例、日志目录是否齐全。缺少权重文件时服务启动会报OSError: Unable to load weights缺少 tokenizer 文件时可能到第一句问答才报错。提前看一眼目录比看一屏报错快得多。常见文件或目录用途缺失时的表现config.json模型结构配置加载模型时报配置缺失tokenizer.model或 tokenizer 相关文件文本切分启动后问答报 tokenizer 错误pytorch_model.bin或分片权重模型参数显存分配后加载失败generation_config.json生成参数默认值可能能跑但输出参数异常requirements.txtPython 依赖清单导入模块时报ModuleNotFoundErrorconfig.yaml服务、模型、知识库参数启动参数缺失或端口不对data/knowledge/私有知识库样例检索为空问答只会泛答app.py或server.py服务入口不知道该启动哪个文件依赖清单不要只看一眼就全装。我的习惯是先建独立环境装 PyTorch再装requirements.txt最后补 ChatGLM 运行时报缺的模块。这样出问题时能判断是底座错了还是某个业务依赖没装。尤其不要把系统 Python、conda 环境、pip 用户级安装混在一起后面which python和pip -V对不上排查会非常难受。3. 安装驱动与 Python 环境CUDA 11.8 与 PyTorch 2.x 的配对顺序3.1 显卡驱动与 CUDA 的最小检查先做最小检查不要一上来就装依赖。下面三条命令分别看显卡、CUDA 编译器和 Python 版本。nvcc不存在不代表一定不能跑 GPU因为 PyTorch wheel 可能自带运行库但如果nvidia-smi都不认识显卡后面装什么都是白费。命令里的|| true只是让检查继续往下走不是修复错误。# 1) 看显卡和驱动确认显卡被系统识别 nvidia-smi # 2) 看系统 CUDA 编译器没有也可先用 PyTorch wheel 验证 nvcc --version || true # 3) 确认 Python 版本建议 3.10 python3 --versionnvidia-smi右上角会显示驱动版本和支持的 CUDA 版本这个“支持版本”是驱动上限不是你必须安装的系统 CUDA 版本。nvcc --version看的是编译工具链和 PyTorch 运行时不是一回事。如果nvidia-smi报command not found先处理驱动或 PATH如果显示显卡但torch.cuda.is_available()是False优先怀疑 PyTorch 装成了 CPU 版或者 wheel 的 CUDA 版本与驱动不匹配。注意不要在同一个环境里反复卸载、重装不同 CUDA 版本的 PyTorch。先把环境删掉重建通常比在脏环境里修依赖更省时间。3.2 用 conda 建独立环境并锁定 Python 3.10独立环境是这套安装里最值的保险。ChatGLM 的依赖和公司内其他项目很容易打架尤其是transformers、protobuf、gradio这些包。下面命令创建名为chatglm-private的环境指定 Python 3.10然后升级 pip、wheel、setuptools。环境名可以换但建议带项目含义后面机器上环境多了不容易混。# 创建独立环境避免污染系统 Python conda create -n chatglm-private python3.10 -y # 激活环境 conda activate chatglm-private # 升级基础打包工具减少旧 pip 解析 wheel 失败 python -m pip install --upgrade pip wheel setuptoolsconda create -n的-n后面是环境名python3.10是版本约束-y表示自动确认。激活后一定要用which python和python -V再确认一次别出现“以为激活了实际还在系统 Python”的情况。我见过 A 同学装了半天依赖最后发现终端开的是另一个窗口环境根本没激活。装完后所有命令都在这个激活环境里执行包括启动服务。3.3 安装 PyTorch 与 ChatGLM 依赖PyTorch 要和 CUDA 版本配对。下面给的是 CUDA 11.8 的常见安装方式--index-url指向对应 wheel 索引如果你的驱动只适合别的 CUDA 版本换成匹配的索引不要在这个环境里混装多个 torch。装完立刻验证不要等模型加载时才发现 GPU 不可用。# 安装与 CUDA 11.8 匹配的 PyTorch其他 CUDA 版本换对应索引 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 立刻验证 GPU 是否可用 python - PY import torch print(torch:, torch.__version__) print(cuda available:, torch.cuda.is_available()) print(cuda runtime:, torch.version.cuda) print(device count:, torch.cuda.device_count()) PY这段验证脚本会输出 PyTorch 版本、CUDA 是否可用、运行时 CUDA 版本和显卡数量。预期至少看到cuda available: True和device count大于 0。如果torch.version.cuda是None基本就是装了 CPU 版如果cuda available是False但nvidia-smi正常先卸载当前 torch再按匹配索引重装。别在旧 wheel 上打补丁越补越乱。接着装资源包依赖。先执行requirements.txt再按报错补 ChatGLM 常见模块。旧版权重可能还需要cpm_kernels新版不一定需要bitsandbytes只在做 8bit 或 4bit 量化时再装。sentencepiece、protobuf、accelerate是问答服务里高频出现的依赖缺了会在加载 tokenizer 或模型分发时暴露。# 先装资源包锁定的依赖 pip install -r requirements.txt # 常见补充依赖按实际报错增删不要无脑全装 pip install transformers accelerate sentencepiece protobuf # 只有需要 GPU 量化时再装 # pip install bitsandbytesrequirements.txt里通常锁了transformers、gradio、fastapi一类版本。如果安装过程中出现依赖冲突优先保留资源包锁定的主版本别为了一个新包把transformers升到不兼容的大版本。补依赖时一次只加一组装完跑一次导入检查出问题能定位到具体包。量化依赖在 Windows 上尤其容易卡 wheel如果只是验证流程可以先不量化用 FP16 或 CPU 把服务跑通。4. 放权重与改配置ChatGLM 模型路径、8bit 量化与知识库参数4.1 模型权重目录与路径校验权重目录建议放在项目根目录下的models/chatglm用相对路径写配置换机器时只改项目根目录。目录里至少要有模型配置、tokenizer 文件和权重文件分片权重还要有对应的索引文件。不要直接把权重散放在下载目录里路径里带空格、中文、特殊符号时某些启动脚本会解析失败。下面命令做最小校验确认关键文件存在。# 假设权重放在项目下的 models/chatglm export MODEL_DIR./models/chatglm # 关键文件存在性检查 test -f $MODEL_DIR/config.json echo config ok test -f $MODEL_DIR/tokenizer.model echo tokenizer ok find $MODEL_DIR -maxdepth 1 -name *.bin -o -name *.safetensors | headtest -f只检查文件是否存在不校验内容完整性。find用来确认权重文件是单文件还是分片如果是分片通常还会有pytorch_model.bin.index.json一类索引文件缺了索引会加载失败。路径校验通过后再用 Python 直接加载一次模型别等 Web 服务起来才排查。加载脚本里trust_remote_codeTrue会执行权重目录内的自定义代码所以只对可信资源开启。from transformers import AutoTokenizer, AutoModel model_dir ./models/chatglm # 加载 tokenizertrust_remote_code 只对可信权重目录开启 tokenizer AutoTokenizer.from_pretrained( model_dir, trust_remote_codeTrue ) # 加载模型device_mapauto 让 accelerate 自动分配设备 model AutoModel.from_pretrained( model_dir, trust_remote_codeTrue, device_mapauto ).eval() print(model loaded)trust_remote_codeTrue不是玄学参数它表示允许加载权重目录里的自定义模型类没有它ChatGLM 一类模型可能直接报找不到模型类。device_mapauto适合单卡或多卡自动分配但在已经手动.to(cuda)的环境里不要重复设置否则容易出现设备不一致。.eval()切到推理模式减少 dropout 一类训练行为对问答结果的影响。加载成功后再进入服务配置。4.2 量化加载显存不够时的取舍显存不够时不要第一时间换显卡先看能不能量化。FP16 效果省心但吃显存8bit 能明显降显存4bit 更省但依赖更多、速度和质量取舍更明显。下面配置只给常见参数实际字段名以资源包config.yaml为准如果资源包没有这些字段就在加载代码里加不要凭空改服务入口。server: host: 0.0.0.0 port: 7860 model: path: ./models/chatglm trust_remote_code: true device_map: auto load_in_8bit: false load_in_4bit: false max_length: 2048 temperature: 0.3 top_p: 0.8 knowledge: enabled: true dir: ./data/knowledge chunk_size: 500 chunk_overlap: 80 top_k: 4host: 0.0.0.0表示服务监听所有网卡局域网其他机器才能访问只在本机用可以改127.0.0.1。port被占用时换一个不要杀不认识的进程。max_length是生成上限调大更吃显存temperature和top_p控制回答发散程度知识库问答一般调低一点。load_in_8bit和load_in_4bit不要同时开开启前先确认bitsandbytes能正常导入。量化方式显存占用依赖适用场景FP16较高基础依赖显存够追求省心8bit中等bitsandbytes单卡显存偏小4bit较低bitsandbytes 及量化配置显存紧张能接受速度取舍CPU不占显存无只做流程验证量化不是越多越好。8bit 在不少单卡环境里已经够用4bit 更适合显存确实卡死的情况。开启量化后如果报CUDA error或bitsandbytes相关错误先退回 FP16 验证模型本身能不能加载再处理量化依赖。Windows 上量化 wheel 的坑更多必要时先用 CPU 或 FP16 把服务跑通别一上来就追 4bit。4.3 服务配置文件端口、模型名、知识库目录服务启动前把配置文件里的模型路径、知识库目录、端口逐项对一遍。下面命令是两种常见入口具体用哪个看资源包里的入口文件不要两个同时启动否则端口会打架。启动后先看日志有没有“模型加载完成”再看端口有没有监听。# 常见入口一带配置文件启动 python app.py --config config.yaml # 常见入口二用 uvicorn 启动 FastAPI 服务 uvicorn server:app --host 0.0.0.0 --port 7860--config config.yaml是让入口读取你改过的配置如果入口不支持这个参数就看app.py里的参数解析。uvicorn server:app里server是模块名app是 FastAPI 实例名别照抄成不存在的文件。启动日志里重点看三行模型路径、设备分配、知识库是否启用。知识库目录为空时服务可能能启动但问答只会泛答不会报明显错误。知识库参数里chunk_size是切片大小chunk_overlap是切片重叠top_k是每次召回片段数。中文知识库切片太大检索会带进无关内容切片太小上下文又拼不起来。500 字、80 字重叠、召回 4 条是常见起点实际按文档类型调。表格和 FAQ 不要切得太碎否则一个问题可能只命中半行。检索效果差时先看日志里有没有命中片段再决定调切片还是换嵌入模型。5. 避坑与排查ChatGLM 本地服务五类翻车记录5.1 现象torch.cuda.is_available()一直是 False现象很直接nvidia-smi能看到显卡但 Python 里 CUDA 不可用模型只能跑 CPU速度慢到没法用。原因通常不是显卡坏了而是 PyTorch 装成了 CPU 版或者 wheel 的 CUDA 版本和驱动不匹配。还有一种情况是 conda 环境里混进了系统级 torchpip show torch看到的路径和你以为的不一样。解决顺序是先看版本再决定重装。下面命令确认当前 torch 来源和 CUDA 状态如果torch.version.cuda是None直接卸载重装匹配 wheel不要在旧包上修。python - PY import torch print(torch.__file__) print(torch.__version__) print(torch.version.cuda) print(torch.cuda.is_available()) PYtorch.__file__能看出包到底装在哪个环境里如果路径指向系统目录说明 conda 环境没生效。torch.version.cuda为None就是 CPU 版。重装时先pip uninstall torch torchvision torchaudio -y再按第 3 章的 CUDA 索引安装。驱动太旧时先升级驱动别硬装高版本 CUDA wheel。5.2 现象加载模型报找不到自定义模型类现象是启动时抛ModuleNotFoundError或者提示某个自定义模型类不存在。原因通常是trust_remote_codeTrue没开或者transformers版本太旧读不懂权重目录里的自定义代码。还有一种情况是权重目录不完整config.json在但自定义模型文件缺失。解决时先看配置文件和加载代码。配置文件里要有trust_remote_code: true直接写 Python 加载时也要显式传入。然后确认transformers版本不要用太旧的版本加载新版权重。from transformers import AutoTokenizer, AutoModel model_dir ./models/chatglm tokenizer AutoTokenizer.from_pretrained( model_dir, trust_remote_codeTrue # 缺少时常见自定义模型类加载失败 ) model AutoModel.from_pretrained( model_dir, trust_remote_codeTrue )如果加了参数还报错检查权重目录里是否有configuration_chatglm.py、modeling_chatglm.py一类文件缺文件就重新解压资源包。不要从别的版本目录里随便拷一个模型文件进来结构对不上时错误会更隐蔽。5.3 现象问答几句后CUDA out of memory现象是模型能加载但一问长问题或连续问几次就 OOM。原因一般不是权重本身而是max_length太大、并发请求太多、历史对话越堆越长或者量化没开。显存被日志、知识库检索、前端进程一起占用时余量比想象中小。解决先从参数下手不要急着换卡。把max_length降到 1024 或 512限制并发清空历史对话再试 8bit 量化。如果只是验证流程把知识库先关掉减少检索模型占用的显存。model: load_in_8bit: true max_length: 1024 device_map: autoload_in_8bit: true需要bitsandbytes正常安装max_length降低会缩短生成长度但能明显减少缓存占用。device_map: auto在多卡环境可能把不同层分到不同卡单卡环境如果报设备不一致可以改成显式单卡加载。OOM 反复出现时看日志里 OOM 前最后一次请求的长度通常能找到触发点。5.4 现象本机 curl 通局域网访问不了现象是服务器本机curl 127.0.0.1:7860有响应另一台机器访问 IP 和端口却连不上。原因通常是服务监听在127.0.0.1只允许本机访问或者系统防火墙没放行端口。也有一种情况是容器端口没映射出来日志里看着启动成功外部就是进不来。解决先看监听地址和端口。下面命令确认 7860 到底监听在哪个网卡如果显示127.0.0.1:7860改配置里的host。ss -lntp | grep 7860ss -lntp会显示监听地址、端口和进程。把配置里的host改成0.0.0.0后重启服务再用局域网 IP 访问。还不行就检查防火墙规则和容器端口映射。不要为了省事直接关防火墙按端口放行更可控。5.5 现象知识库问答答非所问或出现乱码现象是基础问答正常一开知识库就答偏或者文档里的中文变成乱码。原因常见有三类知识库文件不是 UTF-8切片太大导致召回片段混杂top_k太低导致该命中的片段没进来。还有一种情况是知识库目录里混进了日志、临时文件检索时被当成正文。解决先统一编码再调切片。把知识库文件转成 UTF-8清理非文档文件日志里打印召回片段和分数。下面配置是常见起点中文文档不要切得太碎。knowledge: enabled: true dir: ./data/knowledge chunk_size: 500 chunk_overlap: 80 top_k: 4chunk_size调小可能提高命中精度但上下文容易断调大可能带进无关内容。chunk_overlap用来避免切片边界丢句子80 是常见起点。top_k从 4 调到 6 可以增加召回但也会增加噪声。每次只改一个参数问同一个问题对比日志别一次改四项最后不知道是哪项起作用。6. 装完怎么验证三条请求确认 ChatGLM 私有化助理跑通装完不要只看页面能不能打开。页面打开只说明 Web 层活着模型加载、GPU 分配、知识库检索都可能在后台没生效。我一般按“本地直连模型 → HTTP 服务 → 知识库问答”三层验证任何一层失败都能快速缩小范围。先看端口和日志确认模型加载完成且没有 OOM。# 看端口是否监听确认服务进程还活着 ss -lntp | grep 7860 # 看最近日志重点找模型路径、设备、OOM、检索命中 tail -n 50 app.log第一层验证直接问模型不经过前端和接口。能返回一句正常中文说明权重、tokenizer、设备分配没问题。第二层访问 HTTP 服务用浏览器或curl看首页是否返回内容如果资源包提供聊天接口按实际路由发一条短问题不要照抄示例路径。第三层打开知识库问一个只存在于文档里的词再看日志有没有召回记录。验证项预期结果失败时先看端口监听7860 处于 LISTEN启动日志、端口占用首页访问返回页面或接口说明host、防火墙、路由基础问答返回通顺中文模型路径、CUDA、显存知识库问答能答出文档内专有词编码、切片、召回日志连续三次请求不 OOM、延迟可接受max_length、并发、量化最后给一个固定问题做回归比如“用一句话说明这台机器上的助理能做什么”再给一个知识库问题比如“文档里某个流程第一步是什么”。两次都通过再看日志里检索命中的片段是不是正确文档。从那以后我每次装完 ChatGLM 私有化助理都先把知识库关掉问一句固定问题再打开知识库问一个只存在于文档里的词最后看日志里有没有检索命中记录。三步都过了才交给别人用。希望帮到你。本文还有配套的精品资源点击获取
简介面向希望将智能问答系统私有化落地的开发者与课程学习者这套示例项目以 Gradio 搭建交互界面结合 FAISS 向量检索与 Sentence-Transformers 文本嵌入演示文件上传、知识库构建与对话问答的完整链路帮助理解本地部署中模型调用、文档检索和前端交互的衔接方式。压缩包共 18 个文件约 336KB主体为 Python 源码、txt 配置说明与 yaml 环境定义另含 whl 依赖包、sh 安装脚本及 docx、xlsx、pdf 等示例资料和证书文件便于直接运行或替换自有文档。已有 140 人浏览学习适合作为入门级项目骨架。读者可获得可运行的问答助理代码结构、多版本迭代脚本、依赖清单与参考文档用于二次开发、课程实验或小型知识库检索场景并据此掌握向量库构建、文本嵌入与界面集成的实践要点。1. 先别急着拉权重ChatGLM 私有化智能问答助理的安装场景与版本坑本地部署私有化智能问答助理最容易被低估的不是 ChatGLM 权重有多大而是版本配对。很多机器学习项目在演示机上能跑换到内网机器上就变成显卡能用、模型加载失败或者知识库问答答非所问。安装前先把 Python、CUDA、PyTorch、量化依赖四件事对齐比后面改十次配置都省时间。这套环境适合想把人工智能问答能力放进本地、又希望资料留在自己机器上的个人开发者和中小团队。我见过最常见的翻车不是模型下载慢而是先装了一堆依赖最后发现 Python 3.11 和旧版 ChatGLM 自定义模块对不上或者 PyTorch 装成了 CPU 版torch.cuda.is_available()一路返回False。所以这篇安装笔记从环境清单开始按驱动、Python 环境、权重目录、服务配置、验证请求的顺序往下走每一步都给出可抄的命令和失败时该看的地方。2. 装前定环境ChatGLM 助理在 Python 3.10 下的硬件与版本矩阵2.1 硬件与系统基线显存、内存、磁盘怎么估ChatGLM 系权重常见有 6B 级和更大参数版本资源包内实际放的是哪一档要以权重目录里的config.json和说明文件为准。下面按 6B 级模型做估算方便你先判断机器能不能装如果你拿到的是更大参数版本显存和内存按比例往上加不要拿同一套参数硬套。CPU 也能跑但问答延迟会明显拉长适合验证流程不适合多人同时用。使用场景显存建议内存建议磁盘余量说明单机验证、短问答8GB 以上16GB 以上20GB 以上可用 8bit 量化降显存日常个人使用12GB 以上32GB 更稳30GB 以上FP16 更省心量化更省显存小团队内网服务16GB 以上32GB 以上50GB 以上要留日志、知识库和并发余量纯 CPU 验证无强制16GB 以上20GB 以上速度慢先关知识库跑基础问答系统层面我一般先看三件事显卡驱动能不能被nvidia-smi认出来系统里有没有和 PyTorch 对得上的 CUDA 运行库磁盘是不是挂在空间足够的分区上。权重文件动辄十几个 GB放在根分区很容易装到一半报No space left on device。另外知识库目录和日志目录最好提前分开后面排查“模型答得慢”还是“检索拖得慢”会清楚很多。提示显存估算不要只看权重体积。加载 tokenizer、生成长文本、并发请求都会额外占用显存按表里的建议留 2GB 到 4GB 余量更保险。2.2 Python、CUDA、PyTorch 的版本取舍这套环境我建议用 Python 3.10 做基线。原因不是 3.10 有什么特殊能力而是 ChatGLM 相关依赖、量化库、Web 服务依赖在这个版本上踩坑概率低Python 3.11 和 3.12 不是不能跑但旧版权重里的自定义模块、cpm_kernels一类依赖容易在 wheel 上卡住。新手先别追新版本装通之后再考虑升级这是最省时间的做法。组件建议基线检查方式取舍说明Python3.10python3 --version兼容旧版 ChatGLM 依赖更省心显卡驱动能支持所选 CUDAnvidia-smi驱动太旧时先升级驱动CUDA11.8 或 12.1 常见基线nvcc --version以 PyTorch wheel 匹配为准PyTorch与 CUDA 对应的 2.xtorch.version.cuda不要混装 CPU 版和 GPU 版transformers4.30 以上常见pip show transformers太旧会缺自定义模型加载参数量化依赖按需装 bitsandbytespython -c import bitsandbytes只在 GPU 量化时必要CUDA 这里有个反直觉点nvcc --version显示的不是唯一标准PyTorch wheel 自带 CUDA 运行库时系统没装完整 CUDA Toolkit 也能跑。真正要看的是torch.cuda.is_available()和torch.version.cuda。所以安装顺序应该是先确定 PyTorch 用哪个 CUDA 版本的 wheel再反推驱动是否满足而不是先把系统 CUDA 升到最新最后发现 PyTorch 装错索引。2.3 权重与依赖清单资源包该包含哪些文件拿到私有化智能问答助理的资源包后先别急着执行启动脚本。我会先核对目录权重目录、依赖清单、服务入口、配置文件、知识库样例、日志目录是否齐全。缺少权重文件时服务启动会报OSError: Unable to load weights缺少 tokenizer 文件时可能到第一句问答才报错。提前看一眼目录比看一屏报错快得多。常见文件或目录用途缺失时的表现config.json模型结构配置加载模型时报配置缺失tokenizer.model或 tokenizer 相关文件文本切分启动后问答报 tokenizer 错误pytorch_model.bin或分片权重模型参数显存分配后加载失败generation_config.json生成参数默认值可能能跑但输出参数异常requirements.txtPython 依赖清单导入模块时报ModuleNotFoundErrorconfig.yaml服务、模型、知识库参数启动参数缺失或端口不对data/knowledge/私有知识库样例检索为空问答只会泛答app.py或server.py服务入口不知道该启动哪个文件依赖清单不要只看一眼就全装。我的习惯是先建独立环境装 PyTorch再装requirements.txt最后补 ChatGLM 运行时报缺的模块。这样出问题时能判断是底座错了还是某个业务依赖没装。尤其不要把系统 Python、conda 环境、pip 用户级安装混在一起后面which python和pip -V对不上排查会非常难受。3. 安装驱动与 Python 环境CUDA 11.8 与 PyTorch 2.x 的配对顺序3.1 显卡驱动与 CUDA 的最小检查先做最小检查不要一上来就装依赖。下面三条命令分别看显卡、CUDA 编译器和 Python 版本。nvcc不存在不代表一定不能跑 GPU因为 PyTorch wheel 可能自带运行库但如果nvidia-smi都不认识显卡后面装什么都是白费。命令里的|| true只是让检查继续往下走不是修复错误。# 1) 看显卡和驱动确认显卡被系统识别 nvidia-smi # 2) 看系统 CUDA 编译器没有也可先用 PyTorch wheel 验证 nvcc --version || true # 3) 确认 Python 版本建议 3.10 python3 --versionnvidia-smi右上角会显示驱动版本和支持的 CUDA 版本这个“支持版本”是驱动上限不是你必须安装的系统 CUDA 版本。nvcc --version看的是编译工具链和 PyTorch 运行时不是一回事。如果nvidia-smi报command not found先处理驱动或 PATH如果显示显卡但torch.cuda.is_available()是False优先怀疑 PyTorch 装成了 CPU 版或者 wheel 的 CUDA 版本与驱动不匹配。注意不要在同一个环境里反复卸载、重装不同 CUDA 版本的 PyTorch。先把环境删掉重建通常比在脏环境里修依赖更省时间。3.2 用 conda 建独立环境并锁定 Python 3.10独立环境是这套安装里最值的保险。ChatGLM 的依赖和公司内其他项目很容易打架尤其是transformers、protobuf、gradio这些包。下面命令创建名为chatglm-private的环境指定 Python 3.10然后升级 pip、wheel、setuptools。环境名可以换但建议带项目含义后面机器上环境多了不容易混。# 创建独立环境避免污染系统 Python conda create -n chatglm-private python3.10 -y # 激活环境 conda activate chatglm-private # 升级基础打包工具减少旧 pip 解析 wheel 失败 python -m pip install --upgrade pip wheel setuptoolsconda create -n的-n后面是环境名python3.10是版本约束-y表示自动确认。激活后一定要用which python和python -V再确认一次别出现“以为激活了实际还在系统 Python”的情况。我见过 A 同学装了半天依赖最后发现终端开的是另一个窗口环境根本没激活。装完后所有命令都在这个激活环境里执行包括启动服务。3.3 安装 PyTorch 与 ChatGLM 依赖PyTorch 要和 CUDA 版本配对。下面给的是 CUDA 11.8 的常见安装方式--index-url指向对应 wheel 索引如果你的驱动只适合别的 CUDA 版本换成匹配的索引不要在这个环境里混装多个 torch。装完立刻验证不要等模型加载时才发现 GPU 不可用。# 安装与 CUDA 11.8 匹配的 PyTorch其他 CUDA 版本换对应索引 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 立刻验证 GPU 是否可用 python - PY import torch print(torch:, torch.__version__) print(cuda available:, torch.cuda.is_available()) print(cuda runtime:, torch.version.cuda) print(device count:, torch.cuda.device_count()) PY这段验证脚本会输出 PyTorch 版本、CUDA 是否可用、运行时 CUDA 版本和显卡数量。预期至少看到cuda available: True和device count大于 0。如果torch.version.cuda是None基本就是装了 CPU 版如果cuda available是False但nvidia-smi正常先卸载当前 torch再按匹配索引重装。别在旧 wheel 上打补丁越补越乱。接着装资源包依赖。先执行requirements.txt再按报错补 ChatGLM 常见模块。旧版权重可能还需要cpm_kernels新版不一定需要bitsandbytes只在做 8bit 或 4bit 量化时再装。sentencepiece、protobuf、accelerate是问答服务里高频出现的依赖缺了会在加载 tokenizer 或模型分发时暴露。# 先装资源包锁定的依赖 pip install -r requirements.txt # 常见补充依赖按实际报错增删不要无脑全装 pip install transformers accelerate sentencepiece protobuf # 只有需要 GPU 量化时再装 # pip install bitsandbytesrequirements.txt里通常锁了transformers、gradio、fastapi一类版本。如果安装过程中出现依赖冲突优先保留资源包锁定的主版本别为了一个新包把transformers升到不兼容的大版本。补依赖时一次只加一组装完跑一次导入检查出问题能定位到具体包。量化依赖在 Windows 上尤其容易卡 wheel如果只是验证流程可以先不量化用 FP16 或 CPU 把服务跑通。4. 放权重与改配置ChatGLM 模型路径、8bit 量化与知识库参数4.1 模型权重目录与路径校验权重目录建议放在项目根目录下的models/chatglm用相对路径写配置换机器时只改项目根目录。目录里至少要有模型配置、tokenizer 文件和权重文件分片权重还要有对应的索引文件。不要直接把权重散放在下载目录里路径里带空格、中文、特殊符号时某些启动脚本会解析失败。下面命令做最小校验确认关键文件存在。# 假设权重放在项目下的 models/chatglm export MODEL_DIR./models/chatglm # 关键文件存在性检查 test -f $MODEL_DIR/config.json echo config ok test -f $MODEL_DIR/tokenizer.model echo tokenizer ok find $MODEL_DIR -maxdepth 1 -name *.bin -o -name *.safetensors | headtest -f只检查文件是否存在不校验内容完整性。find用来确认权重文件是单文件还是分片如果是分片通常还会有pytorch_model.bin.index.json一类索引文件缺了索引会加载失败。路径校验通过后再用 Python 直接加载一次模型别等 Web 服务起来才排查。加载脚本里trust_remote_codeTrue会执行权重目录内的自定义代码所以只对可信资源开启。from transformers import AutoTokenizer, AutoModel model_dir ./models/chatglm # 加载 tokenizertrust_remote_code 只对可信权重目录开启 tokenizer AutoTokenizer.from_pretrained( model_dir, trust_remote_codeTrue ) # 加载模型device_mapauto 让 accelerate 自动分配设备 model AutoModel.from_pretrained( model_dir, trust_remote_codeTrue, device_mapauto ).eval() print(model loaded)trust_remote_codeTrue不是玄学参数它表示允许加载权重目录里的自定义模型类没有它ChatGLM 一类模型可能直接报找不到模型类。device_mapauto适合单卡或多卡自动分配但在已经手动.to(cuda)的环境里不要重复设置否则容易出现设备不一致。.eval()切到推理模式减少 dropout 一类训练行为对问答结果的影响。加载成功后再进入服务配置。4.2 量化加载显存不够时的取舍显存不够时不要第一时间换显卡先看能不能量化。FP16 效果省心但吃显存8bit 能明显降显存4bit 更省但依赖更多、速度和质量取舍更明显。下面配置只给常见参数实际字段名以资源包config.yaml为准如果资源包没有这些字段就在加载代码里加不要凭空改服务入口。server: host: 0.0.0.0 port: 7860 model: path: ./models/chatglm trust_remote_code: true device_map: auto load_in_8bit: false load_in_4bit: false max_length: 2048 temperature: 0.3 top_p: 0.8 knowledge: enabled: true dir: ./data/knowledge chunk_size: 500 chunk_overlap: 80 top_k: 4host: 0.0.0.0表示服务监听所有网卡局域网其他机器才能访问只在本机用可以改127.0.0.1。port被占用时换一个不要杀不认识的进程。max_length是生成上限调大更吃显存temperature和top_p控制回答发散程度知识库问答一般调低一点。load_in_8bit和load_in_4bit不要同时开开启前先确认bitsandbytes能正常导入。量化方式显存占用依赖适用场景FP16较高基础依赖显存够追求省心8bit中等bitsandbytes单卡显存偏小4bit较低bitsandbytes 及量化配置显存紧张能接受速度取舍CPU不占显存无只做流程验证量化不是越多越好。8bit 在不少单卡环境里已经够用4bit 更适合显存确实卡死的情况。开启量化后如果报CUDA error或bitsandbytes相关错误先退回 FP16 验证模型本身能不能加载再处理量化依赖。Windows 上量化 wheel 的坑更多必要时先用 CPU 或 FP16 把服务跑通别一上来就追 4bit。4.3 服务配置文件端口、模型名、知识库目录服务启动前把配置文件里的模型路径、知识库目录、端口逐项对一遍。下面命令是两种常见入口具体用哪个看资源包里的入口文件不要两个同时启动否则端口会打架。启动后先看日志有没有“模型加载完成”再看端口有没有监听。# 常见入口一带配置文件启动 python app.py --config config.yaml # 常见入口二用 uvicorn 启动 FastAPI 服务 uvicorn server:app --host 0.0.0.0 --port 7860--config config.yaml是让入口读取你改过的配置如果入口不支持这个参数就看app.py里的参数解析。uvicorn server:app里server是模块名app是 FastAPI 实例名别照抄成不存在的文件。启动日志里重点看三行模型路径、设备分配、知识库是否启用。知识库目录为空时服务可能能启动但问答只会泛答不会报明显错误。知识库参数里chunk_size是切片大小chunk_overlap是切片重叠top_k是每次召回片段数。中文知识库切片太大检索会带进无关内容切片太小上下文又拼不起来。500 字、80 字重叠、召回 4 条是常见起点实际按文档类型调。表格和 FAQ 不要切得太碎否则一个问题可能只命中半行。检索效果差时先看日志里有没有命中片段再决定调切片还是换嵌入模型。5. 避坑与排查ChatGLM 本地服务五类翻车记录5.1 现象torch.cuda.is_available()一直是 False现象很直接nvidia-smi能看到显卡但 Python 里 CUDA 不可用模型只能跑 CPU速度慢到没法用。原因通常不是显卡坏了而是 PyTorch 装成了 CPU 版或者 wheel 的 CUDA 版本和驱动不匹配。还有一种情况是 conda 环境里混进了系统级 torchpip show torch看到的路径和你以为的不一样。解决顺序是先看版本再决定重装。下面命令确认当前 torch 来源和 CUDA 状态如果torch.version.cuda是None直接卸载重装匹配 wheel不要在旧包上修。python - PY import torch print(torch.__file__) print(torch.__version__) print(torch.version.cuda) print(torch.cuda.is_available()) PYtorch.__file__能看出包到底装在哪个环境里如果路径指向系统目录说明 conda 环境没生效。torch.version.cuda为None就是 CPU 版。重装时先pip uninstall torch torchvision torchaudio -y再按第 3 章的 CUDA 索引安装。驱动太旧时先升级驱动别硬装高版本 CUDA wheel。5.2 现象加载模型报找不到自定义模型类现象是启动时抛ModuleNotFoundError或者提示某个自定义模型类不存在。原因通常是trust_remote_codeTrue没开或者transformers版本太旧读不懂权重目录里的自定义代码。还有一种情况是权重目录不完整config.json在但自定义模型文件缺失。解决时先看配置文件和加载代码。配置文件里要有trust_remote_code: true直接写 Python 加载时也要显式传入。然后确认transformers版本不要用太旧的版本加载新版权重。from transformers import AutoTokenizer, AutoModel model_dir ./models/chatglm tokenizer AutoTokenizer.from_pretrained( model_dir, trust_remote_codeTrue # 缺少时常见自定义模型类加载失败 ) model AutoModel.from_pretrained( model_dir, trust_remote_codeTrue )如果加了参数还报错检查权重目录里是否有configuration_chatglm.py、modeling_chatglm.py一类文件缺文件就重新解压资源包。不要从别的版本目录里随便拷一个模型文件进来结构对不上时错误会更隐蔽。5.3 现象问答几句后CUDA out of memory现象是模型能加载但一问长问题或连续问几次就 OOM。原因一般不是权重本身而是max_length太大、并发请求太多、历史对话越堆越长或者量化没开。显存被日志、知识库检索、前端进程一起占用时余量比想象中小。解决先从参数下手不要急着换卡。把max_length降到 1024 或 512限制并发清空历史对话再试 8bit 量化。如果只是验证流程把知识库先关掉减少检索模型占用的显存。model: load_in_8bit: true max_length: 1024 device_map: autoload_in_8bit: true需要bitsandbytes正常安装max_length降低会缩短生成长度但能明显减少缓存占用。device_map: auto在多卡环境可能把不同层分到不同卡单卡环境如果报设备不一致可以改成显式单卡加载。OOM 反复出现时看日志里 OOM 前最后一次请求的长度通常能找到触发点。5.4 现象本机 curl 通局域网访问不了现象是服务器本机curl 127.0.0.1:7860有响应另一台机器访问 IP 和端口却连不上。原因通常是服务监听在127.0.0.1只允许本机访问或者系统防火墙没放行端口。也有一种情况是容器端口没映射出来日志里看着启动成功外部就是进不来。解决先看监听地址和端口。下面命令确认 7860 到底监听在哪个网卡如果显示127.0.0.1:7860改配置里的host。ss -lntp | grep 7860ss -lntp会显示监听地址、端口和进程。把配置里的host改成0.0.0.0后重启服务再用局域网 IP 访问。还不行就检查防火墙规则和容器端口映射。不要为了省事直接关防火墙按端口放行更可控。5.5 现象知识库问答答非所问或出现乱码现象是基础问答正常一开知识库就答偏或者文档里的中文变成乱码。原因常见有三类知识库文件不是 UTF-8切片太大导致召回片段混杂top_k太低导致该命中的片段没进来。还有一种情况是知识库目录里混进了日志、临时文件检索时被当成正文。解决先统一编码再调切片。把知识库文件转成 UTF-8清理非文档文件日志里打印召回片段和分数。下面配置是常见起点中文文档不要切得太碎。knowledge: enabled: true dir: ./data/knowledge chunk_size: 500 chunk_overlap: 80 top_k: 4chunk_size调小可能提高命中精度但上下文容易断调大可能带进无关内容。chunk_overlap用来避免切片边界丢句子80 是常见起点。top_k从 4 调到 6 可以增加召回但也会增加噪声。每次只改一个参数问同一个问题对比日志别一次改四项最后不知道是哪项起作用。6. 装完怎么验证三条请求确认 ChatGLM 私有化助理跑通装完不要只看页面能不能打开。页面打开只说明 Web 层活着模型加载、GPU 分配、知识库检索都可能在后台没生效。我一般按“本地直连模型 → HTTP 服务 → 知识库问答”三层验证任何一层失败都能快速缩小范围。先看端口和日志确认模型加载完成且没有 OOM。# 看端口是否监听确认服务进程还活着 ss -lntp | grep 7860 # 看最近日志重点找模型路径、设备、OOM、检索命中 tail -n 50 app.log第一层验证直接问模型不经过前端和接口。能返回一句正常中文说明权重、tokenizer、设备分配没问题。第二层访问 HTTP 服务用浏览器或curl看首页是否返回内容如果资源包提供聊天接口按实际路由发一条短问题不要照抄示例路径。第三层打开知识库问一个只存在于文档里的词再看日志有没有召回记录。验证项预期结果失败时先看端口监听7860 处于 LISTEN启动日志、端口占用首页访问返回页面或接口说明host、防火墙、路由基础问答返回通顺中文模型路径、CUDA、显存知识库问答能答出文档内专有词编码、切片、召回日志连续三次请求不 OOM、延迟可接受max_length、并发、量化最后给一个固定问题做回归比如“用一句话说明这台机器上的助理能做什么”再给一个知识库问题比如“文档里某个流程第一步是什么”。两次都通过再看日志里检索命中的片段是不是正确文档。从那以后我每次装完 ChatGLM 私有化助理都先把知识库关掉问一句固定问题再打开知识库问一个只存在于文档里的词最后看日志里有没有检索命中记录。三步都过了才交给别人用。希望帮到你。本文还有配套的精品资源点击获取
