013、部署篇：从本地开发到云原生（Docker/K8s）服务化部署

013、部署篇从本地开发到云原生Docker/K8s服务化部署一、从一次深夜调试说起上周三凌晨两点我被报警短信吵醒——线上RAG服务的响应时间从200ms飙到了5秒。登录服务器一看CPU跑满了内存倒是还剩不少。第一反应是向量检索模块出了问题但日志里明明显示检索耗时稳定在50ms左右。折腾了半小时才发现问题出在Python的GIL上服务同时处理了太多PDF解析请求这些CPU密集型任务把解释器锁死了连简单的文本匹配都排队等锁。本地开发时我用的是单文件测试压根没触发这个并发场景。这件事让我再次意识到RAG系统的本地原型和线上部署完全是两码事。今天我们就聊聊怎么把一个本地的RAG实验脚本一步步变成能在云上扛住真实流量的生产服务。二、本地开发阶段的“技术债”先看一个典型的本地RAG原型长什么样# rag_local.py —— 典型的本地原型问题一堆但能跑起来fromlangchain.embeddingsimportHuggingFaceEmbeddingsfromlangchain.vectorstoresimportFAISSimportpickleimportos# 1. 全局加载大模型内存杀手embeddingsHuggingFaceEmbeddings(model_nameBAAI/bge-large-zh)# 一启动就吃掉2GB# 2. 向量库直接读本地文件重启就丢ifos.path.exists(faiss_index.pkl):withopen(faiss_index.pkl,rb)asf:vector_storepickle.load(f)# 反序列化慢还容易版本不兼容else:# 全量重建索引生产环境敢这样玩docsload_all_documents()vector_storeFAISS.from_documents(docs,embeddings)# 3. 用Flask裸奔没健康检查没监控app.route(/query,methods[POST])defquery():questionrequest.json.get(question)# 直接调模型超时重试降级不存在的resultsvector_store.similarity_search(question,k3)returnjsonify({results:results})这段代码在开发阶段没问题但放到线上就是颗定时炸弹。主要问题有三个资源管理粗暴模型和向量库全塞内存多实例部署时内存重复消耗状态本地化向量索引存在本地文件容器重启就丢多副本数据不一致服务治理缺失没有熔断、限流、监控流量一来直接雪崩三、容器化改造把“环境依赖”打包带走第一步是Docker化。目标很简单让服务在任何地方跑起来的行为都一样。# Dockerfile FROM python:3.9-slim # 1. 系统依赖注意arm64和x86的包名可能不同 RUN apt-get update apt-get install -y \ gcc g libgomp1 \ # FAISS需要这些 rm -rf /var/lib/apt/lists/* # 2. 分层构建利用缓存 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt \ pip install gunicorn[gevent] # 用gevent协程比多进程省内存 # 3. 应用代码 COPY app /app WORKDIR /app # 4. 非root用户运行安全规范 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser # 5. 健康检查K8s靠这个判断容器是否存活 HEALTHCHECK --interval30s --timeout3s --start-period5s --retries3 \ CMD python -c import requests; requests.get(http://localhost:8080/health, timeout2) # 6. 用gunicorn启动绑定0.0.0.0容器内必须这样写 CMD [gunicorn, -w, 4, -k, gevent, -b, 0.0.0.0:8080, main:app]几个踩坑点不要用latest标签生产环境必须固定基础镜像版本比如python:3.9.18-slim国内镜像加速在pip install前加阿里云或清华源不然构建能卡十分钟内存限制如果向量库很大要在docker run时加--memory4g不然容器可能被OOM Kill四、向量检索服务化把最重的部分拆出去RAG系统里最吃资源的就是向量检索。我的经验是把检索服务单独部署。# retrieval_service.py —— 专做向量检索的微服务importfaissimportnumpyasnpfromflaskimportFlask,requestimportthreading appFlask(__name__)# 全局只加载一次FAISS索引_indexNone_lockthreading.RLock()defload_index_once():global_indexif_indexisNone:with_lock:if_indexisNone:# 双重检查锁防止多线程重复加载_indexfaiss.read_index(/data/faiss_index.bin)# 从共享存储读return_indexapp.route(/search,methods[POST])defsearch():indexload_index_once()vectorrequest.json[embedding]# 假设上游已转成向量krequest.json.get(k,3)# FAISS搜索是线程安全的但返回的id要转成Python类型distances,indicesindex.search(np.array([vector]),k)# 这里有个坑FAISS返回的indices是int64json序列化会出错return{indices:indices[0].astype(int).tolist(),# 一定要转intdistances:distances[0].tolist()}这个服务可以单独扩缩容。比如QPS高了就多起几个检索实例用Nginx做负载均衡。关键优化把索引文件挂载为readOnlyMany的PVCK8s持久化卷所有副本共享同一份数据避免重复加载。五、K8s部署让服务自己管理自己容器化解决了环境一致性问题但容器本身也会挂。K8s负责管理容器的生老病死。# k8s/rag-deployment.yamlapiVersion:apps/v1kind:Deploymentmetadata:name:rag-apispec:replicas:3# 至少3个滚动更新时保证有2个可用selector:matchLabels:app:rag-apitemplate:metadata:labels:app:rag-apispec:containers:-name:mainimage:registry.company.com/rag:v1.2.3# 私有镜像仓库ports:-containerPort:8080resources:requests:memory:2Gi# 必须写调度器靠这个选择节点cpu:500m# 0.5核limits:memory:4Gi# 超过会被OOM Killcpu:2# 最多用2核env:-name:REDIS_HOST# 配置抽成环境变量valueFrom:configMapKeyRef:name:rag-configkey:redis.hostvolumeMounts:-name:index-volumemountPath:/data# 挂载共享索引readOnly:truevolumes:-name:index-volumepersistentVolumeClaim:claimName:faiss-index-pvcimagePullSecrets:-name:regcred# 拉私有镜像的密钥---# 服务暴露apiVersion:v1kind:Servicemetadata:name:rag-servicespec:selector:app:rag-apiports:-port:80targetPort:8080type:ClusterIP# 内网访问前面配Ingress或LB---# 水平自动扩缩HPAapiVersion:autoscaling/v2kind:HorizontalPodAutoscalermetadata:name:rag-hpaspec:scaleTargetRef:apiVersion:apps/v1kind:Deploymentname:rag-apiminReplicas:2maxReplicas:10metrics:-type:Resourceresource:name:cputarget:type:UtilizationaverageUtilization:70# CPU平均使用率70%时触发扩容部署顺序很重要先创建ConfigMap和Secret放数据库密码、API密钥再创建PVC持久化存储等状态变成Bound最后部署Deployment血泪教训一定要设resources.limits不然某个Pod发疯吃光节点内存整个节点上的服务全挂。六、生产环境必备的“生存装备”服务跑起来只是开始要稳定运行还得加几个关键部件1. 健康检查端点app.route(/health)defhealth():# 检查下游依赖redis_okredis_client.ping()db_okdatabase.execute(SELECT 1)# 检查自身状态index_loaded_indexisnotNoneifall([redis_ok,db_ok,index_loaded]):return{status:healthy},200else:return{status:unhealthy},503# 返回503K8s会摘掉流量2. 就绪探针Readiness Probe在K8s里配置readinessProbe:httpGet:path:/healthport:8080initialDelaySeconds:10# 给容器启动留时间periodSeconds:53. 优雅关闭importsignalimportsysdefhandle_shutdown(signum,frame):print(收到终止信号开始清理...)# 1. 先摘掉负载均衡K8s已经做了# 2. 完成正在处理的请求# 3. 关闭数据库连接vector_store.close()sys.exit(0)signal.signal(signal.SIGTERM,handle_shutdown)# K8s发SIGTERM七、一些经验之谈向量索引别放容器镜像里镜像越大部署越慢。用共享存储NFS、Ceph或对象存储S3本地缓存。模型文件同理第一次启动时从对象存储下载到本地加个MD5校验更新时直接换地址。日志统一收集容器标准输出到stdout用Filebeat或Fluentd收走别写本地文件。配置中心化数据库地址、超时时间这些放ConfigMap或Apollo改配置不用重新构建镜像。准备降级方案RAG检索超时了能不能fallback到关键词检索生成模型挂了能不能返回检索结果让前端凑合用压测要在K8s里做本地压测和线上表现差很远网络延迟、存储IO、邻居容器抢资源这些因素只有真实环境才有。最后说个反直觉的不要追求零停机更新。RAG服务依赖向量索引索引更新期间新旧版本可能返回不同结果。我们现在的做法是索引更新时新版本服务先部署但不接流量索引就绪后切50%流量到新版本观察效果没问题再全量切换旧版本保留一天备回滚部署不是把代码扔上线就完事了它是一套保证服务持续可用的系统工程。从本地开发到云原生每一步都在和不确定性做斗争。慢慢来多复盘线上不出问题是偶然出问题才是常态——关键是要有快速发现和恢复的能力。