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。
下载模型
在服务器上执行:
pip install -U huggingface_hubhuggingface-cli download ucaslcl/GOT-OCR2_0 --local-dir /data/models/GOT-OCR2_0
下载完成后,检查目录中是否包含safetensors权重文件和配置文件,并核对仓库页面上的文件大小与本地是否一致。
编写推理服务
项目目录结构如下:
ocr-service/├── Dockerfile├── requirements.txt└── server.py
requirements.txt内容(版本以官方仓库为准):
transformers==4.37.2tokenizers==0.15.1fastapi==0.110.0uvicorn==0.29.0pillowtiktoken
server.py如下。服务只接收Base64图片,限制文件大小和像素数,并通过请求头校验API Key。推理过程由一把锁串行化,保证单卡上同一时间只处理一个请求。
import base64import binasciiimport ioimport osimport secretsimport tempfileimport threadingimport torchfrom fastapi import FastAPI, Header, HTTPExceptionfrom pydantic import BaseModelfrom transformers import AutoModel, AutoTokenizerMODEL_DIR = os.environ.get("MODEL_DIR", "/models/got-ocr2")API_KEY = os.environ["OCR_API_KEY"]MAX_IMAGE_BYTES = int(os.environ.get("MAX_IMAGE_BYTES", 10 * 1024 * 1024))MAX_PIXELS = int(os.environ.get("MAX_PIXELS", 2048 * 2048))tokenizer = AutoTokenizer.from_pretrained(MODEL_DIR, trust_remote_code=True)model = AutoModel.from_pretrained(MODEL_DIR,trust_remote_code=True,low_cpu_mem_usage=True,device_map="cuda",use_safetensors=True,torch_dtype=torch.float16,pad_token_id=151643,).eval()app = FastAPI()infer_lock = threading.Lock()class OCRRequest(BaseModel):image_base64: str@app.get("/healthz")def healthz():return {"status": "ok", "cuda": torch.cuda.is_available()}@app.post("/v1/ocr")def ocr(req: OCRRequest, x_api_key: str = Header(default="")):if not secrets.compare_digest(x_api_key.encode(), API_KEY.encode()):raise HTTPException(status_code=401, detail="invalid api key")payload = req.image_base64.split(",", 1)[-1]try:raw = base64.b64decode(payload, validate=True)except (binascii.Error, ValueError):raise HTTPException(status_code=400, detail="invalid base64")if len(raw) > MAX_IMAGE_BYTES:raise HTTPException(status_code=413, detail="image too large")try:img = Image.open(io.BytesIO(raw)).convert("RGB")except Exception:raise HTTPException(status_code=400, detail="unreadable image")width, height = img.sizeif width * height > MAX_PIXELS:raise HTTPException(status_code=413, detail="resolution too high")with tempfile.NamedTemporaryFile(suffix=".png") as tmp:img.save(tmp.name, format="PNG")with infer_lock, torch.inference_mode():text = model.chat(tokenizer, tmp.name, ocr_type="ocr")return {"text": text}
代码里有两处需要注意。第一,from PIL import Image这一行在上面的代码中漏写了,运行前需要补上,否则会报NameError。第二,torch_dtype=torch.float16是为了降低显存占用。如果输出文本异常,可以去掉这一参数,改用官方演示的默认精度,然后重新测量显存。
构建镜像并启动容器
Dockerfile示例。基础镜像标签请替换为Docker Hub上实际存在的、与PyTorch 2.4.1和CUDA 12.4对应的标签,不要使用latest:
FROM pytorch/pytorch:2.4.1-cuda12.4-cudnn9-runtimeRUN apt-get update && apt-get install -y --no-install-recommends \libgl1 libglib2.0-0 \&& rm -rf /var/lib/apt/lists/*WORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY server.py .CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
构建镜像:
docker build -t ocr-service:1.0.0 .
API Key不要写进命令行参数,否则会留在shell历史里。把它保存到只有root可读的环境文件中:
sudo mkdir -p /etc/ocropenssl rand -hex 32 | sudo tee /tmp/key.txt >/dev/nullecho "OCR_API_KEY=$(cat /tmp/key.txt)" | sudo tee /etc/ocr/ocr.env >/dev/nullsudo chmod 600 /etc/ocr/ocr.envrm -f /tmp/key.txt
启动容器。端口只绑定到127.0.0.1,外部流量必须经过Nginx:
docker run -d --name ocr-server \--gpus all \--restart unless-stopped \--env-file /etc/ocr/ocr.env \-e MODEL_DIR=/models/got-ocr2 \-e MAX_PIXELS=4194304 \-v /data/models/GOT-OCR2_0:/models/got-ocr2:ro \-p 127.0.0.1:8000:8000 \ocr-service:1.0.0
查看启动日志,确认模型加载成功:
docker logs -f ocr-servercurl -s http://127.0.0.1:8000/healthz
健康检查返回{"status":"ok","cuda":true},说明服务和GPU都正常。
配置Nginx反向代理
对外只暴露HTTPS端口。Nginx负责TLS终止、请求限流和请求体大小限制:
limit_req_zone $binary_remote_addr zone=ocr_rl:10m rate=5r/s;server {listen 443 ssl;server_name ocr.example.com;ssl_certificate /etc/ssl/certs/ocr.crt;ssl_certificate_key /etc/ssl/private/ocr.key;client_max_body_size 12m;location /v1/ocr {limit_req zone=ocr_rl burst=10 nodelay;proxy_pass http://127.0.0.1:8000;proxy_read_timeout 60s;}location = /healthz {return 404;}}
client_max_body_size要略大于服务端的MAX_IMAGE_BYTES,因为Base64编码会使数据增大约33%。/healthz不对外开放,只供本机监控使用。
Nginx的访问日志默认不记录请求体,保持这一默认设置即可。不要为了调试而开启请求体日志。
调用与验证
先把图片编码成JSON请求体,避免Base64过长时命令行参数超限:
IMG_B64=$(base64 -w 0 invoice.png)jq -n --arg img "$IMG_B64" '{image_base64: $img}' > req.json
发送请求:
curl -sS https://ocr.example.com/v1/ocr \-H "X-API-Key: $OCR_API_KEY" \-H "Content-Type: application/json" \-d @req.json
正常响应为:
{"text": "识别出的文本内容……"}
错误码含义如下:
| 状态码 | 原因 | 处理方式 |
|---|---|---|
| 400 | Base64格式错误或图片无法解析 | 检查编码命令和图片文件 |
| 401 | API Key错误或缺失 | 核对请求头和环境文件 |
| 413 | 文件超过大小限制或像素数超限 | 缩小图片或调整MAX_PIXELS |
| 429 | 触发Nginx限流 | 降低请求频率,或调整rate和burst |
验证时,在另一个终端持续观察显存和利用率:
watch -n 1 nvidia-smi
发送请求时,显存占用应稳定在模型权重加上推理开销的范围内,并且不会因为连续请求而持续增长。如果显存只增不减,需要检查是否有其他进程占用同一张卡。
压测可以使用hey等工具。由于服务是单worker加锁串行推理,并发数超过1时请求会排队,此时应重点关注P95延迟,而不是吞吐量:
hey -m POST \-H "X-API-Key: $OCR_API_KEY" \-T application/json \-D req.json \-n 100 -c 2 \https://ocr.example.com/v1/ocr
根据压测结果设定客户端超时。Nginx的proxy_read_timeout设为60秒,客户端超时可以设为30秒。如果P95延迟已经接近或超过30秒,应先降低MAX_PIXELS,再考虑增加卡数。
显存与性能排查
出现显存溢出(CUDA out of memory)时,按以下顺序排查,越靠前的越优先:
- 输入分辨率。降低
MAX_PIXELS,或在客户端先把超大图片缩放到合适尺寸。这是最有效的措施。 - 并发与排队。确认容器以
--workers 1运行,避免多进程各自加载一份模型。 - 输出长度。长表格或整页文档会生成大量文本,可以按业务拆分成小块图片处理。
- 显存碎片。设置环境变量
PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True,减少碎片导致的假性溢出。 - 其他进程。执行
nvidia-smi查看同一张卡上是否有其他容器或进程在占用显存。
如果以上措施都做过,显存仍然不足,再考虑更换更小的模型或更高的显存规格。
安全与合规
鉴权与密钥:API Key采用随机生成的长字符串,定期轮换。轮换时先更新环境文件,再重启容器。不要把密钥提交到代码仓库或日志中。
网络暴露:云服务器安全组只放行443端口,8000端口不对公网开放。登录服务器的22端口应限制为固定来源IP。
传输加密:所有请求通过HTTPS访问,证书由可信机构签发,并设置自动续期。
数据留存:服务代码不把图片写入持久化存储,临时文件在请求结束后自动删除。如果后续增加日志,应只记录请求时间、状态码和耗时,不记录图片内容和识别结果。
个人信息:合同、发票、身份证明等文档常包含个人信息。在国内开展相关业务,需要遵守《个人信息保护法》等法规,明确数据的收集目的、存储期限和访问权限,并在用户协议中告知。
许可协议:GOT-OCR2.0的模型许可和代码许可可能不同。商用前,请逐一核对官方仓库中的LICENSE文件和模型卡说明,确认是否允许商业使用,以及是否需要署名。
监控告警:至少监控三项指标:GPU显存占用、接口5xx错误率和P95延迟。发现异常时,优先检查docker logs和nvidia-smi的输出。
完成上述鉴权、限流、健康检查和监控配置后,这套服务具备基础的可用性和安全性。它仍然是单机架构,没有故障转移能力。业务量增长后,再考虑多机部署和负载均衡。

登录后可评论,请前往 登录 或 注册