从原型到产品：RAG应用Docker容器化与CI/CD部署实战-平芜编程栈

1. 项目终局：从原型到产品的最后一公里

折腾了快一个月，从LangChain的基础概念到RAG的核心组件，我们终于走到了最后一天。如果你跟着教程一路搭建下来，现在手头应该已经有了一个能跑起来的AI知识库原型。它能读取你的文档，理解你的问题，并给出基于文档的答案。在本地环境里，它可能运行得还不错。但这就够了吗？远远不够。

一个停留在开发者本地机器上的原型，和一个能被团队其他成员、甚至客户稳定使用的“产品”，中间隔着一道巨大的鸿沟。这道鸿沟，就是今天我们要填平的。想象一下，你的同事想用这个知识库，你总不能说“来，先在我电脑上装个Python 3.11，然后pip install这一长串依赖，哦对了，还得配置一下OpenAI的API Key和环境变量”吧？或者，你更新了代码，如何确保所有部署的实例都能同步更新，且更新过程不会导致服务中断？这就是我们常说的“最后一公里”问题——如何将开发成果，以一种可靠、可重复、可管理的方式交付出去。

今天，我们不谈新的LangChain API，也不深入新的RAG算法。我们要做的，是给过去29天的所有努力，套上一个坚固的“外壳”。这个外壳由三个核心支柱构成：Docker负责封装环境，实现“一次构建，处处运行”；CI/CD负责自动化流程，确保代码从提交到上线的每一步都可靠、高效；文档则负责沟通与传承，让后来者（包括三个月后的你自己）能理解、维护和扩展这个系统。这三者结合，才能将一个实验室里的“玩具”，真正升级为一个“企业级”的应用。这里的“企业级”，指的不是代码多复杂，而是指它的可维护性、可扩展性、可观测性和部署的确定性。

2. 容器化第一步：为RAG应用构建专属Docker镜像

为什么是Docker？在本地，你的环境可能是精心配置的，但换一台机器，可能就是“依赖地狱”。Docker通过将应用及其所有依赖（运行时、系统工具、库、设置）打包成一个标准化的单元（镜像），彻底解决了环境一致性问题。对于我们的RAG应用，这尤其重要，因为它可能依赖特定版本的Python、CUDA（如果用到本地GPU）、向量数据库客户端等。

2.1 设计一个高效的Dockerfile

Dockerfile是构建镜像的蓝图。一个糟糕的Dockerfile会构建出臃肿、不安全、构建缓慢的镜像。我们的目标是构建一个层数合理、体积小巧、安全合规的镜像。

首先，选择合适的基础镜像。对于Python应用，python:3.11-slim是一个很好的起点，它比完整的python:3.11镜像小很多，只包含运行Python所必需的最小包。

# 使用官方Python slim镜像作为基础，减少镜像体积 FROM python:3.11-slim as builder # 设置工作目录 WORKDIR /app # 设置环境变量，确保Python输出直接打印到终端，不缓冲 ENV PYTHONUNBUFFERED=1 \ # 防止Python生成.pyc文件 PYTHONDONTWRITEBYTECODE=1 # 安装系统依赖：构建某些Python包（如psycopg2, chromadb）可能需要gcc等工具 RUN apt-get update && apt-get install -y \ gcc \ g++ \ curl \ && rm -rf /var/lib/apt/lists/* # 清理apt缓存，减小镜像层大小

注意：这里使用apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/*是一条最佳实践。它将更新、安装和清理缓存合并到同一层（RUN指令），避免了缓存文件残留在镜像中，从而减小最终镜像体积。

接下来是依赖安装。一个常见的错误是将所有依赖（包括开发工具）都安装到最终的生产镜像中。我们应该使用多阶段构建。

# 第一阶段：构建依赖 FROM builder as builder # 复制依赖定义文件 COPY requirements.txt . # 安装依赖到 /usr/local，这是Python的默认包安装路径之一 RUN pip install --no-cache-dir --user -r requirements.txt # 第二阶段：生产镜像 FROM python:3.11-slim as production WORKDIR /app # 从构建阶段仅复制已安装的Python包和我们的应用代码 COPY --from=builder /root/.local /root/.local COPY . . # 将用户安装的包路径添加到Python的搜索路径中 ENV PATH=/root/.local/bin:$PATH \ PYTHONPATH=/app # 创建一个非root用户来运行应用，增强安全性 RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app USER appuser # 暴露应用端口（假设你的FastAPI/Streamlit应用运行在7860端口） EXPOSE 7860 # 定义容器启动命令 CMD ["python", "app/main.py"]

这个Dockerfile做了几件关键事：

多阶段构建：第一阶段（builder）安装了所有依赖。第二阶段（production）从一个干净的基础镜像开始，只从第一阶段复制安装好的包（/root/.local）和应用代码。这确保了最终镜像不包含构建工具（如gcc），体积更小。
使用非root用户：默认以root用户运行容器存在安全风险。我们创建了一个名为appuser的普通用户，并切换至此用户运行应用。
优化层缓存：将COPY requirements.txt .和RUN pip install...分开。这样，只要requirements.txt不变，Docker就可以复用这一层的缓存，加速后续构建。
清理缓存：在安装系统包和Python包时都使用了清理命令，减少冗余文件。

2.2 编写精准的requirements.txt

你的requirements.txt是依赖关系的唯一真相源。对于RAG项目，它可能长这样：

# 核心框架 langchain==0.1.0 langchain-community==0.0.10 # 向量数据库客户端，例如Chroma chromadb==0.4.22 # 嵌入模型，例如OpenAI或本地Sentence Transformers openai==1.12.0 sentence-transformers==2.2.2 # Web框架，例如FastAPI fastapi==0.104.1 uvicorn[standard]==0.24.0 # 异步HTTP客户端 httpx==0.25.1 # 环境变量管理 pydantic-settings==2.1.0 # 其他工具 pypdf==3.17.4 # PDF解析 python-dotenv==1.0.0

关键技巧：使用pip freeze > requirements.txt可以生成当前环境的精确依赖，但最好手动维护一个精简的列表，只列出顶级依赖。可以使用pip-compile（来自pip-tools包）来生成一个锁定所有次级依赖版本的requirements.txt，确保每次构建的依赖树完全一致。

2.3 构建、测试与推送镜像

在项目根目录（Dockerfile所在目录）执行构建：

# 构建镜像并打标签 docker build -t my-rag-app:latest . # 运行容器进行测试 docker run -d -p 7860:7860 --name rag-test \ -e OPENAI_API_KEY=your_key_here \ -v $(pwd)/data:/app/data \ my-rag-app:latest # 查看日志，确认应用启动正常 docker logs -f rag-test # 测试API接口（假设是FastAPI） curl http://localhost:7860/docs

如果测试通过，就可以将镜像推送到镜像仓库（如Docker Hub、阿里云容器镜像服务、Harbor等）。

# 登录镜像仓库 docker login your-registry.com # 重新打标签，符合仓库命名规范 docker tag my-rag-app:latest your-registry.com/your-project/my-rag-app:latest # 推送 docker push your-registry.com/your-project/my-rag-app:latest

踩坑实录：卷挂载与权限。上面命令中-v $(pwd)/data:/app/data将宿主机的data目录挂载到容器内，用于持久化向量数据库文件。这里常遇到容器内应用（以appuser运行）没有权限写入宿主机目录的问题。解决方法是在宿主机上确保该目录对Docker的运行时用户（通常是你的系统用户）可写，或者在Dockerfile中创建目录时设置好权限，更复杂的场景可能需要处理用户ID映射。

3. 自动化流水线：为RAG项目搭建CI/CD

CI/CD（持续集成/持续部署）是现代软件工程的基石。对于RAG项目，它的价值在于：

自动化测试：每次代码提交，自动运行单元测试、集成测试，确保新代码不会破坏现有功能（比如检索逻辑、文本分割效果）。
自动化构建：自动构建Docker镜像，保证镜像来源的可追溯性。
自动化部署：将通过测试的镜像自动部署到测试或生产环境。

我们将以GitHub Actions为例，因为它与GitHub集成紧密，无需自建服务器。其他平台如GitLab CI、Jenkins原理类似。

3.1 设计CI/CD工作流

一个典型的RAG项目CI/CD流水线可能包含以下阶段：

代码检查：运行代码风格检查（如black, isort）、类型检查（如mypy）、安全扫描（如bandit）。
测试：运行单元测试和集成测试。对于RAG，集成测试可能涉及启动一个临时的向量数据库容器，测试完整的“索引-检索-生成”流程。
构建与推送：构建Docker镜像，并推送到镜像仓库。镜像标签通常与Git commit SHA或版本号关联。
部署：将新镜像部署到目标环境（如测试服务器、Kubernetes集群）。

我们在项目根目录创建.github/workflows/ci-cd.yml文件。

3.2 编写GitHub Actions工作流文件

name: RAG App CI/CD Pipeline on: push: branches: [ main, develop ] # 在推送到主分支和开发分支时触发 pull_request: branches: [ main ] # 针对主分支的PR也触发CI env: REGISTRY: ghcr.io # 使用GitHub Container Registry IMAGE_NAME: ${{ github.repository }}/rag-app # 镜像名 jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install pytest pytest-asyncio pytest-cov # 测试框架 - name: Lint with black and isort run: | pip install black isort black --check . isort --check-only . - name: Run unit tests run: | pytest tests/unit -v --cov=app --cov-report=xml - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 with: file: ./coverage.xml build-and-push: needs: test # 依赖test job成功 runs-on: ubuntu-latest if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop') permissions: contents: read packages: write steps: - name: Checkout code uses: actions/checkout@v4 - name: Log in to the Container registry uses: docker/login-action@v3 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@v5 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | type=sha,prefix={{branch}}- type=ref,event=branch type=ref,event=tag type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }} - name: Build and push Docker image uses: docker/build-push-action@v5 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max deploy-staging: needs: build-and-push runs-on: ubuntu-latest if: github.ref == 'refs/heads/develop' # 仅对develop分支自动部署到预发环境 steps: - name: Deploy to Staging via SSH uses: appleboy/ssh-action@v1.0.0 with: host: ${{ secrets.STAGING_HOST }} username: ${{ secrets.STAGING_USER }} key: ${{ secrets.STAGING_SSH_KEY }} script: | cd /path/to/your/rag-app docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:develop docker-compose -f docker-compose.staging.yml up -d --force-recreate

这个工作流定义了三个任务（jobs）：

test：运行代码检查和测试。它会在每次推送和PR时触发。
build-and-push：仅在推送到main或develop分支，且test任务成功后执行。它负责构建Docker镜像并推送到GitHub容器注册表（GHCR）。它使用了docker/metadata-action自动生成有意义的镜像标签（如main-<sha>，develop-<sha>，以及main分支的latest标签）。
deploy-staging：一个简单的部署示例，仅在develop分支的推送成功后，通过SSH连接到预发环境服务器，拉取最新镜像并用docker-compose重新启动服务。

3.3 关键配置与避坑指南

Secrets管理：工作流中引用的secrets.GITHUB_TOKEN、secrets.STAGING_HOST等，需要在GitHub仓库的Settings -> Secrets and variables -> Actions页面进行配置。切勿将密码、密钥等敏感信息硬编码在YAML文件中。
测试环境模拟：RAG的集成测试需要向量数据库。可以在GitHub Actions中使用services来启动一个临时容器（如ChromaDB的Docker镜像），并在测试中连接它。这比mock更接近真实情况。
构建缓存：示例中使用了cache-from和cache-to配置，将构建缓存存储在GitHub Actions的缓存中，可以显著加速后续构建。
部署策略：示例是最简单的“直接替换”部署。对于生产环境，你可能需要更复杂的策略，如蓝绿部署或滚动更新，这通常需要配合Kubernetes或更高级的部署工具（如ArgoCD）来实现。

实操心得：在CI/CD流水线中，“失败快速”原则至关重要。把最轻量、最快能发现问题的步骤（如代码风格检查、单元测试）放在前面。如果代码格式都不对，就没必要浪费资源去构建镜像了。另外，为build-and-push任务设置正确的分支触发条件(if)非常重要，避免为每个临时分支都构建镜像，浪费资源和时间。

4. 部署编排与配置管理：使用Docker Compose

在单机或小型服务器上，使用Docker Compose来编排多容器服务是最简单高效的方式。一个典型的RAG应用可能包含以下服务：

应用服务：我们构建的FastAPI/Streamlit应用。
向量数据库服务：如ChromaDB、Qdrant、Weaviate等。
缓存服务（可选）：如Redis，用于缓存频繁查询的嵌入向量或对话历史。
监控与日志（可选）：如Prometheus、Grafana、Loki。

4.1 编写docker-compose.yml

创建一个docker-compose.yml文件来定义这些服务。

version: '3.8' services: chromadb: image: chromadb/chroma:latest container_name: rag-chromadb restart: unless-stopped environment: - IS_PERSISTENT=TRUE - PERSIST_DIRECTORY=/chroma/data - ANONYMIZED_TELEMETRY=FALSE # 根据需求关闭遥测 volumes: - chroma_data:/chroma/data # 持久化向量数据 ports: - "8000:8000" # ChromaDB的HTTP API端口 networks: - rag-network redis: image: redis:7-alpine container_name: rag-redis restart: unless-stopped command: redis-server --appendonly yes # 开启AOF持久化 volumes: - redis_data:/data networks: - rag-network rag-app: image: ghcr.io/your-username/your-repo/rag-app:latest # 替换为你的镜像地址 container_name: rag-app restart: unless-stopped depends_on: - chromadb - redis environment: - OPENAI_API_KEY=${OPENAI_API_KEY} # 从.env文件或宿主机环境变量注入 - CHROMA_SERVER_HOST=chromadb - CHROMA_SERVER_HTTP_PORT=8000 - REDIS_URL=redis://redis:6379/0 - LOG_LEVEL=INFO volumes: - uploaded_files:/app/data/uploads # 挂载上传文件目录 ports: - "7860:7860" # 应用对外暴露的端口 networks: - rag-network # 健康检查，确保应用完全启动 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:7860/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s volumes: chroma_data: redis_data: uploaded_files: networks: rag-network: driver: bridge

4.2 环境变量管理与配置注入

配置管理是部署的关键一环。硬编码配置（如API密钥、数据库连接字符串）是绝对禁止的。我们使用环境变量。

.env文件：在项目根目录创建.env文件（务必加入.gitignore），存放本地开发或部署时的敏感配置。
```
OPENAI_API_KEY=sk-... CHROMA_SERVER_HOST=localhost
```
Docker Compose引用：在docker-compose.yml中，使用${VARIABLE_NAME}语法引用环境变量。Docker Compose会自动从宿主机环境或同目录下的.env文件读取。
生产环境：在生产服务器上，环境变量可以通过Docker的-e参数、Kubernetes的ConfigMap/Secret、或云平台提供的机密管理服务来设置。

重要经验：在应用代码中，使用pydantic-settings或python-decouple这类库来管理配置。它们支持从环境变量、.env文件、甚至远程配置中心读取配置，并提供了类型验证和默认值功能，非常安全方便。

4.3 使用docker-compose部署与运维

# 1. 启动所有服务（后台运行） docker-compose up -d # 2. 查看所有容器状态 docker-compose ps # 3. 查看特定服务日志（如应用日志） docker-compose logs -f rag-app # 4. 进入应用容器执行命令（例如，初始化数据库或运行管理脚本） docker-compose exec rag-app python scripts/init_vector_db.py # 5. 更新应用（假设构建了新镜像并推送到了仓库） # 先拉取最新镜像 docker-compose pull rag-app # 然后重新启动该服务 docker-compose up -d --force-recreate rag-app # 6. 停止并移除所有容器、网络（保留数据卷） docker-compose down # 7. 停止并移除所有容器、网络、数据卷（危险！会丢失数据） docker-compose down -v

通过Docker Compose，我们实现了服务的声明式管理。一个命令就能拉起整个复杂的RAG应用栈，并且所有服务都在一个隔离的网络中，通过服务名（如chromadb）互相通信，无需关心IP地址。

5. 项目文档化：让代码自己“说话”

代码会变，人会走。没有文档的项目，其维护成本会随时间呈指数级增长。好的文档不是事后补的说明书，而应该是开发过程的一部分。对于要交付的RAG项目，以下几类文档必不可少：

5.1 README.md：项目的门面

这是任何人接触你项目的第一个文件。它必须清晰、全面。

# 企业级AI知识库 (RAG System) [![CI/CD Pipeline](https://github.com/your-username/your-rag-repo/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/your-username/your-rag-repo/actions/workflows/ci-cd.yml) [![Docker Image Version](https://img.shields.io/docker/v/your-username/rag-app?sort=semver)](https://hub.docker.com/r/your-username/rag-app) 一个基于LangChain和FastAPI构建的企业级检索增强生成(RAG)系统，支持私有文档上传、智能问答与知识管理。 ## ✨ 核心特性 - **多格式文档解析**: 支持PDF、Word、Excel、PPT、TXT、Markdown。 - **智能文本分割与向量化**: 采用语义分割策略，搭配Sentence-BERT或OpenAI Embeddings。 - **混合检索**: 结合向量检索与关键词（BM25）检索，提升召回率。 - **可配置的LLM接口**: 支持OpenAI GPT、Azure OpenAI、通义千问等。 - **对话历史与上下文管理**。 - **完整的Docker容器化与CI/CD流水线**。 ## 🚀 快速开始 ### 前提条件 - Docker & Docker Compose - OpenAI API Key (或配置其他LLM) ### 本地开发 1. 克隆仓库: `git clone https://github.com/your-username/your-rag-repo.git` 2. 复制环境变量文件: `cp .env.example .env` 3. 编辑 `.env` 文件，填入你的 `OPENAI_API_KEY`。 4. 启动服务: `docker-compose up -d` 5. 打开浏览器访问: `http://localhost:7860/docs` (API文档) 或 `http://localhost:7860` (Web UI)。 ### 生产部署 详见 [DEPLOYMENT.md](./docs/DEPLOYMENT.md)。 ## 📁 项目结构

. ├── app/ # 应用核心代码 │ ├── api/ # FastAPI路由 │ ├── core/ # 核心配置、依赖注入 │ ├── models/ # Pydantic数据模型 │ ├── services/ # 业务逻辑层（检索、生成、缓存） │ └── main.py # 应用入口 ├── scripts/ # 工具脚本（如初始化DB） ├── tests/ # 测试用例 ├── docker-compose.yml ├── Dockerfile ├── requirements.txt └── README.md

## 🔧 配置说明 主要配置通过环境变量管理。所有可用变量见 [配置手册](./docs/CONFIGURATION.md)。 ## 🧪 运行测试 ```bash # 运行单元测试 pytest tests/unit -v # 运行集成测试（需要Docker） pytest tests/integration -v

🤝 贡献指南

欢迎提交Issue和Pull Request！请阅读 CONTRIBUTING.md 。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

### 5.2 API文档：让接口清晰可见 如果你用FastAPI，它自动生成的交互式API文档（`/docs` 或 `/redoc`）已经非常强大。但你可以通过精心设计Pydantic模型和接口描述，让它更友好。 ```python from fastapi import FastAPI, UploadFile, File, Query from pydantic import BaseModel from typing import List app = FastAPI( title="企业知识库RAG API", description="基于LangChain的检索增强生成系统API文档", version="1.0.0" ) class QueryRequest(BaseModel): question: str = Query(..., description="用户提出的问题", example="公司今年的年假政策是什么？") top_k: int = Query(5, description="返回最相关的文档片段数量", ge=1, le=20) class QueryResponse(BaseModel): answer: str = Field(..., description="AI生成的答案") sources: List[DocumentSource] = Field(..., description="答案引用的文档来源") @app.post("/query", response_model=QueryResponse, summary="向知识库提问") async def query_knowledge_base(request: QueryRequest): """ 接收用户问题，从已索引的知识库中检索相关文档，并生成回答。 - **question**: 必须，用户的问题文本。 - **top_k**: 可选，控制检索的文档数量，默认5。 """ # ... 业务逻辑 return response

通过summary,description,example等字段，可以极大提升自动生成文档的可读性。

5.3 架构与决策文档

在docs/目录下，还应该有一些解释“为什么”的文档：

ARCHITECTURE.md：系统架构图（可以用文字或链接到图表），说明各个组件（Web Server, LLM, Vector DB, Cache）如何交互，数据流是怎样的。
DECISIONS.md：记录关键的技术决策。例如：“为什么选择ChromaDB而不是Pinecone？”、“为什么使用FastAPI而不是Flask？”。这有助于新成员快速理解项目背景，避免重复讨论。
DEPLOYMENT.md：详细的生产环境部署手册，包括服务器要求、网络配置、监控告警设置、备份策略等。
DEVELOPMENT.md：本地开发环境设置指南，包括如何配置IDE、如何运行测试、代码风格规范等。

个人体会：写文档最有效的时机是“趁热打铁”。在实现一个复杂模块后，立即花10分钟写下它的设计思路和核心逻辑。这比两周后靠回忆来补要准确、轻松得多。把文档当作代码的一部分来维护，在PR中如果修改了核心逻辑，也应该同步更新相关文档。

6. 监控、日志与维护：让系统健康可见

系统上线不是终点。你需要知道它是否在正常工作，性能如何，出了问题时如何快速定位。

6.1 结构化日志记录

不要再用简单的print了。使用像structlog或配置好的logging模块，输出结构化的JSON日志，便于后续收集和分析。

# app/core/logging.py import structlog import sys structlog.configure( processors=[ structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.TimeStamper(fmt="iso"), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.JSONRenderer() # 输出为JSON格式 ], context_class=dict, logger_factory=structlog.stdlib.LoggerFactory(), cache_logger_on_first_use=True, ) logger = structlog.get_logger() # 在业务代码中使用 logger.info("document.indexed", document_id=doc_id, chunks=len(chunks)) logger.error("query.failed", error=str(e), question=question)

这样，在Docker Compose或Kubernetes中，日志可以被Fluentd、Loki等工具轻松收集。

6.2 添加健康检查与监控端点

在FastAPI应用中，添加一个/health端点，用于检查应用及其依赖（数据库、缓存）的健康状态。

from fastapi import APIRouter, Depends from .services.vector_store import get_vector_store from redis import Redis import asyncio router = APIRouter() @router.get("/health") async def health_check(vector_store = Depends(get_vector_store), redis: Redis = Depends(get_redis)): """综合健康检查端点""" checks = {} # 检查自身状态 checks["api"] = "healthy" # 检查向量数据库连接 try: # 尝试一个轻量级操作，如获取集合数量 await asyncio.to_thread(vector_store._client.list_collections) checks["vector_db"] = "healthy" except Exception as e: checks["vector_db"] = f"unhealthy: {e}" # 检查Redis连接 try: redis.ping() checks["cache"] = "healthy" except Exception as e: checks["cache"] = f"unhealthy: {e}" overall_status = "healthy" if all(v == "healthy" for v in checks.values()) else "unhealthy" return { "status": overall_status, "checks": checks }

这个端点可以被Docker的healthcheck指令（如前文所示）、Kubernetes的存活探针（liveness probe）或外部监控系统（如Prometheus Blackbox Exporter）调用。

6.3 基础指标暴露

使用Prometheus客户端库（如prometheus-fastapi-instrumentator）来暴露应用的基本指标，如请求次数、延迟、错误率等。

from prometheus_fastapi_instrumentator import Instrumentator app = FastAPI() # 添加Prometheus指标中间件 Instrumentator().instrument(app).expose(app)

这会在/metrics端点暴露指标数据，Prometheus可以定期来抓取，再通过Grafana进行可视化。

6.4 制定维护计划

最后，思考一下日常维护工作：

日志轮转与清理：配置Docker的日志驱动或使用logrotate，防止日志占满磁盘。
数据备份：定期备份向量数据库的持久化卷。ChromaDB的PERSIST_DIRECTORY就是需要备份的目标。
依赖更新：定期检查并更新requirements.txt中的依赖版本，特别是安全更新。可以在CI中集成dependabot或renovate来自动化这个过程。
监控告警：为关键指标（如服务不可用、错误率飙升、响应延迟过高）设置告警，确保问题能及时被发现。

走到这一步，你的RAG项目已经从一个脆弱的原型，蜕变成了一个具有工业级韧性的软件产品。它拥有标准化的交付物（Docker镜像）、自动化的质量关卡（CI/CD）、清晰的协作指南（文档）和基本的可观测性（日志监控）。这不仅仅是30天学习的终点，更是一个可维护、可扩展的AI应用项目的坚实起点。剩下的，就是在实际业务场景中迭代、优化和创造价值了。