# 视觉文档检索

如果文档除了文本之外还包含图表、表格和视觉元素，则可能包含多模态数据。从这些文档中检索信息颇具挑战性，因为仅靠文本检索模型无法处理视觉数据，而图像检索模型又缺乏足够的细粒度以及文档处理能力。

视觉文档检索有助于从各类文档中检索信息，包括多模态检索增强生成（RAG）。这些模型接受文档（以图像形式）和文本，并计算它们之间的相似度分数。

本指南演示如何使用 [ColPali](../model_doc/colpali) 对文档进行索引和检索。

> [!TIP]
> 对于大规模应用场景，您可能希望使用向量数据库来索引和检索文档。

请确保已安装 Transformers 和 Datasets。

```bash
pip install -q datasets transformers
```

我们将对一组与 UFO 目击事件相关的文档数据集建立索引。我们会过滤掉目标列缺失的样本。该数据集包含多个列，我们关注的是 `specific_detail_query` 列，其中包含文档的简短摘要，以及 `image` 列，其中包含我们的文档。

```python
from datasets import load_dataset

dataset = load_dataset("davanstrien/ufo-ColPali")
dataset = dataset["train"]
dataset = dataset.filter(lambda example: example["specific_detail_query"] is not None)
print(dataset)
```

```text
Dataset({
    features: ['image', 'raw_queries', 'broad_topical_query', 'broad_topical_explanation', 'specific_detail_query', 'specific_detail_explanation', 'visual_element_query', 'visual_element_explanation', 'parsed_into_json'],
    num_rows: 2172
})
```

让我们加载模型和分词器。

```python
import torch
from transformers import ColPaliForRetrieval, ColPaliProcessor
from accelerate import Accelerator

device = Accelerator().device

model_name = "vidore/colpali-v1.2-hf"

processor = ColPaliProcessor.from_pretrained(model_name)

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    dtype=torch.bfloat16,
    device_map="auto",
).eval()
```

将文本查询传入处理器，并返回模型生成的带索引的文本嵌入。对于图像到文本的搜索，请将 [ColPaliProcessor](/docs/transformers/main/zh/model_doc/colpali#transformers.ColPaliProcessor) 中的 `text` 参数替换为 `images` 参数，以传入图像。

```python
inputs = processor(text="a document about Mars expedition").to(model.device)
with torch.no_grad():
  text_embeds = model(**inputs, return_tensors="pt").embeddings
```

在离线阶段对图像进行索引，在推理阶段返回查询文本的嵌入，以获取其最接近的图像嵌入。

通过向数据集写入图像和图像嵌入来存储它们，如下所示，使用 [map](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset.map)。添加一个包含索引嵌入的 `embeddings` 列。ColPali 嵌入占用大量存储空间，因此请将其从加速器中移除，并以 NumPy 向量的形式存储在 CPU 上。

```python
ds_with_embeddings = dataset.map(lambda example: {'embeddings': model(**processor(images=example["image"]).to(device), return_tensors="pt").embeddings.to(torch.float32).detach().cpu().numpy()})
```

对于在线推理，创建一个函数以批量搜索图像嵌入并检索最相关的 k 个图像。下面的函数针对给定的索引数据集、文本嵌入、前 k 个结果的数量以及批处理大小，返回数据集中的索引及其得分。

```python
def find_top_k_indices_batched(dataset, text_embedding, processor, k=10, batch_size=4):
    scores_and_indices = []

    for start_idx in range(0, len(dataset), batch_size):

        end_idx = min(start_idx + batch_size, len(dataset))
        batch = dataset[start_idx:end_idx]        
        batch_embeddings = [torch.tensor(emb[0], dtype=torch.float32) for emb in batch["embeddings"]]
        scores = processor.score_retrieval(text_embedding.to("cpu").to(torch.float32), batch_embeddings)

        if hasattr(scores, "tolist"):
            scores = scores.tolist()[0]

        for i, score in enumerate(scores):
            scores_and_indices.append((score, start_idx + i))

    sorted_results = sorted(scores_and_indices, key=lambda x: -x[0])

    topk = sorted_results[:k]
    indices = [idx for _, idx in topk]
    scores = [score for score, _ in topk]

    return indices, scores
```

生成文本嵌入，并将其传递给上述函数，以返回数据集索引和分数。

```python
with torch.no_grad():
  text_embeds = model(**processor(text="a document about Mars expedition").to(model.device), return_tensors="pt").embeddings
indices, scores = find_top_k_indices_batched(ds_with_embeddings, text_embeds, processor, k=3, batch_size=4)
print(indices, scores)
```

```text
([440, 442, 443],
 [14.370786666870117,
  13.675487518310547,
  12.9899320602417])
```

显示图像以查看与火星相关的文档。

```python
for i in indices:
  display(dataset[i]["image"])
```

    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/doc_1.png"
         alt="Document 1"
         style="height: 200px; object-fit: contain; margin-right: 10px;">
    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/doc_2.png"
         alt="Document 2"
         style="height: 200px; object-fit: contain;">
    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/doc_3.png"
         alt="Document 3"
         style="height: 200px; object-fit: contain;">

