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. 全局加载大模型（内存杀手）embeddings=HuggingFaceEmbeddings(model_name="BAAI/bge-large-zh")# 一启动就吃掉2GB# 2. 向量库直接读本地文件（重启就丢）ifos.path.exists("faiss_index.pkl"):withopen("faiss_index.pkl","rb")asf:vector_store=pickle.load(f)# 反序列化慢，还容易版本不兼容else:# 全量重建索引（生产环境敢这样玩？）docs=load_all_documents()vector_store=FAISS.from_documents(docs,embeddings)# 3. 用Flask裸奔（没健康检查，没监控）@app.route("/query",methods=["POST"])defquery():question=request.json.get("question")# 直接调模型（超时？重试？降级？不存在的）results=vector_store.similarity_search(question,k=3)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 --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD python -c "import requests; requests.get('http://localhost:8080/health', timeout=2)" # 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时加--memory=4g，不然容器可能被OOM Kill

四、向量检索服务化：把最重的部分拆出去

RAG系统里最吃资源的就是向量检索。我的经验是：把检索服务单独部署。

# retrieval_service.py —— 专做向量检索的微服务importfaissimportnumpyasnpfromflaskimportFlask,requestimportthreading app=Flask(__name__)# 全局只加载一次FAISS索引_index=None_lock=threading.RLock()defload_index_once():global_indexif_indexisNone:with_lock:if_indexisNone:# 双重检查锁，防止多线程重复加载_index=faiss.read_index("/data/faiss_index.bin")# 从共享存储读return_index@app.route("/search",methods=["POST"])defsearch():index=load_index_once()vector=request.json["embedding"]# 假设上游已转成向量k=request.json.get("k",3)# FAISS搜索是线程安全的，但返回的id要转成Python类型distances,indices=index.search(np.array([vector]),k)# 这里有个坑：FAISS返回的indices是int64，json序列化会出错return{"indices":indices[0].astype(int).tolist(),# 一定要转int！"distances":distances[0].tolist()}

这个服务可以单独扩缩容。比如QPS高了就多起几个检索实例，用Nginx做负载均衡。
关键优化：把索引文件挂载为readOnlyMany的PVC（K8s持久化卷），所有副本共享同一份数据，避免重复加载。

五、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---# 水平自动扩缩（HPA）apiVersion:autoscaling/v2kind:HorizontalPodAutoscalermetadata:name:rag-hpaspec:scaleTargetRef:apiVersion:apps/v1kind:Deploymentname:rag-apiminReplicas:2maxReplicas:10metrics:-type:Resourceresource:name:cputarget:type:UtilizationaverageUtilization:70# CPU平均使用率70%时触发扩容

部署顺序很重要：

1. 先创建ConfigMap和Secret（放数据库密码、API密钥）
2. 再创建PVC（持久化存储），等状态变成Bound
3. 最后部署Deployment

血泪教训：一定要设resources.limits，不然某个Pod发疯吃光节点内存，整个节点上的服务全挂。

六、生产环境必备的“生存装备”

服务跑起来只是开始，要稳定运行还得加几个关键部件：

1. 健康检查端点

@app.route("/health")defhealth():# 检查下游依赖redis_ok=redis_client.ping()db_ok=database.execute("SELECT 1")# 检查自身状态index_loaded=_indexisnotNoneifall([redis_ok,db_ok,index_loaded]):return{"status":"healthy"},200else:return{"status":"unhealthy"},503# 返回503，K8s会摘掉流量

2. 就绪探针（Readiness Probe）
在K8s里配置：

readinessProbe:httpGet:path:/healthport:8080initialDelaySeconds:10# 给容器启动留时间periodSeconds:5

3. 优雅关闭

importsignalimportsysdefhandle_shutdown(signum,frame):print("收到终止信号，开始清理...")# 1. 先摘掉负载均衡（K8s已经做了）# 2. 完成正在处理的请求# 3. 关闭数据库连接vector_store.close()sys.exit(0)signal.signal(signal.SIGTERM,handle_shutdown)# K8s发SIGTERM

七、一些经验之谈

1. 向量索引别放容器镜像里：镜像越大部署越慢。用共享存储（NFS、Ceph）或对象存储（S3）+本地缓存。
2. 模型文件同理：第一次启动时从对象存储下载到本地，加个MD5校验，更新时直接换地址。
3. 日志统一收集：容器标准输出到stdout，用Filebeat或Fluentd收走，别写本地文件。
4. 配置中心化：数据库地址、超时时间这些，放ConfigMap或Apollo，改配置不用重新构建镜像。
5. 准备降级方案：RAG检索超时了，能不能fallback到关键词检索？生成模型挂了，能不能返回检索结果让前端凑合用？
6. 压测要在K8s里做：本地压测和线上表现差很远，网络延迟、存储IO、邻居容器抢资源，这些因素只有真实环境才有。

最后说个反直觉的：不要追求零停机更新。RAG服务依赖向量索引，索引更新期间新旧版本可能返回不同结果。我们现在的做法是：

• 索引更新时，新版本服务先部署但不接流量
• 索引就绪后，切50%流量到新版本，观察效果
• 没问题再全量切换，旧版本保留一天备回滚

部署不是把代码扔上线就完事了，它是一套保证服务持续可用的系统工程。从本地开发到云原生，每一步都在和不确定性做斗争。慢慢来，多复盘，线上不出问题是偶然，出问题才是常态——关键是要有快速发现和恢复的能力。