LightOnOCR-2-1B实战教程：OCR结果与原始图片坐标对齐+可视化标注-开发者社区

LightOnOCR-2-1B实战教程：OCR结果与原始图片坐标对齐+可视化标注

1. 为什么需要坐标对齐？——从“只认字”到“懂位置”的关键跨越

你有没有遇到过这样的情况：OCR模型确实把文字识别出来了，但你完全不知道这些文字在原图里具体在哪儿？复制粘贴后发现顺序乱了，表格内容错位，或者想在原图上高亮某个字段却无从下手？

LightOnOCR-2-1B 不是传统 OCR 工具。它不止输出文字，更输出每个字符、每个单词、每段文本在原始图片中的精确像素坐标。这意味着——你不仅能“读出内容”，还能“指给它看”。

这不是锦上添花的功能，而是工程落地的刚需。比如：

在合同扫描件中标记“甲方签字处”并自动框选；
从发票图片中精准提取“金额”字段，并定位到右下角红色数字区域；
对教育试卷做结构化批改，把“第3题第2小问”的答案框出来；
把识别结果实时叠加在摄像头画面上，实现AR式文字增强。

本教程不讲理论推导，不堆参数配置，只带你用最短路径完成三件事：
正确调用 LightOnOCR-2-1B 获取带坐标的结构化结果
将坐标映射回原始图片尺寸（解决缩放失真问题）
用 Python 快速生成带文字标注的可视化图像

全程可复制、可验证、零踩坑。

2. 模型能力快速认知：不只是多语言，更是“空间感知型OCR”

2.1 它能认什么？——远超普通OCR的识别边界

LightOnOCR-2-1B 是一个 1B 参数量的多语言 OCR 模型，原生支持11 种语言：中文、英文、日文、法文、德文、西班牙文、意大利文、荷兰文、葡萄牙文、瑞典文、丹麦文。但它真正的优势不在语言数量，而在理解图文空间关系。

它能稳定识别以下复杂场景：

倾斜/透视文档：身份证、银行卡斜拍仍可准确定位；
密集小字号文本：说明书、药品包装上的8号字；
混合排版内容：左栏正文+右栏注释+底部页码+中间表格；
非标准格式：手写体签名旁的印刷体日期、印章覆盖文字、水印干扰区域；
数学公式与符号：含上下标、积分号、希腊字母的理科公式。

更重要的是——它输出的不是一串文字，而是一个个带x1, y1, x2, y2坐标的文本块（bounding box），每个块还附带置信度（confidence）和识别文本（text）。

2.2 它怎么工作？——两个服务入口，一套底层逻辑

LightOnOCR-2-1B 提供双通道访问方式，但背后共享同一套推理引擎：

访问方式	地址	适用场景	输出特点
Web 界面	`http://<服务器IP>:7860`	快速验证、调试、演示	图形化展示识别结果+可下载 JSON
API 接口	`http://<服务器IP>:8000/v1/chat/completions`	集成进业务系统、批量处理	返回标准 JSON，含完整坐标信息

注意：Web 界面本质是调用同一 API 的前端封装。所以——所有坐标准确性、格式定义、字段含义，都以 API 返回为准。我们后续所有坐标处理，均基于 API 的原始响应结构。

3. 实战第一步：获取带坐标的原始OCR结果

3.1 API 调用要点——绕过常见陷阱

官方提供的 curl 示例能跑通，但实际集成时容易卡在三个地方：图片编码、请求头、响应解析。我们用 Python requests 重写，更可控、更易调试：

import base64 import requests from PIL import Image def encode_image_to_base64(image_path): """将本地图片转为base64字符串（适配API要求）""" with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode("utf-8") def call_lighton_ocr_api(image_path, server_ip="127.0.0.1"): """调用LightOnOCR-2-1B API获取结构化结果""" url = f"http://{server_ip}:8000/v1/chat/completions" # 构造base64图片URL（注意前缀） image_b64 = encode_image_to_base64(image_path) image_url = f"data:image/png;base64,{image_b64}" payload = { "model": "/root/ai-models/lightonai/LightOnOCR-2-1B", "messages": [{ "role": "user", "content": [{"type": "image_url", "image_url": {"url": image_url}}] }], "max_tokens": 4096 } headers = {"Content-Type": "application/json"} try: response = requests.post(url, json=payload, headers=headers, timeout=120) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(f"API调用失败: {e}") return None # 使用示例 result = call_lighton_ocr_api("invoice.jpg", "192.168.1.100") if result: print("API调用成功，返回字段数:", len(result.get("choices", [{}])[0].get("message", {}).get("content", [])))

关键提醒：
图片必须是 PNG 或 JPEG 格式，其他格式（如 WebP、TIFF）可能被拒绝；
max_tokens设为 4096 是为了确保长文档不被截断，但实际消耗取决于文本长度；
如果返回空或报错，先检查ss -tlnp | grep -E "7860|8000"确认服务是否存活。

3.2 解析API响应——找到真正的坐标数据

API 返回的是类 ChatML 结构，但 LightOnOCR-2-1B 的实际 OCR 结果藏在message.content字段中，且是JSON 格式的字符串，不是直接对象。你需要手动json.loads()两次：

import json def parse_ocr_result(api_response): """从API响应中提取结构化OCR结果""" if not api_response: return [] try: # 第一次解析：拿到content字符串 content_str = api_response["choices"][0]["message"]["content"] # 第二次解析：content是JSON字符串，需再loads ocr_data = json.loads(content_str) # LightOnOCR-2-1B返回格式示例： # [ # {"text": "总金额", "bbox": [120, 345, 210, 378], "confidence": 0.98}, # {"text": "¥12,800.00", "bbox": [450, 342, 580, 379], "confidence": 0.96} # ] return ocr_data except (KeyError, json.JSONDecodeError, IndexError) as e: print(f"解析OCR结果失败: {e}") return [] # 解析示例 structured_result = parse_ocr_result(result) print(f"共识别出 {len(structured_result)} 个文本块") print("第一个块:", structured_result[0]) # 输出: {'text': '订单编号', 'bbox': [85, 112, 230, 145], 'confidence': 0.97}

你会发现bbox字段是[x1, y1, x2, y2]格式，单位是像素，原点在左上角。这正是我们后续对齐与可视化的基础。

4. 实战第二步：坐标对齐——让结果真正“贴合”原始图片

4.1 为什么不能直接用？——服务端预处理导致的尺寸偏移

这是 LightOnOCR-2-1B 最易被忽略的细节：API 内部会对输入图片做自适应缩放，以平衡精度与速度。默认策略是将图片最长边缩放到 1540px（见“最佳实践”说明），但返回的bbox坐标是缩放后图片上的坐标，而非你原始上传图片的坐标。

如果你直接拿这个坐标去画在原图上，会发现严重错位——文字框漂移、框变大或变小、位置整体偏移。

正确做法：根据原始图与缩放图的尺寸比例，反向校准坐标

def get_resize_ratio(original_width, original_height): """计算缩放比例（LightOnOCR-2-1B固定最长边为1540）""" max_dim = max(original_width, original_height) if max_dim <= 1540: return 1.0 # 未缩放，比例1:1 return 1540.0 / max_dim def align_bbox_to_original(bbox, original_size, resized_size): """将缩放图上的bbox映射回原始图坐标""" x1, y1, x2, y2 = bbox orig_w, orig_h = original_size res_w, res_h = resized_size # 先还原到缩放前的尺寸（假设等比缩放） scale_x = orig_w / res_w scale_y = orig_h / res_h # 注意：LightOnOCR-2-1B保持宽高比，空白处用padding填充 # 所以实际缩放后尺寸可能小于1540（如原图1000x2000 → 缩放后770x1540） # 我们用实际resize尺寸计算，而非假设1540 # 更鲁棒的做法：用PIL打开原图，获取实际resize尺寸 # 这里简化：假设用户已知或可测得resized_size（见下方工具函数） return [ int(x1 * scale_x), int(y1 * scale_y), int(x2 * scale_x), int(y2 * scale_y) ] # 实用工具：自动获取缩放后尺寸（无需人工测量） def get_resized_dimensions(image_path): """返回LightOnOCR-2-1B实际使用的缩放尺寸""" from PIL import Image img = Image.open(image_path) w, h = img.size ratio = get_resize_ratio(w, h) new_w = int(w * ratio) new_h = int(h * ratio) return (new_w, new_h) # 完整对齐流程 def align_all_bboxes(ocr_result, image_path): """批量对齐所有bbox到原始图片坐标""" original_size = Image.open(image_path).size resized_size = get_resized_dimensions(image_path) aligned_result = [] for item in ocr_result: aligned_bbox = align_bbox_to_original( item["bbox"], original_size, resized_size ) aligned_item = { "text": item["text"], "bbox": aligned_bbox, "confidence": item["confidence"] } aligned_result.append(aligned_item) return aligned_result # 使用 aligned_result = align_all_bboxes(structured_result, "invoice.jpg") print("对齐后第一个块坐标:", aligned_result[0]["bbox"]) # 如 [85, 112, 230, 145] → 变为 [85, 112, 230, 145]（若未缩放）或 [120, 165, 320, 210]（若缩放）

为什么不用简单除以1540？
因为缩放是等比的，如果原图是 800x2400（高是宽的3倍），缩放后是 513x1540，此时 x 方向缩放比是 513/800≈0.64，y 方向是 1540/2400≈0.64 —— 相同。但如果原图是 3000x2000，则缩放后是 1540x1027，x/y 缩放比不同。上述函数自动处理此差异。

4.2 验证对齐效果——三步快速自查法

别急着画图，先用这三步确认坐标已真正对齐：

看极值：取所有aligned_bbox中的最小x1、最小y1、最大x2、最大y2，它们应该都在原始图片尺寸范围内（即0 ≤ x1 < x2 ≤ width,0 ≤ y1 < y2 ≤ height）。超出即说明计算有误。
看比例：任选一个文本块，用画图工具量一下原始图中该文字的实际宽度（像素），对比aligned_bbox[2] - aligned_bbox[0]，误差应小于5像素。
看语义：找一个明显位置的文字（如“发票代码”在左上角，“收款人”在右下角），检查其y1值是否符合“上小下大”的常识（即左上角块的y1应显著小于右下角块的y1）。

5. 实战第三步：可视化标注——一行代码生成专业级标注图

5.1 用 OpenCV 绘制带文字的高亮框（推荐）

OpenCV 渲染快、兼容好、适合生产环境。我们封装一个函数，输入原始图片路径和对齐后的结果，直接输出标注图：

import cv2 import numpy as np from PIL import ImageFont, ImageDraw, Image def draw_ocr_on_image(image_path, ocr_result, output_path=None, font_path="/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"): """在原始图片上绘制OCR结果（带文字+框线）""" # 读取原始图片 img = cv2.imread(image_path) if img is None: raise ValueError(f"无法读取图片: {image_path}") # 设置字体（支持中文） try: font = ImageFont.truetype(font_path, 24) except: # 备用：使用PIL默认字体（可能不支持中文） font = ImageFont.load_default() # 转为PIL以便绘制中文 img_pil = Image.fromarray(cv2.cvtColor(img, cv2.COLOR_BGR2RGB)) draw = ImageDraw.Draw(img_pil) # 绘制每个文本块 for i, item in enumerate(ocr_result): x1, y1, x2, y2 = item["bbox"] text = item["text"] conf = item["confidence"] # 绘制矩形框（绿色，线宽2） draw.rectangle([x1, y1, x2, y2], outline=(0, 255, 0), width=2) # 绘制文字标签（白底黑字，背景半透明） label = f"{text} ({conf:.2f})" text_bbox = draw.textbbox((x1, y1-30), label, font=font) # 绘制半透明背景 draw.rectangle(text_bbox, fill=(0, 0, 0, 180)) # 绘制文字 draw.text((x1, y1-30), label, fill=(255, 255, 255), font=font) # 转回OpenCV格式并保存 img_out = cv2.cvtColor(np.array(img_pil), cv2.COLOR_RGB2BGR) if output_path is None: output_path = image_path.replace(".", "_annotated.") cv2.imwrite(output_path, img_out) print(f"标注图已保存至: {output_path}") return output_path # 一键生成 draw_ocr_on_image("invoice.jpg", aligned_result, "invoice_annotated.jpg")

效果特点：

绿色高亮框精准贴合文字区域；
每个框上方显示原文+置信度（如¥12,800.00 (0.96)）；
支持中英文混排（依赖系统中文字体）；
输出标准 JPG/PNG，可直接用于报告或演示。

5.2 替代方案：用 Matplotlib 快速调试（适合开发阶段）

如果只是想快速看效果、不追求生产级渲染，Matplotlib 更轻量：

import matplotlib.pyplot as plt import matplotlib.patches as patches def quick_visualize_ocr(image_path, ocr_result): """快速可视化（开发调试用）""" img = plt.imread(image_path) fig, ax = plt.subplots(1, figsize=(12, 16)) ax.imshow(img) for item in ocr_result[:20]: # 只画前20个，避免重叠 x1, y1, x2, y2 = item["bbox"] rect = patches.Rectangle((x1, y1), x2-x1, y2-y1, linewidth=2, edgecolor='red', facecolor='none') ax.add_patch(rect) ax.text(x1, y1-5, f"{item['text'][:10]}...", color='red', fontsize=10, weight='bold') plt.axis('off') plt.tight_layout() plt.show() # 调试时调用 quick_visualize_ocr("invoice.jpg", aligned_result)

6. 进阶技巧：提升实用性与鲁棒性

6.1 批量处理脚本——100张发票一键标注

把上面所有步骤打包成命令行工具，支持文件夹批量处理：

# 保存为 batch_annotate.py python batch_annotate.py --input_dir ./invoices/ --output_dir ./annotated/ --server_ip 192.168.1.100

核心逻辑就是遍历.jpg/.png文件，对每个文件执行：
call_api → parse_result → align_bbox → draw_ocr
并自动创建子目录、保留原文件名、跳过失败项。

6.2 坐标后处理——合并相邻文本块

OCR 返回的是细粒度文本块（单字/单词），但业务常需“行”或“段落”。可用简单规则合并：

def merge_line_boxes(boxes, y_threshold=10, x_gap_threshold=30): """按Y轴相近性合并为行，再按X轴顺序排序""" if not boxes: return [] # 按y1分组（行） lines = {} for box in boxes: y_center = (box["bbox"][1] + box["bbox"][3]) // 2 line_id = y_center // y_threshold if line_id not in lines: lines[line_id] = [] lines[line_id].append(box) # 每行内按x1排序，合并为一个大box merged_lines = [] for line_id, line_boxes in lines.items(): line_boxes.sort(key=lambda x: x["bbox"][0]) x1 = min(b["bbox"][0] for b in line_boxes) y1 = min(b["bbox"][1] for b in line_boxes) x2 = max(b["bbox"][2] for b in line_boxes) y2 = max(b["bbox"][3] for b in line_boxes) full_text = " ".join(b["text"] for b in line_boxes) merged_lines.append({ "text": full_text, "bbox": [x1, y1, x2, y2], "confidence": np.mean([b["confidence"] for b in line_boxes]) }) return merged_lines # 合并后可用于：提取整行发票号、合并表格单元格内容 line_result = merge_line_boxes(aligned_result)

6.3 错误防护——当API返回异常时的降级策略

网络抖动、GPU显存不足可能导致 API 返回空或格式错误。加入健壮性处理：

def robust_ocr_pipeline(image_path, server_ip): """带重试和降级的OCR主流程""" # 尝试API三次 for attempt in range(3): result = call_lighton_ocr_api(image_path, server_ip) if result and "choices" in result: parsed = parse_ocr_result(result) if parsed: aligned = align_all_bboxes(parsed, image_path) return aligned print(f"第{attempt+1}次调用失败，等待2秒后重试...") time.sleep(2) # 降级：返回空结果，但记录日志供排查 print(f"OCR服务不可用，跳过 {image_path}") return []