NVIDIA AI 蓝图：PDF 转播客

概述

本 NVIDIA AI 蓝图向开发者展示了如何构建一款将 PDF 文件转换为引人入胜的音频内容的应用程序。该蓝图基于 NVIDIA NIM 构建，具有高度灵活性，可在私有网络中安全运行，在不共享敏感数据的情况下提供可操作的洞察。

该蓝图接受一个目标 PDF 文件，并可选择性地上传多个上下文 PDF 文件。目标 PDF 将作为生成转录文本的主要信息来源，而上下文 PDF 则用作智能体的额外参考材料。用户还可以选择性地指定引导提示，以帮助智能体生成有针对性的转录文本（例如：“重点关注英伟达第三季度财报的关键驱动因素”）。

有关 PDF、智能体和 TTS 服务流程的更多信息，请参阅 Mermaid 图表。

:exclamation: 重要
使用 NVIDIA AI Workbench 运行此蓝图的用户，请直接跳转至快速入门部分 此处!

软件组件

• NVIDIA NIM 微服务
  • 响应生成（推理）
    • NIM for meta/llama-3.1-8b-instruct
    • NIM for meta/llama-3.1-70b-instruct
    • NIM for meta/llama-3.1-405B-instruct
• 文档摄取与提取 - Docling
• 文本转语音 - ElevenLabs
• Redis - Redis
• 存储 - MinIO

注意: 由于 NVIDIA 蓝图可根据您的具体业务场景和/或基础设施进行调整，上述软件组件均可配置。例如，为了减少所需的 GPU 显存，您可以使用较小的 Llama 3.1-8B NIM，并在 docker-compose.yaml 中禁用 Docling 的 GPU 使用。

我们提供了 Docker Compose 脚本，可在单个节点上启动这些微服务。该蓝图包含示例用例 PDF 文件，但开发者可以根据自身特定用例，使用自己的 PDF 文件在此基础上进行扩展。

硬件要求

以下是硬件要求，具体取决于您选择的部署方式。部署此蓝图有两种方法：

1. 默认方式 - 使用 NVIDIA API 目录中的 NIM 端点

   • 可在任何非 GPU 加速的机器或虚拟机上运行
     • 8 核 CPU
     • 64 GB 内存
     • 100 GB 磁盘空间
     • 需要一个公网 IP 地址

2. 在本地托管 NVIDIA NIM

   • Meta Llama 3.1 8B Instruct 支持矩阵
   • Meta Llama 3.1 70B Instruct 支持矩阵
   • Meta Llama 3.1 405B Instruct 支持矩阵

注意: 若要大规模运行该蓝图并加快 PDF 的预处理速度，建议使用 GPU 来运行 PDF 摄取/提取管道。

先决条件

• 需要 NVIDIA AI Enterprise 开发者许可证才能在本地托管 NVIDIA NIM。
• API 目录密钥：
  • NVIDIA API 目录 或 NGC
  • ElevenLabs

快速入门指南

1. Docker Compose

系统要求：基于 Ubuntu 20.04 或 22.04 的机器，具备 sudo 权限

安装软件要求：

• 安装 Docker 引擎和 Docker Compose。请参考 Ubuntu 的安装说明。
• 确保 Docker Compose 插件版本为 2.29.1 或更高。
• 运行 docker compose version 进行确认。
• 更多信息请参阅 Docker 文档中的 安装 Compose 插件。
• 若要配置 Docker 以支持 GPU 加速容器，请安装 NVIDIA Container Toolkit。
• 安装 git

2. 获取 API 密钥：

NVIDIA 推理微服务 (NIM)

• 有两种方法可以为 NIM 生成 API 密钥：
  • 使用您的电子邮件登录 NVIDIA Build 门户。
    • 点击任意一个 模型，然后点击“获取 API 密钥”，最后点击“生成密钥”。
  • 使用您的电子邮件登录 NVIDIA NGC 门户。
    • 登录后从下拉菜单中选择您的组织。您必须选择已启用 NVIDIA AI Enterprise (NVAIE) 的组织。
    • 点击右上角的账户，在下拉菜单中选择“设置”。
    • 点击“生成个人密钥”选项，然后点击“+ 生成个人密钥”按钮以创建您的 API 密钥。
      • 此密钥将用于 NVIDIA_API_KEY 环境变量。
    • 点击“生成 API 密钥”选项，然后点击“+ 生成 API 密钥”按钮以创建 API 密钥。

重要提示：此密钥将用于下方的 NVIDIA_API_KEY 环境变量。

ElevenLabs

3. 克隆仓库

   git clone https://github.com/NVIDIA-AI-Blueprints/pdf-to-podcast
   

4. 设置环境变量

   # 在 /home/<username>/.local/bin/env 中创建包含所需变量的 .env 文件
   echo "ELEVENLABS_API_KEY=your_key" >> .env
   echo "NVIDIA_API_KEY=your_key" >> .env
   echo "MAX_CONCURRENT_REQUESTS=1" >> .env
   

注意： ElevenLabs API 密钥可以处理并发请求。对于本地开发，建议将 MAX_CONCURRENT_REQUESTS 设置为 1，以避免速率限制问题。

5. 安装依赖项

我们使用 UV 来管理 Python 依赖项。

make uv

这将：

• 如果未安装 UV，则进行安装
• 创建虚拟环境
• 安装项目依赖项

如果您打开一个新的终端窗口并希望快速重新使用相同的环境，可以再次运行 make uv。

6. 启动开发服务器

   make all-services
   

注意： 首次运行 make all-services 时，docling 服务可能需要 10-15 分钟来拉取和构建镜像。后续运行会快得多。

该命令将：

• 验证环境变量是否已设置
• 创建必要的目录
• 使用 Docker Compose 以 --build 模式启动所有服务。

注意： 设置 DETACH=1 可以使服务在分离模式下运行，以便在服务运行时继续使用您的终端。

7. 查看 Swagger API 文档

要查看 API 的 Swagger UI，您可以本地访问 localhost:8002/docs。如果在虚拟机上运行，您需要将 8002 端口进行端口转发，或将该端口暴露在您的虚拟机上。

8. 生成播客

   source .venv/bin/activate
   python tests/test.py --target <pdf1.pdf> --context <pdf2.pdf>
   

默认情况下，此命令会生成一个双人播客。若要生成单人播客，请添加 --monologue 标志。重要提示：默认情况下，test.py 假设 PDF 文件位于 samples 目录中。

若测试过程中出现错误，可查看 Docker Compose 的日志以进行调试。

自定义

1. 将 PDF 服务托管在独立机器上。

本蓝图默认使用 docling 作为 PDF 提取服务。

若要在独立机器上运行 PDF 提取服务，请在 .env 文件中添加以下内容：

echo "MODEL_API_URL=<pdf-model-service-url" >> .env

make model-dev 目标将仅启动 docling 服务。

2. 使用自托管的 NIM

默认情况下，本蓝图使用由 3 个 LLM 组成的集成模型来生成播客。示例中使用了 Llama 3.1-8B、Llama 3.1-70B 和 Llama 3.1-405B NIM，以实现性能与准确性的平衡。若要使用其他模型，请更新 models.json 文件以包含所需的模型。默认的 models.json 会调用 NVIDIA 托管的 API 目录端点。这是默认配置，推荐给刚开始使用本蓝图的用户；但当您希望对蓝图进行调整时，则需要使用本地托管的 NIM 端点。

3. 更改默认模型和 GPU 分配

您可以轻松替换堆栈中的不同组件，以优化现有硬件上的 GPU 使用情况。例如，通过替换为较小的 Llama 3.1-8B NIM，并在 docker-compose.yaml 中禁用 docling 的 GPU 使用，从而减少 GPU 资源占用。

4. 启用追踪功能

我们在 http://localhost:16686/ 上公开了一个 Jaeger 实例，用于系统追踪。这对于调试和监控系统非常有用。

贡献

1. fork 仓库
2. 创建功能分支
3. 进行更改
4. 运行测试： python tests/test.py
5. 运行代码检查： make ruff
6. 提交拉取请求

代码质量

该项目使用 ruff 进行代码检查和格式化。在合并您的 PR 之前，必须运行 make ruff：

make ruff  # 同时运行检查和格式化

CI/CD

我们使用 GitHub Actions 进行 CI/CD。我们执行以下操作：

• ruff：运行代码检查和格式化
• pr-test：在 PR 上运行端到端播客测试
• build-and-push：构建并将新的容器镜像推送到远程仓库。此操作用于更新生产部署。

安全注意事项

重要提示：此设置使用 HTTP 协议，不适用于生产环境部署。对于生产环境部署，建议实施以下安全措施：

• 添加 SSL/TLS 加密，方法如下：
  • 使用 SSL 证书配置 uvicorn
  • 设置反向代理（如 Nginx）以处理 SSL 终止
  • 实施适当的证书管理
  • 配置合适的安全头信息
• 遵循其他 Web 安全最佳实践

PDF 转播客 (pdf-to-podcast) 快速上手指南

本指南帮助开发者快速部署 NVIDIA AI Blueprint: PDF to Podcast，将 PDF 文档转换为生动的双人或单人播客音频。该工具基于 NVIDIA NIM 构建，支持私有网络部署，保障数据安全。

环境准备

系统要求

• 操作系统: Ubuntu 20.04 或 22.04
• 权限: 需要 sudo 权限
• 硬件配置 (取决于部署方式):
  • 方案 A (默认，调用云端 API): 适用于无 GPU 机器
    • 8 CPU 核心
    • 64 GB 内存
    • 100 GB 磁盘空间
    • 需具备公网 IP
  • 方案 B (本地托管 NIM): 需配备相应规格的 NVIDIA GPU (参考 Llama 3.1 8B/70B/405B 支持矩阵)
  • 建议: 若需大规模运行或加速 PDF 预处理，推荐使用 GPU 运行 Docling 服务。

前置依赖

1. Docker 环境:
   • 安装 Docker Engine 和 Docker Compose (插件版本需 ≥ 2.29.1)。
   • 若使用 GPU，需安装 NVIDIA Container Toolkit。
   • 安装 git。
2. API 密钥:
   • NVIDIA API Key: 用于推理服务 (Llama 3.1)。
     • 访问 NVIDIA Build 或 NGC 生成。
   • ElevenLabs API Key: 用于文本转语音 (TTS)。
     • 访问 ElevenLabs 获取。
   • 注意: 本地托管 NVIDIA NIM 需要 NVIDIA AI Enterprise 开发者许可证。

安装步骤

1. 克隆项目

git clone https://github.com/NVIDIA-AI-Blueprints/pdf-to-podcast
cd pdf-to-podcast

2. 配置环境变量

在项目根目录下创建 .env 文件并填入您的 API 密钥。 注：本地开发建议将并发请求数设为 1 以避免速率限制。

echo "ELEVENLABS_API_KEY=your_elevenlabs_key" >> .env
echo "NVIDIA_API_KEY=your_nvidia_key" >> .env
echo "MAX_CONCURRENT_REQUESTS=1" >> .env

(请将 your_elevenlabs_key 和 your_nvidia_key 替换为实际密钥)

3. 安装依赖

本项目使用 uv 管理 Python 依赖。运行以下命令自动安装 uv、创建虚拟环境并安装项目依赖：

make uv

4. 启动服务

启动所有微服务（包括 Docling、Redis、MinIO 等）。 首次运行可能需要 10-15 分钟拉取和构建 Docling 镜像，后续启动将更快。

make all-services

提示：若希望后台运行以便继续使用终端，可添加 DETACH=1 参数：DETACH=1 make all-services

基本使用

服务启动后，您可以通过命令行脚本生成播客。默认情况下，脚本会读取 samples 目录下的 PDF 文件。

生成双人播客

激活虚拟环境并运行测试脚本，指定目标 PDF (--target) 和可选的上下文 PDF (--context)：

source .venv/bin/activate
python tests/test.py --target samples/target.pdf --context samples/context.pdf

生成单人播客

添加 --monologue 标志即可生成单人讲述模式：

python tests/test.py --target samples/target.pdf --monologue

查看 API 文档

如需查看详细的 Swagger API 文档，请在浏览器访问：

• 本地访问: http://localhost:8002/docs
• 若在虚拟机运行，请确保端口 8002 已映射或转发。

调试与监控

• 查看日志: 若运行出错，请检查 Docker Compose 日志。
• 链路追踪: 系统内置 Jaeger 实例，访问 http://localhost:16686/ 可进行调试和监控。