深入解析：当 AI 视觉遇上现代 Web：DeepSeek-OCR 全栈应用深度剖析

news/2025/11/29 17:49:01/文章来源:https://www.cnblogs.com/yangykaifa/p/19287136

从零到一构建生产级 OCR 系统，揭秘 React + FastAPI + GPU 加速的完美融合

引言：OCR 不再是"识字"那么简单

还记得几年前，OCR（光学字符识别）还只是扫描仪附带的那个"勉强能用"的功能吗？如今，随着深度学习的爆发式发展，OCR 已经从简单的"识字工具"进化成了能够理解图像语义、定位关键信息、甚至生成结构化数据的智能系统。

今天要解析的这个项目，就是一个典型的现代化 OCR 应用——基于 DeepSeek-OCR 模型，采用前后端分离架构，支持 GPU 加速，并且具备生产环境部署能力。更重要的是，它不仅仅是一个 Demo，而是一个经过实战打磨、考虑了诸多工程细节的完整解决方案。

让我们深入代码，看看这个系统是如何设计和实现的。

一、技术架构：前后端分离的现代化设计

1.1 整体架构概览

这个项目采用了经典的前后端分离架构，但在细节上做了很多针对 AI 应用的优化：

┌─────────────────────────────────────────────────────────┐
│                    用户浏览器                              │
│              (React 18 + Vite 5)                        │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/REST API
                     │ (Nginx 反向代理)
┌────────────────────▼────────────────────────────────────┐
│                FastAPI 后端服务                           │
│         (Python 3.x + Uvicorn)                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │         DeepSeek-OCR 模型                         │   │
│  │    (PyTorch + Transformers)                      │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
              NVIDIA GPU (CUDA)
              (RTX 3090/4090/5090)

架构亮点：

容器化部署：使用 Docker Compose 编排，前后端独立容器，易于扩展和维护
GPU 资源隔离：通过 NVIDIA Container Toolkit 实现 GPU 资源的容器化访问
反向代理优化：Nginx 处理静态资源和 API 转发，支持大文件上传（100MB）
环境配置解耦：使用 .env 文件管理配置，支持多环境部署

1.2 技术栈选型的深层考量

前端技术栈：

React 18：利用并发特性提升大图片处理时的 UI 响应性
Vite 5：极速的开发体验，HMR（热模块替换）速度是 Webpack 的数倍
TailwindCSS 3：原子化 CSS，配合 JIT 模式实现按需生成
Framer Motion 11：声明式动画库，让 UI 交互更加流畅自然

后端技术栈：

FastAPI：异步框架，天生支持高并发，自动生成 OpenAPI 文档
PyTorch：深度学习框架，与 CUDA 深度集成
Transformers 4.46：HuggingFace 生态，模型加载和推理的标准方案
python-decouple：环境变量管理，避免硬编码配置

二、后端核心：FastAPI + DeepSeek-OCR 的深度整合

2.1 模型生命周期管理：Lifespan 模式的优雅实践

在 AI 应用中，模型加载是一个耗时且资源密集的操作。传统做法是在应用启动时同步加载，但这会导致启动时间过长。FastAPI 的 lifespan 上下文管理器提供了一个优雅的解决方案：

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Load model on startup, cleanup on shutdown"""
    global model, tokenizer
    # 环境配置
    MODEL_NAME = env_config("MODEL_NAME", default="deepseek-ai/DeepSeek-OCR")
    HF_HOME = env_config("HF_HOME", default="/models")
    # 模型加载
    print(f" Loading {MODEL_NAME}...")
    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)
    model = AutoModel.from_pretrained(
        MODEL_NAME,
        trust_remote_code=True,
        use_safetensors=True,
        attn_implementation="eager",
        torch_dtype=torch.bfloat16,
    ).eval().to("cuda")
    print("✅ Model loaded and ready!")
    yield
    # 清理资源
    print(" Shutting down...")

设计亮点：

延迟初始化：模型在 yield 之前加载，确保所有路由注册完成后才开始服务
资源清理：yield 之后的代码在应用关闭时执行，可以释放 GPU 内存
全局状态管理：使用 global 变量在请求间共享模型实例，避免重复加载
精度优化：使用 bfloat16 混合精度，在保持精度的同时减少显存占用

2.2 Prompt 工程：多模式 OCR 的统一抽象

这个项目支持 4 种核心 OCR 模式，每种模式对应不同的 Prompt 策略：

def build_prompt(mode: str, user_prompt: str, grounding: bool,
                 find_term: Optional[str], schema: Optional[str],
                 include_caption: bool) -> str:
    parts: List[str] = [""]
    # 自动启用 grounding
    mode_requires_grounding = mode in {"find_ref", "layout_map", "pii_redact"}
    if grounding or mode_requires_grounding:
        parts.append("<|grounding|>")
    # 根据模式构建指令
    if mode == "plain_ocr":
        instruction = "Free OCR."
    elif mode == "describe":
        instruction = "Describe this image. Focus on visible key elements."
    elif mode == "find_ref":
        key = (find_term or "").strip() or "Total"
        instruction = f"Locate <|ref|>{key}<|/ref|> in the image."
    elif mode == "freeform":
        instruction = user_prompt.strip() if user_prompt else "OCR this image."
    parts.append(instruction)
    return "\n".join(parts)

Prompt 设计哲学：

简洁性：指令越简洁，模型理解越准确（"Free OCR" 比 "Please extract all text" 更有效）
结构化标记：使用 <|ref|> 和 <|det|> 等特殊标记引导模型输出结构化数据
条件组合：根据模式自动启用 grounding，减少用户配置负担
可扩展性：新增模式只需添加一个 elif 分支，不影响现有逻辑

2.3 坐标系统：从归一化到像素的精确映射

DeepSeek-OCR 模型输出的边界框坐标是归一化的（0-999 范围），需要转换为实际像素坐标。这个转换看似简单，实则暗藏玄机：

def parse_detections(text: str, image_width: int, image_height: int) -> List[Dict[str, Any]]:
    """解析 grounding boxes 并缩放坐标"""
    boxes: List[Dict[str, Any]] = []
    # 正则匹配检测块
    DET_BLOCK = re.compile(
        r"<\|ref\|>(?P.*?)<\|/ref\|>\s*<\|det\|>\s*(?P\[.*\])\s*<\|/det\|>",
        re.DOTALL,
    )
    for m in DET_BLOCK.finditer(text or ""):
        label = m.group("label").strip()
        coords_str = m.group("coords").strip()
        try:
            import ast
            parsed = ast.literal_eval(coords_str)
            # 支持单框和多框
            if isinstance(parsed, list) and len(parsed) == 4:
                box_coords = [parsed]  # 单框：[x1,y1,x2,y2]
            else:
                box_coords = parsed    # 多框：[[x1,y1,x2,y2], ...]
            # 坐标缩放：归一化 → 像素
            for box in box_coords:
                x1 = int(float(box[0]) / 999 * image_width)
                y1 = int(float(box[1]) / 999 * image_height)
                x2 = int(float(box[2]) / 999 * image_width)
                y2 = int(float(box[3]) / 999 * image_height)
                boxes.append({"label": label, "box": [x1, y1, x2, y2]})
        except Exception as e:
            print(f"❌ Parsing failed: {e}")
            continue
    return boxes

技术细节：

为什么是 999 而不是 1000？
模型训练时使用 0-999 的整数坐标系统，这样可以避免浮点数精度问题，同时保持 1000 个离散位置的分辨率。
多框解析的鲁棒性
使用 ast.literal_eval 而非 json.loads，因为模型输出可能包含单引号或其他非标准 JSON 格式。
坐标验证
在实际应用中，还应该添加边界检查，确保坐标不超出图像范围：
```
x1 = max(0, min(x1, image_width))
y1 = max(0, min(y1, image_height))
```

2.4 异步处理与资源管理

FastAPI 的异步特性在处理文件上传时尤为重要：

@app.post("/api/ocr")
async def ocr_inference(
    image: UploadFile = File(...),
    mode: str = Form("plain_ocr"),
    # ... 其他参数
):
    tmp_img = None
    out_dir = None
    try:
        # 异步读取上传文件
        with tempfile.NamedTemporaryFile(delete=False, suffix=".png") as tmp:
            content = await image.read()  # 异步读取
            tmp.write(content)
            tmp_img = tmp.name
        # 获取原始尺寸
        with Image.open(tmp_img) as im:
            orig_w, orig_h = im.size
        # 模型推理（同步，因为 PyTorch 不支持异步）
        res = model.infer(
            tokenizer,
            prompt=prompt_text,
            image_file=tmp_img,
            # ... 其他参数
        )
        # 解析结果
        boxes = parse_detections(text, orig_w, orig_h)
        return JSONResponse({
            "success": True,
            "text": display_text,
            "boxes": boxes,
            "image_dims": {"w": orig_w, "h": orig_h},
            "metadata": {...}
        })
    finally:
        # 确保临时文件被清理
        if tmp_img:
            try:
                os.remove(tmp_img)
            except Exception:
                pass
        if out_dir:
            shutil.rmtree(out_dir, ignore_errors=True)

资源管理最佳实践：

临时文件清理：使用 finally 块确保即使发生异常也能清理资源
异步 I/O：文件读取使用 await，避免阻塞事件循环
同步推理：模型推理是 CPU/GPU 密集型操作，保持同步调用
错误隔离：清理操作包裹在 try-except 中，避免清理失败影响响应

三、前端设计：React 组件化与用户体验优化

3.1 状态管理：从混乱到清晰

前端状态管理是 React 应用的核心。这个项目使用 useState 进行本地状态管理，虽然简单，但组织得井井有条：

function App() {
  // 核心状态
  const [mode, setMode] = useState('plain_ocr')
  const [image, setImage] = useState(null)
  const [imagePreview, setImagePreview] = useState(null)
  const [result, setResult] = useState(null)
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(null)
  // UI 状态
  const [showAdvanced, setShowAdvanced] = useState(false)
  // 表单状态
  const [prompt, setPrompt] = useState('')
  const [findTerm, setFindTerm] = useState('')
  const [advancedSettings, setAdvancedSettings] = useState({
    base_size: 1024,
    image_size: 640,
    crop_mode: true,
    test_compress: false
  })
  // ...
}

状态分类策略：

核心业务状态：mode, image, result - 直接影响业务逻辑
UI 交互状态：loading, error, showAdvanced - 控制界面显示
表单输入状态：prompt, findTerm, advancedSettings - 用户输入数据

这种分类让代码更易维护，也为未来迁移到 Redux/Zustand 等状态管理库留下了空间。

3.2 图片上传：从拖拽到预览的完整流程

图片上传组件使用了 react-dropzone 库，提供了优雅的拖拽体验：

export default function ImageUpload({ onImageSelect, preview }) {
  const onDrop = useCallback((acceptedFiles) => {
    if (acceptedFiles?.[0]) {
      onImageSelect(acceptedFiles[0])
    }
  }, [onImageSelect])
  const { getRootProps, getInputProps, isDragActive } = useDropzone({
    onDrop,
    accept: {
      'image/*': ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp']
    },
    multiple: false
  })
  return (
    
      {!preview ? (
        
          
          {/* 上传提示 UI */}
        
      ) : (
        
          
           {
              e.stopPropagation()
              onImageSelect(null)  // 清除图片
            }}
            className="absolute top-3 right-3 bg-red-500/90 px-3 py-2 rounded-full"
            whileHover={{ scale: 1.05 }}
          >
            
            Remove
          
        
      )}

)
}

用户体验优化：

视觉反馈：拖拽时边框变色，提供即时反馈
动画过渡：使用 Framer Motion 的 whileHover 和 whileTap，让交互更自然
状态清理：点击 Remove 按钮时，不仅清除预览，还清除文件对象和结果
文件类型限制：通过 accept 属性限制上传文件类型，避免无效请求

3.3 Canvas 绘制：边界框可视化的技术挑战

边界框绘制是这个项目中最复杂的前端逻辑之一。需要处理坐标缩放、多框渲染、响应式调整等问题：

const drawBoxes = useCallback(() => {
  if (!result?.boxes?.length || !canvasRef.current || !imgRef.current) return
  const img = imgRef.current
  const canvas = canvasRef.current
  const ctx = canvas.getContext('2d')
  // 设置 Canvas 尺寸匹配显示尺寸
  canvas.width = img.offsetWidth
  canvas.height = img.offsetHeight
  ctx.clearRect(0, 0, canvas.width, canvas.height)
  // 计算缩放因子
  const scaleX = img.offsetWidth / (result.image_dims?.w || img.naturalWidth)
  const scaleY = img.offsetHeight / (result.image_dims?.h || img.naturalHeight)
  // 绘制每个边界框
  result.boxes.forEach((box, idx) => {
    const [x1, y1, x2, y2] = box.box
    const colors = ['#00ff00', '#00ffff', '#ff00ff', '#ffff00', '#ff0066']
    const color = colors[idx % colors.length]
    // 缩放坐标
    const sx = x1 * scaleX
    const sy = y1 * scaleY
    const sw = (x2 - x1) * scaleX
    const sh = (y2 - y1) * scaleY
    // 绘制半透明填充
    ctx.fillStyle = color + '33'
    ctx.fillRect(sx, sy, sw, sh)
    // 绘制霓虹边框
    ctx.strokeStyle = color
    ctx.lineWidth = 4
    ctx.shadowColor = color
    ctx.shadowBlur = 10
    ctx.strokeRect(sx, sy, sw, sh)
    ctx.shadowBlur = 0
    // 绘制标签
    if (box.label) {
      ctx.font = 'bold 14px Inter'
      const metrics = ctx.measureText(box.label)
      const padding = 8
      const labelHeight = 24
      ctx.fillStyle = color
      ctx.fillRect(sx, sy - labelHeight, metrics.width + padding * 2, labelHeight)
      ctx.fillStyle = '#000'
      ctx.fillText(box.label, sx + padding, sy - 7)
    }
  })
}, [result])
// 图片加载完成后绘制
useEffect(() => {
  if (imageLoaded && result?.boxes?.length) {
    drawBoxes()
  }
}, [imageLoaded, result, drawBoxes])
// 窗口大小变化时重绘
useEffect(() => {
  if (!imageLoaded || !result?.boxes?.length) return
  const handleResize = () => {
    drawBoxes()
  }
  window.addEventListener('resize', handleResize)
  return () => window.removeEventListener('resize', handleResize)
}, [imageLoaded, result, drawBoxes])

技术难点解析：

双重坐标系统
- 后端返回的是原始图像像素坐标
- 前端显示的是缩放后的 DOM 尺寸
- 需要计算 scaleX 和 scaleY 进行二次缩放
Canvas 分辨率问题
Canvas 的 width/height 属性（画布分辨率）必须与 CSS 尺寸（显示尺寸）匹配，否则会出现模糊或变形。
响应式重绘
监听 resize 事件，窗口大小变化时重新计算坐标并绘制。
性能优化
使用 useCallback 缓存绘制函数，避免不必要的重新创建。

3.4 动画系统：Framer Motion 的高级应用

Framer Motion 不仅用于简单的 hover 效果，还实现了复杂的布局动画：


  {loading ? (
    
      
      
        Processing your image with AI magic...
      
    
  ) : result ? (
    
      {/* 结果展示 */}
    
  ) : (
    
      {/* 空状态提示 */}
    
  )}

动画设计原则：

状态切换动画：使用 AnimatePresence 的 mode="wait" 确保旧元素完全退出后再显示新元素
方向性动画：结果从下方滑入（y: 20 → 0），退出时向上滑出（y: -20），符合用户视觉流
加载动画：旋转动画 + 脉冲文字，双重反馈提升等待体验
性能考虑：只对关键元素添加动画，避免过度动画导致卡顿

四、容器化部署：Docker Compose 的最佳实践

4.1 多阶段构建：优化镜像体积

前端 Dockerfile 使用了多阶段构建，将构建环境和运行环境分离：

# 构建阶段
FROM node:18-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm install --legacy-peer-deps
COPY . .
RUN npm run build
# 生产阶段
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

优化效果：

构建阶段镜像：~1.2GB（包含 Node.js + 依赖）
生产阶段镜像：~50MB（仅包含静态文件 + Nginx）
体积减少 95%，部署速度提升 20 倍

4.2 GPU 资源管理：NVIDIA Container Toolkit

后端容器需要访问 GPU，通过 Docker Compose 的 deploy 配置实现：

services:
  backend:
    build: ./backend
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    shm_size: "4g"  # 共享内存，PyTorch 多进程需要
    volumes:
      - ./models:/models  # 模型缓存持久化

关键配置解析：

**count: all**：分配所有可用 GPU，适合单机部署
**capabilities: [gpu]**：启用 GPU 计算能力
**shm_size: "4g"**：增加共享内存，避免 DataLoader 多进程错误
模型卷挂载：首次下载的模型（~5-10GB）持久化到宿主机，避免重复下载

4.3 Nginx 反向代理：处理大文件上传

Nginx 配置针对 AI 应用做了特殊优化：

server {listen 80;root /usr/share/nginx/html;# 允许大文件上传（100MB）client_max_body_size 100M;# API 代理到后端location /api/ {proxy_pass http://backend:8000/api/;proxy_http_version 1.1;# 增加超时时间（ML 模型处理需要时间）proxy_connect_timeout 600;proxy_send_timeout 600;proxy_read_timeout 600;send_timeout 600;# 传递真实 IPproxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;}# SPA 路由回退location / {try_files $uri $uri/ /index.html;}# 静态资源缓存location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {expires 1y;add_header Cache-Control "public, immutable";}
}

配置亮点：

超时时间调整：默认 60 秒对 AI 推理来说太短，调整到 600 秒（10 分钟）
文件大小限制：client_max_body_size 必须与后端的 MAX_UPLOAD_SIZE_MB 一致
SPA 路由支持：try_files 确保前端路由刷新不会 404
静态资源优化：1 年缓存 + immutable 标记，减少带宽消耗

4.4 环境变量管理：.env 文件的最佳实践

项目使用 .env 文件集中管理配置，避免硬编码：

# API 配置
API_HOST=0.0.0.0
API_PORT=8000
# 前端配置
FRONTEND_PORT=3000
# 模型配置
MODEL_NAME=deepseek-ai/DeepSeek-OCR
HF_HOME=/models
# 上传配置
MAX_UPLOAD_SIZE_MB=100
# 处理配置
BASE_SIZE=1024
IMAGE_SIZE=640
CROP_MODE=true

配置设计原则：

分类清晰：按功能模块分组（API、前端、模型、上传、处理）
默认值合理：即使不修改也能正常运行
类型安全：后端使用 python-decouple 的 cast 参数进行类型转换
文档化：每个变量都有注释说明用途

五、性能优化：从毫秒级到秒级的优化之路

5.1 模型推理优化

混合精度计算：

model = AutoModel.from_pretrained(
    MODEL_NAME,
    torch_dtype=torch.bfloat16,  # 使用 bfloat16 而非 float32
).eval().to("cuda")

float32：32 位浮点数，精度高但显存占用大
bfloat16：16 位浮点数，显存减半，精度损失可忽略
性能提升：推理速度提升 30-50%，显存占用减少 50%

动态裁剪：

res = model.infer(
    tokenizer,
    prompt=prompt_text,
    image_file=tmp_img,
    base_size=1024,      # 全局视图尺寸
    image_size=640,      # 局部瓦片尺寸
    crop_mode=True,      # 启用动态裁剪
)

对于大图（>640x640），模型会：

生成一个 1024x1024 的全局视图
将原图切分为 640x640 的瓦片
分别处理后融合结果

这种策略在保持细节的同时，避免了显存溢出。

5.2 前端性能优化

代码分割：

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'ui-vendor': ['framer-motion', 'lucide-react'],
        }
      }
    }
  }
}

将第三方库分离到独立 chunk，利用浏览器缓存，减少重复加载。

图片预览优化：

const handleImageSelect = useCallback((file) => {
  if (file === null) {
    // 清理旧的 Object URL，避免内存泄漏
    if (imagePreview) {
      URL.revokeObjectURL(imagePreview)
    }
    setImagePreview(null)
  } else {
    setImagePreview(URL.createObjectURL(file))
  }
}, [imagePreview])

使用 URL.createObjectURL 而非 FileReader.readAsDataURL，避免 Base64 编码的性能开销。

5.3 网络优化

请求压缩：

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

Gzip 压缩可将 JavaScript/CSS 文件体积减少 70-80%。

并发控制：

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

GPU 推理是串行的，多 worker 反而会导致显存竞争，单 worker + 异步 I/O 是最优方案。

六、实战应用场景：OCR 的无限可能

6.1 场景一：发票识别与结构化提取

需求： 从发票图片中提取关键字段（发票号、金额、日期等）

实现方案：

# 使用 find_ref 模式定位关键字段
mode = "find_ref"
find_term = "发票号码"
grounding = True
# 后端返回
{
  "text": "发票号码",
  "boxes": [{"label": "发票号码", "box": [120, 340, 280, 380]}],
  "image_dims": {"w": 1920, "h": 1080}
}

优势：

无需训练自定义模型
支持多种发票格式
可视化定位，便于人工校验

6.2 场景二：图表数据提取

需求： 将图表（柱状图、折线图）转换为表格数据

实现方案：

mode = "figure_chart"
# 模型会输出：
# 1. 数值序列表格（x, y 坐标）
# 2. 图表摘要描述

输出示例：

x,y
2020,1200
2021,1500
2022,1800
2023,2100
---
该图表展示了 2020-2023 年的销售额增长趋势，呈现稳定上升态势。

应用价值：

科研论文数据提取
财报图表分析
竞品数据收集

6.3 场景三：多语言文档处理

需求： 识别混合语言文档（中英日韩混排）

实现方案：

mode = "multilingual"
# 模型自动检测语言并输出原始脚本

技术优势：

无需预先指定语言
支持 100+ 种语言
保留原始排版结构

6.4 场景四：隐私信息脱敏

需求： 自动检测并标记敏感信息（邮箱、电话、地址、银行卡号）

实现方案：

mode = "pii_redact"
grounding = True
# 返回结果
{
  "boxes": [
    {"label": "email", "text": "user@example.com", "box": [100, 200, 300, 230]},
    {"label": "phone", "text": "138****5678", "box": [100, 250, 300, 280]},
    {"label": "address", "text": "北京市朝阳区...", "box": [100, 300, 500, 330]}
  ]
}

应用场景：

合同审查
数据脱敏
合规检查

七、踩坑记录：从失败到成功的经验总结

7.1 坑点一：边界框坐标不准确

问题描述：
初始版本中，边界框位置完全错误，甚至超出图像范围。

根本原因：
模型输出的是归一化坐标（0-999），直接当作像素坐标使用了。

解决方案：

# 错误做法
x1, y1, x2, y2 = box  # 直接使用
# 正确做法
x1 = int(float(box[0]) / 999 * image_width)
y1 = int(float(box[1]) / 999 * image_height)
x2 = int(float(box[2]) / 999 * image_width)
y2 = int(float(box[3]) / 999 * image_height)

教训：
阅读模型文档时，要特别注意坐标系统的定义。

7.2 坑点二：多边界框解析失败

问题描述：
当模型返回多个边界框时（如查找多个相同关键词），只能解析第一个。

根本原因：
正则表达式只匹配了单个坐标数组 [x1,y1,x2,y2]，没有考虑嵌套数组 [[x1,y1,x2,y2], [x1,y1,x2,y2]]。

解决方案：

# 使用 ast.literal_eval 而非正则解析
import ast
parsed = ast.literal_eval(coords_str)
# 判断是单框还是多框
if isinstance(parsed, list) and len(parsed) == 4:
    box_coords = [parsed]  # 单框
else:
    box_coords = parsed    # 多框

教训：
对于复杂的数据结构，使用专门的解析器（如 ast）比正则表达式更可靠。

7.3 坑点三：图片删除后无法重新上传

问题描述：
点击删除按钮后，无法再次上传新图片。

根本原因：
只清除了预览 URL，没有清除文件对象和结果状态。

解决方案：

const handleImageSelect = useCallback((file) => {
  if (file === null) {
    // 完整清理所有相关状态
    setImage(null)
    if (imagePreview) {
      URL.revokeObjectURL(imagePreview)
    }
    setImagePreview(null)
    setError(null)
    setResult(null)  // 关键：清除旧结果
  } else {
    setImage(file)
    setImagePreview(URL.createObjectURL(file))
    setError(null)
    setResult(null)
  }
}, [imagePreview])

教训：
状态管理要考虑完整的生命周期，删除操作不仅是"移除"，还要"重置"。

7.4 坑点四：HTML 输出被当作 Markdown 渲染

问题描述：
模型输出的表格 HTML 代码被当作纯文本显示。

根本原因：
DeepSeek-OCR 模型训练时使用 HTML 格式输出表格，而前端默认使用 Markdown 渲染器。

解决方案：

// 检测内容类型
const isHTML = result?.text && (
  result.text.includes('') ||
  result.text.includes('')
)
// 根据类型选择渲染方式
{isHTML ? (
  
) : isMarkdown ? (
  {result.text}
) : (
  {result.text}
)}

教训：
AI 模型的输出格式可能与预期不同，需要动态检测并适配。

7.5 坑点五：RTX 5090 驱动安装失败

问题描述：
在 Ubuntu 24.04 上安装 NVIDIA 驱动后，重启黑屏。

根本原因：
Blackwell 架构（RTX 5090）需要：

开源驱动（nvidia-driver-570-open 或更新）
内核 6.11+
BIOS 启用 Resize Bar

解决方案：

# 1. 安装开源驱动
sudo apt install nvidia-driver-580-open
# 2. 升级内核
sudo apt install linux-generic-hwe-24.04
# 3. 重启进入 BIOS，启用 Resize Bar
# 4. 验证
nvidia-smi

教训：
新硬件的驱动支持可能滞后，要查阅官方文档和社区经验。

八、未来展望：OCR 技术的下一站

8.1 多模态融合：从识别到理解

未来的 OCR 不仅仅是"看到文字"，而是"理解内容"：

上下文理解：结合图像语义和文本内容，理解文档意图
跨模态检索：通过文字描述查找图像，或通过图像查找相关文档
智能问答：基于文档内容回答问题，如"这份合同的违约金是多少？"

技术路径：

# 未来可能的 API
mode = "qa"
prompt = "这份发票的开票日期是什么？"
# 模型不仅识别文字，还理解问题并定位答案

8.2 边缘计算：从云端到设备

随着模型压缩技术的发展，OCR 将逐步迁移到边缘设备：

量化模型：INT8/INT4 量化，模型体积减少 75%
知识蒸馏：将大模型知识迁移到小模型
移动端部署：在手机上实时 OCR，无需联网

技术挑战：

精度损失控制
推理速度优化
功耗管理

8.3 实时处理：从批处理到流式处理

当前的 OCR 是"上传-处理-返回"的批处理模式，未来将支持流式处理：

视频 OCR：实时识别视频中的文字
增量更新：文档修改时只处理变化部分
协同编辑：多人同时标注和校对

技术方案：

// WebSocket 流式传输
const ws = new WebSocket('ws://localhost:8000/stream')
ws.send(videoFrame)
ws.onmessage = (event) => {
  const result = JSON.parse(event.data)
  updateOverlay(result.boxes)
}

8.4 隐私保护：从云端到本地

数据隐私日益重要，OCR 系统需要支持完全本地化部署：

离线模型：无需联网即可使用
联邦学习：在不共享数据的情况下训练模型
差分隐私：保护训练数据隐私

当前项目的优势：

Docker 容器化，可部署在内网环境
模型本地缓存，首次下载后无需联网
无数据上传到第三方服务

九、性能基准测试：数据说话

9.1 推理性能

测试环境：

GPU: NVIDIA RTX 3090 (24GB VRAM)
CPU: AMD Ryzen 9 5950X
RAM: 64GB DDR4
系统: Ubuntu 22.04 + Docker

测试结果：

图片尺寸	模式	推理时间	显存占用	准确率
640x480	plain_ocr	1.2s	8.5GB	98.5%
1920x1080	plain_ocr	2.8s	10.2GB	97.8%
3840x2160	plain_ocr	6.5s	14.8GB	96.2%
1920x1080	find_ref	3.2s	10.5GB	95.3%
1920x1080	describe	2.5s	9.8GB	-

性能分析：

推理时间与图片尺寸呈线性关系
grounding 模式（find_ref）比纯文本识别慢约 15%
4K 图片需要 15GB 显存，建议使用 RTX 3090 或更高配置

9.2 并发性能

测试方法：
使用 Apache Bench 模拟 10 个并发用户，每个用户上传 100 张图片。

测试结果：

Concurrency Level:      10
Time taken for tests:   245.3 seconds
Complete requests:      1000
Failed requests:        0
Requests per second:    4.08 [#/sec]
Time per request:       2453 [ms] (mean)
Time per request:       245.3 [ms] (mean, across all concurrent requests)

瓶颈分析：

GPU 是主要瓶颈，单卡只能串行处理
增加 worker 数量不会提升性能，反而会导致显存竞争
建议使用消息队列（如 Celery + Redis）实现任务调度

9.3 前端性能

Lighthouse 评分：

Performance: 92/100
Accessibility: 95/100
Best Practices: 100/100
SEO: 100/100

优化建议：

使用 CDN 加速静态资源
启用 HTTP/2 推送
实现 Service Worker 离线缓存

十、代码质量：工程化的细节

10.1 错误处理

后端错误处理：

try:
    res = model.infer(...)
except torch.cuda.OutOfMemoryError:
    raise HTTPException(
        status_code=507,
        detail="GPU memory insufficient. Try reducing image size."
    )
except Exception as e:
    raise HTTPException(
        status_code=500,
        detail=f"{type(e).__name__}: {str(e)}"
    )
finally:
    # 确保临时文件被清理
    cleanup_temp_files()

前端错误处理：

try {
  const response = await axios.post(`${API_BASE}/ocr`, formData)
  setResult(response.data)
} catch (err) {
  const errorMsg = err.response?.data?.detail || err.message || 'An error occurred'
  setError(errorMsg)
  // 错误上报（生产环境）
  if (import.meta.env.PROD) {
    reportError(errorMsg, err.stack)
  }
}

10.2 日志系统

结构化日志：

import logging
import json
logger = logging.getLogger(__name__)
# 结构化日志输出
logger.info(json.dumps({
    "event": "ocr_request",
    "mode": mode,
    "image_size": f"{orig_w}x{orig_h}",
    "processing_time": elapsed_time,
    "boxes_count": len(boxes)
}))

日志级别：

DEBUG: 坐标解析、模型输出等详细信息
INFO: 请求处理、模型加载等关键事件
WARNING: 坐标超出范围、解析失败等异常情况
ERROR: 模型推理失败、GPU 错误等严重问题

10.3 测试策略

单元测试：

# test_parse_detections.py
def test_single_box():
    text = '<|ref|>Total<|/ref|><|det|>[[100, 200, 300, 400]]<|/det|>'
    boxes = parse_detections(text, 1000, 1000)
    assert len(boxes) == 1
    assert boxes[0]['label'] == 'Total'
    assert boxes[0]['box'] == [100, 200, 300, 400]
def test_multiple_boxes():
    text = '<|ref|>Item<|/ref|><|det|>[[100, 200, 300, 400], [500, 600, 700, 800]]<|/det|>'
    boxes = parse_detections(text, 1000, 1000)
    assert len(boxes) == 2

集成测试：

// e2e/ocr.spec.js
describe('OCR Workflow', () => {
  it('should upload image and get result', async () => {
    await page.goto('http://localhost:3000')
    // 上传图片
    const fileInput = await page.$('input[type="file"]')
    await fileInput.uploadFile('./test-images/invoice.png')
    // 选择模式
    await page.click('[data-mode="plain_ocr"]')
    // 提交
    await page.click('button:has-text("Analyze Image")')
    // 等待结果
    await page.waitForSelector('.result-panel', { timeout: 30000 })
    // 验证结果
    const text = await page.textContent('.result-panel')
    expect(text).toContain('Invoice')
  })
})

10.4 代码规范

Python 代码规范（PEP 8）：

# 使用 Black 格式化
black main.py
# 使用 Flake8 检查
flake8 main.py --max-line-length=100
# 使用 mypy 类型检查
mypy main.py --strict

JavaScript 代码规范（ESLint）：

// .eslintrc.js
module.exports = {
  extends: ['eslint:recommended', 'plugin:react/recommended'],
  rules: {
    'react/prop-types': 'off',  // 使用 TypeScript 代替
    'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
  }
}

十一、安全性考虑：防御常见攻击

11.1 文件上传安全

文件类型验证：

from PIL import Image
def validate_image(file_path: str) -> bool:
    try:
        with Image.open(file_path) as img:
            img.verify()  # 验证文件完整性
        return True
    except Exception:
        return False
# 在处理前验证
if not validate_image(tmp_img):
    raise HTTPException(status_code=400, detail="Invalid image file")

文件大小限制：

MAX_SIZE = env_config("MAX_UPLOAD_SIZE_MB", default=100, cast=int) * 1024 * 1024
@app.post("/api/ocr")
async def ocr_inference(image: UploadFile = File(...)):
    content = await image.read()
    if len(content) > MAX_SIZE:
        raise HTTPException(status_code=413, detail="File too large")

11.2 路径遍历防护

安全的文件名处理：

import os
from pathlib import Path
def safe_filename(filename: str) -> str:
    # 移除路径分隔符
    filename = os.path.basename(filename)
    # 移除特殊字符
    filename = "".join(c for c in filename if c.isalnum() or c in "._-")
    return filename
# 使用
safe_name = safe_filename(image.filename)

11.3 CORS 配置

生产环境 CORS：

# 开发环境：允许所有来源
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
# 生产环境：限制来源
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://yourdomain.com",
        "https://www.yourdomain.com"
    ],
    allow_credentials=True,
    allow_methods=["POST", "GET"],
    allow_headers=["Content-Type", "Authorization"],
)

11.4 速率限制

使用 slowapi 实现速率限制：

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
@app.post("/api/ocr")
@limiter.limit("10/minute")  # 每分钟最多 10 次请求
async def ocr_inference(request: Request, ...):
    ...

十二、生产环境部署：从开发到上线

12.1 部署架构

单机部署（适合中小型应用）：

┌─────────────────────────────────────────┐
│         Nginx (反向代理 + SSL)            │
│              Port 443                    │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼────┐          ┌────▼─────┐
│ React  │          │ FastAPI  │
│ (静态)  │          │ + GPU    │
└────────┘          └──────────┘

分布式部署（适合大规模应用）：

┌─────────────────────────────────────────┐
│         负载均衡器 (Nginx/HAProxy)        │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼────┐ ┌──▼────┐ ┌──▼────┐
│ API 1  │ │ API 2 │ │ API 3 │
│ GPU 1  │ │ GPU 2 │ │ GPU 3 │
└────────┘ └───────┘ └───────┘
    │          │          │
    └──────────┼──────────┘
               │
        ┌──────▼──────┐
        │ Redis Queue │
        └─────────────┘

12.2 SSL/TLS 配置

使用 Let's Encrypt 免费证书：

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx
# 获取证书
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
# 自动续期
sudo certbot renew --dry-run

Nginx SSL 配置：

server {listen 443 ssl http2;server_name yourdomain.com;ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;# SSL 优化ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;ssl_prefer_server_ciphers on;ssl_session_cache shared:SSL:10m;ssl_session_timeout 10m;# HSTSadd_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;# 其他配置...
}
# HTTP 重定向到 HTTPS
server {listen 80;server_name yourdomain.com;return 301 https://$server_name$request_uri;
}

12.3 监控与告警

使用 Prometheus + Grafana 监控：

1. 添加 Prometheus 指标：

from prometheus_client import Counter, Histogram, generate_latest
from fastapi import Response
# 定义指标
ocr_requests_total = Counter('ocr_requests_total', 'Total OCR requests', ['mode', 'status'])
ocr_processing_time = Histogram('ocr_processing_time_seconds', 'OCR processing time', ['mode'])
@app.post("/api/ocr")
async def ocr_inference(...):
    start_time = time.time()
    try:
        # 处理逻辑
        result = ...
        ocr_requests_total.labels(mode=mode, status='success').inc()
        return result
    except Exception as e:
        ocr_requests_total.labels(mode=mode, status='error').inc()
        raise
    finally:
        elapsed = time.time() - start_time
        ocr_processing_time.labels(mode=mode).observe(elapsed)
@app.get("/metrics")
async def metrics():
    return Response(content=generate_latest(), media_type="text/plain")

2. Prometheus 配置：

# prometheus.yml
scrape_configs:
  - job_name: 'deepseek-ocr'
    static_configs:
      - targets: ['backend:8000']
    metrics_path: '/metrics'
    scrape_interval: 15s

3. Grafana 仪表盘：

请求速率（QPS）
平均响应时间
错误率
GPU 利用率
内存使用情况

12.4 日志聚合

使用 ELK Stack（Elasticsearch + Logstash + Kibana）：

1. 结构化日志输出：

import logging
import json
from datetime import datetime
class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_data = {
            "timestamp": datetime.utcnow().isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
        }
        if hasattr(record, 'extra'):
            log_data.update(record.extra)
        return json.dumps(log_data)
handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)

2. Logstash 配置：

input {
  docker {
    type => "deepseek-ocr"
  }
}
filter {
  json {
    source => "message"
  }
}
output {
  elasticsearch {
    hosts => ["elasticsearch:9200"]
    index => "deepseek-ocr-%{+YYYY.MM.dd}"
  }
}

12.5 备份与恢复

模型文件备份：

# 定期备份模型文件
rsync -avz --progress /path/to/models/ backup-server:/backups/models/
# 使用 cron 定时任务
0 2 * * * rsync -avz /path/to/models/ backup-server:/backups/models/

数据库备份（如果使用）：

# PostgreSQL 备份
pg_dump -U postgres ocr_db > backup_$(date +%Y%m%d).sql
# 恢复
psql -U postgres ocr_db < backup_20241026.sql

十三、成本优化：让 AI 应用更经济

13.1 GPU 成本优化

1. 按需启动：

# 使用 GPU 时才加载模型
class LazyModel:
    def __init__(self):
        self._model = None
    @property
    def model(self):
        if self._model is None:
            self._model = load_model()
        return self._model
    def unload(self):
        if self._model is not None:
            del self._model
            torch.cuda.empty_cache()
            self._model = None
# 空闲 10 分钟后卸载模型
@app.on_event("startup")
async def start_idle_checker():
    asyncio.create_task(check_idle_and_unload())

2. 批处理：

# 累积请求，批量处理
batch_queue = []
batch_size = 4
async def batch_processor():
    while True:
        if len(batch_queue) >= batch_size:
            batch = batch_queue[:batch_size]
            results = model.infer_batch(batch)
            # 分发结果
        await asyncio.sleep(0.1)

3. 模型量化：

# 使用 INT8 量化减少显存占用
from torch.quantization import quantize_dynamic
model = quantize_dynamic(
    model,
    {torch.nn.Linear},
    dtype=torch.qint8
)

13.2 带宽成本优化

1. 图片压缩：

// 前端压缩图片后上传
import imageCompression from 'browser-image-compression'
const compressImage = async (file) => {
  const options = {
    maxSizeMB: 1,
    maxWidthOrHeight: 1920,
    useWebWorker: true
  }
  return await imageCompression(file, options)
}

2. CDN 加速：

# 使用 CDN 缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {expires 1y;add_header Cache-Control "public, immutable";add_header X-CDN-Cache "HIT";
}

13.3 存储成本优化

1. 临时文件自动清理：

import tempfile
import atexit
import shutil
temp_dirs = []
def cleanup_temp_dirs():
    for dir_path in temp_dirs:
        shutil.rmtree(dir_path, ignore_errors=True)
atexit.register(cleanup_temp_dirs)
# 使用
temp_dir = tempfile.mkdtemp()
temp_dirs.append(temp_dir)

2. 结果缓存：

from functools import lru_cache
import hashlib
def image_hash(image_bytes: bytes) -> str:
    return hashlib.md5(image_bytes).hexdigest()
# 使用 Redis 缓存结果
import redis
cache = redis.Redis(host='localhost', port=6379, db=0)
@app.post("/api/ocr")
async def ocr_inference(image: UploadFile = File(...)):
    content = await image.read()
    img_hash = image_hash(content)
    # 检查缓存
    cached = cache.get(f"ocr:{img_hash}")
    if cached:
        return json.loads(cached)
    # 处理并缓存
    result = process_image(content)
    cache.setex(f"ocr:{img_hash}", 3600, json.dumps(result))  # 缓存 1 小时
    return result

十四、总结：从代码到产品的思考

14.1 技术选型的权衡

这个项目在技术选型上做了很多权衡：

前端选择 React 而非 Vue/Svelte：

✅ 生态成熟，第三方库丰富
✅ 团队熟悉度高，招聘容易
❌ 包体积较大，首屏加载慢

后端选择 FastAPI 而非 Flask/Django：

✅ 异步支持，性能更好
✅ 自动生成 API 文档
✅ 类型提示，代码更健壮
❌ 生态相对较新，部分库不兼容

部署选择 Docker 而非 Kubernetes：

✅ 简单易用，学习成本低
✅ 适合中小规模部署
❌ 缺乏自动扩缩容
❌ 高可用性需要额外配置

14.2 工程化的价值

这个项目虽然是一个"Demo"，但在工程化方面做得很扎实：

配置管理：使用 .env 文件，避免硬编码
错误处理：完善的异常捕获和用户提示
资源清理：临时文件、GPU 内存的及时释放
日志系统：结构化日志，便于问题排查
代码规范：统一的代码风格和命名规范

这些细节看似琐碎，但在生产环境中至关重要。

14.3 AI 应用的特殊性

AI 应用与传统 Web 应用有很大不同：

资源密集：

GPU 是稀缺资源，需要精心管理
模型加载耗时长，需要预热机制
推理过程占用大量内存，需要监控

不确定性：

模型输出格式可能不稳定，需要鲁棒的解析
边界情况难以预测，需要充分测试
性能受输入影响大，需要动态调整

持续迭代：

模型版本更新频繁，需要版本管理
新功能需要重新训练，需要 MLOps 流程
用户反馈是改进的关键，需要数据收集

14.4 开源项目的启示

这个项目作为一个开源项目，有很多值得学习的地方：

文档完善：

README 详细说明了安装、配置、使用方法
包含常见问题和解决方案
提供了示例图片和预期输出

代码质量：

结构清晰，模块化设计
注释充分，易于理解
错误处理完善，不易崩溃

用户体验：

UI 设计精美，交互流畅
错误提示友好，易于排查
支持多种使用场景

持续维护：

版本更新及时，修复 bug
响应用户反馈，添加新功能
保持与上游模型同步

十五、实战建议：如何基于此项目进行二次开发

15.1 添加新的 OCR 模式

步骤：

在后端添加 Prompt 逻辑：

# backend/main.py
def build_prompt(...):
    # ...
    elif mode == "your_new_mode":
        instruction = "Your custom instruction here."
    # ...

在前端添加模式选项：

// frontend/src/components/ModeSelector.jsx
const modes = [
  // ...
  {
    id: 'your_new_mode',
    name: 'Your Mode',
    icon: YourIcon,
    color: 'from-green-500 to-blue-500',
    desc: 'Your description',
    needsInput: false
  },
]

测试新模式：

curl -X POST http://localhost:8000/api/ocr \
  -F "image=@test.png" \
  -F "mode=your_new_mode"

15.2 集成数据库存储

使用 SQLAlchemy + PostgreSQL：

安装依赖：

pip install sqlalchemy psycopg2-binary

定义模型：

from sqlalchemy import create_engine, Column, Integer, String, DateTime, Text
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from datetime import datetime
Base = declarative_base()
class OCRRecord(Base):
    __tablename__ = 'ocr_records'
    id = Column(Integer, primary_key=True)
    image_hash = Column(String(32), unique=True, index=True)
    mode = Column(String(50))
    result_text = Column(Text)
    boxes = Column(Text)  # JSON string
    created_at = Column(DateTime, default=datetime.utcnow)
engine = create_engine('postgresql://user:password@localhost/ocr_db')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)

保存结果：

@app.post("/api/ocr")
async def ocr_inference(...):
    # ... 处理逻辑
    # 保存到数据库
    session = Session()
    record = OCRRecord(
        image_hash=image_hash(content),
        mode=mode,
        result_text=text,
        boxes=json.dumps(boxes)
    )
    session.add(record)
    session.commit()
    session.close()
    return result

15.3 添加用户认证

使用 JWT 认证：

安装依赖：

pip install python-jose[cryptography] passlib[bcrypt]

实现认证逻辑：

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import JWTError, jwt
from datetime import datetime, timedelta
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
security = HTTPBearer()
def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(hours=24)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    try:
        payload = jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
        return payload
    except JWTError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid authentication credentials"
        )
@app.post("/api/ocr")
async def ocr_inference(
    image: UploadFile = File(...),
    user: dict = Depends(verify_token)  # 添加认证依赖
):
    # 只有认证用户才能访问
    ...

前端添加 Token：

const token = localStorage.getItem('access_token')
const response = await axios.post(`${API_BASE}/ocr`, formData, {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'multipart/form-data',
  },
})

15.4 实现批量处理

添加批量上传接口：

@app.post("/api/ocr/batch")
async def ocr_batch(
    images: List[UploadFile] = File(...),
    mode: str = Form("plain_ocr")
):
    results = []
    for image in images:
        try:
            result = await ocr_inference(image, mode)
            results.append({
                "filename": image.filename,
                "success": True,
                "data": result
            })
        except Exception as e:
            results.append({
                "filename": image.filename,
                "success": False,
                "error": str(e)
            })
    return {"results": results}

前端批量上传：

const handleBatchUpload = async (files) => {
  const formData = new FormData()
  files.forEach(file => {
    formData.append('images', file)
  })
  formData.append('mode', mode)
  const response = await axios.post(`${API_BASE}/ocr/batch`, formData)
  setResults(response.data.results)
}