前阵子做了一次智谱GLM-5.2的私有化部署交付项目地点在深圳客户是一家对数据安全要求很高、同时又不希望把核心业务数据送出内网的科技公司。整个项目从环境准备、模型权重交付、推理服务搭建到最终接入业务系统和自有AI平台前后磨合了不少细节。今天把这次部署的关键思路、操作步骤和踩过的坑整理成文希望能给正在做大模型私有化部署的团队一些参考。私有化部署这件事真正有价值的部分往往不是“把模型跑起来”而是让模型在客户自己的机房或云环境里长期、稳定、可控地提供服务。很多人以为拿到权重、装个推理框架、起一个API服务就算交付但实际做过一次完整交付就会知道后面的架构设计、网关鉴权、监控告警、模型回滚这些工程细节才是决定项目能不能真正落地为生产系统的关键。1. 为什么这次选择了私有化部署而不是直接调用云端API先回答一个很多团队都会问的问题智谱GLM本身就提供云端API调用简单、按量计费、不用管GPU为什么还要折腾私有化从这次项目的实际情况看原因集中在三个方面。第一是数据安全边界。客户的核心业务数据包含大量内部资料、客户信息和业务运行数据公司明确规定这些数据不能出内网也不能进入第三方模型服务商的云端接口。即使云端API承诺数据不用于训练在合规层面依然存在很多难以向客户解释清楚的问题。私有化部署最直接的价值就是把模型服务完全放进客户自己的网络边界内数据从进入到产出始终留在可控环境里。第二是成本结构。云端API适合调用量不高、波峰波谷明显的场景。但这个客户是打算把模型能力嵌入到自身的核心产品流程里每天会产生大量持续调用按Token计费的积少成多非常可观长期下来成本会超过自建GPU服务。私有化部署的硬件和人力投入是一次性或分期折旧成本当业务量稳定增长时边际成本会明显下降。第三是集成自由度。私有化部署后客户可以自己在模型服务前面加网关、做缓存、定制策略可以把多个模型组件的链路沉淀成内部平台能力也可以按照业务需求对模型做后训练或微调。使用云端API时这些能力都受制于服务商的开放范围。但并不是所有场景都适合私有化部署。如果只是做内部小范围试用、验证模型能力、或者团队没有GPU运维经验先使用云端API把业务跑通是更聪明的选择。私有化部署更适合那些已经明确模型会长期高频使用、数据又必须留在内网的企业。这次项目中GPU资源采用了自购物理机加算力云补充并用的方式。核心模型服务跑在客户自购的GPU服务器上而一些临时的评测、压测和试用环境放到算力云上按需开通既控制了采购成本又保留了弹性。这个思路在后续做资源规划时可以参考。2. 部署前必须搞清楚的三个问题在真正动手部署智谱GLM-5.2之前先要回答三个问题这三个问题决定了后面所有技术选型和架构设计。很多人部署失败或交付延期往往就是在这一层没有想清楚。2.1 模型权重从哪来授权边界是什么私有化部署的第一步不是写代码而是确认模型权重的合法获取渠道和使用权限。通过正规渠道获取权重并且明确部署环境、允许的并发规模、是否允许微调、数据是否可以本地留存这些授权边界会直接影响部署方案。这里不是走流程的形式主义。如果授权范围只允许在特定地域、特定硬件上运行那么部署架构就必须围绕这个边界做设计。如果允许微调权重文件的存储和管理方式也要提前想好。从项目实践看建议把授权文件和许可条款作为交付文档的一部分和权重文件一起归档。2.2 部署形态是单机Demo还是多实例生产服务很多人在验证阶段用的是单卡、单实例、最小化配置跑通一个对话就觉得完事了。但生产环境看到的完全是另一套问题多用户并发、请求排队、超时重试、显存占用波动、模型频繁重启等。如果一开始就清楚这是一个生产级交付建议从第一天就按生产架构设计不要先搭一个单机Demo后面再推倒重来。单机Demo和生产服务的差别不是量变而是架构变化。生产环境会在模型服务外面再加网关层、鉴权层、日志审计和监控告警这在前期的架构图里就要体现出来。2.3 推理框架选哪一个目前主流的LLM推理框架有vLLM、SGLang、TGI、llama.cpp等各自有不同的侧重点。框架适合场景特点与注意点vLLM生产环境高吞吐、OpenAI兼容API社区活跃支持PagedAttention适合大多数部署场景SGLang结构化输出、复杂推理场景性能优秀但新版本迭代较快需要关注兼容性TGIHugging Face生态衔接依赖HF生态部署方式偏重llama.cpp边缘设备、量化部署、CPU推理适合资源受限场景GPU利用率通常不如专用推理框架这次项目最终使用vLLM作为核心推理框架原因是它生态成熟、API兼容性好、社区支持多遇到问题更容易找到解决思路。不过不同版本对模型架构的支持情况不同具体使用哪个版本务必以官方项目说明和模型实际兼容性为准不要照搬网上旧教程里的写法。3. 整体部署架构设计一次合格的私有化部署应该有清晰的分层架构。因为模型推理服务本身只是整个系统的一层如果直接把模型服务的端口暴露给业务方问题会非常多。这次项目采用的架构大致分为三层。3.1 接入层最外层是API网关负责接收业务系统的请求执行API Key校验、统一鉴权、请求频率限制、流量分发和审计日志记录。这一层解决的核心问题有两个一是不要让模型服务直接暴露在业务网络里二是为后续多模型、多版本切换留一个稳定入口。网关层可以使用Kong、APISIX、Nginx等常用组件。因为客户内部已有网关体系我们直接复用了现有网关将模型服务的路由规则、鉴权策略和负载均衡统一配置在网关层模型服务本身只接受来自内网网关的请求。3.2 推理服务层中间层是模型推理服务也就是跑GLM-5.2权重的vLLM实例。这一层关注的指标是显存、吞吐、TTFT首Token延迟和TPOT每Token生成延迟。生产环境建议部署至少两个实例放到网关后面做负载均衡避免单点故障。实例数并不是越多越好。每个大模型实例加载权重后会占据大量显存实例增加会导致单卡必须加载多份模型副本显存压力随之上升。更合理的做法是根据GPU卡数、权重大小和并发预期先做一个容量估算再确定实例数。3.3 资源层底层是GPU服务器、存储和网络。模型权重文件建议放在高速磁盘上因为首启动时要把整个模型加载进显存磁盘读取速度会直接影响启动时间。如果有多台GPU服务器还要考虑服务器之间的高速互联例如InfiniBand或RoCE因为张量并行或多实例部署时节点间通信会成为瓶颈。一个完整的请求链路是这样的业务系统调用网关地址网关校验API Key和调用权限将请求转发给后端的vLLM实例vLLM把文本Token化、经过模型计算、生成输出再逐Token返回给调用方同时网关记录完整的调用日志。整个过程模型服务不需要关心业务逻辑只需要稳定提供OpenAI兼容的推理能力。4. 环境准备与硬件选型在真正开始安装之前先把环境清单列清楚。这里说的“环境”不只是软件环境也包括硬件资源。4.1 硬件层面GLM-5.2这类大模型的私有化部署核心瓶颈在GPU显存其次是显存带宽和服务器间通信。组件建议配置说明GPU建议使用支持BF16的高端数据中心GPU具体型号和数量取决于权重大小、批量大小和并发要求CPU32核以上主要处理Token化、调度和请求排队内存至少256GB模型推理过程中CPU内存用于KV Cache之外的临时数据系统盘1TB NVMe SSD安装操作系统、Docker、日志存储数据盘至少3倍权重文件大小存放模型权重、缓存和备份具体大小以实际交付为准网络内网10GbE以上多机互联建议100GbE以上多实例张量并行时网络直接影响性能需要注意上面这些只是通用参考。实际项目中应该先拿到模型权重的实际大小和量化格式再根据精度要求计算显存需求。不要只看模型文件大小还要给KV Cache和推理开销预留足够空间。4.2 软件层面操作系统选择了Ubuntu 22.04 LTS这是当前大模型部署生态兼容性较好的选择软件源丰富社区问题也容易搜到。需要安装的核心组件包括NVIDIA驱动CUDA工具包DockerNVIDIA Container Toolkit安装NVIDIA驱动前建议先确认GPU型号和驱动版本之间的兼容关系。这里给出通用检查命令具体版本号请以官方驱动页面和当前系统信息为准。# 查看GPU信息 nvidia-smi # 查看系统内核版本 uname -r # 查看操作系统版本 cat /etc/os-release安装Docker和NVIDIA Container Toolkit后需要验证Docker是否能真正使用GPU# 验证Docker是否可以使用GPU docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi如果能正常输出GPU信息说明Docker里的GPU透传已经就绪。这一步没通过的话后面所有容器部署都会有问题。还有一点容易被忽略就是检查可用磁盘空间# 检查数据盘挂载和剩余空间 df -h权重文件动辄几十GB甚至几百GB如果数据盘空间不足拷贝到一半失败会非常尴尬。这次项目在现场就遇到过一次数据盘挂载路径和预期不一致的情况幸好提前检查发现了。5. 核心部署流程从权重到可用API环境准备完成后进入真正的部署阶段。这里不追求一次把所有组件全装齐而是先把最小链路跑通再逐步扩展。5.1 模型权重准备与校验拿到模型权重后第一件事不是急着启动服务而是先做完整性校验。官方交付通常会附带哈希值使用sha256sum进行核对确保权重文件没有损坏或被截断。# 解压或校验权重以实际交付文件为准 sha256sum /data/models/glm-5.2/weights.bin同时建议保留一份原始压缩包不直接删除作为后续回滚的备份。5.2 使用Docker Compose编排推理服务生产环境不建议直接手动运行vLLM命令行而是使用docker-compose.yaml把服务定义固化下来这样重启、迁移、记录版本都很方便。下面是一个可用于参考的docker-compose.yaml示例实际使用时应替换镜像版本、模型路径和端口号。# 文件路径/opt/llm/docker-compose.yaml version: 3.8 services: glm52: image: vllm/vllm-openai:latest container_name: glm52-server restart: unless-stopped ports: - 8000:8000 volumes: - /data/models:/models - /data/cache:/cache environment: - HF_HOME/cache/huggingface command: - --model/models/glm-5.2 - --served-model-nameglm-5.2 - --max-model-len32768 - --gpu-memory-utilization0.90 - --enforce-eager deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] shm_size: 16gb healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 5 start_period: 300s这里有几个参数值得重点说明。--model指向容器内的权重路径宿主机路径在volumes中映射。--served-model-name是API调用方看到的模型名可以改成自己业务侧容易识别的名字。--max-model-len控制最大上下文长度并不是越长越好因为越长占用显存越多。如果最大上下文设置过大超出显存容量启动时就会报显存不足。--gpu-memory-utilization表示vLLM最多可以使用多少比例的显存默认值是0.9实际场景里需要根据并发和上下文长度做调整。--enforce-eager用来关闭CUDA Graph优化换取消极少部分性能换来的是更快的启动和更少的内存估算误差首次部署建议先开启跑通后再关闭以提升性能。5.3 启动服务编写好docker-compose.yaml后在对应目录下执行cd /opt/llm docker compose up -d首次启动时vLLM会加载模型权重并进行图优化这个过程耗时较长几分钟到几十分钟都有可能取决于磁盘速度和模型大小。期间不要反复重启容器以免每次都重新加载。需要查看服务日志时执行docker logs -f glm52-server出现类似下面的日志说明服务开始对外提供能力INFO: Started server process [1] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:80005.4 配置systemd自启动Docker Compose中的restart: unless-stopped解决了容器异常退出后的自动重启问题。但机器重启后Docker服务本身需要先启动再启动容器。对生产环境来说可以配置systemd服务把这一点管理起来。# 创建systemd服务文件 sudo tee /etc/systemd/system/glm52-llm.service /dev/null EOF [Unit] DescriptionGLM-5.2 LLM Container Service Requiresdocker.service Afterdocker.service network-online.target [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/llm ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down TimeoutStartSec0 [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload sudo systemctl enable glm52-llm.service sudo systemctl start glm52-llm.service这样配置后即使服务器整机重启模型服务也能自动恢复。5.5 验证OpenAI兼容APIvLLM启动后默认提供OpenAI兼容的/v1/chat/completions接口这是后续所有业务接入的基础。先用curl做一次最小验证。curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: glm-5.2, messages: [ {role: user, content: 你好请用一句话介绍你自己} ], max_tokens: 100 }如果返回内容包含choices字段和生成的文本说明推理链路已打通。6. 对接业务系统与Dify等应用平台模型服务跑起来只是第一步真正交付给客户时业务系统要能稳定调用它才行。6.1 使用Python调用推理服务业务侧使用Python调用时可以采用兼容OpenAI SDK的方式。# 文件路径/opt/llm/test_client.py from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelglm-5.2, messages[ {role: system, content: 你是一个专业的AI助手。}, {role: user, content: 私有化部署和云端API有什么区别} ], max_tokens200, temperature0.7, ) print(response.choices[0].message.content)执行python3 test_client.py需要注意示例中的api_key写的是EMPTY因为vLLM本身默认不开启鉴权。生产环境必须依靠前面说的网关层来增加API Key校验不要裸奔在业务网络中。6.2 接入Dify平台现在很多企业会使用Dify这类LLM应用平台做知识库、Agent工作流和应用编排。私有化部署的模型服务正好可以作为Dify的模型供应来源。Dify支持通过OpenAI API兼容格式接入自定义模型操作路径很简单在“设置-模型供应商”中选择“OpenAI-API-compatible”类型填写模型服务地址、API Key和实际模型名称即可。一个典型的配置如下{ model_name: glm-5.2, model_type: llm, base_url: http://模型服务网关地址/v1, api_key: 客户自定义的网关API Key }配置完成后可以在Dify中创建一个简单的对话应用把默认模型切换成glm-5.2测试对话效果。这样Dify只负责工作流编排和知识库管理真正的推理全部走私有化部署的服务数据不会出内网。6.3 周边系统集成思路除了Dify客户内部还会有一堆系统需要接入模型能力。比如知识库文档生成后借助OnlyOffice做在线预览和协同编辑再比如OCR识别接口与模型服务串联形成“文字识别-文档解析-智能问答”的完整链路。这些周边系统不需要自己实现模型推理只需要按OpenAI兼容API规范调用网关服务即可。私有化部署到这里才真正开始释放价值。7. 功能与性能验证交付不是“能对话”就算完成还需要从功能和性能两方面做系统性验证。7.1 功能验证功能验证至少要覆盖这几项模型列表接口确认模型名称正确。单轮问答确认基础生成能力正常。多轮对话确认上下文记忆正确。工具调用或Function Call确认结构化输出正常。长文本输入确认达到配置的上下文长度上限时不会异常报错。逐项测试通过后再进入性能验证不要跳过。7.2 性能验证性能验证关注两个核心指标吞吐量和延迟。先写一个简单的并发压测脚本使用Python的concurrent.futures同时发出多个请求。# 文件路径/opt/llm/pressure_test.py from openai import OpenAI from concurrent.futures import ThreadPoolExecutor import time client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) def single_request(idx): start time.time() try: response client.chat.completions.create( modelglm-5.2, messages[ {role: user, content: 请用200字解释什么是私有化部署} ], max_tokens200, temperature0.3, ) latency time.time() - start return idx, latency, response.choices[0].message.content except Exception as e: return idx, time.time() - start, str(e) def main(): total_requests 20 with ThreadPoolExecutor(max_workers5) as executor: results list(executor.map(single_request, range(total_requests))) latencies [r[1] for r in results] avg_latency sum(latencies) / len(latencies) total_time max(latencies) qps len(latencies) / (sum(latencies) / len(latencies)) print(f总请求数: {len(latencies)}) print(f平均耗时: {avg_latency:.2f}s) print(f最大耗时: {max(latencies):.2f}s) print(f估算QPS: {qps:.2f}) failed [r for r in results if Error in str(r[2]) or error in str(r[2])] print(f失败请求数: {len(failed)}) if __name__ __main__: main()这个脚本只是估算QPS不是精确的压测工具。真正上线前建议再用locust、k6或wrk做更正式的压测并把结果和业务的预期目标做对比。如果平均延迟明显偏高优先检查GPU利用率、显存占用和是否发生了KV Cache驱逐。稳定性的判断还要结合监控数据。关注GPU利用率是否持续打满、显存是否稳定、请求失败率是否在可接受范围内。建议至少持续观察数小时观察有无缓慢泄漏或异常波动。8. 常见问题与排查思路把这次项目中遇到过以及行业里常见的问题整理成一张排查表实际操作时可以从这些方向入手。问题现象可能原因排查方式解决方案容器启动后立即退出模型路径不对或权重格式不兼容查看docker logs启动日志检查volume挂载路径和模型目录结构显存不足导致启动失败max-model-len或gpu-memory-utilization设置过高查看日志中的显存估算用nvidia-smi确认剩余显存调低max-model-len或gpu-memory-utilization或增加GPU资源请求返回模型不存在API调用时model参数和--served-model-name不一致调用GET /v1/models确认统一模型名称或调用时使用served-model-name并发请求时部分请求超时推理实例吞吐不足或网关超时设置过短查看网关和vLLM日志观察GPU利用率增加实例、调优max-num-seqs、优化网关超时配置首Token延迟很高输入长度过长、队列堆积或网络抖动查看监控面板TTFT指标和vLLM日志限制单请求最大输入长度或调大并发队列上限生成内容质量不可控温度、top_p等参数设置不适合当前场景检查调用参数和系统提示词针对业务场景做Prompt调优服务重启一次要等很久权重文件在低速磁盘上加载耗时长查看磁盘IO和启动时间把权重迁移到高速SSD或增加缓存容器日志出现CUDA OOM多实例并发下显存碎片化查看显存监控和vLLM OOM日志降低gpu-memory-utilization或减少并发实例数9. 生产环境最佳实践与安全建议部署完成后真正考验工程能力的阶段才刚刚开始。整理几条生产环境建议这些都是在真实项目里反复验证过的。9.1 镜像与依赖版本固化生产环境不能每次启动都拉取最新镜像这样会把不确定因素引进来。建议把推理框架镜像固定到具体tag并把docker-compose.yaml纳入Git版本管理。权重文件、模型配置、启动参数都要有版本记录方便出现问题时快速回滚到上一个可用状态。9.2 显存与并发控制大模型的显存管理是生产环境最微妙的问题。KV Cache会随着并发请求动态变化如果并发调大显存瞬间被占满就会触发OOM或请求排队。上线前务必结合最大输入长度、最大输出长度和并发数做容量压测明确服务的最大能力边界必要时在网关上配置并发限制。9.3 最小权限与数据安全私有化部署中的数据安全要从两个方向考虑。第一模型权重的访问权限要限制只有运维人员能接触权重文件。第二模型服务调用层面API Key要按团队和业务线进行隔离避免一个Key走天下。模型服务本身存储的日志也要避免记录过长的业务内容防止敏感数据被集中保存在日志文件中。还有一点必须强调模型权重必须通过正规渠道获取使用范围要严格遵守授权协议。尤其要确认授权是否覆盖生产环境和使用地域如果客户要求模型输出内容合规需要在系统提示词和上层应用里增加内容过滤策略而不是在模型层做不可控的修改。9.4 监控与告警上线后至少关注四个维度的指标GPU利用率、显存占用、请求延迟、失败率。这些指标都接入统一监控平台设置告警阈值。模型服务异常时第一响应人是运维而不是业务方这是生产级交付的基本要求。9.5 给客户留好交接文档交付的不仅仅是代码和模型还有能独立运维的能力。建议交付一份完整文档内容至少包括环境说明、启动流程、日志位置、常见问题处理、备份和恢复步骤、模型版本升级方案以及联系人信息。一个团队是否专业很多时候就体现在这份文档的质量上。桌面上的工作做完了真正的考验是接下来的一年。模型能稳定跑起来不算本事能在业务高峰期不出问题、能快速定位并修复故障、能在模型升级时平滑切换这才是一次真正成功的私有化部署交付。 智谱GLM-5.2私有化部署实战：从架构设计到生产落地
前阵子做了一次智谱GLM-5.2的私有化部署交付项目地点在深圳客户是一家对数据安全要求很高、同时又不希望把核心业务数据送出内网的科技公司。整个项目从环境准备、模型权重交付、推理服务搭建到最终接入业务系统和自有AI平台前后磨合了不少细节。今天把这次部署的关键思路、操作步骤和踩过的坑整理成文希望能给正在做大模型私有化部署的团队一些参考。私有化部署这件事真正有价值的部分往往不是“把模型跑起来”而是让模型在客户自己的机房或云环境里长期、稳定、可控地提供服务。很多人以为拿到权重、装个推理框架、起一个API服务就算交付但实际做过一次完整交付就会知道后面的架构设计、网关鉴权、监控告警、模型回滚这些工程细节才是决定项目能不能真正落地为生产系统的关键。1. 为什么这次选择了私有化部署而不是直接调用云端API先回答一个很多团队都会问的问题智谱GLM本身就提供云端API调用简单、按量计费、不用管GPU为什么还要折腾私有化从这次项目的实际情况看原因集中在三个方面。第一是数据安全边界。客户的核心业务数据包含大量内部资料、客户信息和业务运行数据公司明确规定这些数据不能出内网也不能进入第三方模型服务商的云端接口。即使云端API承诺数据不用于训练在合规层面依然存在很多难以向客户解释清楚的问题。私有化部署最直接的价值就是把模型服务完全放进客户自己的网络边界内数据从进入到产出始终留在可控环境里。第二是成本结构。云端API适合调用量不高、波峰波谷明显的场景。但这个客户是打算把模型能力嵌入到自身的核心产品流程里每天会产生大量持续调用按Token计费的积少成多非常可观长期下来成本会超过自建GPU服务。私有化部署的硬件和人力投入是一次性或分期折旧成本当业务量稳定增长时边际成本会明显下降。第三是集成自由度。私有化部署后客户可以自己在模型服务前面加网关、做缓存、定制策略可以把多个模型组件的链路沉淀成内部平台能力也可以按照业务需求对模型做后训练或微调。使用云端API时这些能力都受制于服务商的开放范围。但并不是所有场景都适合私有化部署。如果只是做内部小范围试用、验证模型能力、或者团队没有GPU运维经验先使用云端API把业务跑通是更聪明的选择。私有化部署更适合那些已经明确模型会长期高频使用、数据又必须留在内网的企业。这次项目中GPU资源采用了自购物理机加算力云补充并用的方式。核心模型服务跑在客户自购的GPU服务器上而一些临时的评测、压测和试用环境放到算力云上按需开通既控制了采购成本又保留了弹性。这个思路在后续做资源规划时可以参考。2. 部署前必须搞清楚的三个问题在真正动手部署智谱GLM-5.2之前先要回答三个问题这三个问题决定了后面所有技术选型和架构设计。很多人部署失败或交付延期往往就是在这一层没有想清楚。2.1 模型权重从哪来授权边界是什么私有化部署的第一步不是写代码而是确认模型权重的合法获取渠道和使用权限。通过正规渠道获取权重并且明确部署环境、允许的并发规模、是否允许微调、数据是否可以本地留存这些授权边界会直接影响部署方案。这里不是走流程的形式主义。如果授权范围只允许在特定地域、特定硬件上运行那么部署架构就必须围绕这个边界做设计。如果允许微调权重文件的存储和管理方式也要提前想好。从项目实践看建议把授权文件和许可条款作为交付文档的一部分和权重文件一起归档。2.2 部署形态是单机Demo还是多实例生产服务很多人在验证阶段用的是单卡、单实例、最小化配置跑通一个对话就觉得完事了。但生产环境看到的完全是另一套问题多用户并发、请求排队、超时重试、显存占用波动、模型频繁重启等。如果一开始就清楚这是一个生产级交付建议从第一天就按生产架构设计不要先搭一个单机Demo后面再推倒重来。单机Demo和生产服务的差别不是量变而是架构变化。生产环境会在模型服务外面再加网关层、鉴权层、日志审计和监控告警这在前期的架构图里就要体现出来。2.3 推理框架选哪一个目前主流的LLM推理框架有vLLM、SGLang、TGI、llama.cpp等各自有不同的侧重点。框架适合场景特点与注意点vLLM生产环境高吞吐、OpenAI兼容API社区活跃支持PagedAttention适合大多数部署场景SGLang结构化输出、复杂推理场景性能优秀但新版本迭代较快需要关注兼容性TGIHugging Face生态衔接依赖HF生态部署方式偏重llama.cpp边缘设备、量化部署、CPU推理适合资源受限场景GPU利用率通常不如专用推理框架这次项目最终使用vLLM作为核心推理框架原因是它生态成熟、API兼容性好、社区支持多遇到问题更容易找到解决思路。不过不同版本对模型架构的支持情况不同具体使用哪个版本务必以官方项目说明和模型实际兼容性为准不要照搬网上旧教程里的写法。3. 整体部署架构设计一次合格的私有化部署应该有清晰的分层架构。因为模型推理服务本身只是整个系统的一层如果直接把模型服务的端口暴露给业务方问题会非常多。这次项目采用的架构大致分为三层。3.1 接入层最外层是API网关负责接收业务系统的请求执行API Key校验、统一鉴权、请求频率限制、流量分发和审计日志记录。这一层解决的核心问题有两个一是不要让模型服务直接暴露在业务网络里二是为后续多模型、多版本切换留一个稳定入口。网关层可以使用Kong、APISIX、Nginx等常用组件。因为客户内部已有网关体系我们直接复用了现有网关将模型服务的路由规则、鉴权策略和负载均衡统一配置在网关层模型服务本身只接受来自内网网关的请求。3.2 推理服务层中间层是模型推理服务也就是跑GLM-5.2权重的vLLM实例。这一层关注的指标是显存、吞吐、TTFT首Token延迟和TPOT每Token生成延迟。生产环境建议部署至少两个实例放到网关后面做负载均衡避免单点故障。实例数并不是越多越好。每个大模型实例加载权重后会占据大量显存实例增加会导致单卡必须加载多份模型副本显存压力随之上升。更合理的做法是根据GPU卡数、权重大小和并发预期先做一个容量估算再确定实例数。3.3 资源层底层是GPU服务器、存储和网络。模型权重文件建议放在高速磁盘上因为首启动时要把整个模型加载进显存磁盘读取速度会直接影响启动时间。如果有多台GPU服务器还要考虑服务器之间的高速互联例如InfiniBand或RoCE因为张量并行或多实例部署时节点间通信会成为瓶颈。一个完整的请求链路是这样的业务系统调用网关地址网关校验API Key和调用权限将请求转发给后端的vLLM实例vLLM把文本Token化、经过模型计算、生成输出再逐Token返回给调用方同时网关记录完整的调用日志。整个过程模型服务不需要关心业务逻辑只需要稳定提供OpenAI兼容的推理能力。4. 环境准备与硬件选型在真正开始安装之前先把环境清单列清楚。这里说的“环境”不只是软件环境也包括硬件资源。4.1 硬件层面GLM-5.2这类大模型的私有化部署核心瓶颈在GPU显存其次是显存带宽和服务器间通信。组件建议配置说明GPU建议使用支持BF16的高端数据中心GPU具体型号和数量取决于权重大小、批量大小和并发要求CPU32核以上主要处理Token化、调度和请求排队内存至少256GB模型推理过程中CPU内存用于KV Cache之外的临时数据系统盘1TB NVMe SSD安装操作系统、Docker、日志存储数据盘至少3倍权重文件大小存放模型权重、缓存和备份具体大小以实际交付为准网络内网10GbE以上多机互联建议100GbE以上多实例张量并行时网络直接影响性能需要注意上面这些只是通用参考。实际项目中应该先拿到模型权重的实际大小和量化格式再根据精度要求计算显存需求。不要只看模型文件大小还要给KV Cache和推理开销预留足够空间。4.2 软件层面操作系统选择了Ubuntu 22.04 LTS这是当前大模型部署生态兼容性较好的选择软件源丰富社区问题也容易搜到。需要安装的核心组件包括NVIDIA驱动CUDA工具包DockerNVIDIA Container Toolkit安装NVIDIA驱动前建议先确认GPU型号和驱动版本之间的兼容关系。这里给出通用检查命令具体版本号请以官方驱动页面和当前系统信息为准。# 查看GPU信息 nvidia-smi # 查看系统内核版本 uname -r # 查看操作系统版本 cat /etc/os-release安装Docker和NVIDIA Container Toolkit后需要验证Docker是否能真正使用GPU# 验证Docker是否可以使用GPU docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi如果能正常输出GPU信息说明Docker里的GPU透传已经就绪。这一步没通过的话后面所有容器部署都会有问题。还有一点容易被忽略就是检查可用磁盘空间# 检查数据盘挂载和剩余空间 df -h权重文件动辄几十GB甚至几百GB如果数据盘空间不足拷贝到一半失败会非常尴尬。这次项目在现场就遇到过一次数据盘挂载路径和预期不一致的情况幸好提前检查发现了。5. 核心部署流程从权重到可用API环境准备完成后进入真正的部署阶段。这里不追求一次把所有组件全装齐而是先把最小链路跑通再逐步扩展。5.1 模型权重准备与校验拿到模型权重后第一件事不是急着启动服务而是先做完整性校验。官方交付通常会附带哈希值使用sha256sum进行核对确保权重文件没有损坏或被截断。# 解压或校验权重以实际交付文件为准 sha256sum /data/models/glm-5.2/weights.bin同时建议保留一份原始压缩包不直接删除作为后续回滚的备份。5.2 使用Docker Compose编排推理服务生产环境不建议直接手动运行vLLM命令行而是使用docker-compose.yaml把服务定义固化下来这样重启、迁移、记录版本都很方便。下面是一个可用于参考的docker-compose.yaml示例实际使用时应替换镜像版本、模型路径和端口号。# 文件路径/opt/llm/docker-compose.yaml version: 3.8 services: glm52: image: vllm/vllm-openai:latest container_name: glm52-server restart: unless-stopped ports: - 8000:8000 volumes: - /data/models:/models - /data/cache:/cache environment: - HF_HOME/cache/huggingface command: - --model/models/glm-5.2 - --served-model-nameglm-5.2 - --max-model-len32768 - --gpu-memory-utilization0.90 - --enforce-eager deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] shm_size: 16gb healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 5 start_period: 300s这里有几个参数值得重点说明。--model指向容器内的权重路径宿主机路径在volumes中映射。--served-model-name是API调用方看到的模型名可以改成自己业务侧容易识别的名字。--max-model-len控制最大上下文长度并不是越长越好因为越长占用显存越多。如果最大上下文设置过大超出显存容量启动时就会报显存不足。--gpu-memory-utilization表示vLLM最多可以使用多少比例的显存默认值是0.9实际场景里需要根据并发和上下文长度做调整。--enforce-eager用来关闭CUDA Graph优化换取消极少部分性能换来的是更快的启动和更少的内存估算误差首次部署建议先开启跑通后再关闭以提升性能。5.3 启动服务编写好docker-compose.yaml后在对应目录下执行cd /opt/llm docker compose up -d首次启动时vLLM会加载模型权重并进行图优化这个过程耗时较长几分钟到几十分钟都有可能取决于磁盘速度和模型大小。期间不要反复重启容器以免每次都重新加载。需要查看服务日志时执行docker logs -f glm52-server出现类似下面的日志说明服务开始对外提供能力INFO: Started server process [1] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:80005.4 配置systemd自启动Docker Compose中的restart: unless-stopped解决了容器异常退出后的自动重启问题。但机器重启后Docker服务本身需要先启动再启动容器。对生产环境来说可以配置systemd服务把这一点管理起来。# 创建systemd服务文件 sudo tee /etc/systemd/system/glm52-llm.service /dev/null EOF [Unit] DescriptionGLM-5.2 LLM Container Service Requiresdocker.service Afterdocker.service network-online.target [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/llm ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down TimeoutStartSec0 [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload sudo systemctl enable glm52-llm.service sudo systemctl start glm52-llm.service这样配置后即使服务器整机重启模型服务也能自动恢复。5.5 验证OpenAI兼容APIvLLM启动后默认提供OpenAI兼容的/v1/chat/completions接口这是后续所有业务接入的基础。先用curl做一次最小验证。curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: glm-5.2, messages: [ {role: user, content: 你好请用一句话介绍你自己} ], max_tokens: 100 }如果返回内容包含choices字段和生成的文本说明推理链路已打通。6. 对接业务系统与Dify等应用平台模型服务跑起来只是第一步真正交付给客户时业务系统要能稳定调用它才行。6.1 使用Python调用推理服务业务侧使用Python调用时可以采用兼容OpenAI SDK的方式。# 文件路径/opt/llm/test_client.py from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelglm-5.2, messages[ {role: system, content: 你是一个专业的AI助手。}, {role: user, content: 私有化部署和云端API有什么区别} ], max_tokens200, temperature0.7, ) print(response.choices[0].message.content)执行python3 test_client.py需要注意示例中的api_key写的是EMPTY因为vLLM本身默认不开启鉴权。生产环境必须依靠前面说的网关层来增加API Key校验不要裸奔在业务网络中。6.2 接入Dify平台现在很多企业会使用Dify这类LLM应用平台做知识库、Agent工作流和应用编排。私有化部署的模型服务正好可以作为Dify的模型供应来源。Dify支持通过OpenAI API兼容格式接入自定义模型操作路径很简单在“设置-模型供应商”中选择“OpenAI-API-compatible”类型填写模型服务地址、API Key和实际模型名称即可。一个典型的配置如下{ model_name: glm-5.2, model_type: llm, base_url: http://模型服务网关地址/v1, api_key: 客户自定义的网关API Key }配置完成后可以在Dify中创建一个简单的对话应用把默认模型切换成glm-5.2测试对话效果。这样Dify只负责工作流编排和知识库管理真正的推理全部走私有化部署的服务数据不会出内网。6.3 周边系统集成思路除了Dify客户内部还会有一堆系统需要接入模型能力。比如知识库文档生成后借助OnlyOffice做在线预览和协同编辑再比如OCR识别接口与模型服务串联形成“文字识别-文档解析-智能问答”的完整链路。这些周边系统不需要自己实现模型推理只需要按OpenAI兼容API规范调用网关服务即可。私有化部署到这里才真正开始释放价值。7. 功能与性能验证交付不是“能对话”就算完成还需要从功能和性能两方面做系统性验证。7.1 功能验证功能验证至少要覆盖这几项模型列表接口确认模型名称正确。单轮问答确认基础生成能力正常。多轮对话确认上下文记忆正确。工具调用或Function Call确认结构化输出正常。长文本输入确认达到配置的上下文长度上限时不会异常报错。逐项测试通过后再进入性能验证不要跳过。7.2 性能验证性能验证关注两个核心指标吞吐量和延迟。先写一个简单的并发压测脚本使用Python的concurrent.futures同时发出多个请求。# 文件路径/opt/llm/pressure_test.py from openai import OpenAI from concurrent.futures import ThreadPoolExecutor import time client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) def single_request(idx): start time.time() try: response client.chat.completions.create( modelglm-5.2, messages[ {role: user, content: 请用200字解释什么是私有化部署} ], max_tokens200, temperature0.3, ) latency time.time() - start return idx, latency, response.choices[0].message.content except Exception as e: return idx, time.time() - start, str(e) def main(): total_requests 20 with ThreadPoolExecutor(max_workers5) as executor: results list(executor.map(single_request, range(total_requests))) latencies [r[1] for r in results] avg_latency sum(latencies) / len(latencies) total_time max(latencies) qps len(latencies) / (sum(latencies) / len(latencies)) print(f总请求数: {len(latencies)}) print(f平均耗时: {avg_latency:.2f}s) print(f最大耗时: {max(latencies):.2f}s) print(f估算QPS: {qps:.2f}) failed [r for r in results if Error in str(r[2]) or error in str(r[2])] print(f失败请求数: {len(failed)}) if __name__ __main__: main()这个脚本只是估算QPS不是精确的压测工具。真正上线前建议再用locust、k6或wrk做更正式的压测并把结果和业务的预期目标做对比。如果平均延迟明显偏高优先检查GPU利用率、显存占用和是否发生了KV Cache驱逐。稳定性的判断还要结合监控数据。关注GPU利用率是否持续打满、显存是否稳定、请求失败率是否在可接受范围内。建议至少持续观察数小时观察有无缓慢泄漏或异常波动。8. 常见问题与排查思路把这次项目中遇到过以及行业里常见的问题整理成一张排查表实际操作时可以从这些方向入手。问题现象可能原因排查方式解决方案容器启动后立即退出模型路径不对或权重格式不兼容查看docker logs启动日志检查volume挂载路径和模型目录结构显存不足导致启动失败max-model-len或gpu-memory-utilization设置过高查看日志中的显存估算用nvidia-smi确认剩余显存调低max-model-len或gpu-memory-utilization或增加GPU资源请求返回模型不存在API调用时model参数和--served-model-name不一致调用GET /v1/models确认统一模型名称或调用时使用served-model-name并发请求时部分请求超时推理实例吞吐不足或网关超时设置过短查看网关和vLLM日志观察GPU利用率增加实例、调优max-num-seqs、优化网关超时配置首Token延迟很高输入长度过长、队列堆积或网络抖动查看监控面板TTFT指标和vLLM日志限制单请求最大输入长度或调大并发队列上限生成内容质量不可控温度、top_p等参数设置不适合当前场景检查调用参数和系统提示词针对业务场景做Prompt调优服务重启一次要等很久权重文件在低速磁盘上加载耗时长查看磁盘IO和启动时间把权重迁移到高速SSD或增加缓存容器日志出现CUDA OOM多实例并发下显存碎片化查看显存监控和vLLM OOM日志降低gpu-memory-utilization或减少并发实例数9. 生产环境最佳实践与安全建议部署完成后真正考验工程能力的阶段才刚刚开始。整理几条生产环境建议这些都是在真实项目里反复验证过的。9.1 镜像与依赖版本固化生产环境不能每次启动都拉取最新镜像这样会把不确定因素引进来。建议把推理框架镜像固定到具体tag并把docker-compose.yaml纳入Git版本管理。权重文件、模型配置、启动参数都要有版本记录方便出现问题时快速回滚到上一个可用状态。9.2 显存与并发控制大模型的显存管理是生产环境最微妙的问题。KV Cache会随着并发请求动态变化如果并发调大显存瞬间被占满就会触发OOM或请求排队。上线前务必结合最大输入长度、最大输出长度和并发数做容量压测明确服务的最大能力边界必要时在网关上配置并发限制。9.3 最小权限与数据安全私有化部署中的数据安全要从两个方向考虑。第一模型权重的访问权限要限制只有运维人员能接触权重文件。第二模型服务调用层面API Key要按团队和业务线进行隔离避免一个Key走天下。模型服务本身存储的日志也要避免记录过长的业务内容防止敏感数据被集中保存在日志文件中。还有一点必须强调模型权重必须通过正规渠道获取使用范围要严格遵守授权协议。尤其要确认授权是否覆盖生产环境和使用地域如果客户要求模型输出内容合规需要在系统提示词和上层应用里增加内容过滤策略而不是在模型层做不可控的修改。9.4 监控与告警上线后至少关注四个维度的指标GPU利用率、显存占用、请求延迟、失败率。这些指标都接入统一监控平台设置告警阈值。模型服务异常时第一响应人是运维而不是业务方这是生产级交付的基本要求。9.5 给客户留好交接文档交付的不仅仅是代码和模型还有能独立运维的能力。建议交付一份完整文档内容至少包括环境说明、启动流程、日志位置、常见问题处理、备份和恢复步骤、模型版本升级方案以及联系人信息。一个团队是否专业很多时候就体现在这份文档的质量上。桌面上的工作做完了真正的考验是接下来的一年。模型能稳定跑起来不算本事能在业务高峰期不出问题、能快速定位并修复故障、能在模型升级时平滑切换这才是一次真正成功的私有化部署交付。