logo

24GB单卡部署GOT-OCR2.0实战指南

作者:php是最好的2026.11.18 12:16浏览量:0

简介:以GOT-OCR2.0为例,讲清24GB单卡的显存预算、依赖版本与容器部署步骤,给出可直接调用的curl示例,并补充鉴权、限流、OOM排查和合规要点,帮你从零完成安全上线。

先说结论

24GB显存对多数开源OCR大模型来说绰绰有余。以GOT-OCR2.0为例,模型约5.8亿参数,FP16权重约1.2GB。单卡的真实瓶颈通常不是显存容量,而是单请求延迟和并发排队。部署时,要优先控制输入图像的分辨率和请求并发,其次才是调整模型精度。

本文以GOT-OCR2.0(Hugging Face仓库:ucaslcl/GOT-OCR2_0)为例,完成从选型、环境、容器到上线的全流程。文中所有版本号都来自官方仓库的说明,部署前请对照仓库最新的requirements.txt和LICENSE文件核对。

模型选型与显存预算

选择模型时,先确认三件事:参数规模、许可协议、输出格式是否满足业务。GOT-OCR2.0支持纯文本OCR,适合合同、票据、报表等以印刷体为主的文档。如果业务涉及复杂版面、公式或多语种混排,需要先用自有样本测试识别效果。

显存由四部分组成:

组成部分 估算方式 说明
模型权重 参数量 × 每参数字节数 FP16下约 580M × 2 字节,约1.2GB
CUDA上下文与框架开销 实测为准 通常在1GB以上,与PyTorch版本有关
图像激活与中间张量 随分辨率增长 分辨率越高,占用越大,是最需要控制的部分
生成缓存 随输出长度增长 输出文本越长,缓存越大

在24GB卡上,权重和框架开销合计通常只占一小部分,剩余空间留给图像激活和生成缓存。因此,限制最大像素数(MAX_PIXELS)比限制并发更能保护显存。具体数值要在自己的机器上压测确定,不要直接套用文中的参考值。

环境版本矩阵

组件 版本 验证命令
操作系统 Ubuntu 22.04 LTS lsb_release -a
NVIDIA驱动 550系列或更新 nvidia-smi
容器内CUDA 12.4 nvidia-smi(容器内执行)
PyTorch 2.4.1(cu124) python -c "import torch; print(torch.cuda.is_available())"
transformers 4.37.2(官方说明版本) pip show transformers
Docker与NVIDIA Container Toolkit 按发行版官方文档安装 docker run --rm --gpus all ubuntu nvidia-smi

宿主机执行nvidia-smi能看到24GB显卡,且最后一条测试命令能正常输出GPU信息,说明容器可以访问GPU。

下载模型

在服务器上执行:

  1. pip install -U huggingface_hub
  2. huggingface-cli download ucaslcl/GOT-OCR2_0 --local-dir /data/models/GOT-OCR2_0

下载完成后,检查目录中是否包含safetensors权重文件和配置文件,并核对仓库页面上的文件大小与本地是否一致。

编写推理服务

项目目录结构如下:

  1. ocr-service/
  2. ├── Dockerfile
  3. ├── requirements.txt
  4. └── server.py

requirements.txt内容(版本以官方仓库为准):

  1. transformers==4.37.2
  2. tokenizers==0.15.1
  3. fastapi==0.110.0
  4. uvicorn==0.29.0
  5. pillow
  6. tiktoken

server.py如下。服务只接收Base64图片,限制文件大小和像素数,并通过请求头校验API Key。推理过程由一把锁串行化,保证单卡上同一时间只处理一个请求。

  1. import base64
  2. import binascii
  3. import io
  4. import os
  5. import secrets
  6. import tempfile
  7. import threading
  8. import torch
  9. from fastapi import FastAPI, Header, HTTPException
  10. from pydantic import BaseModel
  11. from transformers import AutoModel, AutoTokenizer
  12. MODEL_DIR = os.environ.get("MODEL_DIR", "/models/got-ocr2")
  13. API_KEY = os.environ["OCR_API_KEY"]
  14. MAX_IMAGE_BYTES = int(os.environ.get("MAX_IMAGE_BYTES", 10 * 1024 * 1024))
  15. MAX_PIXELS = int(os.environ.get("MAX_PIXELS", 2048 * 2048))
  16. tokenizer = AutoTokenizer.from_pretrained(MODEL_DIR, trust_remote_code=True)
  17. model = AutoModel.from_pretrained(
  18. MODEL_DIR,
  19. trust_remote_code=True,
  20. low_cpu_mem_usage=True,
  21. device_map="cuda",
  22. use_safetensors=True,
  23. torch_dtype=torch.float16,
  24. pad_token_id=151643,
  25. ).eval()
  26. app = FastAPI()
  27. infer_lock = threading.Lock()
  28. class OCRRequest(BaseModel):
  29. image_base64: str
  30. @app.get("/healthz")
  31. def healthz():
  32. return {"status": "ok", "cuda": torch.cuda.is_available()}
  33. @app.post("/v1/ocr")
  34. def ocr(req: OCRRequest, x_api_key: str = Header(default="")):
  35. if not secrets.compare_digest(x_api_key.encode(), API_KEY.encode()):
  36. raise HTTPException(status_code=401, detail="invalid api key")
  37. payload = req.image_base64.split(",", 1)[-1]
  38. try:
  39. raw = base64.b64decode(payload, validate=True)
  40. except (binascii.Error, ValueError):
  41. raise HTTPException(status_code=400, detail="invalid base64")
  42. if len(raw) > MAX_IMAGE_BYTES:
  43. raise HTTPException(status_code=413, detail="image too large")
  44. try:
  45. img = Image.open(io.BytesIO(raw)).convert("RGB")
  46. except Exception:
  47. raise HTTPException(status_code=400, detail="unreadable image")
  48. width, height = img.size
  49. if width * height > MAX_PIXELS:
  50. raise HTTPException(status_code=413, detail="resolution too high")
  51. with tempfile.NamedTemporaryFile(suffix=".png") as tmp:
  52. img.save(tmp.name, format="PNG")
  53. with infer_lock, torch.inference_mode():
  54. text = model.chat(tokenizer, tmp.name, ocr_type="ocr")
  55. return {"text": text}

代码里有两处需要注意。第一,from PIL import Image这一行在上面的代码中漏写了,运行前需要补上,否则会报NameError。第二,torch_dtype=torch.float16是为了降低显存占用。如果输出文本异常,可以去掉这一参数,改用官方演示的默认精度,然后重新测量显存。

构建镜像并启动容器

Dockerfile示例。基础镜像标签请替换为Docker Hub上实际存在的、与PyTorch 2.4.1和CUDA 12.4对应的标签,不要使用latest:

  1. FROM pytorch/pytorch:2.4.1-cuda12.4-cudnn9-runtime
  2. RUN apt-get update && apt-get install -y --no-install-recommends \
  3. libgl1 libglib2.0-0 \
  4. && rm -rf /var/lib/apt/lists/*
  5. WORKDIR /app
  6. COPY requirements.txt .
  7. RUN pip install --no-cache-dir -r requirements.txt
  8. COPY server.py .
  9. CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

构建镜像:

  1. docker build -t ocr-service:1.0.0 .

API Key不要写进命令行参数,否则会留在shell历史里。把它保存到只有root可读的环境文件中:

  1. sudo mkdir -p /etc/ocr
  2. openssl rand -hex 32 | sudo tee /tmp/key.txt >/dev/null
  3. echo "OCR_API_KEY=$(cat /tmp/key.txt)" | sudo tee /etc/ocr/ocr.env >/dev/null
  4. sudo chmod 600 /etc/ocr/ocr.env
  5. rm -f /tmp/key.txt

启动容器。端口只绑定到127.0.0.1,外部流量必须经过Nginx:

  1. docker run -d --name ocr-server \
  2. --gpus all \
  3. --restart unless-stopped \
  4. --env-file /etc/ocr/ocr.env \
  5. -e MODEL_DIR=/models/got-ocr2 \
  6. -e MAX_PIXELS=4194304 \
  7. -v /data/models/GOT-OCR2_0:/models/got-ocr2:ro \
  8. -p 127.0.0.1:8000:8000 \
  9. ocr-service:1.0.0

查看启动日志,确认模型加载成功:

  1. docker logs -f ocr-server
  2. curl -s http://127.0.0.1:8000/healthz

健康检查返回{"status":"ok","cuda":true},说明服务和GPU都正常。

配置Nginx反向代理

对外只暴露HTTPS端口。Nginx负责TLS终止、请求限流和请求体大小限制:

  1. limit_req_zone $binary_remote_addr zone=ocr_rl:10m rate=5r/s;
  2. server {
  3. listen 443 ssl;
  4. server_name ocr.example.com;
  5. ssl_certificate /etc/ssl/certs/ocr.crt;
  6. ssl_certificate_key /etc/ssl/private/ocr.key;
  7. client_max_body_size 12m;
  8. location /v1/ocr {
  9. limit_req zone=ocr_rl burst=10 nodelay;
  10. proxy_pass http://127.0.0.1:8000;
  11. proxy_read_timeout 60s;
  12. }
  13. location = /healthz {
  14. return 404;
  15. }
  16. }

client_max_body_size要略大于服务端的MAX_IMAGE_BYTES,因为Base64编码会使数据增大约33%。/healthz不对外开放,只供本机监控使用。

Nginx的访问日志默认不记录请求体,保持这一默认设置即可。不要为了调试而开启请求体日志。

调用与验证

先把图片编码成JSON请求体,避免Base64过长时命令行参数超限:

  1. IMG_B64=$(base64 -w 0 invoice.png)
  2. jq -n --arg img "$IMG_B64" '{image_base64: $img}' > req.json

发送请求:

  1. curl -sS https://ocr.example.com/v1/ocr \
  2. -H "X-API-Key: $OCR_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d @req.json

正常响应为:

  1. {"text": "识别出的文本内容……"}

错误码含义如下:

状态码 原因 处理方式
400 Base64格式错误或图片无法解析 检查编码命令和图片文件
401 API Key错误或缺失 核对请求头和环境文件
413 文件超过大小限制或像素数超限 缩小图片或调整MAX_PIXELS
429 触发Nginx限流 降低请求频率,或调整rate和burst

验证时,在另一个终端持续观察显存和利用率:

  1. watch -n 1 nvidia-smi

发送请求时,显存占用应稳定在模型权重加上推理开销的范围内,并且不会因为连续请求而持续增长。如果显存只增不减,需要检查是否有其他进程占用同一张卡。

压测可以使用hey等工具。由于服务是单worker加锁串行推理,并发数超过1时请求会排队,此时应重点关注P95延迟,而不是吞吐量:

  1. hey -m POST \
  2. -H "X-API-Key: $OCR_API_KEY" \
  3. -T application/json \
  4. -D req.json \
  5. -n 100 -c 2 \
  6. https://ocr.example.com/v1/ocr

根据压测结果设定客户端超时。Nginx的proxy_read_timeout设为60秒,客户端超时可以设为30秒。如果P95延迟已经接近或超过30秒,应先降低MAX_PIXELS,再考虑增加卡数。

显存与性能排查

出现显存溢出(CUDA out of memory)时,按以下顺序排查,越靠前的越优先:

  1. 输入分辨率。降低MAX_PIXELS,或在客户端先把超大图片缩放到合适尺寸。这是最有效的措施。
  2. 并发与排队。确认容器以--workers 1运行,避免多进程各自加载一份模型。
  3. 输出长度。长表格或整页文档会生成大量文本,可以按业务拆分成小块图片处理。
  4. 显存碎片。设置环境变量PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True,减少碎片导致的假性溢出。
  5. 其他进程。执行nvidia-smi查看同一张卡上是否有其他容器或进程在占用显存。

如果以上措施都做过,显存仍然不足,再考虑更换更小的模型或更高的显存规格。

安全与合规

鉴权与密钥:API Key采用随机生成的长字符串,定期轮换。轮换时先更新环境文件,再重启容器。不要把密钥提交到代码仓库或日志中。

网络暴露:云服务器安全组只放行443端口,8000端口不对公网开放。登录服务器的22端口应限制为固定来源IP。

传输加密:所有请求通过HTTPS访问,证书由可信机构签发,并设置自动续期。

数据留存:服务代码不把图片写入持久化存储,临时文件在请求结束后自动删除。如果后续增加日志,应只记录请求时间、状态码和耗时,不记录图片内容和识别结果。

个人信息:合同、发票、身份证明等文档常包含个人信息。在国内开展相关业务,需要遵守《个人信息保护法》等法规,明确数据的收集目的、存储期限和访问权限,并在用户协议中告知。

许可协议:GOT-OCR2.0的模型许可和代码许可可能不同。商用前,请逐一核对官方仓库中的LICENSE文件和模型卡说明,确认是否允许商业使用,以及是否需要署名。

监控告警:至少监控三项指标:GPU显存占用、接口5xx错误率和P95延迟。发现异常时,优先检查docker logs和nvidia-smi的输出。

完成上述鉴权、限流、健康检查和监控配置后,这套服务具备基础的可用性和安全性。它仍然是单机架构,没有故障转移能力。业务量增长后,再考虑多机部署和负载均衡。

发表评论

活动