最近这两年里很多企业做 AI 应用时都卡在同一个环节模型能力已经验证过了API 调用也跑通了但真正要放进生产环境时就发现数据安全、成本上限、版本迭代和响应延迟这些问题光靠公共 API 解决不了。我前阵子帮深圳一家科技公司做智谱 GLM-5.2 的私有化部署从需求沟通到上线验证完整走完了一轮大模型落地的闭环。整个过程里最深的感受是私有化部署这件事难点从来不在把模型权重下载到服务器上而在于如何用一套稳定、可维护、可扩展的架构把大模型真正接入业务系统。这篇文章不打算只贴安装命令而是结合这次部署实践把私有化部署的完整路径拆开讲清楚哪些业务适合私有化部署、硬件和算力怎么评估、推理服务怎么起、Dify 这类应用编排平台怎么接、OnlyOffice 这类办公文档服务怎么打通以及上线之后怎么验证、怎么排错。如果你正在评估公司是否要做大模型私有化或者已经拿到 GLM-5.2 的授权但不知道从哪儿下手这篇文章应该能帮你省掉不少试错成本。1. 私有化部署之前先想清楚这几件事很多人一听到私有化部署第一反应是把模型放到自己的服务器上跑起来。这个理解没有错但太表面了。真正的私有化部署是把大模型从按量付费的外部服务变成可以自主掌控的内部基础设施这个转变带来的不只是部署方式的变化而是整个技术决策链条的变化。1.1 什么业务真正需要私有化部署从这次深圳公司的需求来看他们选择 GLM-5.2 私有化核心原因有三条。第一是数据合规。他们业务的业务数据包含大量客户合同、内部研发文档和运营报表这些数据如果通过公共 API 传给外部模型服务在合规审计上是有风险的。私有化部署后数据从采集、存储到推理都在企业内部完成合规边界清晰。第二是成本结构。业务量上来之后按 token 计费的公共 API 成本增长非常快。私有化部署更像固定资产投入GPU 服务器采购或租用、软件授权、运维人力是主要成本边际调用成本趋近于电费和硬件损耗。对于调用量稳定的场景私有化在长期成本上更有优势。第三是版本和服务稳定性。公共 API 背后是服务商统一维护的模型版本企业无法控制升级节奏。私有化以后模型版本、推理参数、量化方式都由企业自己决定可以锁定在一个经过验证的版本上避免上游更新带来的回归问题。1.2 哪些场景其实不适合私有化话说回来私有化部署不是万能解药。如果公司只是做内部小批量试验、需求方不确定、调用量很低那直接使用公共 API 的成本和交付周期都更优。私有化部署需要专业运维能力来撑住 GPU 驱动、容器编排、模型推理调优和故障恢复这套体系对团队的要求比想象中高。换句话说私有化部署省的是调用费花的是运维费和硬件费决策前要把这笔账算清楚。另一个容易被忽略的点是模型权重获取本身有门槛。智谱 GLM 系列的商用授权需要通过官方渠道申请拿到权重文件之后还要签署相关协议。部署之前务必确认授权范围避免在合规上踩坑。1.3 这次部署的整体思路明确了需求和边界之后我们把整个私有化部署拆成了四个层次基础设施层GPU 服务器、操作系统、NVIDIA 驱动、容器运行时。模型推理层通过 vLLM 这类推理框架加载 GLM-5.2 权重提供兼容 OpenAI 格式的推理接口。应用编排层部署 Dify用来搭建 Agent、知识库问答、工作流等应用。业务集成层打通 OnlyOffice 文档服务、企业 OA/IM、内部系统 API。下面按这个层次逐步展开。2. GLM-5.2 私有化部署的核心概念与总体架构在写部署命令之前先花一点时间把架构和概念说清楚。很多部署问题本质上是对架构理解不到位导致的。2.1 这些概念先分清模型权重训练完成后得到的参数文件是模型知识的载体。GLM-5.2 的权重文件通常有几个 GB 到几十 GB具体大小以官方模型卡为准。推理时必须先加载权重。推理引擎负责把权重加载到 GPU 显存里并对外提供推理服务的程序。常见的有 vLLM、SGLang、TGI 等。vLLM 因为吞吐高、兼容 OpenAI API 格式是企业私有化部署的主流选择。应用编排平台Dify 是典型的 LLMOps 平台提供可视化的工作流编排、知识库、Prompt 管理、Agent 能力。它本身不跑模型而是对接各种模型服务。文档服务OnlyOffice Document Server 是开源的在线文档编辑服务支持 Word、Excel、PPT 预览和协同编辑。在私有化场景里它可以和大模型结合做文档解析、摘要、问答。反向代理Nginx 一类的网关统一入口地址做 HTTPS 终止、负载均衡和简单的接口鉴权。2.2 总体架构图部署完成后整个系统的调用链路是这样的客户端Web/App- Nginx 反向代理 - Dify 应用编排平台 - vLLM 推理服务 - GPU 显存中的 GLM-5.2 模型同时Dify 内部的知识库模块依赖向量数据库如 pgvector 或 Milvus文档类业务调用 OnlyOffice Document Server 进行在线预览和编辑。2.3 为什么用 vLLM 而不是直接用官方脚本智谱官方提供的部署方式可能有多种但从可维护性角度我们选择了 vLLM。原因有三个第一vLLM 的 OpenAI 兼容接口非常成熟Dify、LangChain 等生态可以直接对接不需要写自定义适配层。第二vLLM 的 PagedAttention 显存管理机制能显著提升吞吐高并发场景下收益明显。第三vLLM 社区活跃遇到问题容易找到排查思路。需要注意具体启动参数要匹配 GLM-5.2 的官方模型卡推荐配置。不同版本的模型对tensor-parallel-size、量化方式、上下文窗口长度的要求可能有差异部署前务必阅读官方文档。3. 环境准备与硬件评估环境准备是整个部署过程中最容易出问题、也最容易被轻视的环节。深圳公司这次准备了两台 GPU 服务器我们花了整整一个下午处理驱动和容器环境的兼容问题。先把清单列出来。3.1 硬件与环境清单项目建议说明GPU根据模型参数量选择以官方模型卡要求为准企业级建议 A100/H800/4090 等CPU32 核以上影响数据预处理和并发调度内存128 GB 起步加载权重和进程运行都需要内存系统盘500 GB SSD用于系统和容器数据盘2 TB 以上 NVMe存放模型权重和 Dify 数据操作系统Ubuntu 22.04 LTS驱动和内核兼容性较好容器运行时Docker NVIDIA Container Toolkit让容器访问 GPU网络内网千兆以上模型分发、推理请求传输这里要提醒GPU 显存大小决定了能否加载整个模型。如果显存不够可以考虑量化版本或减小tensor-parallel-size但精度会有损失。具体的最低显存要求必须以 GLM-5.2 官方部署文档为准不要凭经验猜测。3.2 NVIDIA 驱动与容器环境安装新到的 GPU 服务器第一步是安装 NVIDIA 驱动和 CUDA。驱动版本要和 GPU 型号匹配建议直接在 NVIDIA 官网查询对应版本。安装完成后用下面命令验证nvidia-smi如果能看到 GPU 型号、显存大小和驱动版本说明驱动正常。接着安装 Docker 和 NVIDIA Container Toolkit# 添加 NVIDIA Container Toolkit 源并安装 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit # 重启 Docker sudo systemctl restart docker验证容器能否访问 GPUdocker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi只要容器内也能输出 GPU 信息环境准备就算完成。这里最容易踩的坑是宿主机的 NVIDIA 驱动版本和容器内 CUDA 镜像版本不匹配所以建议先做这个最小验证再继续往下走。4. 模型权重的获取与校验环境就绪之后进入模型权重的获取环节。这一步看似简单其实包含了授权确认、下载、校验三个动作。4.1 授权确认智谱 GLM 系列模型的商用私有化部署需要先确认授权状态。一般流程是向官方提交申请 - 签署商用协议 - 获取模型权重下载权限。没有授权就自行下载使用存在合规风险这一点务必提前确认。4.2 下载模型权重权重文件通常会放在官方指定的下载渠道。以 ModelScope 为例如果模型已经发布到 ModelScope可以用下面的方式拉取# 安装 modelscope pip install modelscope # 下载模型到本地目录 modelscope download --model ZhipuAI/GLM-5.2 --local_dir /data/models/GLM-5.2GLM-5.2 的权重文件比较大如果下载中断建议使用支持断点续传的工具或者直接检查官方是否提供了 OSS 下载地址。下载完成后记录权重目录路径后面推理服务要用。4.3 文件完整性校验大文件下载容易损坏强烈建议下载后做一次完整性校验。官方一般会提供 sha256 校验值。校验命令如下find /data/models/GLM-5.2 -type f -exec sha256sum {} \; checksums.txt # 将输出与官方校验值对比确认一致这一步容易被跳过但如果权重文件损坏推理服务启动时会报各种奇怪的错误排查成本远高于校验成本。5. 核心部署基于 Docker Compose 的推理服务搭建下面进入核心实操。我们用 Docker Compose 把推理服务、Dify、OnlyOffice 编排到一起。为了保持篇幅可控我先从推理服务开始再展示整体编排文件。5.1 编写推理服务部署配置在服务器上创建/opt/llm-deploy目录编写docker-compose.yml。# 文件路径/opt/llm-deploy/docker-compose.yml version: 3.8 services: glm-inference: image: vllm/vllm-openai:latest container_name: glm-inference command: --model /data/models/GLM-5.2 --served-model-name glm-5.2 --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 --gpu-memory-utilization 0.90 --max-model-len 32768 volumes: - /data/models:/data/models ports: - 8000:8000 environment: - HF_HOME/data/models/hf_cache deploy: resources: reservations: devices: - driver: nvidia count: 2 capabilities: [gpu] restart: unless-stopped logging: driver: json-file options: max-size: 100m max-file: 3关键参数说明--served-model-name对外暴露的模型名称Dify 对接时要用到。--tensor-parallel-size使用几张 GPU 并行推理。如果只有一张 GPU设为 1。--gpu-memory-utilization限制显存使用比例建议 0.85 到 0.95留出余量给 KV Cache。--max-model-len上下文最大长度要根据模型支持的窗口大小和显存来调整设得过大容易 OOM。启动命令docker compose up -d glm-inference docker logs -f glm-inference看到日志中出现类似Starting vLLM API server的信息说明推理服务启动成功。5.2 用 curl 验证推理接口vLLM 提供 OpenAI 兼容接口最小验证命令如下curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: glm-5.2, messages: [ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 请用一句话介绍深圳这座城市。} ], temperature: 0.7 }正常响应中会包含content字段和usage字段。usage里的total_tokens能帮助判断上下文长度是否接近上限。5.3 推理服务问题快速定位如果接口报错优先检查三个方向模型名称是否匹配model字段必须和--served-model-name一致。显存是否溢出用nvidia-smi观察显存占用如果接近 100% 且日志出现CUDA out of memory需要调低--max-model-len或--gpu-memory-utilization。端口是否被占用用ss -lntp | grep 8000检查。推理服务稳定之后再把它接入应用编排层。6. 接入 Dify 与 OnlyOffice从模型能力到业务应用模型推理服务跑通只是第一步。企业真正需要用上的是能回答业务问题的智能应用所以还要把模型接入 Dify并打通 OnlyOffice 文档服务。6.1 Dify 私有化部署Dify 本身也有完善的私有化部署方案。我们把它部署在应用服务器上和推理服务放在同一内网。# 文件路径/opt/dify/docker-compose.yml仅展示核心服务完整版参考官方仓库 services: dify-api: image: langgenius/dify-api:latest container_name: dify-api restart: unless-stopped environment: MODE: api SECRET_KEY: your-secret-key-here DB_HOST: postgres DB_PORT: 5432 DB_USERNAME: dify DB_PASSWORD: your-db-password DB_DATABASE: dify REDIS_HOST: redis REDIS_PORT: 6379 # 其他配置项以官方 .env 为准 ports: - 5001:5001 depends_on: - postgres - redis postgres: image: postgres:15-alpine environment: POSTGRES_USER: dify POSTGRES_PASSWORD: your-db-password POSTGRES_DB: dify volumes: - dify-postgres-data:/var/lib/postgresql/data redis: image: redis:7-alpine volumes: - dify-redis-data:/data volumes: dify-postgres-data: dify-redis-data:Dify 官方仓库提供了完整的 docker-compose 文件包含 API、Worker、Web、PostgreSQL、Redis、向量数据库等组件。生产环境别自己手写精简版直接基于官方模板改环境变量更稳妥。启动后访问 Dify Web 界面首次进入会要求设置管理员账号。6.2 在 Dify 中配置 GLM-5.2 模型进入 Dify 控制台在设置 - 模型供应商中选择OpenAI-API-compatible类型填入API Base URLhttp://推理服务器内网IP:8000/v1API Key可以填任意值因为 vLLM 默认不校验但生产环境建议在 Nginx 层加入鉴权。Model Nameglm-5.2保存后在创建应用时选择该模型就可以在 Dify 里搭建知识库问答、Agent 工作流、对话应用了。这个环节我们花的时间最多因为知识库的文档解析效果直接决定了问答质量。6.3 集成 OnlyOffice 文档服务企业内部知识和业务文档很多是 Word、Excel、PPT 格式。要让 Dify 知识库能解析这些文件除了 Dify 自带的文档加载器很多场景还需要在线预览和协同编辑能力这里就用到 OnlyOffice Document Server。# 文件路径/opt/onlyoffice/docker-compose.yml version: 3.8 services: onlyoffice-document-server: image: onlyoffice/documentserver:latest container_name: onlyoffice-docserver ports: - 8080:80 environment: - JWT_ENABLEDtrue - JWT_SECRETyour-jwt-secret-here volumes: - onlyoffice-data:/var/www/onlyoffice/Data - onlyoffice-logs:/var/log/onlyoffice restart: unless-stopped volumes: onlyoffice-data: onlyoffice-logs:启动后访问http://服务器IP:8080能打开欢迎页即部署成功。在私有化场景中OnlyOffice 常见的使用方式有两种第一种是作为文档预览和编辑服务嵌入到企业的 OA 或知识管理系统中。当用户打开一份合同或技术文档时前端调用 OnlyOffice API把文档渲染在浏览器里进行在线编辑。第二种是与大模型工作流配合先用 OnlyOffice 打开文档再把文档内容交给大模型进行摘要、校对、翻译或合同条款提取。这样可以做到人审 AI 辅助的业务闭环。6.4 用 Python 脚本验证完整链路为了确认大模型和 Dify 这条链路真正打通可以写一个简单的 Python 测试脚本直接调用 vLLM 接口# 文件路径/opt/llm-deploy/test_chat.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelglm-5.2, messages[ {role: system, content: 你是一个严谨的技术助手。}, {role: user, content: 请解释一下大模型私有化部署和公有云 API 调用的区别。}, ], temperature0.3, max_tokens512, ) print(response.choices[0].message.content)运行pip install openai python test_chat.py如果能正常输出回答说明推理服务可用接下来可以放心在 Dify 中配置应用。7. 功能验证与性能评估部署完成不代表上线完成。我们用了半天时间做功能验证和压测这步能暴露大量问题。7.1 功能验证清单验证项方法预期结果推理服务健康curl 接口返回 200正常返回 JSON 响应并发稳定性使用hey或ab压测错误率低于 1%长文本支持输入 8000 字中文文档不报上下文超限错误知识库问答上传 PDF/Word 后提问答案包含文档关键信息OnlyOffice 在线预览打开 Word 文件浏览器正常渲染权限隔离未授权用户访问接口请求被拒绝或超时7.2 一个简单的并发压测示例用hey做 100 个并发请求、总计 1000 个请求的压测hey -n 1000 -c 100 \ -m POST \ -H Content-Type: application/json \ -d {model:glm-5.2,messages:[{role:user,content:你好}],max_tokens:100} \ http://localhost:8000/v1/chat/completions观察输出中的Requests/sec和Error distribution。如果错误率偏高优先检查 GPU 显存是否打满、tensor-parallel-size是否合理、网络带宽是否有瓶颈。7.3 运行结果如何判断判断标准的优先级是先正确再性能。在功能正确的前提下再看首 token 延迟TTFT和生成速度tokens/s。不同硬件条件下差异很大不要拿别人的 Benchmark 数字硬套应该以自己环境测出的基线为准并记录下来用于后续调优对比。如果压测失败第一步看推理服务日志第二步看 GPU 显存和温度第三步看 Dify 侧日志。按照这个顺序排查大多数问题都能定位。8. 常见问题与排查思路把这次部署中实际遇到的高频问题整理成了表格按现象分类。问题现象可能原因排查方式解决方案容器内看不到 GPUNVIDIA Container Toolkit 未安装或 Docker 未重启执行docker run --rm --gpus all ubuntu nvidia-smi安装 nvidia-container-toolkit 并重启 DockervLLM 启动报 CUDA OOMmax-model-len或gpu-memory-utilization设置过大查看日志中显存使用估算调低参数或增加 GPU 数量接口返回 404model名称与served-model-name不一致对比 curl 请求体中的 model 字段统一模型名称中文回答质量差未使用正确的 System Prompt 或温度过高检查 Prompt 和 temperature 参数针对业务场景调试 PromptDify 测试报连接超时推理服务地址不可达或防火墙拦截curl http://推理IP:8000/v1/models开放内网端口或检查网络策略OnlyOffice 页面打不开Docker 端口映射错误或 JWT 配置问题docker logs查看日志检查端口和 JWT_SECRET 一致性服务重启后模型重新加载很慢权重未做缓存或磁盘读取慢查看启动耗时使用 NVMe 磁盘必要时预加载压测时出现大量超时GPU 资源不足或并发设置过高查看 GPU 利用率和日志降低并发或扩展 GPU 节点9. 生产环境最佳实践与工程建议9.1 安全与权限私有化部署最容易犯的错误是把推理服务直接暴露到公网。我们这次把推理服务放在内网只开放 Dify 和 OnlyOffice 的对外入口并在 Nginx 层做了 HTTPS 终止和基础鉴权。即便在内网也建议通过 API Key 或网关鉴权限制推理接口的访问范围。模型本身有生成有害内容的可能性所以生产环境必须在 Dify 里配置内容审核机制对输入输出做一轮安全过滤。不要觉得私有化部署就没有风险内部的滥用同样需要管控。9.2 数据与版本管理模型权重大文件要放在独立数据盘不要塞进系统盘。建议保留至少一份原始版本备份方便回滚。推理服务、Dify、OnlyOffice 的镜像都要固定版本不要使用latest标签长期运行避免上游更新带来不可控变化。Dify 的数据库和 OnlyOffice 的数据卷都要配置定期备份。备份策略落实到 cron 任务并且每月做一次恢复演练确保备份真的能用。9.3 监控与告警生产环境需要建立监控体系GPU 监控nvidia-smi定期采集显存使用率、温度、功耗。服务监控用 Prometheus Grafana 采集推理服务的延迟、吞吐、错误率。日志聚合Docker json-file 日志切割后接入 ELK 或 Loki。告警阈值建议设置为GPU 显存使用率超过 95% 持续 5 分钟、推理错误率超过 2%、服务进程退出。监控的意义不是出问题后看数据而是在出问题前先收到预警。9.4 团队协作与文档沉淀私有化部署不是一次性的项目后续还有模型升级、业务接入、调优迭代。建议把部署架构、配置清单、故障排查手册沉淀成团队文档。凡是配置过的地方都记录当时为什么这样选避免后人盲目改配置。同时建立变更审批机制任何涉及推理服务参数、Dify 应用、环境依赖的变更先在测试环境验证再走上线流程。这次部署后期我们改过两次max-model-len参数都是先在测试服务器验证后才同步到生产环境。10. 总结与后续实践建议这次深圳公司的 GLM-5.2 私有化部署核心收获可以浓缩成三句话第一私有化部署的价值不在拥有模型而在掌控能力。数据不出域、版本可锁定、成本可预测这些都是公共 API 给不了的。第二推理服务只是底座应用编排和业务集成才是真正产生价值的地方。Dify 负责降低应用开发门槛OnlyOffice 负责解决文档场景的落地问题三者组合起来才是一个完整的私有化智能平台。第三部署上线只是开始监控、备份、调优、安全治理才是长期工作。建议团队在完成部署后用一周时间跑通知识库问答、文档处理、Agent 工作流三个典型场景把性能和效果基线记录下来后续迭代才有参照。如果你也准备做类似项目下一步建议按顺序做三件事确认 GLM-5.2 的授权与模型卡要求用最小环境跑通 vLLM 推理接口再接入 Dify 做第一个真实业务应用。先把链路跑通再逐步完善监控和安全体系。这条路走通之后大模型就不再是演示项目而是真正可以承载业务的基础设施了。 大模型私有化部署全流程：GLM-5.2 + vLLM + Dify 企业落地实践
最近这两年里很多企业做 AI 应用时都卡在同一个环节模型能力已经验证过了API 调用也跑通了但真正要放进生产环境时就发现数据安全、成本上限、版本迭代和响应延迟这些问题光靠公共 API 解决不了。我前阵子帮深圳一家科技公司做智谱 GLM-5.2 的私有化部署从需求沟通到上线验证完整走完了一轮大模型落地的闭环。整个过程里最深的感受是私有化部署这件事难点从来不在把模型权重下载到服务器上而在于如何用一套稳定、可维护、可扩展的架构把大模型真正接入业务系统。这篇文章不打算只贴安装命令而是结合这次部署实践把私有化部署的完整路径拆开讲清楚哪些业务适合私有化部署、硬件和算力怎么评估、推理服务怎么起、Dify 这类应用编排平台怎么接、OnlyOffice 这类办公文档服务怎么打通以及上线之后怎么验证、怎么排错。如果你正在评估公司是否要做大模型私有化或者已经拿到 GLM-5.2 的授权但不知道从哪儿下手这篇文章应该能帮你省掉不少试错成本。1. 私有化部署之前先想清楚这几件事很多人一听到私有化部署第一反应是把模型放到自己的服务器上跑起来。这个理解没有错但太表面了。真正的私有化部署是把大模型从按量付费的外部服务变成可以自主掌控的内部基础设施这个转变带来的不只是部署方式的变化而是整个技术决策链条的变化。1.1 什么业务真正需要私有化部署从这次深圳公司的需求来看他们选择 GLM-5.2 私有化核心原因有三条。第一是数据合规。他们业务的业务数据包含大量客户合同、内部研发文档和运营报表这些数据如果通过公共 API 传给外部模型服务在合规审计上是有风险的。私有化部署后数据从采集、存储到推理都在企业内部完成合规边界清晰。第二是成本结构。业务量上来之后按 token 计费的公共 API 成本增长非常快。私有化部署更像固定资产投入GPU 服务器采购或租用、软件授权、运维人力是主要成本边际调用成本趋近于电费和硬件损耗。对于调用量稳定的场景私有化在长期成本上更有优势。第三是版本和服务稳定性。公共 API 背后是服务商统一维护的模型版本企业无法控制升级节奏。私有化以后模型版本、推理参数、量化方式都由企业自己决定可以锁定在一个经过验证的版本上避免上游更新带来的回归问题。1.2 哪些场景其实不适合私有化话说回来私有化部署不是万能解药。如果公司只是做内部小批量试验、需求方不确定、调用量很低那直接使用公共 API 的成本和交付周期都更优。私有化部署需要专业运维能力来撑住 GPU 驱动、容器编排、模型推理调优和故障恢复这套体系对团队的要求比想象中高。换句话说私有化部署省的是调用费花的是运维费和硬件费决策前要把这笔账算清楚。另一个容易被忽略的点是模型权重获取本身有门槛。智谱 GLM 系列的商用授权需要通过官方渠道申请拿到权重文件之后还要签署相关协议。部署之前务必确认授权范围避免在合规上踩坑。1.3 这次部署的整体思路明确了需求和边界之后我们把整个私有化部署拆成了四个层次基础设施层GPU 服务器、操作系统、NVIDIA 驱动、容器运行时。模型推理层通过 vLLM 这类推理框架加载 GLM-5.2 权重提供兼容 OpenAI 格式的推理接口。应用编排层部署 Dify用来搭建 Agent、知识库问答、工作流等应用。业务集成层打通 OnlyOffice 文档服务、企业 OA/IM、内部系统 API。下面按这个层次逐步展开。2. GLM-5.2 私有化部署的核心概念与总体架构在写部署命令之前先花一点时间把架构和概念说清楚。很多部署问题本质上是对架构理解不到位导致的。2.1 这些概念先分清模型权重训练完成后得到的参数文件是模型知识的载体。GLM-5.2 的权重文件通常有几个 GB 到几十 GB具体大小以官方模型卡为准。推理时必须先加载权重。推理引擎负责把权重加载到 GPU 显存里并对外提供推理服务的程序。常见的有 vLLM、SGLang、TGI 等。vLLM 因为吞吐高、兼容 OpenAI API 格式是企业私有化部署的主流选择。应用编排平台Dify 是典型的 LLMOps 平台提供可视化的工作流编排、知识库、Prompt 管理、Agent 能力。它本身不跑模型而是对接各种模型服务。文档服务OnlyOffice Document Server 是开源的在线文档编辑服务支持 Word、Excel、PPT 预览和协同编辑。在私有化场景里它可以和大模型结合做文档解析、摘要、问答。反向代理Nginx 一类的网关统一入口地址做 HTTPS 终止、负载均衡和简单的接口鉴权。2.2 总体架构图部署完成后整个系统的调用链路是这样的客户端Web/App- Nginx 反向代理 - Dify 应用编排平台 - vLLM 推理服务 - GPU 显存中的 GLM-5.2 模型同时Dify 内部的知识库模块依赖向量数据库如 pgvector 或 Milvus文档类业务调用 OnlyOffice Document Server 进行在线预览和编辑。2.3 为什么用 vLLM 而不是直接用官方脚本智谱官方提供的部署方式可能有多种但从可维护性角度我们选择了 vLLM。原因有三个第一vLLM 的 OpenAI 兼容接口非常成熟Dify、LangChain 等生态可以直接对接不需要写自定义适配层。第二vLLM 的 PagedAttention 显存管理机制能显著提升吞吐高并发场景下收益明显。第三vLLM 社区活跃遇到问题容易找到排查思路。需要注意具体启动参数要匹配 GLM-5.2 的官方模型卡推荐配置。不同版本的模型对tensor-parallel-size、量化方式、上下文窗口长度的要求可能有差异部署前务必阅读官方文档。3. 环境准备与硬件评估环境准备是整个部署过程中最容易出问题、也最容易被轻视的环节。深圳公司这次准备了两台 GPU 服务器我们花了整整一个下午处理驱动和容器环境的兼容问题。先把清单列出来。3.1 硬件与环境清单项目建议说明GPU根据模型参数量选择以官方模型卡要求为准企业级建议 A100/H800/4090 等CPU32 核以上影响数据预处理和并发调度内存128 GB 起步加载权重和进程运行都需要内存系统盘500 GB SSD用于系统和容器数据盘2 TB 以上 NVMe存放模型权重和 Dify 数据操作系统Ubuntu 22.04 LTS驱动和内核兼容性较好容器运行时Docker NVIDIA Container Toolkit让容器访问 GPU网络内网千兆以上模型分发、推理请求传输这里要提醒GPU 显存大小决定了能否加载整个模型。如果显存不够可以考虑量化版本或减小tensor-parallel-size但精度会有损失。具体的最低显存要求必须以 GLM-5.2 官方部署文档为准不要凭经验猜测。3.2 NVIDIA 驱动与容器环境安装新到的 GPU 服务器第一步是安装 NVIDIA 驱动和 CUDA。驱动版本要和 GPU 型号匹配建议直接在 NVIDIA 官网查询对应版本。安装完成后用下面命令验证nvidia-smi如果能看到 GPU 型号、显存大小和驱动版本说明驱动正常。接着安装 Docker 和 NVIDIA Container Toolkit# 添加 NVIDIA Container Toolkit 源并安装 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit # 重启 Docker sudo systemctl restart docker验证容器能否访问 GPUdocker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi只要容器内也能输出 GPU 信息环境准备就算完成。这里最容易踩的坑是宿主机的 NVIDIA 驱动版本和容器内 CUDA 镜像版本不匹配所以建议先做这个最小验证再继续往下走。4. 模型权重的获取与校验环境就绪之后进入模型权重的获取环节。这一步看似简单其实包含了授权确认、下载、校验三个动作。4.1 授权确认智谱 GLM 系列模型的商用私有化部署需要先确认授权状态。一般流程是向官方提交申请 - 签署商用协议 - 获取模型权重下载权限。没有授权就自行下载使用存在合规风险这一点务必提前确认。4.2 下载模型权重权重文件通常会放在官方指定的下载渠道。以 ModelScope 为例如果模型已经发布到 ModelScope可以用下面的方式拉取# 安装 modelscope pip install modelscope # 下载模型到本地目录 modelscope download --model ZhipuAI/GLM-5.2 --local_dir /data/models/GLM-5.2GLM-5.2 的权重文件比较大如果下载中断建议使用支持断点续传的工具或者直接检查官方是否提供了 OSS 下载地址。下载完成后记录权重目录路径后面推理服务要用。4.3 文件完整性校验大文件下载容易损坏强烈建议下载后做一次完整性校验。官方一般会提供 sha256 校验值。校验命令如下find /data/models/GLM-5.2 -type f -exec sha256sum {} \; checksums.txt # 将输出与官方校验值对比确认一致这一步容易被跳过但如果权重文件损坏推理服务启动时会报各种奇怪的错误排查成本远高于校验成本。5. 核心部署基于 Docker Compose 的推理服务搭建下面进入核心实操。我们用 Docker Compose 把推理服务、Dify、OnlyOffice 编排到一起。为了保持篇幅可控我先从推理服务开始再展示整体编排文件。5.1 编写推理服务部署配置在服务器上创建/opt/llm-deploy目录编写docker-compose.yml。# 文件路径/opt/llm-deploy/docker-compose.yml version: 3.8 services: glm-inference: image: vllm/vllm-openai:latest container_name: glm-inference command: --model /data/models/GLM-5.2 --served-model-name glm-5.2 --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 --gpu-memory-utilization 0.90 --max-model-len 32768 volumes: - /data/models:/data/models ports: - 8000:8000 environment: - HF_HOME/data/models/hf_cache deploy: resources: reservations: devices: - driver: nvidia count: 2 capabilities: [gpu] restart: unless-stopped logging: driver: json-file options: max-size: 100m max-file: 3关键参数说明--served-model-name对外暴露的模型名称Dify 对接时要用到。--tensor-parallel-size使用几张 GPU 并行推理。如果只有一张 GPU设为 1。--gpu-memory-utilization限制显存使用比例建议 0.85 到 0.95留出余量给 KV Cache。--max-model-len上下文最大长度要根据模型支持的窗口大小和显存来调整设得过大容易 OOM。启动命令docker compose up -d glm-inference docker logs -f glm-inference看到日志中出现类似Starting vLLM API server的信息说明推理服务启动成功。5.2 用 curl 验证推理接口vLLM 提供 OpenAI 兼容接口最小验证命令如下curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: glm-5.2, messages: [ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 请用一句话介绍深圳这座城市。} ], temperature: 0.7 }正常响应中会包含content字段和usage字段。usage里的total_tokens能帮助判断上下文长度是否接近上限。5.3 推理服务问题快速定位如果接口报错优先检查三个方向模型名称是否匹配model字段必须和--served-model-name一致。显存是否溢出用nvidia-smi观察显存占用如果接近 100% 且日志出现CUDA out of memory需要调低--max-model-len或--gpu-memory-utilization。端口是否被占用用ss -lntp | grep 8000检查。推理服务稳定之后再把它接入应用编排层。6. 接入 Dify 与 OnlyOffice从模型能力到业务应用模型推理服务跑通只是第一步。企业真正需要用上的是能回答业务问题的智能应用所以还要把模型接入 Dify并打通 OnlyOffice 文档服务。6.1 Dify 私有化部署Dify 本身也有完善的私有化部署方案。我们把它部署在应用服务器上和推理服务放在同一内网。# 文件路径/opt/dify/docker-compose.yml仅展示核心服务完整版参考官方仓库 services: dify-api: image: langgenius/dify-api:latest container_name: dify-api restart: unless-stopped environment: MODE: api SECRET_KEY: your-secret-key-here DB_HOST: postgres DB_PORT: 5432 DB_USERNAME: dify DB_PASSWORD: your-db-password DB_DATABASE: dify REDIS_HOST: redis REDIS_PORT: 6379 # 其他配置项以官方 .env 为准 ports: - 5001:5001 depends_on: - postgres - redis postgres: image: postgres:15-alpine environment: POSTGRES_USER: dify POSTGRES_PASSWORD: your-db-password POSTGRES_DB: dify volumes: - dify-postgres-data:/var/lib/postgresql/data redis: image: redis:7-alpine volumes: - dify-redis-data:/data volumes: dify-postgres-data: dify-redis-data:Dify 官方仓库提供了完整的 docker-compose 文件包含 API、Worker、Web、PostgreSQL、Redis、向量数据库等组件。生产环境别自己手写精简版直接基于官方模板改环境变量更稳妥。启动后访问 Dify Web 界面首次进入会要求设置管理员账号。6.2 在 Dify 中配置 GLM-5.2 模型进入 Dify 控制台在设置 - 模型供应商中选择OpenAI-API-compatible类型填入API Base URLhttp://推理服务器内网IP:8000/v1API Key可以填任意值因为 vLLM 默认不校验但生产环境建议在 Nginx 层加入鉴权。Model Nameglm-5.2保存后在创建应用时选择该模型就可以在 Dify 里搭建知识库问答、Agent 工作流、对话应用了。这个环节我们花的时间最多因为知识库的文档解析效果直接决定了问答质量。6.3 集成 OnlyOffice 文档服务企业内部知识和业务文档很多是 Word、Excel、PPT 格式。要让 Dify 知识库能解析这些文件除了 Dify 自带的文档加载器很多场景还需要在线预览和协同编辑能力这里就用到 OnlyOffice Document Server。# 文件路径/opt/onlyoffice/docker-compose.yml version: 3.8 services: onlyoffice-document-server: image: onlyoffice/documentserver:latest container_name: onlyoffice-docserver ports: - 8080:80 environment: - JWT_ENABLEDtrue - JWT_SECRETyour-jwt-secret-here volumes: - onlyoffice-data:/var/www/onlyoffice/Data - onlyoffice-logs:/var/log/onlyoffice restart: unless-stopped volumes: onlyoffice-data: onlyoffice-logs:启动后访问http://服务器IP:8080能打开欢迎页即部署成功。在私有化场景中OnlyOffice 常见的使用方式有两种第一种是作为文档预览和编辑服务嵌入到企业的 OA 或知识管理系统中。当用户打开一份合同或技术文档时前端调用 OnlyOffice API把文档渲染在浏览器里进行在线编辑。第二种是与大模型工作流配合先用 OnlyOffice 打开文档再把文档内容交给大模型进行摘要、校对、翻译或合同条款提取。这样可以做到人审 AI 辅助的业务闭环。6.4 用 Python 脚本验证完整链路为了确认大模型和 Dify 这条链路真正打通可以写一个简单的 Python 测试脚本直接调用 vLLM 接口# 文件路径/opt/llm-deploy/test_chat.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) response client.chat.completions.create( modelglm-5.2, messages[ {role: system, content: 你是一个严谨的技术助手。}, {role: user, content: 请解释一下大模型私有化部署和公有云 API 调用的区别。}, ], temperature0.3, max_tokens512, ) print(response.choices[0].message.content)运行pip install openai python test_chat.py如果能正常输出回答说明推理服务可用接下来可以放心在 Dify 中配置应用。7. 功能验证与性能评估部署完成不代表上线完成。我们用了半天时间做功能验证和压测这步能暴露大量问题。7.1 功能验证清单验证项方法预期结果推理服务健康curl 接口返回 200正常返回 JSON 响应并发稳定性使用hey或ab压测错误率低于 1%长文本支持输入 8000 字中文文档不报上下文超限错误知识库问答上传 PDF/Word 后提问答案包含文档关键信息OnlyOffice 在线预览打开 Word 文件浏览器正常渲染权限隔离未授权用户访问接口请求被拒绝或超时7.2 一个简单的并发压测示例用hey做 100 个并发请求、总计 1000 个请求的压测hey -n 1000 -c 100 \ -m POST \ -H Content-Type: application/json \ -d {model:glm-5.2,messages:[{role:user,content:你好}],max_tokens:100} \ http://localhost:8000/v1/chat/completions观察输出中的Requests/sec和Error distribution。如果错误率偏高优先检查 GPU 显存是否打满、tensor-parallel-size是否合理、网络带宽是否有瓶颈。7.3 运行结果如何判断判断标准的优先级是先正确再性能。在功能正确的前提下再看首 token 延迟TTFT和生成速度tokens/s。不同硬件条件下差异很大不要拿别人的 Benchmark 数字硬套应该以自己环境测出的基线为准并记录下来用于后续调优对比。如果压测失败第一步看推理服务日志第二步看 GPU 显存和温度第三步看 Dify 侧日志。按照这个顺序排查大多数问题都能定位。8. 常见问题与排查思路把这次部署中实际遇到的高频问题整理成了表格按现象分类。问题现象可能原因排查方式解决方案容器内看不到 GPUNVIDIA Container Toolkit 未安装或 Docker 未重启执行docker run --rm --gpus all ubuntu nvidia-smi安装 nvidia-container-toolkit 并重启 DockervLLM 启动报 CUDA OOMmax-model-len或gpu-memory-utilization设置过大查看日志中显存使用估算调低参数或增加 GPU 数量接口返回 404model名称与served-model-name不一致对比 curl 请求体中的 model 字段统一模型名称中文回答质量差未使用正确的 System Prompt 或温度过高检查 Prompt 和 temperature 参数针对业务场景调试 PromptDify 测试报连接超时推理服务地址不可达或防火墙拦截curl http://推理IP:8000/v1/models开放内网端口或检查网络策略OnlyOffice 页面打不开Docker 端口映射错误或 JWT 配置问题docker logs查看日志检查端口和 JWT_SECRET 一致性服务重启后模型重新加载很慢权重未做缓存或磁盘读取慢查看启动耗时使用 NVMe 磁盘必要时预加载压测时出现大量超时GPU 资源不足或并发设置过高查看 GPU 利用率和日志降低并发或扩展 GPU 节点9. 生产环境最佳实践与工程建议9.1 安全与权限私有化部署最容易犯的错误是把推理服务直接暴露到公网。我们这次把推理服务放在内网只开放 Dify 和 OnlyOffice 的对外入口并在 Nginx 层做了 HTTPS 终止和基础鉴权。即便在内网也建议通过 API Key 或网关鉴权限制推理接口的访问范围。模型本身有生成有害内容的可能性所以生产环境必须在 Dify 里配置内容审核机制对输入输出做一轮安全过滤。不要觉得私有化部署就没有风险内部的滥用同样需要管控。9.2 数据与版本管理模型权重大文件要放在独立数据盘不要塞进系统盘。建议保留至少一份原始版本备份方便回滚。推理服务、Dify、OnlyOffice 的镜像都要固定版本不要使用latest标签长期运行避免上游更新带来不可控变化。Dify 的数据库和 OnlyOffice 的数据卷都要配置定期备份。备份策略落实到 cron 任务并且每月做一次恢复演练确保备份真的能用。9.3 监控与告警生产环境需要建立监控体系GPU 监控nvidia-smi定期采集显存使用率、温度、功耗。服务监控用 Prometheus Grafana 采集推理服务的延迟、吞吐、错误率。日志聚合Docker json-file 日志切割后接入 ELK 或 Loki。告警阈值建议设置为GPU 显存使用率超过 95% 持续 5 分钟、推理错误率超过 2%、服务进程退出。监控的意义不是出问题后看数据而是在出问题前先收到预警。9.4 团队协作与文档沉淀私有化部署不是一次性的项目后续还有模型升级、业务接入、调优迭代。建议把部署架构、配置清单、故障排查手册沉淀成团队文档。凡是配置过的地方都记录当时为什么这样选避免后人盲目改配置。同时建立变更审批机制任何涉及推理服务参数、Dify 应用、环境依赖的变更先在测试环境验证再走上线流程。这次部署后期我们改过两次max-model-len参数都是先在测试服务器验证后才同步到生产环境。10. 总结与后续实践建议这次深圳公司的 GLM-5.2 私有化部署核心收获可以浓缩成三句话第一私有化部署的价值不在拥有模型而在掌控能力。数据不出域、版本可锁定、成本可预测这些都是公共 API 给不了的。第二推理服务只是底座应用编排和业务集成才是真正产生价值的地方。Dify 负责降低应用开发门槛OnlyOffice 负责解决文档场景的落地问题三者组合起来才是一个完整的私有化智能平台。第三部署上线只是开始监控、备份、调优、安全治理才是长期工作。建议团队在完成部署后用一周时间跑通知识库问答、文档处理、Agent 工作流三个典型场景把性能和效果基线记录下来后续迭代才有参照。如果你也准备做类似项目下一步建议按顺序做三件事确认 GLM-5.2 的授权与模型卡要求用最小环境跑通 vLLM 推理接口再接入 Dify 做第一个真实业务应用。先把链路跑通再逐步完善监控和安全体系。这条路走通之后大模型就不再是演示项目而是真正可以承载业务的基础设施了。