dustynv/nanodb

NanoDB 镜像文档

1. 镜像概述和主要用途

NanoDB 是一个基于 CUDA 优化的多模态向量数据库，它使用 CLIP（对比语言-图像预训练）视觉Transformer模型生成的嵌入向量，实现文本到图像（txt2img）和图像到图像（img2img）的相似性搜索。该数据库专为边缘设备优化，可在 Jetson 等嵌入式平台上实时运行（如在 Jetson AGX Orin 上对 MS COCO 数据集的 27.5 万张图像进行实时检索）。

除边缘环境下的高效数据索引与检索外，NanoDB 常与大型语言模型（LLM）结合，用于检索增强生成（RAG），以扩展 LLM 的上下文长度（如突破 Llama-2 模型的 4096 令牌限制）。同时，其生成的嵌入向量可直接作为视觉语言模型（VLM）的输入。

2. 核心功能与特性

• CUDA 加速：针对 GPU 优化，支持边缘设备上的高效向量计算。
• 多模态嵌入：基于 CLIP 模型生成文本与图像的共享嵌入空间，实现跨模态检索。
• 数据索引：递归扫描图像目录，自动计算嵌入向量并以 float16 格式存储，节省存储空间。
• 灵活交互：支持控制台命令行交互（搜索、增量扫描、数据库保存）和 Web UI（Gradio）可视化操作。
• 兼容性：与 Jetson 平台的 JetPack 系统（L4T ≥32.6）兼容，依赖 PyTorch、FAISS 等开源库。
• RAG 集成：生成的嵌入向量可作为 LLM 的外部知识库，支持长文本记忆与检索。

3. 使用场景

• 边缘多模态检索：在嵌入式设备上对本地图像数据集进行文本或图像查询（如工业质检、安防监控）。
• 检索增强生成（RAG）：为 LLM 提供外部知识库，扩展其上下文能力，适用于问答系统、文档分析。
• 视觉语言模型输入：生成的嵌入向量可直接作为 VLM 的输入，支持图像描述、跨模态理解等任务。
• 数据集管理：对大规模图像数据集进行高效索引与相似性去重。

4. 部署与运行

4.1 前提条件

• 硬件：Jetson 系列设备（如 AGX Orin、Xavier NX 等）。
• 系统：JetPack 5.1+（L4T R35.x）或 JetPack 6.0+（L4T R36.x）。
• 软件：Docker 与 NVIDIA Container Runtime 已安装。

4.2 镜像获取

NanoDB 镜像可通过 jetson-containers 工具自动获取（推荐），或手动指定 Docker 镜像标签：

bash
# 使用 jetson-containers 自动拉取/构建兼容镜像
jetson-containers run $(autotag nanodb)

# 或手动指定镜像标签（需匹配 JetPack 版本）
sudo docker run --runtime nvidia -it --rm --network=host dustynv/nanodb:r36.2.0

4.3 数据索引

4.3.1 基本索引命令

将本地图像数据集挂载到容器中，通过 --scan 命令递归扫描并生成嵌入向量：

bash
# 示例：索引 /path/to/dataset 目录，结果保存至 /path/to/dataset/nanodb
sudo docker run --runtime nvidia -it --rm \
  -v /path/to/dataset:/my_dataset \
  dustynv/nanodb:r36.2.0 \
  python3 -m nanodb \
    --scan /my_dataset \          # 待扫描的图像目录（可多次指定）
    --path /my_dataset/nanodb \   # 数据库保存路径（自动创建）
    --autosave \                  # 扫描后自动保存数据库
    --validate                    # 验证图像是否可被正确检索

说明：若数据集位于 jetson-containers/data 目录下，容器会自动将其挂载为 /data，无需额外 -v 参数。

4.3.2 预索引数据库

如需跳过索引步骤，可下载预构建的数据库，参考 NanoDB 教程。

4.4 控制台交互

索引完成后，NanoDB 会进入命令行交互模式，支持搜索、增量扫描、保存数据库等操作。

4.4.1 文本/图像搜索

在控制台输入文本查询，返回相似图像结果：

bash
> a girl riding a horse  # 文本查询示例

# 输出结果（默认返回 top 8，可通过 --k 参数调整）
* index=80110   /data/datasets/coco/2017/train2017/000000393735.jpg      similarity=0.29991915822029114
* index=158747  /data/datasets/coco/2017/unlabeled2017/000000189708.jpg  similarity=0.29254037141799927
...

4.4.2 增量扫描目录

输入目录路径，增量扫描并添加新图像到数据库：

bash
> /data/pascal_voc  # 扫描新数据集目录

# 输出示例
-- loaded /data/pascal_voc/VOCdevkit/VOC2012/JPEGImages/2007_000027.jpg in 4 ms
-- loaded /data/pascal_voc/VOCdevkit/VOC2012/JPEGImages/2007_000032.jpg in 2 ms
...

4.4.3 保存数据库

完成增量更新后，保存数据库：

bash
> save  # 将更新保存至 --path 指定的目录

# 输出示例
-- saving database to /my_dataset/nanodb

4.5 交互式 Web UI

通过 --server 参数启动 Gradio Web 服务，支持文本查询与图像上传：

4.5.1 启动 Web UI

bash
sudo docker run --runtime nvidia -it --rm \
  -v /path/to/dataset:/my_dataset \
  -p 7860:7860 \  # 映射端口（默认 7860）
  dustynv/nanodb:r36.2.0 \
  python3 -m nanodb \
    --path /my_dataset/nanodb \   # 加载现有数据库
    --server \                    # 启动 Web 服务
    --port=7860 \                 # 端口号（默认 7860）
    --host=0.0.0.0                # 绑定所有网络接口（默认）

4.5.2 访问 Web UI

在浏览器中访问 http://<设备IP>:7860?__theme=dark，可输入文本查询或上传图像进行相似性搜索。

5. 配置参数说明

6. 镜像信息

6.1 可用镜像标签

兼容性说明：L4T R35.x 镜像可在所有 JetPack 5.1+ 版本上运行，R36.x 镜像可在 JetPack 6.0+ 上运行。

6.2 依赖项

NanoDB 依赖以下组件（已预安装在镜像中）：

• 系统库：build-essential、cmake、rust
• CUDA 组件：cuda:11.4、cudnn、cuda-python
• 深度学习框架：pytorch:2.2、torchvision、tensorrt、torch2trt
• 工具库：numpy、onnx、faiss（向量检索）、huggingface_hub、transformers

7. 构建容器（可选）

若需手动构建镜像，可使用 jetson-containers 工具：

bash
# 自动构建兼容当前 JetPack 版本的镜像
jetson-containers build nanodb

构建过程将自动拉取依赖项并编译，完成后可通过 autotag nanodb 引用生成的镜像。