章节四十四：项目部署

一、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