重要提示：默认分支为 main，该分支跟踪活跃开发，可能领先于最新的支持版本。

如需使用最新稳定版本，请使用 release/26.03 分支。

请参阅相应的 NeMo Retriever Library 文档。

NeMo Retriever Library

NeMo Retriever Library 是一款可扩展、高性能的文档内容与元数据提取微服务。它利用专门的 NVIDIA NIM 微服务来查找、上下文化并提取文本、表格、图表和信息图，这些内容可用于下游的生成式应用中。

[!注] NeMo Retriever 提取也称为 NVIDIA Ingest 和 nv-ingest。

NeMo Retriever Library 支持将文档并行分割成页面，对其中的内容（如文本、表格、图表和信息图）进行分类、提取，并通过光学字符识别 (OCR) 进一步上下文化处理，最终输出为结构清晰的 JSON 模式。随后，NeMo Retriever Library 会为提取的内容计算嵌入向量，并将其存储到向量数据库 Milvus 中。

下图展示了 NeMo Retriever Library 的处理流程。

为了实现生产级别的性能和可扩展性，我们建议您使用 Kubernetes（Helm Charts）部署该流程及配套的 NIM 服务。更多信息请参阅 先决条件。

注： 随着近期仓库名称的变更，我们将逐步淘汰 nv-ingest API 并简化依赖关系。您可以通过 nemo_retriever 库子文件夹关注相关工作进展，并查看未来的 API 设计。

典型用法

对于小型工作负载，例如少于 100 个 PDF 文件的工作负载，您可以使用我们正在开发中的库设置，该设置可在本地 GPU 上运行 HuggingFace 模型，或在 build.nvidia.com 上托管的 NIM 服务上运行。

按照 快速入门安装步骤 后，您可以开始导入内容，例如使用以下代码片段：

from nemo_retriever import create_ingestor
from nemo_retriever.io import to_markdown, to_markdown_by_page
from pathlib import Path

documents = [str(Path("../data/multimodal_test.pdf"))]
ingestor = create_ingestor(run_mode="batch")

# 提取任务可以链式调用，且采用惰性定义
ingestor = (
  ingestor.files(documents)
  .extract(
    # 以下是默认值，但也可以控制提取的内容类型
    extract_text=True,
    extract_charts=True,
    extract_tables=True,
    extract_infographics=True
  )
  .embed()
  .vdb_upload()
)

# ingestor.ingest() 实际执行整个流程
# 结果以 Ray 数据集的形式返回，可按块检查
ray_dataset = ingestor.ingest()
chunks = ray_dataset.get_dataset().take_all()

您可以查看已提取的文本，这些文本代表了所导入测试文档的内容。

# 第一页原始文本：
>>> chunks[0]["text"]
'TestingDocument\r\n包含标题和占位符文本的示例文档\r\n引言\r\n这是一个可用于任何目的的占位符文档...'

# 第一页格式化为 Markdown 的表格
>>> chunks[1]["text"]
'| 表格 | 1 |\n| 此 | 表格 | 描述 | 一些 | 动物 | 和 | 一些 | 活动 | 它们 | 可能 | 在 | 特定 | 地点 | 进行。 |\n| 动物 | 活动 | 地点 |\n| 长颈鹿 | 开车 | 在 | 海滩 |\n| 狮子 | 涂抹 | 防晒霜 | 在 | 公园 |\n| 猫 | 跳上 | 笔记本电脑 | 在 | 家庭办公室 |\n| 狗 | 追逐 | 松鼠 | 在 | 前院 |\n| 图表 | 1 |'

# 第一页的一张图表
>>> chunks[2]["text"]
'图表 1\n此图表展示了一些小工具及其虚构的成本。\n小工具及其成本\n$160.00\n$140.00\n$120.00\n$100.00\n美元\n$80.00\n$60.00\n$40.00\n$20.00\n$-\n电钻\n蓝牙音箱\n迷你冰箱\n高级台扇\n锤子\n成本'

# 将整页或整份文档格式化为 Markdown：
# 文档结果按源文件名进行索引
>>> to_markdown_by_page(chunks).keys()
dict_keys(['multimodal_test.pdf'])

# 每个文档的结果以页码为键
>>> to_markdown_by_page(chunks)["multimodal_test.pdf"].keys()
dict_keys([1, 2, 3])

>>> to_markdown_by_page(chunks)["multimodal_test.pdf"][1]
'测试文档\r\n一个包含标题和占位符文本的示例文档\r\n引言\r\n这是一份可用于任何目的的占位符文档。它包含一些标题和一些占位符文本以填充空间。这些文本并不重要，也不具有实际价值，但对测试很有用。下面我们将有一些简单的表格和图表，可以用来确认 Ingest 是否按预期工作。\r\n表1\r\n此表描述了一些动物以及它们可能在特定地点进行的一些活动。\r\n动物 活动 地点\r\n长颈鹿 驾驶汽车 在海滩\r\n狮子 涂抹防晒霜 在公园\r\n猫 跳上笔记本电脑 在家庭办公室\r\n狗 追逐松鼠 在前院\r\n图1\r\n这张图展示了一些小工具以及一些虚构的成本。\n\n| 此 | 表格 | 描述 | 一些 | 动物，| 和 | 一些 | 活动 | 他们 | 或许 | 正在 | 进行 | 在 | 特定 |\n| 地点。|\n| 动物 | 活动 | 地点 |\n| 长颈鹿 | 驾驶 | 一辆 | 汽车 | 在 | 海滩 |\n| 狮子 | 涂抹 | 防晒霜 | 在 | 公园 |\n| 猫 | 跳跃 | 上 | 一台 | 笔记本电脑 | 在 | 一个 | 家庭 | 办公室 |\n| 狗 | 追逐 | 一只 | 松鼠 | 在 | 前 | 庭院 |\n| 图 | 1 |\n\n### 表1\n\n| 此 | 表格 | 描述 | 一些 | 动物，| 和 | 一些 | 活动 | 他们 | 或许 | 正在 | 进行 | 在 | 特定 |\n| 地点。|\n| 动物 | 活动 | 地点 |\n| 长颈鹿 | 驾驶 | 一辆 | 汽车 | 在 | 海滩 |\n| 狮子 | 涂抹 | 防晒霜 | 在 | 公园 |\n| 猫 | 跳跃 | 上 | 一台 | 笔记本电脑 | 在 | 一个 | 家庭 | 办公室 |\n| 狗 | 追逐 | 一只 | 松鼠 | 在 | 前 | 庭院 |\n| 图 | 1 |\n\n### 图1\n\n图1展示了某些小工具及其虚构的成本。小工具及其成本 $160.00 $140.00 $120.00 $100.00 美元 $80.00 $60.00 $40.00 $20.00 $- 电钻 蓝牙音箱 迷你冰箱 高级台式风扇 锤子 成本\n\n### 表2\n\n| 此 | 表格 | 描述 | 一些 | 动物，| 和 | 一些 | 活动 | 他们 | 或许 | 正在 | 进行 | 在 | 特定 |\n| 地点。|\n| 动物 | 活动 | 地点 |\n| 长颈鹿 | 驾驶 | 一辆 | 汽车 | 在 | 海滩 |\n| 狮子 | 涂抹 | 防晒霜 | 在 | 公园 |\n| 猫 | 跳跃 | 上 | 一台 | 笔记本电脑 | 在 | 一个 | 家庭 | 办公室 |\n| 狗 | 追逐 | 一只 | 松鼠 | 在 | 前 | 庭院 |\n| 图 | 1 |\n\n### 图2\n\n图1展示了某些小工具及其虚构的成本。小工具及其成本 $160.00 $140.00 $120.00 $100.00 美元 $80.00 $60.00 $40.00 $20.00 $- 电钻 蓝牙音箱 迷尼冰箱 高级台式风扇 锤子 成本\n\n### 表3\n\n| 此 | 表格 | 描述 | 一些 | 动物，| 和 | 一些 | 活动 | 他们 | 或许 | 正在 | 进行 | 在 | 特定 |\n| 地点。|\n| 动物 | 活动 | 地点 |\n| 长颈鹿 | 驾驶 | 一辆 | 汽车 | 在 | 海滩 |\n| 狮子 | 涂抹 | 防晒霜 | 在 | 公园 |\n| 猫 | 跳跃 | 上 | 一台 | 笔记本电脑 | 在 | 一个 | 家庭 | 办公室 |\n| 狗 | 追逐 | 一只 | 松鼠 | 在 | 前 | 庭院 |\n| 图 | 1 |\n\n### 图3\n\n图1展示了某些小工具及其虚构的成本。小工具及其成本 $160.00 $140.00 $120.00 $100.00 美元 $80.00 $60.00 $40.00 $20.00 $- 电钻 蓝牙音箱 迷尼冰箱 高级台式风扇 锤子 成本'

# 整个文档的 Markdown 也以源文件名为键
>>> to_markdown(chunks).keys()
dict_keys(['multimodal_test.pdf'])

第3步：查询已提取的内容

要查询已提取内容中的相关片段，并将其与 LLM 结合生成答案，请使用以下代码。

from nemo_retriever.retriever import Retriever
from openai import OpenAI
import os

retriever = Retriever()

query = "根据它们的活动，哪个动物导致了我的文档中出现错别字？"

# 也可以通过 retriever.queries[...] 提交列表
hits = retriever.query(query)

client = OpenAI(
  base_url = "https://integrate.api.nvidia.com/v1",
  api_key = os.environ.get("NVIDIA_API_KEY")
)

hit_texts = [hit["text"] for hit in hits]
prompt = f"""
根据以下检索到的文档，回答问题：{query}

文档：
{hit_texts}
"""

completion = client.chat.completions.create(
  model="nvidia/nemotron-3-super-120b-a12b",
  messages=[{"role":"user","content":prompt}],
  stream=False
)

answer = completion.choices[0].message.content
print(answer)

答案：

猫是那种活动（跳上笔记本电脑）与错别字位置相符的动物，因此文档中的错别字是由猫造成的。

[!提示] 除了检查结果之外，您还可以将这些结果导入诸如 llama-index 或 langchain 的检索管道中。

请同时查看我们在 build.nvidia.com 上提供的演示，该演示使用检索管道查询预先由 NVIDIA Ingest 提取的文档内容： build.nvidia.com/nvidia/multimodal-pdf-data-extraction-for-enterprise-rag

文档资源

• 官方文档 - 完整的用户指南、API 参考和部署说明
• 入门指南 - 生产部署概述和先决条件
• 基准测试指南 - 性能测试和召回率评估框架
• MIG 部署 - 用于 Kubernetes 的多实例 GPU 配置
• API 文档 - Python 客户端和 API 参考

公告

第三方许可声明：

如果已配置为执行此操作，该项目将下载并安装其他第三方开源软件项目。 在使用这些开源项目之前，请先查看其许可条款：

https://pypi.org/project/pdfservices-sdk/

• INSTALL_ADOBE_SDK:
  • 描述：如果设置为 true，Adobe SDK 将在容器启动时安装。如果您希望使用 Adobe 提取服务对 PDF 进行分解，则必须启用此选项。请在启用此选项前查阅 pdfservices-sdk 的许可协议。
• 基于 Llama 构建：

  • 描述：NV-Ingest 容器预装了 meta-llama/Llama-3.2-1B 分词器，以便分块任务可以直接使用该分词器进行基于标记的拆分，而无需发起网络请求。您对这些 Llama 资料的使用受《Llama 3.2 社区许可协议》约束。

    如果您自行构建容器并希望预先下载此模型，首先需要将 DOWNLOAD_LLAMA_TOKENIZER 设置为 True。由于该模型属于受控访问模型，您还需申请访问权限，并将您的 HuggingFace 访问令牌设置为 HF_ACCESS_TOKEN 才能使用它。

在为本项目做出贡献之前，请先阅读我们的贡献者指南。

安全注意事项

• NeMo Retriever Extraction 不会生成任何可能需要沙箱隔离的代码。
• NeMo Retriever Extraction 仅作为参考示例提供，按“原样”交付。生产环境中的安全性由部署它的最终用户负责。在生产环境中部署时，请务必请安全专家评估潜在风险与威胁；明确信任边界，实施日志记录与监控功能，确保通信通道的安全性，集成身份认证与授权机制并实施适当的访问控制，保持部署的最新状态，确保容器和源代码的安全且不存在已知漏洞。
• 应部署具备身份认证与授权功能的前端系统；若缺少此类功能，直接暴露于互联网等外部环境时，可能导致客户模型被未授权访问，从而造成客户成本增加、资源耗尽或服务拒绝等后果。
• NeMo Retriever Extraction 无需任何系统级别的特权访问权限。
• 最终用户需负责保障其部署的可用性。
• 最终用户需自行构建容器镜像并保持其更新。
• 最终用户需确保开发者蓝图中使用的开源软件包均为最新版本。
• Nginx 代理、后端服务及演示应用的日志均输出至标准输出流。出于开发目的，这些日志可能包含输入提示和输出内容。建议最终用户在生产环境中妥善管理日志记录，避免信息泄露。

NeMo-Retriever 快速上手指南

NeMo-Retriever（曾用名 NVIDIA Ingest）是一个可扩展的文档内容与元数据提取微服务。它利用 NVIDIA NIM 微服务，从文档中精准查找、上下文化并提取文本、表格、图表和信息图，并将其转换为结构化 JSON 或 Markdown，适用于下游生成式 AI 应用（如 RAG）。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04/22.04)
• GPU: 支持 CUDA 的 NVIDIA GPU（本地运行需安装驱动；若使用云端 NIM 则无需本地 GPU）
• Python: 3.10 或更高版本
• 容器运行时: Docker 或 Kubernetes（生产环境推荐）

前置依赖

• NVIDIA API Key: 若使用 build.nvidia.com 托管的 NIM 服务，需准备 API Key。
• 向量数据库: 如需存储嵌入向量，需部署 Milvus 或使用默认配置。
• 可选依赖:
  • 若需使用 Adobe PDF 分解服务，需同意其许可协议并设置 INSTALL_ADOBE_SDK=true。
  • 若需本地进行基于 Token 的文档分割，需申请 HuggingFace 权限并设置 HF_ACCESS_TOKEN 以下载 Llama 3.2 分词器。

安装步骤

对于小规模工作负载（如少于 100 个 PDF），推荐使用开发版库直接在本地 Python 环境中运行，配合本地 GPU 或云端 NIM。

1. 安装 Python 包

   pip install nemo-retriever
   

2. 配置环境变量 如果使用云端 NIM 服务，请导出您的 NVIDIA API Key：

   export NVIDIA_API_KEY="your_nvidia_api_key_here"
   

   (注：目前官方未提供特定的中国镜像源，如遇网络问题，请配置通用的 PyPI 国内镜像，如清华源或阿里源)

   pip install nemo-retriever -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

以下示例展示如何提取 PDF 中的文本、表格和图表，将其转换为 Markdown 格式，并进行简单的检索问答。

1. 文档提取与转换

创建一个 Python 脚本（例如 ingest_example.py）：

from nemo_retriever import create_ingestor
from nemo_retriever.io import to_markdown, to_markdown_by_page
from pathlib import Path

# 指定待处理的文档路径
documents = [str(Path("multimodal_test.pdf"))]

# 创建提取器，设置为批处理模式
ingestor = create_ingestor(run_mode="batch")

# 定义处理流水线：加载文件 -> 提取内容 -> 生成嵌入 -> 上传至向量库
# 可根据需要控制提取类型 (extract_text, extract_charts, extract_tables, extract_infographics)
ingestor = (
  ingestor.files(documents)
  .extract(
    extract_text=True,
    extract_charts=True,
    extract_tables=True,
    extract_infographics=True
  )
  .embed()
  .vdb_upload()
)

# 执行流水线
ray_dataset = ingestor.ingest()
chunks = ray_dataset.get_dataset().take_all()

# 查看提取结果 (例如第一页的原始文本)
print("Page 1 Raw Text:")
print(chunks[0]["text"])

# 将结果转换为按页组织的 Markdown
md_by_page = to_markdown_by_page(chunks)
print("\nMarkdown Keys:", md_by_page.keys())

2. 检索与生成回答

提取完成后，可使用内置的 Retriever 结合大模型进行问答：

from nemo_retriever.retriever import Retriever
from openai import OpenAI
import os

# 初始化检索器
retriever = Retriever()

query = "Given their activities, which animal is responsible for the typos in my documents?"

# 执行检索
hits = retriever.query(query)

# 配置 OpenAI 客户端指向 NVIDIA 接口
client = OpenAI(
  base_url="https://integrate.api.nvidia.com/v1",
  api_key=os.environ.get("NVIDIA_API_KEY")
)

# 构建提示词
hit_texts = [hit["text"] for hit in hits]
prompt = f"""
Given the following retrieved documents, answer the question: {query}

Documents:
{hit_texts}
"""

# 调用模型生成回答
completion = client.chat.completions.create(
  model="nvidia/nemotron-3-super-120b-a12b",
  messages=[{"role": "user", "content": prompt}],
  stream=False
)

answer = completion.choices[0].message.content
print("Answer:", answer)

输出示例：

Answer: Cat is the animal whose activity (jumping onto a laptop) matches the location of the typos, so the cat is responsible for the typos in the documents.

提示: 提取出的 chunks 数据也可以直接集成到 LlamaIndex 或 LangChain 的 RAG 流水线中使用。