章节四十四：项目部署
一、GPU模型部署（vLLM+BGE）
1.1 部署目标
用2台Linux GPU服务器承载3个本地模型服务：
- BGE-M3和bge-reranker-large部署在同一台机器上
- Qwen3-8B通过vLLM部署在另一台机器上
- 业务项目通过HTTP远程调用三个模型服务
生产环境两台模型服务器：
- 模型服务器A：运行BGE-M3（端口6006）和reranker（端口6008）
- 模型服务器B：运行Qwen3-8B vLLM（端口6006）
业务项目、Milvus、Neo4j、MongoDB、MinIO继续部署在业务服务器上。两台模型服务器只负责模型推理服务。
1.2 模板机准备
先准备一台模板机，验证阶段安装并测试三个服务。
第一步：检查GPU环境
执行nvidia-smi命令，能看到GPU、驱动版本和CUDA Version即可。
第二步：创建目录
创建工作目录/data和模型目录/data/models。
第三步：创建Python虚拟环境
创建并激活虚拟环境。如果镜像已预装PyTorch，先验证torch.cuda.is_available()是否为True。如果没有，根据服务器CUDA版本安装对应PyTorch。
第四步：安装依赖
安装vLLM、fastapi、uvicorn、transformers、FlagEmbedding等。注意：模型服务器不需要安装langchain、langgraph、neo4j等业务依赖。
1.3 准备模型文件
使用ModelScope下载模型文件到/data/models目录。
1.4 部署Qwen3-8B（vLLM服务）
启动vLLM的关键参数：served-model-name（业务项目中配置的模型名）、api-key（开启鉴权）、gpu-memory-utilization（GPU显存利用率）、max-model-len（最大上下文长度，RAG场景先用8k）、trust-remote-code（Qwen系模型建议开启）。
通过curl调用vLLM的chat/completions接口验证服务是否正常。
1.5 部署BGE-M3（hybrid embedding服务）
BGE-M3不能只用普通dense embedding替换，因为当前项目Milvus混合检索依赖dense+sparse双路召回。
使用FastAPI封装BGE-M3的hybrid embedding功能，接收文本列表，返回dense（稠密向量）和sparse（稀疏向量）两种表示。启动后通过curl验证返回结果是否同时包含两类向量。
1.6 部署reranker（重排序服务）
使用FastAPI封装bge-reranker-large，接收query+documents列表，返回每个文档与查询的相关性分数。启动后通过curl验证。
1.7 模板机联调测试
建议在克隆前做一次完整联调。如果显存允许，同时启动三个服务测试；如果显存不够，按顺序逐个验证。
验证核心目标：Python依赖可用、模型文件路径正确、服务脚本无语法错误、三个HTTP接口都能返回正确结构、端口和防火墙没问题。
1.8 克隆与正式部署
模板机验证通过后，关闭三个模型服务，克隆出新机器。
模型服务器A：正式只启动BGE-M3（端口6006）和reranker（端口6008），不启动Qwen3-8B。
模型服务器B：正式只启动Qwen3-8B（适当调高gpu-memory-utilization），不启动BGE-M3和reranker。如果启动报显存不足，优先降低max-model-len或减少并发。
1.9 改造业务项目代码
第一步：改造bge_m3_embedding_util.py，改为调用远程HTTP服务获取hybrid embedding。
第二步：改造bge_rerank_util.py，改为调用远程HTTP服务获取重排序分数。
第三步：生成新的llm_client_txt_util.py，替换原有基于阿里云模型的文本模型调用。
第四步：在本地启动业务服务测试。
二、应用服务部署
2.1 整体部署流程
当前业务主链路默认使用外部API，不强依赖GPU。导入链路依赖MinerU API、DashScope/OpenAI兼容LLM、DashScope Embedding、Milvus、Neo4j、MinIO。查询链路依赖DashScope/OpenAI兼容LLM、DashScope Embedding、DashScope Rerank、Milvus、Neo4j、MongoDB。
建议按下面顺序部署：
第一步：在本地整理代码，确保仓库已推送到Gitee。
第二步：购买腾讯云服务器，推荐Ubuntu 22.04，2核4G或4核8G，系统盘至少50GB。
第三步：安装git、docker、docker compose。
第四步：从Gitee拉取项目代码到服务器。
第五步：编写生产环境配置文件.env.prod。
第六步：基于项目编写导入服务和查询服务的Dockerfile。导入和查询服务都是Python FastAPI服务，推荐保留一份公共Dockerfile，在docker compose里通过不同command区分。
第七步：编写docker-compose.yml，统一编排：kb-import、kb-query、etcd、minio、Milvus（standalone）、mongodb、neo4j。
第八步：先启动基础中间件，再启动业务服务。
第九步：通过接口和容器日志做健康检查。
第十步：后续通过docker compose up/down/restart/logs维护服务。
2.2 中间件版本
- Milvus：milvusdb/milvus:v2.4.0
- etcd：quay.io/coreos/etcd:v3.5.0
- MinIO：minio/minio:RELEASE.2023-03-20T20-16-18Z
- MongoDB：mongo:7.0
- Neo4j：neo4j:5.15.0-community
2.3 端口建议
公网只开放：22（SSH）、8000（导入服务）、8001（查询服务）。
尽量不要直接暴露到公网：27017（MongoDB）、19530（Milvus）、2379（etcd）、9000（MinIO API）。
2.4 启停服务
首次启动：先确认基础中间件正常（docker compose ps），确认无误后再启动业务服务。
分两步启动的原因：导入服务在模块加载时会初始化MinIO客户端，如果MinIO还没准备好，minio_client可能是None。因此建议先启动MinIO再启动kb-import。
健康检查：查询服务提供/health接口；导入服务可访问页面验证；中间件通过各自方式检查。
日常维护命令：
- 停止容器：docker compose stop
- 停止并删除容器（保留数据）：docker compose down
- 重启全部：docker compose restart
- 重启单个服务：docker compose restart kb-query
- 代码更新后重新构建：git pull origin main && docker compose up -d --build