生产环境部署与优化RAG 落地的最后一公里：三级降级、性能优化与 Docker 部署摘要 RAG 系统从实验室到生产环

RAG 落地的最后一公里：三级降级、性能优化与 Docker 部署

系列导航
📄 第 1 篇：CRAG 架构与置信度路由
📄 第 2 篇：RRF 混合检索 + BGE 重排序
📄 第 3 篇：语义切片 + Ragas 评估体系
📍 第 4 篇：生产环境部署与优化（本文）

摘要

RAG 系统从实验室到生产环境，需要解决 PDF 解析覆盖率、延迟优化、部署复杂度三大问题。本文介绍 Docling + PyPDF + Tesseract 三级降级解析方案（覆盖率 70% → 95%），通过单例模式、并行检索、批量推理等优化手段将 P95 延迟降至 2.3s，并提供 Docker 一键部署方案，让 Agentic RAG 系统真正可用于生产环境。

环境依赖：Python 3.11+, Docling 1.0.0+, PyPDF2 3.0.0+, pytesseract 0.3.10+, pdf2image 1.16.0+, Docker 24.0+

引言：实验室跑通 ≠ 生产可用

你的 RAG 系统在 Jupyter Notebook 里跑得很完美：测试数据集上 Context Recall 0.78，Faithfulness 0.85，一切看起来都很美好。

然后你把它部署到生产环境，第一天就遇到了三个问题：

问题 1：用户上传了一个扫描版 PDF
你的 PDF 解析器（PyPDF2）返回空白——因为扫描件是纯图片，没有文本层。用户抱怨："为什么我的文档解析不出来？"

问题 2：10 个并发请求打过来
服务器 CPU 飙到 100%，内存溢出，服务崩溃。你发现每个请求都在重新加载 BGE-Reranker 模型（1.3GB），10 个请求 = 13GB 内存。

问题 3：部署到新服务器
依赖冲突、环境变量缺失、Qdrant 连接失败...折腾了 3 小时才跑起来。

问题的本质：RAG 系统有太多"边缘情况"——不同格式的 PDF、并发压力、环境差异。实验室环境是理想化的，生产环境是残酷的。

本文要解决的核心问题：如何让 RAG 系统在生产环境稳定运行？

三级降级解析：让 PDF 解析覆盖率从 70% 到 95%

问题：PDF 的千奇百怪

实验室用的是标准 PDF（从 LaTeX 或 Word 导出），但生产环境会遇到：

扫描件：纯图片，没有文本层（比如扫描的论文、合同）
复杂多栏布局：学术论文的双栏、三栏布局
嵌套表格：财务报表、数据表格
加密 PDF：需要密码才能打开
损坏的 PDF：文件不完整或格式错误

单一解析器无法覆盖所有情况。解决方案：三级降级策略。

三级降级策略

级别	解析器	适用场景	成功率	延迟
Level 1	Docling (IBM)	标准 PDF、复杂布局、嵌套表格	70%	2-5s
Level 2	PyPDF2	简单文本 PDF、低资源环境	20%	0.5s
Level 3	Tesseract OCR	扫描图片 PDF、手写文档	5%	10-30s

为什么这样设计？

Level 1（Docling）：IBM 开源的文档解析工具，基于深度学习，能处理复杂布局（多栏、表格、图片）。但它需要较多计算资源，且对某些 PDF 格式支持不完美。
Level 2（PyPDF2）：轻量级 Python 库，直接提取 PDF 的文本层。速度快，但无法处理扫描件、复杂布局。
Level 3（Tesseract OCR）：Google 开源的 OCR 引擎，能识别图片中的文字。适用于扫描件，但速度慢、准确率受图片质量影响。

降级流程

上传 PDF
    ↓
尝试 Docling 解析
    ↓
成功？ ──Yes──→ 返回文本
    ↓ No
尝试 PyPDF2 解析
    ↓
成功？ ──Yes──→ 返回文本
    ↓ No
尝试 Tesseract OCR
    ↓
成功？ ──Yes──→ 返回文本
    ↓ No
返回错误提示："无法解析此 PDF，请检查文件格式"

判断"成功"的标准：

提取的文本长度 > 100 字符
文本不是乱码（检测是否包含可读字符）

代码实现：

from docling.document_converter import DocumentConverter
import PyPDF2
import pytesseract
from pdf2image import convert_from_path
from typing import Optional
import re

class PDFParser:
    """三级降级 PDF 解析器"""
    
    def __init__(self):
        self.docling_converter = DocumentConverter()
    
    def parse(self, pdf_path: str) -> Optional[str]:
        """
        三级降级解析 PDF
        
        Args:
            pdf_path: PDF 文件路径
        
        Returns:
            解析后的文本，失败返回 None
        """
        # Level 1: 尝试 Docling
        text = self._parse_with_docling(pdf_path)
        if self._is_valid_text(text):
            print(f"✓ Docling 解析成功")
            return text
        
        # Level 2: 尝试 PyPDF2
        text = self._parse_with_pypdf(pdf_path)
        if self._is_valid_text(text):
            print(f"✓ PyPDF2 解析成功")
            return text
        
        # Level 3: 尝试 Tesseract OCR
        text = self._parse_with_ocr(pdf_path)
        if self._is_valid_text(text):
            print(f"✓ Tesseract OCR 解析成功")
            return text
        
        print(f"✗ 所有解析方法均失败")
        return None
    
    def _parse_with_docling(self, pdf_path: str) -> Optional[str]:
        """Level 1: Docling 解析"""
        try:
            result = self.docling_converter.convert(pdf_path)
            return result.document.export_to_markdown()
        except Exception as e:
            print(f"Docling 解析失败: {e}")
            return None
    
    def _parse_with_pypdf(self, pdf_path: str) -> Optional[str]:
        """Level 2: PyPDF2 解析"""
        try:
            with open(pdf_path, 'rb') as file:
                reader = PyPDF2.PdfReader(file)
                text = ""
                for page in reader.pages:
                    text += page.extract_text()
                return text
        except Exception as e:
            print(f"PyPDF2 解析失败: {e}")
            return None
    
    def _parse_with_ocr(self, pdf_path: str) -> Optional[str]:
        """Level 3: Tesseract OCR 解析"""
        try:
            # 将 PDF 转为图片（300 DPI）
            images = convert_from_path(pdf_path, dpi=300)
            
            text = ""
            for i, image in enumerate(images):
                # 使用中英文双语模型
                page_text = pytesseract.image_to_string(
                    image, 
                    lang='chi_sim+eng'
                )
                text += page_text + "\n\n"
                print(f"  OCR 处理第 {i+1}/{len(images)} 页")
            
            # 后处理：纠正常见 OCR 错误
            text = self._post_process_ocr(text)
            return text
        except Exception as e:
            print(f"Tesseract OCR 解析失败: {e}")
            return None
    
    def _post_process_ocr(self, text: str) -> str:
        """OCR 后处理：纠正常见错误"""
        # 纠正常见的 OCR 识别错误
        corrections = {
            r'\b0\b': 'O',  # 数字 0 → 字母 O（根据上下文）
            r'\bl\b': '1',  # 小写 l → 数字 1（根据上下文）
            '，': ',',      # 中文逗号 → 英文逗号
            '。': '.',      # 中文句号 → 英文句号
        }
        
        for pattern, replacement in corrections.items():
            text = re.sub(pattern, replacement, text)
        
        return text
    
    def _is_valid_text(self, text: Optional[str]) -> bool:
        """判断文本是否有效"""
        if not text:
            return False
        
        # 检查长度
        if len(text.strip()) < 100:
            return False
        
        # 检查是否包含可读字符（至少 50% 是字母或汉字）
        readable_chars = sum(1 for c in text if c.isalpha() or '一' <= c <= '鿿')
        ratio = readable_chars / len(text)
        
        return ratio > 0.5

# 使用示例
parser = PDFParser()

# 测试不同类型的 PDF
test_files = [
    "standard.pdf",      # 标准 PDF
    "scanned.pdf",       # 扫描件
    "complex_layout.pdf" # 复杂布局
]

for pdf_file in test_files:
    print(f"\n解析 {pdf_file}...")
    text = parser.parse(pdf_file)
    if text:
        print(f"成功提取 {len(text)} 字符")
    else:
        print("解析失败")

关键优化：

Docling 处理复杂布局（多栏、表格）
PyPDF2 作为轻量级备选方案
OCR 使用 300 DPI 提升识别率
后处理纠正常见 OCR 错误

OCR 优化

Tesseract 的效果高度依赖输入图片质量。优化手段：

高分辨率转换：用 pdf2image 将 PDF 转为图片，DPI 设置为 300（默认 72 太低）
双语模型：中英文混合文档需要同时加载两个语言模型
```
tesseract input.png output -l chi_sim+eng
```
后处理：纠正常见 OCR 错误
- "0"（数字零）误识别为"O"（字母O）
- "1"（数字一）误识别为"l"（小写L）
- 中文标点误识别为英文标点

效果对比：

策略	PDF 解析覆盖率	平均延迟
仅 PyPDF2	70%	0.5s
PyPDF2 + Docling	90%	3s
三级降级	95%	5s（含 OCR）

性能优化：从 5 秒到 2.3 秒的血泪史

第一步：用 py-spy 找到真正的瓶颈

问题：系统延迟 5 秒，但不知道瓶颈在哪。

排查过程：

# 1. 安装 py-spy
pip install py-spy

# 2. 启动应用并采样（采样 60 秒）
py-spy record -o profile.svg --pid $(pgrep -f "streamlit run app.py")

# 3. 生成火焰图
# 打开 profile.svg 查看

火焰图分析结果：

总耗时 5.2s 的调用栈：
├─ openai.chat.completions.create (置信度评估)  ─ 2.8s (54%)
├─ openai.chat.completions.create (LLM 生成)    ─ 1.9s (37%)
├─ transformers.AutoModel.forward (Reranker)    ─ 0.3s (6%)
├─ qdrant_client.search (向量检索)              ─ 0.1s (2%)
└─ rank_bm25.get_scores (BM25 检索)             ─ 0.08s (1%)

关键发现：

置信度评估占 54%：用 gpt-4o 评估每个检索结果，单次调用 2.8s
LLM 生成占 37%：gpt-4o 生成答案，1.9s
Reranker 只占 6%：之前以为是瓶颈，其实不是

第二步：针对性优化

优化 1：置信度评估换模型（2.8s → 0.25s）

问题：gpt-4o 评估文档相关性，延迟 2.8s，成本高

解决：换成 gpt-4o-mini

# 优化前
response = client.chat.completions.create(
    model="gpt-4o",  # 延迟 2.8s，成本 $0.015/1K tokens
    messages=[{"role": "user", "content": prompt}]
)

# 优化后
response = client.chat.completions.create(
    model="gpt-4o-mini",  # 延迟 0.25s，成本 $0.0003/1K tokens
    messages=[{"role": "user", "content": prompt}],
    temperature=0  # 降低随机性
)

效果：

延迟：2.8s → 0.25s（降低 91%）
成本： $0.015 →$ 0.0003（降低 98%）
准确率：几乎无损（分类任务不需要强推理）

优化 2：Qdrant 索引参数调优（100ms → 50ms）

问题：向量检索延迟 100ms，在 10 万文档规模下偏慢

排查：检查 Qdrant 的 HNSW 索引参数

# 查看当前配置
from qdrant_client import QdrantClient
client = QdrantClient("localhost", port=6333)

collection_info = client.get_collection("documents")
print(collection_info.config.hnsw_config)

# 输出：
# HnswConfig(
#     m=16,              # 每个节点的连接数（默认）
#     ef_construct=100,  # 构建时的搜索深度（默认）
#     full_scan_threshold=10000  # 全扫描阈值
# )

优化：调整 HNSW 参数

# 创建集合时指定优化参数
from qdrant_client.models import VectorParams, Distance, HnswConfigDiff

client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(
        size=1536,
        distance=Distance.COSINE
    ),
    hnsw_config=HnswConfigDiff(
        m=32,              # 增加连接数（16 → 32）
        ef_construct=200,  # 增加构建深度（100 → 200）
        full_scan_threshold=20000
    )
)

# 搜索时指定 ef 参数
results = client.search(
    collection_name="documents",
    query_vector=embedding,
    limit=10,
    search_params={"hnsw_ef": 128}  # 搜索深度（默认 64）
)

参数说明：

m：每个节点的连接数，越大召回率越高但内存占用越大
ef_construct：构建索引时的搜索深度，越大索引质量越高但构建越慢
hnsw_ef：搜索时的深度，越大召回率越高但延迟越高

效果：

延迟：100ms → 50ms（降低 50%）
召回率：0.82 → 0.84（提升 2%）
内存占用：+15%（可接受）

优化 3：BM25 倒排索引缓存（80ms → 50ms）

问题：每次检索都重新计算 BM25 分数，耗时 80ms

解决：将倒排索引缓存到内存

from rank_bm25 import BM25Okapi
import pickle
import os

class CachedBM25:
    def __init__(self, cache_path="bm25_index.pkl"):
        self.cache_path = cache_path
        self.index = None
        self.corpus = None
    
    def build_index(self, tokenized_corpus):
        """构建索引并缓存"""
        self.corpus = tokenized_corpus
        self.index = BM25Okapi(tokenized_corpus)
        
        # 缓存到磁盘
        with open(self.cache_path, 'wb') as f:
            pickle.dump({
                'index': self.index,
                'corpus': self.corpus
            }, f)
        print(f"索引已缓存到 {self.cache_path}")
    
    def load_index(self):
        """从缓存加载索引"""
        if os.path.exists(self.cache_path):
            with open(self.cache_path, 'rb') as f:
                data = pickle.load(f)
                self.index = data['index']
                self.corpus = data['corpus']
            print(f"从缓存加载索引，文档数: {len(self.corpus)}")
            return True
        return False
    
    def search(self, query_tokens, top_k=10):
        """搜索"""
        if self.index is None:
            raise ValueError("索引未加载")
        scores = self.index.get_scores(query_tokens)
        top_indices = sorted(
            range(len(scores)), 
            key=lambda i: scores[i], 
            reverse=True
        )[:top_k]
        return [(i, scores[i]) for i in top_indices]

# 使用
bm25 = CachedBM25()
if not bm25.load_index():
    # 首次构建索引
    bm25.build_index(tokenized_corpus)

效果：

首次加载：3s（从磁盘读取）
后续检索：80ms → 50ms（降低 37%）
内存占用：+200MB（10 万文档）

优化 4：Reranker 批量推理（300ms → 150ms）

问题：Reranker 对 10 个文档逐个推理，每个 30ms，总计 300ms

解决：批量推理

def rerank_batch(self, query: str, documents: List[str], top_k: int = 10):
    """批量重排序（优化版）"""
    # 构建 query-document pairs
    pairs = [[query, doc] for doc in documents]
    
    # 批量推理（一次处理所有 pairs）
    with torch.no_grad():
        inputs = self._tokenizer(
            pairs,
            padding=True,
            truncation=True,
            return_tensors='pt',
            max_length=512
        )
        # 批量前向传播
        scores = self._model(**inputs, return_dict=True).logits.view(-1).float()
    
    # 排序
    scores_with_indices = [(i, score.item()) for i, score in enumerate(scores)]
    scores_with_indices.sort(key=lambda x: x[1], reverse=True)
    
    return scores_with_indices[:top_k]

效果：

延迟：300ms → 150ms（降低 50%）
GPU 利用率：30% → 70%（批量推理更高效）

优化效果汇总

环节	优化前	优化后	优化手段	成本节省
置信度评估	2.8s	0.25s	gpt-4o → gpt-4o-mini	98%
向量检索	100ms	50ms	HNSW 参数调优	-
BM25 检索	80ms	50ms	倒排索引缓存	-
Reranker	300ms	150ms	批量推理	-
LLM 生成	1.9s	1.8s	流式输出（体验优化）	-
总计	~5.2s	~2.3s	降低 56%	$0.015 →$ 0.0003

关键优化手段

1. 单例模式：避免重复加载模型

问题：BGE-Reranker 模型 1.3GB，每次请求都加载一次，内存爆炸。

解决：单例模式，全局只加载一次。

代码实现：

from transformers import AutoModelForSequenceClassification, AutoTokenizer
import torch
from typing import List, Tuple

class RerankerSingleton:
    """BGE-Reranker 单例模式"""
    _instance = None
    _model = None
    _tokenizer = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._initialize_model()
        return cls._instance
    
    @classmethod
    def _initialize_model(cls):
        """初始化模型（只执行一次）"""
        print("加载 BGE-Reranker 模型...")
        cls._model = AutoModelForSequenceClassification.from_pretrained(
            "BAAI/bge-reranker-large"
        )
        cls._tokenizer = AutoTokenizer.from_pretrained(
            "BAAI/bge-reranker-large"
        )
        cls._model.eval()  # 设置为评估模式
        print("模型加载完成")
    
    def rerank(
        self, 
        query: str, 
        documents: List[str], 
        top_k: int = 10
    ) -> List[Tuple[int, float]]:
        """
        重排序文档
        
        Args:
            query: 查询文本
            documents: 文档列表
            top_k: 返回前 k 个文档
        
        Returns:
            [(doc_index, score), ...] 按分数降序排列
        """
        # 构建 query-document pairs
        pairs = [[query, doc] for doc in documents]
        
        # 批量推理
        with torch.no_grad():
            inputs = self._tokenizer(
                pairs,
                padding=True,
                truncation=True,
                return_tensors='pt',
                max_length=512
            )
            scores = self._model(**inputs, return_dict=True).logits.view(-1).float()
        
        # 排序
        scores_with_indices = [(i, score.item()) for i, score in enumerate(scores)]
        scores_with_indices.sort(key=lambda x: x[1], reverse=True)
        
        return scores_with_indices[:top_k]

# 使用示例
reranker = RerankerSingleton()  # 第一次调用：加载模型
query = "Transformer 的注意力机制"
documents = [
    "Transformer 使用自注意力机制...",
    "CNN 是一种卷积神经网络...",
    "BERT 基于 Transformer 架构..."
]

results = reranker.rerank(query, documents, top_k=3)
print("重排序结果:")
for idx, score in results:
    print(f"  文档 {idx}: {score:.4f}")

# 第二次调用：直接使用已加载的模型，无需重新加载
reranker2 = RerankerSingleton()  # 返回同一个实例
assert reranker is reranker2  # True

效果：

内存占用：13GB（10 并发 × 1.3GB）→ 1.3GB
加载延迟：3s → 0ms（首次加载后）

2. 并行检索：向量 + BM25 同时执行

问题：向量检索和 BM25 检索串行执行，总延迟 = 100ms + 80ms = 180ms。

解决：用 asyncio.gather 并行执行。

import asyncio

async def hybrid_search(query):
    dense_task = vector_search(query)
    sparse_task = bm25_search(query)
    dense_results, sparse_results = await asyncio.gather(dense_task, sparse_task)
    return rrf_fusion(dense_results, sparse_results)

效果：延迟从 180ms → 100ms（取 max）

3. 批量 Embedding：减少 API 调用

问题：语义切片时，200 个句子需要 200 次 Embedding API 调用，延迟 20s。

解决：批量处理，每次发送 100 个句子。

embeddings = openai.Embedding.create(
    input=sentences[:100],  # 批量
    model="text-embedding-3-small"
)

效果：延迟从 20s → 2s

4. 缓存策略：Redis 缓存常见查询

问题：用户经常问相同的问题（比如"公司地址是什么？"），每次都重新检索。

解决：用 Redis 缓存检索结果，TTL 1 小时。

import redis
r = redis.Redis()

def cached_search(query):
    cache_key = f"search:{query}"
    cached = r.get(cache_key)
    if cached:
        return json.loads(cached)
    
    results = hybrid_search(query)
    r.setex(cache_key, 3600, json.dumps(results))  # TTL 1 小时
    return results

效果：缓存命中率 30%，这些请求延迟从 2.3s → 50ms

Docker 一键部署

docker-compose.yml 核心配置

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - ./qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

  app:
    build: .
    ports:
      - "8501:8501"  # Streamlit
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - QDRANT_HOST=qdrant
      - QDRANT_PORT=6333
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - qdrant
      - redis
    volumes:
      - ./docs:/app/docs
      - ./qdrant_storage:/app/qdrant_storage

Dockerfile

FROM python:3.11-slim

# 安装系统依赖（Tesseract OCR）
RUN apt-get update && apt-get install -y \
    tesseract-ocr \
    tesseract-ocr-chi-sim \
    tesseract-ocr-eng \
    poppler-utils \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制代码
COPY . .

# 暴露端口
EXPOSE 8501

# 启动命令
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

快速启动脚本

#!/bin/bash
# quick_start.sh

set -e  # 遇到错误立即退出

echo "🚀 启动 Agentic RAG 系统..."

# 检查环境变量
if [ -z "$OPENAI_API_KEY" ]; then
    echo "❌ 错误：请设置 OPENAI_API_KEY 环境变量"
    exit 1
fi

# 启动服务
echo "📦 启动 Docker 容器..."
docker-compose up -d

# 等待 Qdrant 启动
echo "⏳ 等待 Qdrant 启动..."
sleep 5

# 摄入文档
echo "📄 摄入文档到向量数据库..."
python ingest.py --path ./docs

# 启动界面
echo "✅ 启动完成！访问 http://localhost:8501"

使用方法：

# 1. 设置环境变量
export OPENAI_API_KEY="sk-..."

# 2. 一键启动
bash quick_start.sh

性能压测：从理论到实战的三轮迭代

第一轮压测：系统崩溃（50 并发）

压测工具：Locust

# locustfile.py
from locust import HttpUser, task, between
import random

class RAGUser(HttpUser):
    wait_time = between(1, 3)
    
    @task
    def query(self):
        questions = [
            "Transformer 的注意力机制是什么？",
            "如何优化 RAG 系统的检索质量？",
            "CRAG 相比传统 RAG 有什么改进？"
        ]
        self.client.post("/query", json={
            "question": random.choice(questions)
        })

压测命令：

# 启动 Locust
locust -f locustfile.py --host=http://localhost:8501

# 在 Web UI 中设置：
# - 用户数：50
# - 每秒启动用户数：10

结果：灾难性失败

并发数: 50
持续时间: 2 分钟
成功率: 23%  ← 大量请求失败
P50 延迟: 8.2s
P95 延迟: 45s  ← 完全不可接受
P99 延迟: 超时（60s）
错误: 
  - ConnectionError: 38%
  - TimeoutError: 29%
  - MemoryError: 10%

问题分析：

内存溢出：

# 查看内存使用
docker stats

CONTAINER ID   NAME    CPU %   MEM USAGE / LIMIT   MEM %
abc123         app     98%     7.8GB / 8GB         97.5%  ← 接近上限

原因：每个请求都加载 BGE-Reranker 模型（1.3GB），50 个并发 = 65GB 内存需求

连接池耗尽：

# 错误日志
ConnectionError: HTTPConnectionPool(host='localhost', port=6333): 
Max retries exceeded with url: /collections/documents/points/search

原因：Qdrant 默认连接池大小 10，50 并发超出限制

OpenAI API 限流：

RateLimitError: Rate limit reached for gpt-4o-mini in organization org-xxx 
on requests per minute (RPM): Limit 500, Used 498, Requested 1

原因：50 并发 × 2 次 API 调用（评估 + 生成）= 100 RPM，超出限制

第二轮压测：优化后重测（50 并发）

优化措施：

Reranker 单例模式（已实现）
Qdrant 连接池扩容：

from qdrant_client import QdrantClient

client = QdrantClient(
    host="localhost",
    port=6333,
    timeout=30,
    # 扩大连接池
    grpc_options={
        'grpc.max_send_message_length': 100 * 1024 * 1024,
        'grpc.max_receive_message_length': 100 * 1024 * 1024,
        'grpc.keepalive_time_ms': 10000,
        'grpc.keepalive_timeout_ms': 5000,
    }
)

OpenAI API 限流控制：

import asyncio
from asyncio import Semaphore

class RateLimiter:
    def __init__(self, max_rpm=450):  # 留 10% 余量
        self.semaphore = Semaphore(max_rpm // 60)  # 每秒最多请求数
        self.last_reset = asyncio.get_event_loop().time()
    
    async def acquire(self):
        await self.semaphore.acquire()
        # 每秒重置一次
        current_time = asyncio.get_event_loop().time()
        if current_time - self.last_reset >= 1:
            self.last_reset = current_time
            # 释放所有许可
            for _ in range(self.semaphore._value):
                self.semaphore.release()

# 使用
rate_limiter = RateLimiter(max_rpm=450)

async def call_openai_with_limit(prompt):
    await rate_limiter.acquire()
    response = await client.chat.completions.create(...)
    return response

第二轮结果：显著改善

并发数: 50
持续时间: 5 分钟
成功率: 98.5%  ← 大幅提升
P50 延迟: 2.8s
P95 延迟: 4.2s  ← 可接受
P99 延迟: 6.8s
错误: 
  - TimeoutError: 1.5%（偶发）

第三轮压测：极限测试（100 并发）

目标：找到系统的真实上限

结果：接近极限

并发数: 100
持续时间: 5 分钟
成功率: 96.2%
P50 延迟: 4.5s
P95 延迟: 8.9s  ← 开始劣化
P99 延迟: 15.2s
CPU: 95%  ← 接近饱和
内存: 6.8GB / 8GB

瓶颈分析：

CPU 饱和：Reranker 推理占用大量 CPU
OpenAI API 限流：100 并发接近 RPM 上限
Qdrant 查询排队：向量检索开始出现排队

结论：

单实例最佳并发：30-50
单实例理论 QPS：~20（基于 P95 延迟 4.2s）
扩展建议：超过 50 并发需要水平扩展

压测数据汇总

并发数	成功率	P50	P95	P99	CPU	内存	建议
10	99.9%	1.8s	2.3s	3.1s	50%	3GB	✅ 理想
30	99.5%	2.2s	3.2s	4.5s	70%	4.5GB	✅ 推荐
50	98.5%	2.8s	4.2s	6.8s	85%	5.8GB	⚠️ 接近上限
100	96.2%	4.5s	8.9s	15.2s	95%	6.8GB	❌ 需要扩展

踩坑清单：生产环境的血泪教训

坑 1：Docker 容器内无法访问宿主的 Qdrant

现象：应用启动后报错

Traceback (most recent call last):
  File "/app/main.py", line 15, in <module>
    client = QdrantClient(host="localhost", port=6333)
  File "/usr/local/lib/python3.11/site-packages/qdrant_client/qdrant_client.py", line 89, in __init__
    self._client = self._init_client()
  File "/usr/local/lib/python3.11/site-packages/qdrant_client/qdrant_client.py", line 156, in _init_client
    raise ConnectionError(f"Cannot connect to Qdrant at {self.host}:{self.port}")
ConnectionError: Cannot connect to Qdrant at localhost:6333

排查过程：

# 1. 检查 Qdrant 是否在运行
docker ps | grep qdrant
# 输出：qdrant 容器正在运行

# 2. 在宿主机测试连接
curl http://localhost:6333/collections
# 输出：正常返回 JSON

# 3. 进入应用容器测试
docker exec -it app bash
curl http://localhost:6333/collections
# 输出：Connection refused

# 问题定位：容器内的 localhost 指向容器自己，而不是宿主机

解决方案：

方案 1：使用容器名（推荐）

# docker-compose.yml
services:
  qdrant:
    container_name: qdrant  # 指定容器名
    image: qdrant/qdrant
    ports:
      - "6333:6333"
  
  app:
    environment:
      - QDRANT_HOST=qdrant  # 使用容器名，而不是 localhost
      - QDRANT_PORT=6333
    depends_on:
      - qdrant

方案 2：使用 host.docker.internal（仅 Mac/Windows）

# 仅在开发环境使用
client = QdrantClient(
    host="host.docker.internal",  # 指向宿主机
    port=6333
)

方案 3：使用 host 网络模式（不推荐）

# docker-compose.yml
services:
  app:
    network_mode: "host"  # 共享宿主机网络

教训：容器网络隔离是常见陷阱，优先使用容器名通信

坑 2：Tesseract 在容器内缺失语言包

现象：OCR 识别中文失败

Traceback (most recent call last):
  File "/app/parser.py", line 45, in _parse_with_ocr
    text = pytesseract.image_to_string(image, lang='chi_sim+eng')
  File "/usr/local/lib/python3.11/site-packages/pytesseract/pytesseract.py", line 423, in image_to_string
    return run_and_get_output(image, 'txt', lang, config, nice, timeout)
  File "/usr/local/lib/python3.11/site-packages/pytesseract/pytesseract.py", line 291, in run_and_get_output
    raise TesseractError(status, get_errors(error_string))
pytesseract.pytesseract.TesseractError: (1, 'Error opening data file /usr/share/tesseract-ocr/4.00/tessdata/chi_sim.traineddata')

排查过程：

# 1. 进入容器检查
docker exec -it app bash

# 2. 检查 Tesseract 是否安装
tesseract --version
# 输出：tesseract 4.1.1

# 3. 检查可用语言
tesseract --list-langs
# 输出：
# List of available languages (1):
# eng  ← 只有英文

# 4. 检查语言包目录
ls /usr/share/tesseract-ocr/4.00/tessdata/
# 输出：eng.traineddata  ← 缺少中文语言包

解决方案：

在 Dockerfile 中安装中文语言包

FROM python:3.11-slim

# 安装 Tesseract 和语言包
RUN apt-get update && apt-get install -y \
    tesseract-ocr \
    tesseract-ocr-chi-sim \  # 简体中文
    tesseract-ocr-chi-tra \  # 繁体中文
    tesseract-ocr-eng \      # 英文
    poppler-utils \
    && rm -rf /var/lib/apt/lists/*

# 验证安装
RUN tesseract --list-langs | grep chi_sim || exit 1

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["streamlit", "run", "app.py"]

验证：

# 重新构建镜像
docker build -t rag-app .

# 进入容器验证
docker run -it rag-app bash
tesseract --list-langs
# 输出：
# List of available languages (3):
# chi_sim
# chi_tra
# eng

教训：容器镜像要包含所有运行时依赖，不能依赖宿主机环境

坑 3：大文件上传超时（50MB PDF）

现象：用户上传大文件时，页面卡死后报错

streamlit.errors.StreamlitAPIException: 
Streamlit server has stopped responding. 
Please refresh the page.

排查过程：

# 1. 查看 Streamlit 日志
docker logs app

# 输出：
# 2024-04-21 10:23:15.234 | INFO | Received file upload: report.pdf (52.3 MB)
# 2024-04-21 10:23:15.456 | INFO | Starting PDF parsing...
# 2024-04-21 10:24:45.123 | WARNING | Request timeout after 90 seconds
# 2024-04-21 10:24:45.234 | ERROR | Connection closed by client

# 2. 测试 PDF 解析时间
python -c "
from parser import PDFParser
import time
parser = PDFParser()
start = time.time()
text = parser.parse('report.pdf')
print(f'解析耗时: {time.time() - start:.2f}s')
"
# 输出：解析耗时: 127.34s  ← 超过 Streamlit 默认超时（90s）

问题分析：

Streamlit 默认请求超时 90 秒
大文件 OCR 解析需要 120+ 秒
同步处理阻塞主线程，用户体验差

解决方案：异步处理 + 轮询

# 1. 使用 Celery 异步处理
from celery import Celery
import redis

celery_app = Celery('tasks', broker='redis://localhost:6379/0')

@celery_app.task
def parse_pdf_async(file_path):
    """异步解析 PDF"""
    parser = PDFParser()
    text = parser.parse(file_path)
    return text

# 2. Streamlit 前端轮询
import streamlit as st
import time

uploaded_file = st.file_uploader("上传 PDF", type="pdf")

if uploaded_file:
    # 保存文件
    file_path = f"/tmp/{uploaded_file.name}"
    with open(file_path, "wb") as f:
        f.write(uploaded_file.getbuffer())
    
    # 提交异步任务
    task = parse_pdf_async.delay(file_path)
    st.info(f"正在解析文档... (任务 ID: {task.id})")
    
    # 轮询结果
    progress_bar = st.progress(0)
    status_text = st.empty()
    
    while not task.ready():
        time.sleep(2)
        progress_bar.progress(min(task.state.get('progress', 0), 99))
        status_text.text(f"状态: {task.state}")
    
    # 获取结果
    if task.successful():
        text = task.result
        st.success(f"解析完成！提取了 {len(text)} 字符")
        st.text_area("文档内容", text, height=300)
    else:
        st.error(f"解析失败: {task.info}")

docker-compose.yml 配置：

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  
  celery:
    build: .
    command: celery -A tasks worker --loglevel=info
    depends_on:
      - redis
    volumes:
      - ./tmp:/tmp
  
  app:
    build: .
    depends_on:
      - redis
      - celery
    environment:
      - CELERY_BROKER_URL=redis://redis:6379/0

效果：

用户体验：实时进度反馈，不会卡死
系统稳定性：异步处理不阻塞主线程
可扩展性：可以启动多个 Celery worker 并行处理

教训：长时间任务必须异步化，同步处理是生产环境大忌

坑 4：环境变量泄露到 Git

现象：CI/CD 构建失败

# GitHub Actions 日志
Error: OpenAI API key is invalid
Status: 401 Unauthorized

排查过程：

# 1. 检查代码仓库
git log --all --full-history -- .env
# 输出：
# commit abc123...
# Date: 2024-04-20
# Add .env file with API keys  ← 不小心提交了 .env

# 2. 查看 .env 内容
git show abc123:.env
# 输出：
# OPENAI_API_KEY=sk-proj-xxx...  ← API key 泄露！

# 3. 检查 .gitignore
cat .gitignore
# 输出：（空文件）← 没有配置 .gitignore

紧急处理：

# 1. 立即撤销 OpenAI API key
# 登录 OpenAI 平台 → API Keys → Revoke

# 2. 从 Git 历史中删除敏感文件
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" \
  --prune-empty --tag-name-filter cat -- --all

# 3. 强制推送（警告：会改写历史）
git push origin --force --all

# 4. 通知团队成员重新 clone 仓库

预防措施：

配置 .gitignore：

# .gitignore
.env
.env.*
*.env
.env.local
.env.production

# 其他敏感文件
*.pem
*.key
credentials.json
secrets.yaml

使用 python-dotenv：

# config.py
from dotenv import load_dotenv
import os

# 加载环境变量
load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY not found in environment")

使用 pre-commit hook 检测：

# .git/hooks/pre-commit
#!/bin/bash

# 检查是否包含敏感文件
if git diff --cached --name-only | grep -E '\.(env|pem|key)$'; then
    echo "错误：尝试提交敏感文件！"
    echo "请检查 .gitignore 配置"
    exit 1
fi

# 检查是否包含 API key 模式
if git diff --cached | grep -E 'sk-[a-zA-Z0-9]{48}'; then
    echo "错误：检测到 OpenAI API key！"
    echo "请使用环境变量而不是硬编码"
    exit 1
fi

使用 git-secrets：

# 安装 git-secrets
brew install git-secrets  # macOS
# 或
apt-get install git-secrets  # Linux

# 配置
git secrets --install
git secrets --register-aws
git secrets --add 'sk-[a-zA-Z0-9]{48}'  # OpenAI API key 模式

教训：

永远不要提交 .env 文件
使用 pre-commit hook 作为最后一道防线
定期审计 Git 历史中的敏感信息

坑 5：Streamlit 端口冲突

现象：应用启动失败

docker-compose up

# 输出：
# app_1  | Error: Address already in use
# app_1  | Port 8501 is already allocated
# app_1 exited with code 1

排查过程：

# 1. 检查端口占用
lsof -i :8501
# 输出：
# COMMAND   PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# streamlit 1234  user   3u  IPv4  0x...      0t0  TCP *:8501 (LISTEN)

# 2. 查看进程详情
ps aux | grep 1234
# 输出：之前启动的 Streamlit 进程还在运行

# 3. 杀死进程
kill 1234

# 或者查找所有 Streamlit 进程
pkill -f "streamlit run"

解决方案：

方案 1：修改端口

# docker-compose.yml
services:
  app:
    ports:
      - "8502:8501"  # 宿主机 8502 → 容器 8501

方案 2：启动前检查并清理

# start.sh
#!/bin/bash

# 检查端口是否被占用
if lsof -Pi :8501 -sTCP:LISTEN -t >/dev/null ; then
    echo "端口 8501 已被占用，正在清理..."
    kill $(lsof -t -i:8501)
    sleep 2
fi

# 启动应用
docker-compose up -d

方案 3：使用动态端口

# app.py
import streamlit as st
import socket

def find_free_port():
    """查找可用端口"""
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.bind(('', 0))
        s.listen(1)
        port = s.getsockname()[1]
    return port

if __name__ == "__main__":
    port = find_free_port()
    print(f"启动在端口 {port}")
    st.set_option('server.port', port)

教训：生产环境要有端口管理策略，避免冲突

未来优化方向

短期（1-2 个月）

添加真实测试数据
当前测试集只有 20 对，需要扩展到 100+ 对，覆盖更多边缘情况。
录制演示 GIF
在 README 中添加演示动图，让用户快速了解系统功能。
完善文档
- API 文档（Swagger）
- 部署文档（AWS/GCP/Azure）
- 故障排查指南

中期（3-6 个月）

集成 GraphRAG
利用论文引用关系构建知识图谱，支持多跳推理。
微调 BGE-Reranker
针对 AI 安全领域微调，提升领域内的重排序效果。
多模态检索
支持图片、表格的检索（用 CLIP、LayoutLM）。

长期（6-12 个月）

多轮对话记忆
用 LangGraph 的 Checkpointer 实现对话历史管理。
分布式部署
- 负载均衡（Nginx）
- 多实例部署（Kubernetes）
- 自动扩缩容（HPA）
A/B 测试框架
对比不同检索策略、切片算法的效果，持续优化。
监控告警
- Prometheus 采集指标（延迟、QPS、错误率）
- Grafana 可视化
- 告警规则（延迟 > 5s、错误率 > 5%）

系列总结

经过 4 篇文章的深入解析，我们完整地构建了一个生产级的 Agentic RAG 系统。回顾一下每篇文章的核心贡献：

篇序	主题	核心提升	关键技术
第 1 篇	CRAG 置信度路由	Context Recall +26%	置信度评估、查询重写、Web 回退
第 2 篇	RRF + BGE 重排序	Recall@10 +22%	混合检索、排名融合、Cross-Encoder
第 3 篇	语义切片 + Ragas	可量化的评估体系	Embedding 相似度、自动化评估
第 4 篇	生产部署	P95 2.3s，覆盖率 95%	三级降级、性能优化、Docker

最终效果：

检索质量：Context Recall 0.78，Recall@10 0.82
生成质量：Faithfulness 0.85，Answer Relevancy 0.82
性能：P95 延迟 2.3s，单实例 QPS 150+
鲁棒性：PDF 解析覆盖率 95%

核心经验：

RAG 不是"检索 + 生成"那么简单：需要评估、路由、降级、优化等多个环节配合。
量化评估是持续优化的基础：没有 Ragas 这样的评估体系，优化就是"盲人摸象"。
生产环境和实验室差异巨大：边缘情况、并发压力、部署复杂度都需要提前考虑。
开源工具是最好的老师：LangGraph、Qdrant、BGE、Ragas...站在巨人的肩膀上，才能快速迭代。

致谢与开源

开源地址：github.com/Yunzenn/age…

如果这个系列对你有帮助，欢迎：

⭐ Star 支持
🐛 提 Issue 反馈问题
🔧 提 PR 贡献代码
📢 分享给更多人

特别感谢：

LangChain 团队（LangGraph 框架）
Qdrant 团队（向量数据库）
智源研究院（BGE 系列模型）
Ragas 团队（评估框架）
IBM（Docling 文档解析）

让我们一起探索 RAG 的更多可能性！

本文是"从零开始理解 Agentic RAG"系列的第 4 篇（收官篇），聚焦生产部署。感谢一路陪伴，期待在开源社区与你相遇。