YOLO X Layout实操手册：输出结果叠加原图保存为带标注PNG/JPEG文件

YOLO X Layout实操手册：输出结果叠加原图保存为带标注PNG/JPEG文件

1. 这个工具到底能帮你做什么

你有没有遇到过这样的情况：手头有一堆扫描的PDF或手机拍的文档照片，想快速知道里面哪些是标题、哪些是表格、哪些是图片，但又不想一页页手动标记？或者你需要把一份技术文档自动拆解成结构化数据，方便后续做知识提取或内容重排？

YOLO X Layout就是为这类需求而生的轻量级文档版面分析工具。它不是那种动辄要配GPU、调参数、写几十行代码才能跑起来的复杂系统，而是一个开箱即用的“文档眼睛”——你丢一张图进去，它几秒钟就告诉你：这儿是标题、那儿是表格、角落有张图、底部是页脚……清清楚楚，一目了然。

它背后用的是YOLO系列中兼顾速度与精度的YOLOX模型，但做了专门针对文档场景的优化和训练。不像通用目标检测模型容易把“一段文字”误判成“一个物体”，YOLO X Layout学的是文档的“语言”：它认识段落的呼吸感、表格的网格节奏、标题的视觉重量、页眉页脚的固定位置规律。所以它识别的不是“一堆像素”，而是“文档的骨架”。

更关键的是，它不只给你返回坐标和类别，还直接帮你把结果画回原图上——而且你能控制怎么画、画多粗、用什么颜色、标不标文字，最后稳稳保存成一张带标注的PNG或JPEG文件。这才是真正能落地进工作流的一步。

2. 从零开始：本地启动+快速验证

2.1 环境准备确认

在动手前，请先确认你的机器已满足基础依赖。这不是苛刻的要求，而是确保你不会卡在第一步：

• Python 3.8 或更高版本（推荐 3.10）
• 已安装opencv-python（≥4.8.0）、numpy（≥1.24.0）、onnxruntime（≥1.16.0）和gradio（≥4.0.0）

你可以用这条命令一次性检查核心依赖是否就位：

python -c "import cv2, numpy, onnxruntime, gradio; print(' 依赖全部就绪')"

如果报错提示某个包缺失，就用 pip 安装它，比如：

pip install opencv-python>=4.8.0 numpy>=1.24.0 onnxruntime>=1.16.0 gradio>=4.0.0

2.2 启动服务只需两行命令

进入项目根目录，执行启动脚本：

cd /root/yolo_x_layout python /root/yolo_x_layout/app.py

看到终端输出类似这样的日志，就说明服务已成功启动：

Running on local URL: http://localhost:7860 To create a public link, set `share=True` in `launch()`.

打开浏览器，访问 http://localhost:7860，你会看到一个干净的界面：左侧是上传区，右侧是参数调节栏和结果预览区。整个过程不需要改任何配置，也不需要碰模型文件路径——因为默认设置已经指向/root/ai-models/AI-ModelScope/yolo_x_layout/这个位置。

2.3 上传一张测试图，30秒内见效果

找一张清晰的文档截图或扫描件（JPG/PNG格式，A4尺寸效果最佳），拖进上传框。不用等太久，几秒后，界面上就会出现一张带彩色方框的图。

每个方框都代表一种文档元素：

• 蓝色是Text（正文段落）
• 绿色是Table（表格区域）
• 橙色是Picture（插图）
• 紫色是Title（大标题）
• 青色是Section-header（小节标题）
• ……其余8类也各有专属颜色

你还能在右下角看到一个实时更新的统计栏：“检测到 12 个元素”，并列出每类各几个。这比看一串JSON更直观，也更符合人眼快速理解的习惯。

3. 超越界面：用代码批量处理文档图片

Web界面适合单张调试和演示，但如果你要处理上百份合同、几十页产品说明书，手动点上传就太慢了。这时候，API 就是你的自动化引擎。

3.1 一行Python调用，拿到结构化结果

下面这段代码，是你批量处理的最小可行单元。它不依赖任何额外框架，只用标准库requests，就能完成一次完整的分析请求：

import requests import json # 准备请求 url = "http://localhost:7860/api/predict" files = {"image": open("invoice_scan.jpg", "rb")} data = {"conf_threshold": 0.3} # 置信度调高一点，减少误检 # 发送请求 response = requests.post(url, files=files, data=data) # 解析结果 if response.status_code == 200: result = response.json() print(f" 共检测到 {len(result['detections'])} 个元素") for det in result["detections"][:3]: # 只打印前3个，避免刷屏 print(f" - {det['label']} (置信度: {det['confidence']:.2f}) " f"位置: [{det['bbox'][0]:.0f}, {det['bbox'][1]:.0f}, " f"{det['bbox'][2]:.0f}, {det['bbox'][3]:.0f}]") else: print(f"❌ 请求失败，状态码: {response.status_code}")

运行后，你会看到类似这样的输出：

共检测到 15 个元素 - Title (置信度: 0.92) 位置: [120, 85, 480, 145] - Table (置信度: 0.88) 位置: [95, 210, 560, 490] - Text (置信度: 0.76) 位置: [110, 510, 540, 560]

这就是你后续做结构化提取、自动归档、OCR定向识别的原始数据基础。

3.2 关键参数怎么调才靠谱

API里最常调的参数就两个：conf_threshold和model_name。

• conf_threshold（置信度阈值）：默认是0.25。数值越高，检测越“保守”，只保留把握大的结果；数值越低，越“大胆”，会召回更多边缘案例。建议日常用0.3，查漏补缺时降到0.15。
• model_name（模型选择）：可选"yolox_tiny"、"yolox_l005_quantized"或"yolox_l005"。它们不是简单的“小中大”关系，而是速度与精度的三角权衡：
  • yolox_tiny：20MB，1080p图约0.3秒出结果，适合对延迟敏感的场景（如实时预览）；
  • yolox_l005_quantized：53MB，0.6秒，精度比tiny高12%，是大多数业务的甜点选择；
  • yolox_l005：207MB，1.2秒，精度最高，适合对准确率要求严苛的质检环节。

你可以在API请求里这样指定模型：

data = { "conf_threshold": 0.3, "model_name": "yolox_l005_quantized" }

4. 实战重点：把检测结果叠加到原图并保存为PNG/JPEG

这才是本手册的核心价值——不只看结果，还要把结果“印”在图上，变成一张可交付、可存档、可分享的带标注图像。

4.1 手动操作：Web界面一键导出

在Web界面完成分析后，右下角会出现一个醒目的按钮：“Save Annotated Image”。点击它，会弹出一个对话框，让你选择：

• 保存格式：PNG（无损，推荐）或 JPEG（体积小，网页友好）
• 标注样式：
  • Draw boxes only：只画边框，不标文字（最简洁）
  • Draw boxes + labels：边框+类别名（最常用）
  • Draw boxes + labels + confidence：边框+类别名+置信度（适合调试）
• 线宽与字体大小：滑块可调，建议线宽2-3，字体大小12-14，保证在A4尺寸下清晰可读

选好后点“Download”，浏览器就会自动下载一张命名如document_annotated.png的文件。打开它，你看到的就是最终成果：原图打上了彩色方框和文字标签，所有信息一图呈现。

4.2 编程实现：用OpenCV自己画，完全可控

如果你需要集成进自己的脚本，或者想自定义颜色、字体、布局，那就得自己动手画。下面是一段精简、健壮、可直接复用的Python代码：

import cv2 import numpy as np import json def draw_detections_on_image(image_path, detections, output_path, font_scale=1.0, line_thickness=2, show_confidence=False): """ 将YOLO X Layout的检测结果绘制到原图上，并保存为PNG/JPEG Args: image_path: 原图路径 detections: API返回的detections列表，每个元素含'label', 'bbox', 'confidence' output_path: 输出路径，后缀决定格式(.png/.jpg) font_scale: 字体大小缩放因子 line_thickness: 边框线宽 show_confidence: 是否在标签后显示置信度 """ # 读取原图 img = cv2.imread(image_path) if img is None: raise ValueError(f"无法读取图片: {image_path}") # 预定义11类颜色（BGR格式，OpenCV用） colors = { "Title": (128, 0, 128), # 紫色 "Section-header": (0, 128, 128), # 青色 "Text": (255, 0, 0), # 蓝色 "List-item": (0, 255, 0), # 绿色 "Table": (0, 255, 255), # 黄绿色 "Picture": (0, 165, 255), # 橙色 "Figure": (255, 0, 255), # 品红 "Formula": (255, 255, 0), # 青色 "Caption": (128, 128, 0), # 棕色 "Page-header": (128, 0, 0), # 深红 "Page-footer": (0, 0, 128), # 深蓝 "Footnote": (255, 128, 0), # 橙红 "Other": (192, 192, 192) # 灰色（兜底） } # 遍历每个检测框 for det in detections: label = det["label"] bbox = det["bbox"] # [x1, y1, x2, y2] conf = det["confidence"] # 获取颜色，找不到则用灰色 color = colors.get(label, colors["Other"]) # 绘制矩形框 x1, y1, x2, y2 = map(int, bbox) cv2.rectangle(img, (x1, y1), (x2, y2), color, line_thickness) # 绘制标签文字 text = label if show_confidence: text += f" ({conf:.2f})" # 计算文字位置（框上方） text_size = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, font_scale, 1)[0] text_x = x1 text_y = max(y1 - 10, text_size[1] + 5) # 绘制文字背景（半透明黑底） cv2.rectangle(img, (text_x, text_y - text_size[1] - 5), (text_x + text_size[0], text_y + 5), (0, 0, 0), -1) # 绘制白色文字 cv2.putText(img, text, (text_x, text_y), cv2.FONT_HERSHEY_SIMPLEX, font_scale, (255, 255, 255), 1) # 保存图像 cv2.imwrite(output_path, img) print(f" 标注图像已保存至: {output_path}") # 使用示例 if __name__ == "__main__": # 假设你已通过API获取了检测结果 sample_detections = [ {"label": "Title", "bbox": [120, 85, 480, 145], "confidence": 0.92}, {"label": "Table", "bbox": [95, 210, 560, 490], "confidence": 0.88}, {"label": "Text", "bbox": [110, 510, 540, 560], "confidence": 0.76} ] draw_detections_on_image( image_path="invoice_scan.jpg", detections=sample_detections, output_path="invoice_annotated.png", font_scale=0.8, line_thickness=2, show_confidence=True )

这段代码的关键优势在于：

• 颜色精准对应：11类标签都有预设的BGR颜色，且区分度高，避免视觉混淆；
• 文字自动避让：标签文字始终画在框的上方，不会遮挡内容；
• 背景增强可读性：文字加了黑色半透明底衬，无论原图背景多复杂，文字都清晰可见；
• 格式自由切换：只要输出路径后缀是.png或.jpg，OpenCV会自动按需编码。

运行后，你得到的invoice_annotated.png就是一张专业级的标注图，可以直接插入报告、发给同事评审，或作为训练数据的可视化样本。

5. Docker部署：一次配置，长期复用

当你的分析任务从“偶尔用用”变成“每天都要跑”，或者需要在多台机器上保持环境一致时，Docker就是最省心的选择。

5.1 一条命令，容器化启动

使用你提供的Docker命令，即可一键拉起服务：

docker run -d -p 7860:7860 \ -v /root/ai-models:/app/models \ yolo-x-layout:latest

这里的关键是-v参数：它把宿主机的/root/ai-models目录挂载到了容器内的/app/models路径。这意味着，只要你把模型文件放在宿主机的这个目录下，容器里的程序就能直接找到它们，无需在镜像里打包大模型，既减小镜像体积，又方便模型热更新。

5.2 验证容器是否健康运行

启动后，用这条命令检查容器状态：

docker ps | grep yolo-x-layout

你应该看到类似这样的输出，表示容器正在运行：

a1b2c3d4e5f6 yolo-x-layout:latest "python /app/app.py" 2 minutes ago Up 2 minutes 0.0.0.0:7860->7860/tcp relaxed_mirzakhani

再用curl快速测试API是否通：

curl -X POST "http://localhost:7860/api/health"

如果返回{"status":"ok"}，说明服务一切正常，随时可以接收请求。

6. 总结：让文档理解真正走进日常工作流

YOLO X Layout不是一个炫技的AI玩具，而是一把趁手的“文档解剖刀”。它把复杂的版面分析能力，压缩成一个端口、一个接口、一张图——没有繁杂的配置，没有漫长的训练，也没有陡峭的学习曲线。

回顾我们走过的路：

• 你学会了如何在本地快速启动服务，30秒内看到第一张标注图；
• 你掌握了用Python脚本批量调用API，把分析能力嵌入自己的工作流；
• 你亲手用OpenCV把检测结果“印”在原图上，生成可交付的PNG/JPEG文件，每一个细节都由你掌控；
• 你还用Docker把它变成了一个稳定、可迁移的服务，告别环境冲突的烦恼。

下一步，你可以尝试：

• 把标注图和OCR结果结合，自动生成Markdown结构化文档；
• 用检测到的Table区域坐标，裁剪出表格图片，再喂给专用表格识别模型；
• 将Title和Section-header的层级关系，用于构建文档的思维导图。

文档理解的价值，从来不在“识别出来”，而在于“识别之后能做什么”。YOLO X Layout，正是那个帮你跨过第一道门槛的可靠伙伴。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。