DeepSeek-OCR-WEBUI 本地部署与 OCR 自动化集成

启用 CORS 中间件以允许跨域请求，便于前端页面访问：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

模型加载与设备适配策略

DeepSeek-OCR 使用 HuggingFace Transformers 框架加载，需设置 trust_remote_code=True 以启用自定义模型逻辑：

from transformers import AutoModel, AutoTokenizer
import torch

MODEL_NAME = "/home/qwt/models/DeepSeek-OCR"

# 可替换为远程仓库名
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)
model = AutoModel.from_pretrained(
    MODEL_NAME,
    trust_remote_code=True,
    use_safetensors=True
)

根据可用硬件自动选择最优计算精度与设备：

if torch.cuda.is_available():
    device = torch.device("cuda:0")
    model = model.eval().to(device)
    try:
        model = model.to(torch.bfloat16)
    except Exception:
        try:
            model = model.to(torch.float16)
            log.info("BF16 不可用，已回退至 FP16")
        except Exception:
            model = model.to(torch.float32)
else:
    device = torch.device("cpu")
    model = model.eval().to(device)
    log.warning("未检测到 CUDA，将在 CPU 上运行")

此策略确保在不同设备上均能稳定运行，兼顾性能与兼容性。

核心功能实现与接口设计

图像输入处理机制

系统支持三种图像输入方式：Base64 编码、本地路径、HTTP(S) URL。封装统一函数 _download_to_temp 实现自动识别与下载：

def _download_to_temp(url: str) -> str:
    if url.startswith("data:"):  # 处理 Data URI
        header, b64 = url.split(",", 1)
        ext = ".png" if "image/png" in header else ".jpg"
        raw = base64.b64decode(b64)
        return _save_bytes_to_temp(raw, suffix=ext)
    elif _is_local_like(url):  # 处理本地文件
        p = _to_local_path(url)
        with open(p, "rb") as f:
            data = f.read()
        ext = os.path.splitext(p)[1] or ".img"
        return _save_bytes_to_temp(data, suffix=ext)
    else:  # 下载远程图片
        resp = requests.get(url, timeout=30)
        resp.raise_for_status()
        ext = mimetypes.guess_extension(resp.headers.get("Content-Type", "")) or ".img"
        return _save_bytes_to_temp(resp.content, suffix=ext)

所有临时文件在推理完成后自动清理，防止磁盘占用。

OpenAI 兼容接口实现

健康检查 /health

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

模型列表 /v1/models

@app.get("/v1/models")
async def list_models():
    return {
        "object": "list",
        "data": [{"id": "deepseek-ocr", "object": "model", "created": int(time.time()), "owned_by": "owner"}]
    }

推理接口 /v1/chat/completions

接收符合 OpenAI 协议的消息格式，解析图文混合输入：

@app.post("/v1/chat/completions")
async def chat_completions(request: Request):
    payload = await request.json()
    messages = payload.get("messages")
    prompt_text, image_path = _extract_text_and_first_image_from_messages(messages)
    
    if not image_path:
        raise HTTPException(status_code=400, detail="No image found in messages.")
    
    try:
        answer = _run_ocr_infer(prompt_text, image_path)
    finally:
        if image_path and os.path.exists(image_path):
            os.unlink(image_path)
    
    return JSONResponse({
        "id": f"chatcmpl_{uuid.uuid4().hex[:24]}",
        "object": "chat.completion",
        "created": int(time.time()),
        "model": "deepseek-ocr",
        "choices": [{"index": 0, "message": {"role": "assistant", "content": answer}, "finish_reason": "stop"}],
        "usage": {
            "prompt_tokens": _token_count_approx(prompt_text),
            "completion_tokens": _token_count_approx(answer),
            "total_tokens": _token_count_approx(prompt_text + answer)
        }
    })

Web 前端交互与用户体验优化

单页 HTML 界面设计

static/ui.html 是一个轻量级前端页面，包含图片上传、预设指令选择、结果展示等功能模块。关键特性包括：

• 支持拖拽或点击上传图片
• 自动转换为 Base64 发送至后端
• 提供 Markdown / 纯文本 / JSON 三种输出模式
• 内置 Markdown 预览功能

样式采用现代化暗色主题，适配移动端与桌面端浏览。

前端逻辑实现要点

JavaScript 部分主要完成以下任务：

1. 图片读取与编码：

const fileToDataURI = (file) => new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = () => reject(new Error('读取失败'));
    reader.readAsDataURL(file);
});

2. 请求构造与发送：

const body = {
    model: "deepseek-ocr",
    messages: [
        {
            role: "user",
            content: [
                { type: "text", text: selectedPrompt },
                { type: "image_url", image_url: { url: dataUri } }
            ]
        }
    ]
};
fetch('/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
})

3. 结果渲染与切换：支持原始文本与 Markdown 预览双模式切换，利用 marked.js 实现富文本展示。

实际调用与集成实践

Python 客户端调用示例

使用 OpenAI SDK 兼容方式调用本地服务：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8001/v1", api_key="sk-x")
response = client.chat.completions.create(
    model="deepseek-ocr",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请以 Markdown 格式返回 OCR 结果"},
                {"type": "image_url", "image_url": {"url": "test.png"}}
            ]
        }
    ]
)
print(response.choices[0].message.content)

批量处理与自动化脚本

可通过循环调用实现批量图像处理：

import glob

for img_path in glob.glob("invoices/*.jpg"):
    response = client.chat.completions.create(
        model="deepseek-ocr",
        messages=[{"role": "user", "content": [
            {"type": "text", "text": "提取发票金额与日期"},
            {"type": "image_url", "image_url": {"url": img_path}}
        ]}]
    )
    with open(f"output/{img_path}.txt", "w") as f:
        f.write(response.choices[0].message.content)

总结

技术价值回顾

DeepSeek-OCR-WEBUI 提供了一套完整、易用且高性能的 OCR 解决方案，其核心优势体现在：

• 高精度识别：基于先进 CNN 与注意力机制，在复杂场景下仍保持优异表现
• 多模态输入支持：兼容 Base64、本地路径、URL 等多种图像来源
• OpenAI 协议兼容：便于与现有 AI 工作流集成
• 可视化 Web 界面：降低使用门槛，提升交互体验
• 国产自研保障：针对中文优化，符合数据安全合规要求

最佳实践建议

1. 生产环境部署：建议使用 Nginx + Gunicorn + Uvicorn 进行反向代理与负载均衡
2. 性能优化：启用 flash-attn 并使用 FP16/BF16 精度提升吞吐量
3. 安全性加固：限制上传文件类型、大小，关闭不必要的调试接口
4. 日志监控：记录请求频率、响应时间、错误码分布，便于运维分析

通过本文指导，你已具备将 DeepSeek-OCR-WEBUI 快速应用于实际项目的全部能力。无论是金融票据自动化、教育资料数字化，还是档案管理系统升级，这套方案都将成为强有力的支撑工具。