关于

此仓库提供了用于连接 llmsherpa API 的服务代码。 该仓库包含针对以下文件格式的自定义 RAG（检索增强生成）友好解析器：

PDF

PDF 解析器是一种基于规则的解析器，它利用文本坐标（边界框）、图形和字体数据，这些数据来自 nlmatics 修改过的 Tika 版本，详见此处：https://github.com/nlmatics/nlm-tika。 PDF 解析器主要基于文本层工作，并提供 OCR 选项（apply_ocr），以便在 PDF 中存在扫描页面时自动启用 OCR。OCR 功能基于 nlmatics 修改的 Tika 版本实现，底层使用 Tesseract 引擎。 请查看笔记本 pdf_visual_ingestor_step_by_step，直接体验 PDF 解析器。

PDF 解析器具备以下功能：

1. 各级章节与子章节。
2. 段落——将多行文本合并为段落。
3. 章节与段落之间的链接。
4. 表格及其所在章节。
5. 列表及嵌套列表。
6. 跨页内容的拼接。
7. 重复页眉和页脚的去除。
8. 水印移除。
9. 带边界框的 OCR。

HTML

一种特殊的 HTML 解析器，能够创建布局感知的块，从而以更高质量的片段提升 RAG 性能。

文本

一种特殊的文本解析器，仅通过分析文本内容来识别列表、表格、标题等，而不依赖任何视觉、字体或边界框信息。

DOCX、PPTX 以及 Apache Tika 支持的其他格式

处理这些类型的文档有两种方式：

• 使用 Tika 为这些文件类型生成的 HTML 输出，并由 HTML 解析器进行解析。

安装步骤：

直接执行每一步

1. 从 https://www.oracle.com/java/technologies/downloads/ 安装最新版本的 Java。
2. 运行 Tika 服务器：

java -jar <path_to_nlm_ingestor>/jars/tika-server-standard-nlm-modified-2.9.2_v2.jar

3. 安装 ingestor：

!pip install nlm-ingestor

4. 运行 ingestor：

python -m nlm_ingestor.ingestion_daemon

使用 Docker 文件

可通过公共 GitHub 容器注册表获取 Docker 镜像。

拉取 Docker 镜像：

docker pull ghcr.io/nlmatics/nlm-ingestor:latest

运行 Docker 镜像，并将端口 5001 映射到您选择的端口：

docker run -p 5010:5001 ghcr.io/nlmatics/nlm-ingestor:latest-<version>

服务器启动后，您可以使用 llmsherpa API 库获取片段，并将其用于您的 LLM 项目。您的 llmsherpa URL 将是： "http://localhost:5010/api/parseDocument?renderFormat=all"

• 若要启用 OCR，请添加 &applyOcr=yes。
• 若要使用新的缩进解析器（采用不同算法分配标题级别），请添加 &useNewIndentParser=yes。
• 此服务器适用于开发环境；在生产环境中，建议通过 Nginx 或云网关等安全网关来部署。

测试 ingestor 服务器

用于测试服务器与 llmsherpa 解析器的示例代码位于此笔记本中：[notebooks/test_llmsherpa_api.ipynb]。

基于规则的解析器 vs 基于模型的解析器

在过去四年里，nlmatics 团队评估了多种方案，其中包括由 Tom Liu 和 Yi Zhang 开发的基于 YOLO 的视觉解析器。最终，我们选择了基于规则的解析器，原因如下：

1. 相较于任何视觉解析器，它的速度要快得多（约 100 倍）。因为即使对于带有文本层的 PDF，使用视觉解析器也至少需要先将所有页面转换为图像。我们认为，视觉解析器更适合用于没有文本层的 OCR 处理后的 PDF，或者包含表单数据的小型 PDF 文件；而对于包含数百页的大规模文本层 PDF，像我们这样的基于规则的解析器更为实用。
2. 如果不使用 PDF 的 OCR 功能，运行此解析器无需特殊硬件。即使是 2000 年代初期的硬件也能胜任！
3. 我们发现，视觉解析器（实际上包括所有解析器，也包括我们自己的解析器）容易出错，而修复模型错误的方法并不理想：
   • 向训练集添加更多样本，这可能会降低模型先前学习的准确性，导致原有代码出现不确定性。
   • 使用基于规则的方法来修复基于模型的解析器问题，最终又会回到编写大量规则的老路。

致谢

PDF 解析器中的 visual_ingestor 和 new_indent_parser 由 Ambika Sukla 编写，Reshav Abraham 对其进行了补充贡献，他编写了最初的 Tika 修改代码；Tom Liu 则撰写了原始的缩进解析器；Kiran Panicker 在解析速度、表格解析精度、缩进解析精度以及重新排序精度等方面做出了多项改进。

HTML Ingestor 由 Tom Liu 编写。

Markdown Parser 由 Yi Zhang 编写。

Text Ingestor 由 Reshav Abraham 编写。

XML Ingestor 主要由 Ambika Sukla 编写，用于处理 PubMed XML 文件。

作为所有其他解析器的核心句子处理工具，line_parser 由 Ambika Sukla 编写。

此外，我们还要感谢 Apache PDFBox 和 Tika 的开发者社区，多年来他们为 PDF 解析器奠定了基础。

Nlm 修改版 Tika

Nlm 修改版的 Tika 可以在以下分支中找到：https://github.com/nlmatics/nlm-tika/tree/2.4.1-nlm。
为方便起见，该仓库的 jars/ 文件夹中已包含编译好的 JAR 文件。

在某些情况下，您的 PDF 文件可能会导致 Java 服务器出现错误，这时您需要修改相关代码以解决问题，并重新编译 JAR 文件。

以下是被修改的文件：

1. https://github.com/nlmatics/nlm-tika/blob/2.4.1-nlm/tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-pdf-module/src/main/java/org/apache/tika/parser/pdf/PDF2XHTML.java
2. https://github.com/nlmatics/nlm-tika/blob/2.4.1-nlm/tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-pdf-module/src/main/java/org/apache/tika/parser/pdf/AbstractPDF2XHTML.java

上述修改旨在为每个文本元素添加字体和坐标信息，并移除水印。

3. https://github.com/nlmatics/nlm-tika/blob/2.4.1-nlm/tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-pdf-module/src/main/java/org/apache/tika/parser/pdf/GraphicsStreamProcessor.java

该文件的修改是为了添加线条和矩形，这可能有助于表格的检测。

要查看这些更改的效果，请参阅笔记本的第一部分：https://github.com/nlmatics/nlm-ingestor/blob/main/notebooks/pdf_visual_ingestor_step_by_step.ipynb

未来工作的一些想法：

1. 通过基于 PDFBox 编写自己的封装器，使这些更改与 Tika 解析器解耦。
2. 升级到最新版本的 Tika。
3. 清理返回的 HTML 格式，使其更符合 CSS 规范。

Pacific 使用说明

1. 运行测试
   make test
make test-pdf-ingestor

2. 构建镜像。此操作会将镜像推送到 Pacific 生产环境的 ECR 仓库。
   make build_and_push

3. 镜像构建完成后，您需要前往 pacific-server 仓库并部署模态应用。请确保您的本地环境中已设置好 Pacific 生产环境的 AWS 环境变量。

如果您需要更新 nlm-utils，请前往 nlm-utils 仓库，更新依赖项，构建 WHL 文件，并将其复制到本仓库的 whl/ 目录下。

nlm-ingestor 快速上手指南

nlm-ingestor 是一个专为 RAG（检索增强生成）优化的文档解析服务，能够高质量地提取 PDF、HTML、TXT、DOCX 等格式中的章节、段落、表格和列表结构。它通常与 llmsherpa API 配合使用，为大模型项目提供结构化数据块。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 Linux 环境以获得最佳兼容性)
• Java: 必须安装最新版 Java (JDK/JRE)，这是运行底层 Tika 服务器的必要条件。
  • 下载地址：Oracle Java Downloads
• Python: Python 3.8+ 环境
• Docker (可选): 如果选择容器化部署，需安装 Docker。

安装步骤

您可以选择直接运行或Docker 部署两种方式。

方式一：直接运行（适合开发与调试）

1. 启动 Tika 服务器 下载或找到项目中的修改版 Tika JAR 文件，并在终端运行：

   java -jar <path_to_nlm_ingestor>/jars/tika-server-standard-nlm-modified-2.9.2_v2.jar
   

   注意：请将 <path_to_nlm_ingestor> 替换为您的实际项目路径。保持此终端窗口开启。

2. 安装 Python 包 在新的终端窗口中安装 ingestor：

   pip install nlm-ingestor
   

   国内加速提示：如果遇到下载速度慢的问题，建议使用清华或阿里镜像源： pip install nlm-ingestor -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 启动 Ingestor 服务

   python -m nlm_ingestor.ingestion_daemon
   

   默认服务将运行在 http://localhost:5001。

方式二：Docker 部署（推荐生产环境）

1. 拉取镜像

   docker pull ghcr.io/nlmatics/nlm-ingestor:latest
   

   国内加速提示：如果无法访问 ghcr.io，可能需要配置 Docker 镜像加速器或使用代理。

2. 运行容器 将容器端口映射到您选择的本地端口（例如 5010）：

   docker run -p 5010:5001 ghcr.io/nlmatics/nlm-ingestor:latest
   

基本使用

服务启动后，您可以通过 HTTP API 解析文档。最常用的是结合 llmsherpa 库使用，也可以直接使用 curl 测试。

1. 使用 llmsherpa 库（推荐）

首先安装客户端库：

pip install llmsherpa

然后使用以下 Python 代码进行解析：

from llmsherpa.readers import LayoutPDFReader

# 配置服务地址
# 如果使用 Docker 部署且映射到 5010 端口：
llmsherpa_api_url = "http://localhost:5010/api/parseDocument?renderFormat=all"

# 如果需要启用 OCR (针对扫描版 PDF)，添加 &applyOcr=yes
# llmsherpa_api_url = "http://localhost:5010/api/parseDocument?renderFormat=all&applyOcr=yes"

# 初始化阅读器
pdf_reader = LayoutPDFReader(llmsherpa_api_url)

# 解析本地文件或在线 URL
doc = pdf_reader.read_pdf("path/to/your/document.pdf")
# 或者 doc = pdf_reader.read_pdf("https://example.com/document.pdf")

# 遍历解析出的块 (chunks)
for chunk in doc.chunks():
    print(f"类型：{chunk.tag}, 内容：{chunk.to_text()}")

2. 直接使用 Curl 测试

如果您想直接测试 API 返回的 JSON 结构：

curl -X POST -F "file=@/path/to/your/document.pdf" "http://localhost:5010/api/parseDocument?renderFormat=all"

关键参数说明

在构建 API URL 时，可附加以下参数以增强功能：

• &applyOcr=yes: 自动对扫描页启用 OCR 识别。
• &useNewIndentParser=yes: 使用新的缩进算法来更准确地判断标题层级。

注意：默认端口为开发用途。在生产环境中部署时，建议将其置于 Nginx 或云网关之后，并配置 HTTPS 以确保安全。