跳到正文
Hugging Face Blog·· 2026-08-18精選AI 評分72

Sentence Transformers v6.0 多向量(Late Interaction)嵌入模型使用指南

Multi-Vector (Late Interaction) Embedding Models with Sentence Transformers

AI 導讀

Sentence Transformers v6.0 新增 MultiVectorEncoder,支援 ColBERT 式多向量檢索。文中示範載入 PyLate 與 Stanford-NLP ColBERT checkpoint、接入檢索索引,以及以同一 API 執行 ColPali 視覺文件檢索。

推薦理由

文章對照 LateOn 與 DenseOn 在 NanoBEIR 13 個資料集的結果,並以索引體積數據呈現多向量檢索表現與儲存成本的取捨。

正文 · 繁體中文

Sentence Transformers 是一個 Python 程式庫,可用於使用及訓練嵌入和重排序模型,支援檢索增強生成、語義搜尋等應用。v6.0 更新加入第四種模型類型:用於 ColBERT 式晚期交互檢索的 MultiVectorEncoder。任何 PyLate 或 Stanford-NLP ColBERT checkpoint 都可直接載入;colpali-engine 的視覺文件檢索模型也可使用,而且沿用你使用密集、稀疏及重排序模型時熟悉的 API。

一般嵌入模型會把整段文字壓縮成一個向量;多向量模型則會為每個 token 保留一個向量,再以 MaxSim 運算子計算查詢與文件的分數。這樣能保留單一向量不得不平均掉的 token 層級配對資訊,通常可提升檢索效果,代價是索引較大。它亦是視覺文件檢索的最先進方法,可直接以文字查詢比對頁面影像,毋須經過 OCR。

本文會示範如何使用這些模型:載入不同格式的 checkpoint、編碼和計分、接入搜尋架構、處理頁面影像,以及控制索引成本。以下所有內容只需執行一般的 pip install -U sentence-transformers 即可。

本文介紹如何使用多向量模型。如想了解如何訓練這些模型,請參閲配套網誌使用 Sentence Transformers 訓練及微調多向量嵌入模型。

目錄

甚麼是多向量模型?

密集嵌入模型讀取文字後會輸出一個固定大小的向量。模型注意到的所有內容都必須塞進 384、768 或 1024 個數值中,而相似度則是兩個摘要向量之間的一次點積。這種方法效果相當出色,但壓縮會帶來特定資訊損失:罕見實體、精確識別碼,或長篇段落中的關鍵子句,都要爭奪同一向量中的空間。包含多項要求的查詢也會遇到同樣限制。以「綠色梳化、木腳和圓潤坐墊」為例,單一向量必須把四項條件融合成一個點,因此腳架不合的綠色梳化也可能與你真正想找的款式非常接近。

多向量模型(亦稱為晚期交互或 ColBERT 式模型,名稱源自ColBERT 論文)省略了這種壓縮。它使用相同的 Transformer,但不會把 token 嵌入池化成單一向量,而是把每個 token 嵌入投影至較小維度(傳統上是 128),並全部保留下來。包含 9 個 token 的文件會變成 9x128 矩陣,而不是 1x128 向量。

查詢與文件的交互會延至計分時才進行,「晚期交互」一名由此而來。交叉編碼器會提早交互,讓兩段文字一同輸入模型;雖然準確,但無法預先計算,因為每次有新查詢時都要重新編碼每份文件。上文的密集嵌入模型屬於雙編碼器,兩者幾乎不會交互(只對兩個已完成的摘要向量計算一次點積),這正是可以只編碼一次整個資料集、並快速查詢的原因。晚期交互介乎兩者之間:文件仍可獨立編碼並離線建立索引,但計分時會比較每個查詢 token 與每個文件 token,讓兩者有更多交互空間。

Dense embedding versus multi-vector late interaction: a dense model encodes each text into one vector and scores with cosine similarity, while a multi-vector model keeps one vector per token and scores every query token against every document token with MaxSim

MaxSim 運算子

計分會使用 MaxSim:對每個查詢 token,找出它與任何文件 token 之間的最高相似度,再把查詢中各 token 的最高值相加。

MaxSim(Q,D)=∑Qi∈Qmax⁡Dj∈DQi⋅Dj\text{MaxSim}(Q, D) = \sum_{Q_i \in Q} \max_{D_j \in D} Q_i \cdot D_j

由於 token 嵌入經過 L2 正規化,每個點積都是介乎 [-1, 1] 的餘弦相似度,因此總和會落在 [-num_query_tokens, num_query_tokens] 範圍內。

可以把這個運算子理解為一種軟對齊:每個查詢 token 都會指向最能解釋它的文件 token,而分數則表示整份文件整體上對查詢的支持程度。

由於 token 嵌入包含上下文資訊,這種對齊不必是字面配對。使用 lightonai/mLateOn 對「企鵝住在哪裏?」和「企鵝棲居於南極洲。」進行編碼,查詢 token live 會以 0.94 的相似度配對到 inhabit,兩個字甚至沒有任何相同字母!這正是字面檢索做不到的事:BM25 及同類方法需要詞項本身,因此同義詞和意譯容易被漏掉。密集嵌入模型當然也能彌補這個差距。晚期交互的優勢,是在做到這一點的同時,保留另一個方向的能力。若精確配對很重要(例如產品代碼、姓氏或函式名稱),MaxSim 仍會把該 token 獨立保留;單一向量模型則必須把它與所有其他內容平均融合。它也不是一對一配對,因為多個查詢 token 經常會對應至同一個文件 token。

效益與代價

多向量模型可提升檢索品質,尤其適用於由文件中特定內容決定相關性的查詢、像上文梳化例子那樣每項要求都需要各自證據的複合查詢,以及密集模型的壓縮方式針對不同資料分佈調校過的領域外資料。這種壓縮是從訓練查詢中學得,因此模型會保留訓練時需要的內容、丟棄其他資訊;被丟掉的內容可能正是你的正式環境查詢所需。文件越長,影響越明顯,因為更多文字必須塞進同一個固定向量。

代價是索引大小。每個 token 一個向量,而不是每份文件一個向量,向量數目會大幅增加;較小的維度只能抵銷部分增幅。使用 lightonai/LateOn 編碼 4,874 段 Natural Questions 內容後,產生了 608,414 個 token 向量,平均每段 124.8 個:

表徵方式 向量數 維度 float32 大小
密集,all-MiniLM-L6-v2 4,874 384 7.5 MB
密集,gte-modernbert-base 4,874 768 15.0 MB
多向量,LateOn 608,414 128 311.5 MB

這約為 MiniLM 索引儲存空間的 42 倍,即每段 62 KiB。不過索引通常會壓縮,例如同一批 608,414 個向量製成 fast-plaid 索引後只佔 92 MB,因為 PLAID 為每個向量儲存的是中心點 ID 和量化殘差,而非向量本身。作為比較,像 Qwen3-Embedding-8B 這種 4096 維密集模型,處理同樣 4,874 段內容約需 80 MB;因此壓縮後的多向量索引,大小與大家現有的密集索引相若。Token 池化可在此之前減少向量數目,而先檢索後重排序則完全毋須建立索引。

本文會多次提到 PyLate,簡單來説:Sentence Transformers 原本支援密集和稀疏模型,但不支援晚期交互,因此 LightOn 在其上建立 PyLate,補足這項能力,並加入這些模型所需的訓練、推論和檢索功能。下文會載入的許多模型都是以它訓練,LightOn 亦圍繞它建立了一套生態系統,包括fast-plaid;這種晚期交互索引會在索引一節介紹。v6.0 起,這些功能已直接納入 Sentence Transformers。

瞭解這項取捨後,現在就來執行模型。

安裝

一般安裝即可使用多向量模型:

pip install -U sentence-transformers

如要使用 ColPali 式視覺文件檢索,亦須安裝影像相關依賴(所有額外套件請參閲安裝文件;多模態支援的一般介紹則見多模態嵌入與重排序模型):

pip install -U "sentence-transformers[image]"

Sentence Transformers v6.0 需要 transformers v5.x、torch 2.2+,以及 huggingface-hub v1.x。如果你鎖定的版本較舊,請先規劃升級。完整的不相容變更清單請參閲遷移指南。

載入模型

載入多向量模型的方式,與載入其他 Sentence Transformers 模型完全相同:

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("lightonai/LateOn")

要尋找相容模型,可在 Hub 查看帶有 multi-vector 和 sentence-transformers 標籤的項目。帶有這些標籤的模型都可用上面的程式碼載入,不論它原本是 PyLate checkpoint、Stanford-NLP ColBERT checkpoint,還是用於視覺文件檢索的 ColPali 系列模型。我們正逐步為所有相容模型加上標籤,因此清單會持續擴大。

在底層,MultiVectorEncoder 可讀取這些 checkpoint 多年來採用的各種發布格式,因此即使尚未加上標籤,PyLate 和 Stanford-NLP checkpoint 也能直接載入:

from sentence_transformers import MultiVectorEncoder

# Native Sentence Transformers checkpoints. PyLate builds on the same schema,
# so any PyLate checkpoint loads identically
model = MultiVectorEncoder("lightonai/LateOn")
model = MultiVectorEncoder("mixedbread-ai/mxbai-edge-colbert-v0-17m")
model = MultiVectorEncoder("LiquidAI/LFM2.5-ColBERT-350M", trust_remote_code=True)

# Any Stanford-NLP ColBERT checkpoint, detected via the `HF_ColBERT` architecture
# marker. The inline projection weight and the recipe come from `artifact.metadata`
model = MultiVectorEncoder("colbert-ir/colbertv2.0")
model = MultiVectorEncoder("answerdotai/answerai-colbert-small-v1")

# A bare transformer: a fresh random projection is appended, so training is required
model = MultiVectorEncoder("answerdotai/ModernBERT-base")

視覺文件檢索模型是例外。ColPali 系列 checkpoint 使用 colpali-engine 自有格式,其中沒有 Sentence Transformers 可讀取的資訊,因此必須先在各自的 repository 加入少量設定才能載入。大部分工作已完成,正等待合併。現況及目前的載入方式請參閲支援的模型。

查看 checkpoint 的設定

多向量模型包含一些會因 checkpoint 而異的設定:查詢和文件的標記前綴、長度上限、查詢是否以 [MASK] token 補齊,以及文件計分時略過哪些 token。這些設定都在模組配置中,因此執行 print(model) 就能查看實際載入的內容。以下是原始 ColBERTv2 checkpoint:每個查詢會補齊至正好 32 個 token,文件則截斷至 180 個 token:

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("colbert-ir/colbertv2.0")
print(model)
"""
MultiVectorEncoder(
  (0): Transformer({..., 'document_length': 180,
                    'query_expansion': {'strategy': 'fixed', 'attend': False, 'token': None, 'length': 32}})
  (1): Dense({'in_features': 768, 'out_features': 128, 'bias': False, ...})
  (2): MultiVectorMask({'skiplist_words': ['!', '"', '#', ...], 'skiplist_tasks': ['document'], ...})
  (3): Normalize({...})
)
"""
print(model.prompts)
# {'query': '[unused0] ', 'document': '[unused1] '}

這就是經典的 ColBERT pipeline:由 Transformer 產生具上下文資訊的 token 嵌入;token 層級的 Dense 將每個嵌入投影至 128 維;MultiVectorMask 決定計分時哪些 token 有效;最後由 token 層級的 Normalize 處理。其他 checkpoint 的設定值則有所不同。lightonai/GTE-ModernColBERT-v1 使用相同四個模組,提示為 [Q] 和 [D] ,不擴展查詢,上限分別為 48 和 300。

通常毋須修改這些設定,因為每個已發布的 checkpoint 都已自行配置。只有從純 backbone 建立模型時才需要處理,詳情請參閲建立自訂模型。

不過,有一個數值值得按你的資料檢查:document_length 會截斷文件,超出部分不會進入索引。例如,662 個 token 的段落經過 LateOn 的 300 上限後,會只剩下 273 個向量,其餘內容就此消失。這些 checkpoint 大多以短段落訓練;如果你的分塊長度超出上限,可在單次呼叫中提高上限:encode_document(..., processing_kwargs={"text": {"max_length": 512}})。但要留意,這會令模型處理超出訓練長度的內容,索引大小亦大致按比例增加。多向量模型通常能妥善處理這種情況。在長文件檢索基準 MLDR 上,上述模型的多語言版本清楚展現差距:mLateOn 得分為 77.92,mDenseOn 則為 51.59。

編碼查詢和文件

多向量模型具有非對稱性,因此查詢和文件會使用不同前綴、長度上限和計分遮罩。許多密集模型可互換處理兩者,但要取得正確嵌入,必須分別使用 encode_query() 和 encode_document():

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("lightonai/mLateOn")

queries = ["What is the capital of France?"]
documents = [
    "Paris is the capital of France.",
    "Berlin is the capital and largest city of Germany, by both area and population.",
]

query_embeddings = model.encode_query(queries)
document_embeddings = model.encode_document(documents)

print(query_embeddings[0].shape)
# (10, 128)
print(document_embeddings[0].shape, document_embeddings[1].shape)
# (10, 128) (19, 128)

回傳結果是 2D tensor 的清單,每項輸入各有一個,形狀為 (num_tokens, embedding_dim)。與密集嵌入不同,這些 tensor 無法堆疊成一個長方形 tensor,因為每項輸入的 token 數目都不同。第二份文件比第一份長,因此回傳的矩陣也更高。

每次呼叫都會自動套用模型本身的設定。encode_query 會加上查詢標記;若 checkpoint 有要求,便把查詢擴展至固定長度,並按查詢長度上限截斷。encode_document 會加上文件標記、按文件長度上限截斷,並從計分遮罩中移除略過清單上的 token(大部分 checkpoint 會略過標點符號)。

一般 encode() 的參數仍然適用,因此 batch_size、show_progress_bar、convert_to_numpy、device 和多程序工作池都可照常使用:

document_embeddings = model.encode_document(
    documents,
    batch_size=64,
    show_progress_bar=True,
)

使用 MaxSim 計分

model.similarity() 會計算所有配對的完整 MaxSim 矩陣:

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("lightonai/LateOn")

query_embeddings = model.encode_query(["Which planet is known as the Red Planet?"])
document_embeddings = model.encode_document([
    "Venus is often called Earth's twin because of its similar size and proximity.",
    "Mars, known for its reddish appearance, is often referred to as the Red Planet.",
    "Jupiter, the largest planet in our solar system, has a prominent red spot.",
    "Saturn, famous for its rings, is sometimes mistaken for the Red Planet.",
])

scores = model.similarity(query_embeddings, document_embeddings)
print(scores)
# tensor([[10.7942, 11.1104, 10.9743, 11.0811]])

火星如預期般排名第一,後續名次則非常接近。土星也包含「紅色星球」這個字面詞組,而木星是有紅斑的行星,因此 token 層級運算子在三者中都有不少可比對的內容。重要的是排名次序。

正如 GLInt 透過量度完整候選集的分數分佈所示,分數往往如此接近。MaxSim 會為每個查詢 token 取最大值,因此文件通常都能為每個查詢 token 提供某種不錯的最佳配對,令分數有一定底線。具上下文資訊的 token 嵌入亦具有各向異性,會聚集在狹窄圓錐內而非四散,因此即使任意配對的 token 也往往得分偏高。

如果已經有配對好的項目,只想取得各配對分數而非完整相似度矩陣,也可使用 model.similarity_pairwise():

scores = model.similarity_pairwise(query_embeddings, document_embeddings[:1])
print(scores)
# tensor([10.7942])

分數幅度與 MeanMaxSim

MaxSim 會加總查詢 token,因此分數幅度會隨查詢 token 數目變化;這表示不同查詢設定的模型之間,分數不可直接比較。LateOn 會把上文的「紅色星球」查詢編碼成 12 個 token。若把相同查詢和文件交由 ColBERTv2 處理,它會把每個查詢補齊或截斷至正好 32 個 token,分數便會落在完全不同的範圍:

model = MultiVectorEncoder("colbert-ir/colbertv2.0")
# ... same encode_query / encode_document / similarity calls ...
print(scores)
# tensor([[12.7970, 27.1945, 23.8495, 24.5656]])

在同一個模型內,排名次序已足夠;但如果你想把分數限制在固定範圍,可把模型的相似度函式切換為 MeanMaxSim,它會除以查詢 token 數目。以下切回 LateOn:

model = MultiVectorEncoder("lightonai/LateOn", similarity_fn_name="meanmaxsim")
# or on an already-loaded model: model.similarity_fn_name = "meanmaxsim"

print(model.similarity(query_embeddings, document_embeddings))
# tensor([[0.8995, 0.9259, 0.9145, 0.9234]])

現在每個分數都是介乎 [-1, 1] 的平均餘弦相似度,但實際上只會看到 [0, 1]。

語義搜尋

如果語料庫規模較小,對全部內容執行完整 MaxSim 是最簡單可行的方法。只需把語料庫編碼一次,之後每個查詢都與全部內容計分:

import time

from datasets import load_dataset

from sentence_transformers import MultiVectorEncoder

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
# Several questions share an answer passage, so drop repeats but keep the order
corpus = list(dict.fromkeys(dataset["answer"]))  # 5,000 rows -> 4,874 passages

model = MultiVectorEncoder("lightonai/LateOn")
corpus_embeddings = model.encode_document(corpus, show_progress_bar=True)

query = "when did richmond last play in a preliminary final"
start = time.perf_counter()
query_embeddings = model.encode_query([query])
scores = model.similarity(query_embeddings, corpus_embeddings)[0]  # 98ms
top_scores, top_indices = scores.topk(3)
print(f"Search took {(time.perf_counter() - start) * 1000:.1f}ms")

for score, index in zip(top_scores.tolist(), top_indices.tolist()):
    print(f"{score:.4f}  {corpus[index][:100]}")
"""
Search took 122.7ms
11.9192  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieved
11.7591  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contest
11.6710  Battle of Appomattox Court House The Battle of Appomattox Court House (Virginia, U.S.), fou
"""

在 RTX 3090 上,編碼這 4,874 段內容需時 20 秒;每次搜尋由頭到尾約需 120ms,大部分時間都用於對全部 608,414 個 token 向量執行 MaxSim 計分。結果雖然精確,但耗時會隨語料庫 token 總數線性增加,而且所有 token 向量都要留在記憶體中,因此較適合數千份文件,而非數百萬份。可執行版本的腳本是 semantic_search.py。

超出這個規模後,就需要真正的晚期交互索引,而 Sentence Transformers 並沒有內置這種索引。不過這並非必要,因為這些索引會儲存 encode_document 的輸出;你只需在此編碼,再把 token 嵌入交給專門處理它們的工具。建立索引一節提供四種方案的可用程式碼,下一節則介紹如何完全略過索引。

先檢索後重排序

你亦可把多向量模型用作重排序器,在不維護晚期交互索引的情況下取得晚期交互的品質。先由快速的雙編碼器從大型語料庫中篩選出少量候選項目,再由多向量模型重新評分:

from datasets import load_dataset

from sentence_transformers import MultiVectorEncoder, SentenceTransformer
from sentence_transformers.util import semantic_search

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:50000]")
corpus = list(dict.fromkeys(dataset["answer"]))

retriever = SentenceTransformer("jinaai/jina-embeddings-v5-text-nano-retrieval")
reranker = MultiVectorEncoder("perplexity-ai/pplx-embed-v1-late-0.6b", trust_remote_code=True)

# First stage: index the corpus once with a fast bi-encoder
corpus_embeddings = retriever.encode_document(corpus, convert_to_tensor=True, show_progress_bar=True)

# Retrieve the top 50
query = "when did richmond last play in a preliminary final"
hits = semantic_search(retriever.encode_query([query], convert_to_tensor=True), corpus_embeddings, top_k=50)[0]
candidates = [corpus[hit["corpus_id"]] for hit in hits]

# Second stage: rescore just those candidates with MaxSim
query_embeddings = reranker.encode_query([query])
document_embeddings = reranker.encode_document(candidates)
scores = reranker.similarity(query_embeddings, document_embeddings)[0]

for index in scores.argsort(descending=True)[:3].tolist():
    print(f"{scores[index].item():.4f}  {candidates[index][:100]}")

只有 50 個候選項目會被編碼為多向量,因此索引仍是一般密集索引,而 token 向量只會暫時存在。這與檢索加重排序流程中的交叉編碼器作用相同,但多向量模型處理每個候選項目的成本低得多。你可一次批次編碼所有文件,再以矩陣乘法計分,而非對每組查詢與文件執行一次前向傳播。可執行腳本是 retrieve_rerank.py,會輸出兩個階段的耗時。

建立索引

多個向量資料庫已原生支援多向量索引與計分:Qdrant 自 v1.10 起支援、Weaviate 自 v1.29 起支援、Vespa 多年來一直支援、LanceDB 自 v0.15.0 起支援;VectorChord 則為 Postgres 加入一般 pgvector 沒有的 MaxSim 運算子。Milvus 於 v2.6.4 加入支援,採用的是 array-of-structs,而不是它所稱的另一項無關功能「multi-vector search」。如果完全不想運行伺服器,LightOn 的 fast-plaid 只需執行 pip install 即可安裝,並可直接使用 PLAID;PyLate 則把它包裝成更完整的檢索架構。

其他一些工具則只提供部分功能。OpenSearch 和 Elasticsearch 可用 MaxSim 重新評分候選項目,但不能用它進行檢索;而且 Elasticsearch 的相關欄位仍屬技術預覽,並只適用於 Enterprise 版本。turbopuffer 則在私有 beta 測試晚期交互索引。

以下範例以文字建立索引,但程式碼並非文字專用。無論文件是段落、頁面影像、音訊片段還是影片,encode_document 都會回傳相同格式的 token 向量矩陣清單,因此視覺文件檢索一節的 ColPali 式模型也能直接用於這些工具。每份文件的向量只會更多,因此更值得提早使用Token 池化。

fast-plaid、Qdrant、Weaviate 和 Vespa 都直接接收 encode_document 的輸出,因此程式碼只會因客戶端程式庫而異。以下為每種工具提供一段可運行的範例,使用語義搜尋範例中的 4,874 段內容和 608,414 個 token 向量執行。每段程式碼亦列出在同一部電腦(RTX 3090、i7-13700K)上測得的匯入和查詢時間,未作超出範例所示的調校,讓你掌握工作量。四者的查詢速度都比該節中 model.similarity 的 98ms 快,其中三者使用 CPU,因為這裏只有 fast-plaid 使用 GPU。

四者回傳的三段內容及排序,均與本文前面的 PyTorch 完整 MaxSim 相同;三個資料庫更能把分數重現至小數點後四位!這是因為範例會為每份文件計分,以目前規模而言成本可接受,亦排除了近似計算這個變數。fast-plaid 的設計本身採用近似計算,因此分數略有不同。各工具下方的備註會説明改用近似索引後有何變化,排名亦會由此開始偏移。

fast-plaid

fast-plaid 是 LightOn 以 Rust 實作的 PLAID;ColBERT 最初便是圍繞這種索引建立。它毋須啟動伺服器,亦可直接讀取 encode_document 回傳的 tensor,無須轉換。

# pip install sentence-transformers datasets fast-plaid
from datasets import load_dataset
from fast_plaid import search
from sentence_transformers import MultiVectorEncoder

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
corpus = list(dict.fromkeys(dataset["answer"]))
model = MultiVectorEncoder("lightonai/LateOn")
query = "when did richmond last play in a preliminary final"

document_embeddings = model.encode_document(corpus, batch_size=32)
query_embedding = model.encode_query(query)

fast_plaid = search.FastPlaid(index="natural-questions", device="cuda")

# 4,874 documents (608,414 token vectors) indexed in 5s
fast_plaid.create(documents_embeddings=document_embeddings)

results = fast_plaid.search(queries_embeddings=query_embedding.unsqueeze(0), top_k=3)  # 11ms

for index, score in results[0]:
    print(f"{score:.4f}  {corpus[index][:90]}")
"""
11.8828  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieve
11.7676  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contes
11.6758  Battle of Appomattox Court House The Battle of Appomattox Court House (Virginia, U.S.), fo
"""

index 參數代表目錄,而非單純標籤,因此建立索引時會寫入磁碟。新的 FastPlaid 指向相同路徑時,便可重新開啟索引用於搜尋或加入更多文件,毋須每次從嵌入重新建置。這個語料庫的索引佔用 92 MB;原始 float32 向量則佔 311.5 MB。

四者之中只有這個工具採用近似計算,也是本節唯一一個分數與完整 MaxSim 不同的方案。PLAID 會利用中心點剪枝並儲存量化殘差,因此三個分數與之前計算的 11.9192 / 11.7591 / 11.6710 相比,會向上或向下偏移幾個百分點。此處的排名未受影響,這正是 PLAID 的取捨。它是為遠大於目前規模、無法逐一掃描所有內容的語料庫而設計。

Qdrant

Qdrant 需要伺服器:docker run -p 6333:6333 qdrant/qdrant。客戶端亦提供毋須伺服器的本機模式(QdrantClient(":memory:")),但它是純 Python 重新實作,因此適合試用,不適合用來測量效能。

# pip install sentence-transformers datasets qdrant-client
from datasets import load_dataset
from qdrant_client import QdrantClient, models
from sentence_transformers import MultiVectorEncoder

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
corpus = list(dict.fromkeys(dataset["answer"]))
model = MultiVectorEncoder("lightonai/LateOn")
query = "when did richmond last play in a preliminary final"

document_embeddings = model.encode_document(corpus, batch_size=32)
query_embedding = model.encode_query(query)

client = QdrantClient("http://localhost:6333")
client.create_collection(
    collection_name="natural-questions",
    vectors_config=models.VectorParams(
        size=model.get_embedding_dimension(),
        distance=models.Distance.COSINE,
        multivector_config=models.MultiVectorConfig(
            comparator=models.MultiVectorComparator.MAX_SIM
        ),
        # MaxSim never walks the HNSW graph, so skip building one
        hnsw_config=models.HnswConfigDiff(m=0),
    ),
)

# 4,874 documents (608,414 token vectors) ingested in 26.3s
client.upload_points(
    collection_name="natural-questions",
    points=[
        models.PointStruct(id=idx, vector=embedding, payload={"text": text})
        for idx, (embedding, text) in enumerate(zip(document_embeddings, corpus))
    ],
    batch_size=64,
)

results = client.query_points(
    collection_name="natural-questions",
    query=query_embedding,
    limit=3,
    with_payload=True,
).points  # 18ms

for result in results:
    print(f"{result.score:.4f}  {result.payload['text'][:90]}")
"""
11.9192  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieve
11.7591  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contes
11.6710  Battle of Appomattox Court House The Battle of Appomattox Court House (Virginia, U.S.), fo
"""

MAX_SIM 是 Qdrant 唯一提供的比較運算子;由於向量用於重新評分,而非圖形遍歷,Qdrant 建議晚期交互欄位使用 hnsw_config=HnswConfigDiff(m=0)。請留意,Qdrant 本身建議只對數百個候選項目使用晚期交互重排序,而非掃描整個集合,這正是先檢索後重排序模式。對 4,874 份文件進行完整掃描需時 18ms 且結果精確,但不能據此推算更大規模的效能。

Weaviate

Weaviate 同樣需要伺服器:docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.34.0。多向量支援需要 1.29 或更新版本,而 Windows 不支援內嵌模式。

# pip install sentence-transformers datasets weaviate-client
import weaviate
from datasets import load_dataset
from sentence_transformers import MultiVectorEncoder
from weaviate.classes.config import Configure, DataType, Property
from weaviate.classes.query import MetadataQuery

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
corpus = list(dict.fromkeys(dataset["answer"]))
model = MultiVectorEncoder("lightonai/LateOn")
query = "when did richmond last play in a preliminary final"

document_embeddings = model.encode_document(corpus, batch_size=32)
query_embedding = model.encode_query(query)

client = weaviate.connect_to_local()
collection = client.collections.create(
    "Documents",
    # self_provided turns on MaxSim late interaction
    vector_config=[Configure.MultiVectors.self_provided(name="colbert")],
    properties=[Property(name="text", data_type=DataType.TEXT)],
)

# 4,874 documents (608,414 token vectors) ingested in 41s
with collection.batch.fixed_size(batch_size=64) as batch:
    for text, embedding in zip(corpus, document_embeddings):
        batch.add_object(properties={"text": text}, vector={"colbert": embedding.tolist()})

results = collection.query.near_vector(
    near_vector=query_embedding.tolist(),
    target_vector="colbert",
    limit=3,
    return_metadata=MetadataQuery(distance=True),
)  # 17ms

for result in results.objects:
    # Weaviate reports the MaxSim score as a negated distance
    print(f"{-result.metadata.distance:.4f}  {result.properties['text'][:90]}")
"""
11.9192  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieve
11.7591  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contes
11.6710  Battle of Appomattox Court House The Battle of Appomattox Court House (Virginia, U.S.), fo
"""

client.close()

這裏使用預設值已足夠。Weaviate 的動態 ef 在 top-3 查詢中會設為 100,而從約 32 起,排名已經精確。這個餘裕來自嵌入本身,而非 Weaviate,因此值得在自己的模型上確認,不要假設預設值一定適用。

Weaviate 亦支援 MUVERA 編碼;在我們的測試中,匯入速度提高 3 倍,查詢速度提高 1.8 倍。不過,以目前規模而言,準確度損失遠超速度提升的價值,因為正確的第三段內容甚至沒有出現在前 50 名。

Vespa

Vespa 亦在容器中運行,但 pyvespa 會替你啟動,因此毋須另外執行 docker run。

# pip install sentence-transformers datasets pyvespa
from datasets import load_dataset
from sentence_transformers import MultiVectorEncoder
from vespa.deployment import VespaDocker
from vespa.package import (
    ApplicationPackage, Document, Field, FirstPhaseRanking, Function, RankProfile, Schema,
)

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
corpus = list(dict.fromkeys(dataset["answer"]))
model = MultiVectorEncoder("lightonai/LateOn")
query = "when did richmond last play in a preliminary final"

document_embeddings = model.encode_document(corpus, batch_size=32)
query_embedding = model.encode_query(query)

# "dt" is a mapped dimension over the variable token count, "x" the dense 128-dim vector
package = ApplicationPackage(
    name="colbert",
    schema=[
        Schema(
            name="doc",
            document=Document(fields=[
                Field(name="text", type="string", indexing=["summary"]),
                Field(name="colbert", type="tensor<float>(dt{}, x[128])", indexing=["attribute"]),
            ]),
            rank_profiles=[
                RankProfile(
                    name="colbert",
                    inputs=[("query(qt)", "tensor<float>(qt{}, x[128])")],
                    functions=[Function(
                        name="max_sim",  # per query token take the best document token, then sum
                        expression="sum(reduce(sum(query(qt) * attribute(colbert), x), max, dt), qt)",
                    )],
                    first_phase=FirstPhaseRanking(expression="max_sim"),
                )
            ],
        )
    ],
)
app = VespaDocker(port=8080).deploy(application_package=package)  # ~40s to boot

# Vespa reads a mixed tensor as {token index: vector}, for documents and queries alike
def to_tensor(embedding):
    return {str(token): vector for token, vector in enumerate(embedding.tolist())}

# 4,874 documents (608,414 token vectors) ingested in ~80s
app.feed_iterable(
    ({"id": str(idx), "fields": {"text": text, "colbert": to_tensor(embedding)}}
     for idx, (text, embedding) in enumerate(zip(corpus, document_embeddings))),
    schema="doc",
)

response = app.query(body={
    "yql": "select text from doc where true",
    "ranking.profile": "colbert",
    "hits": 3,
    "input.query(qt)": to_tensor(query_embedding),
})  # ~75ms warm, ~115ms on the first call

for hit in response.hits:
    print(f"{hit['relevance']:.4f}  {hit['fields']['text'][:90]}")
"""
11.9192  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieve
11.7591  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contes
11.6710  Battle of Appomattox Court House The Battle of Appomattox Court House (Virginia, U.S.), fo
"""

四種方案之中,Vespa 需要最多前置設定,因為你要宣告的是排名 pipeline,而不只是索引。相對地,你可以把 MaxSim 寫成 tensor 運算式,清楚查看它實際計算的內容。此版本的 first-phase 以 where true 執行 MaxSim,為全部 4,874 份文件計分,因此輸出與完整 MaxSim 完全相同。這刻意不是 Vespa 建議的大規模做法。其 ColBERT 範例應用程式會儲存 int8 二值化向量,並把 MaxSim 移至 second-phase,為成本較低的第一階段結果重排序。

改用分階段設定時要小心,因為 second-phase 預設只會重新評估最佳的 100 個候選項目;在這個例子中,三段正確內容有兩段完全沒有計分。提高 rerank-count 以涵蓋整個候選集即可解決,但以目前規模而言,分階段版本仍比直接掃描全部內容慢。

視覺文件檢索

晚期交互是視覺文件檢索的最先進方法,可直接以文字查詢比對頁面影像,保留圖表、表格和版面,毋須經過 OCR。ColPali 系列模型正是採用此方法,相關 checkpoint 也可透過相同 API 載入和運行;revision 會固定至尚未合併、為這個模型加入 Sentence Transformers 設定的 pull request(完整清單見支援的模型)。影像文件可使用 URL、本機路徑或 PIL 影像傳入:

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder("vidore/colqwen2.5-v0.2")

queries = [
    "What is the variable represented on the y-axis of the graph?",
    "Total outlay is maximum in which year?",
]
images = [
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc1.jpg",
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc2.jpg",
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc3.jpg",
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc4.jpg",
]

query_embeddings = model.encode_query(queries)
document_embeddings = model.encode_document(images)
print(query_embeddings[0].shape, document_embeddings[0].shape)
# (25, 128) (755, 128)

scores = model.similarity(query_embeddings, document_embeddings)
print(scores)
# tensor([[13.8672, 12.3115, 12.1670, 11.0293],
#         [ 7.2012, 14.7207,  6.9414,  6.9746]])

每個查詢都會檢索到對應頁面(即對角線位置);第二個查詢的區分度比第一個高得多,因為四頁之中只有一頁談及隨時間變化的支出。

程式碼無須改動。底層處理器會處理視覺提示和影像 patch,而 MaxSim 會以查詢文字 token 比對文件影像 patch。單一頁麪包含許多不同區域,正好適合使用晚期交互;若只用一個向量,就得把圖表、表格和三段文字平均成一個摘要。不過,這種保真度需要更多索引空間。上方例子中,一頁有 755 個 token 向量,查詢則有 25 個;相比之下,前面的 Natural Questions 段落平均約有 125 個,因此這裏更值得提早使用token 池化。

這些都是 VLM,部署時要預留所需記憶體。支援模型表格涵蓋 252M 至 8.8B 參數的模型;較小的型號仍可在 CPU 上實用地運行,但數十億參數的型號則不然。

頁面影像是常見情況,但並非唯一的非文字模態。Sentence Transformers 接受文字、影像、音訊和影片;checkpoint 支援哪些模態,取決於其處理器,而 model.modalities 會列出相關資訊。單一文件亦可結合多種模態,只需以類似 {"text": ..., "image": ...} 的 dict 取代單一值。多模態嵌入與重排序模型會更全面介紹 Sentence Transformers 的多模態模型,而使用文件則列明每種模態接受的輸入格式。

音訊檢索

vidore/colqwen-omni-v0.1 建基於 Qwen2.5-Omni,支援全部四種模態。使用它檢索錄音對話,與檢索頁面一樣只需兩次呼叫:

# pip install -U "sentence-transformers[audio,video]"
import torch
from datasets import Audio, load_dataset

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder(
    "vidore/colqwen-omni-v0.1",
    model_kwargs={"dtype": torch.bfloat16},
)
print(model.modalities)
# ['text', 'image', 'audio', 'video', 'message']

# 20 recorded conversations, averaging 28 seconds each
dataset = load_dataset("eustlb/dailytalk-conversations-grouped", split="train[:20]")
dataset = dataset.cast_column("audio", Audio(sampling_rate=16_000))
audio = [row["array"] for row in dataset["audio"]]  # raw mono waveforms, float32 at 16 kHz

query_embeddings = model.encode_query(["medicine for car nausea"])
document_embeddings = model.encode_document(audio, batch_size=2)
scores = model.similarity(query_embeddings, document_embeddings)[0]

top_scores, top_indices = scores.topk(3)
for score, index in zip(top_scores.tolist(), top_indices.tolist()):
    print(f"{score:.4f}  {' / '.join(dataset[index]['texts'][:2])}")
"""
50.8902  Excuse me? Do you have anything for a carsickness? / Yes, but you look fine.
46.1028  Excuse me, could you tell me where you have got that music book? / Certainly. Let me see. Oh, it's on that shelf.
46.0514  Jeff, I'm going to the supermarket. Do you want to come with me? / I think the supermarket is closed now.
"""

ColQwen-Omni 只以影像—文字配對進行訓練,因此其音訊檢索屬於 zero-shot。訓練時從未聽過任何音訊範例,整個 pipeline 亦沒有轉錄步驟。查詢使用 nausea,錄音中説的卻是 carsickness;即使如此,它仍能從 20 段對話中以明顯優勢找出藥房對話。

影片檢索

影片檢索方式相同,但要抽取影格,否則會耗盡 VRAM。其發布網誌直接指出,影片「非常耗用記憶體,因此最適合短片段」:

import torch

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder(
    "vidore/colqwen-omni-v0.1",
    model_kwargs={"dtype": torch.bfloat16},
)

# Sparse, low-resolution frames: 0.5 fps rather than the full frame rate
model[0].processing_kwargs.update(
    {"video": {"max_pixels": 32 * 28 * 28, "do_sample_frames": True, "fps": 0.5}}
)

query_embeddings = model.encode_query(["How to cook Mapo Tofu?"])
document_embeddings = model.encode_document([
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/mapo_tofu.mp4",
    "https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/zhajiang_noodle.mp4",
], batch_size=1)
print(model.similarity(query_embeddings, document_embeddings))
# tensor([[53.3100, 51.0561]])

以 1 fps 和完整解像度處理同一對影片,會產生 8,426 和 5,137 個 token 向量,VRAM 峯值達 20.8 GB;此處則分別為 4,240 和 2,446 個向量、12.5 GB,而模型本身佔用 9.0 GB。兩種方式的排名完全相同。長音訊也應採用相同處理方式;發布網誌建議切成 30 秒一段,每段約 800 個 token。

可解釋性

由於 MaxSim 是各查詢 token 最高分的總和,排名可以精確拆解,因此文件分數中的每一部分都可歸因至一個查詢 token 和一個文件 token。這讓你可以精確回答「為何它排在這裏?」,而非只憑肉眼判斷。

對影像文件而言,sentence_transformers.multi_vector_encoder.interpretability 會把拆解結果以標準 ColPali 熱圖疊加到頁面上,可顯示整個查詢的合併結果,亦可為每個查詢 token 各顯示一張圖。以上文支出頁面回答「水資源和電力方面花了多少?」時,water token 的位置如下:

MaxSim heatmap of the query token "water" overlaid on a 1971 US budget outlays page, with the brightest patch on the "Water Resources & Power" bar of the lower chart

可執行版本是 heatmap.py,其中包括把文件嵌入對齊 patch 網格的遮罩步驟。

文字文件沒有可疊加的 patch 網格,但同樣可以拆解分數。text_similarity_map.py 會先為語料庫排名,再逐個 token 説明最高排名結果的分數;此處使用前文的 Natural Questions 語料庫和 32M 參數的 mxbai-edge-colbert-v0-32m:

Query: when did richmond last play in a preliminary final
Top 3 of 4874 documents by exhaustive MaxSim (191.0ms):
  12.3489  Richmond Football Club Richmond began 2017 with 5 straight wins, a feat it had not achieved since 19
  12.1771  2017 AFL Grand Final The 2017 AFL Grand Final was an Australian rules football game contested betwee
  12.0591  2018 UEFA Champions League Final The 2018 UEFA Champions League Final was the final match of the 201

  query token       best document token      sim   share
  when              since                 0.9154    7.4%
  did               had                   0.9675    7.8%
  rich              rich                  0.9764    7.9%
  mond              mond                  0.9856    8.0%
  last              to                    0.9249    7.5%
  play              game                  0.9384    7.6%
  in                the                   0.9732    7.9%
  a                 a                     0.9587    7.8%
  preliminary       preliminary           0.9394    7.6%
  final             final                 0.9654    7.8%
  --------------------------------------------------------
  3 special tokens                        2.8038   22.7%
  MaxSim score                           12.3489  100.0%

rich、mond、preliminary 和 final 都配對到自身;when 配對到 since,而 play 配對到 game。三個特殊 token 貢獻了分數的 22.7%,卻不包含查詢內容。表格下方的腳本會輸出段落本身,並在原文中標示勝出的 token。

Token 池化

如果索引佔用令你擔心,最有效的方法是儲存較少 token 向量。HierarchicalTokenPooling 實作 Clavié、Chaffin 和 Adams 提出的token 池化技術:以 cosine distance 和 Ward linkage 對每份文件的 token 向量分羣,再以每個羣組的平均值取代,保留約 1 / pool_factor 的 token。同一份文件中有不少 token 向量彼此接近,因此被刪除的多半是冗餘,而非有效訊號:

from datasets import load_dataset

from sentence_transformers import MultiVectorEncoder
from sentence_transformers.multi_vector_encoder.modules import HierarchicalTokenPooling

dataset = load_dataset("sentence-transformers/natural-questions", split="train[:5000]")
documents = list(dict.fromkeys(dataset["answer"]))

model = MultiVectorEncoder("lightonai/LateOn")

pooling = HierarchicalTokenPooling(pool_factor=2)
document_embeddings = model.encode_document(documents, token_pooling=pooling)

你可按希望承擔成本的時機,在三個位置套用池化:

# 1. Per encode call, as above
document_embeddings = model.encode_document(documents, token_pooling=pooling)

# 2. Standalone, on embeddings you already have saved (e.g. list of [num_tokens, num_dims] tensors)
pooled = pooling.pool(document_embeddings)

# 3. Baked into the model, so every consumer of the checkpoint gets pooled documents
model.append(HierarchicalTokenPooling(pool_factor=2))
model.save_pretrained("my-pooled-colbert")

預設只會對文件進行池化,因為查詢較短,而且不應扭曲查詢內容。對前文的 Natural Questions 語料庫而言,縮減比例與 pool_factor 接近;為全部 608k 個 token 向量池化約需 6 秒:

pool_factor Token 向量 縮減比例 float32 索引
1 (off) 608,414 1.00x 311.5 MB
2 305,438 1.99x 156.4 MB
3 204,407 2.98x 104.7 MB
4 153,936 3.95x 78.8 MB

羣組平均值與查詢 token 的配對效果,會比羣組中最佳成員更差;羣組越粗略,差距越明顯。原始實驗在 BEIR 上量度這項代價,發現影響很小:pool_factor=2 時平均檢索表現為未池化的 100.6%,pool_factor=3 時則為 99.0%。索引大小減半而幾乎沒有成本,是相當划算的做法,因此 2 是合理起點。不過,對你的資料造成多少影響取決於語料庫,確定因子前應先用評估器測量。可執行比較程式為 token_pooling.py。

pool_factor 可提高至甚麼程度,部分亦取決於模型本身。LightOn 的階層式池化正則化正是為此而訓練,會調整嵌入空間以降低池化代價,並在 5 倍壓縮下保留 99.4% 表現。Sentence Transformers 尚未支援以該正則化訓練,但所得 checkpoint 是一般 PyLate 模型,因此 lightonai/LateOn-hpool-regularized 可像其他模型一樣載入和池化。

加快推論

多向量模型使用與 Sentence Transformers 其他模型相同的後端機制,因此可使用 torch(預設)、onnx 和 openvino,以及半精度、Flash Attention 和 torch.compile。

在 GPU 上,fp16 搭配 Flash Attention 是我們測得的最佳設定:吞吐量為 fp32 的 2.44 倍,而且檢索品質沒有可測量的損失。Flash Attention 對多向量模型的助益尤其大,因為文件只會截斷,不會補齊至統一長度;每個批次的序列長度差異很大,正好可讓取消補齊機制發揮作用:

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder(
    "lightonai/GTE-ModernColBERT-v1",
    model_kwargs={"attn_implementation": "flash_attention_2", "dtype": "float16"},
)

採用非注意式查詢擴展(attend=False)的模型會在載入時拒絕 Flash Attention,這包括 colbert-ir/colbertv2.0 和 answerdotai/answerai-colbert-small-v1 等 Stanford-NLP checkpoint。Flash Attention 會移除 attention_mask=0 的位置,因此 MaxSim 會計分的 [MASK] 擴展 token 永遠不會收到注意力更新。這些模型請使用 "sdpa"。

在 CPU 上,如果架構支援,OpenVINO 是較佳選擇;int8 量化則可進一步加速,代價約為 0.4% 準確度。完整基準測試、匯出與量化工具,以及選擇後端的流程圖,請參閲加快推論。

評估模型

MultiVectorNanoBEIREvaluator 會以 MaxSim 計分,執行包含 13 個小型 BEIR 子集的 NanoBEIR 套件;你毋須預先準備資料:

from sentence_transformers import MultiVectorEncoder
from sentence_transformers.multi_vector_encoder.evaluation import MultiVectorNanoBEIREvaluator

model = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")
evaluator = MultiVectorNanoBEIREvaluator(batch_size=16)
results = evaluator(model)
print(f"{evaluator.primary_metric}: {results[evaluator.primary_metric]:.4f}")

這亦方便驗證本文開首的説法。lightonai/LateOn 和 lightonai/DenseOn 由 LightOn 使用相同資料、相同 ModernBERT backbone 和相同的 149M 參數訓練;唯一差別是前者每個 token 保留一個向量,後者則池化至每份文件一個向量。讓兩者在全部 13 個 NanoBEIR 資料集上運行,便可單獨觀察這項選擇帶來的效果:

NanoBEIR 資料集 LateOn(多向量,128d) DenseOn(密集,768d)
MSMARCO 0.7194 0.6517
NQ 0.7810 0.7511
HotpotQA 0.9295 0.8802
FEVER 0.9702 0.9612
ClimateFEVER 0.4887 0.4846
DBPedia 0.6836 0.6748
QuoraRetrieval 0.9795 0.9687
Touche2020 0.5938 0.5673
ArguAna 0.5562 0.5660
NFCorpus 0.3949 0.3851
SciFact 0.7978 0.8057
SCIDOCS 0.4469 0.4484
FiQA2018 0.5871 0.6491
平均 0.6868 0.6764

晚期交互在 13 個資料集中的 9 個勝出,平均分亦領先約一個 NDCG 點。它落敗的四個資料集(ArguAna、FiQA2018、SCIDOCS 和 SciFact)反映了預期的取捨:模型大小相同時,檢索品質確有提升,但需要較大的索引,而非在每個資料集上都全面勝出。在完整的 15 個資料集 BEIR 上,同一組模型分別得 57.22 和 56.20,差距相若,證明優勢並非小型基準測試造成的假象。

除了 NanoBEIR,MultiVectorInformationRetrievalEvaluator、MultiVectorRerankingEvaluator、MultiVectorTripletEvaluator 和 MultiVectorDistillationEvaluator 亦涵蓋常見評估方式,可用於自己的資料。詳情請參閲評估 API 參考。

從 PyLate 或 colpali-engine 遷移

MultiVectorEncoder 整合了兩個程式庫的建模、推論、訓練和評估功能。所有 PyLate checkpoint 都可直接載入;支援的模型則列出 colpali-engine checkpoint,以及仍須傳入的 revision。如要遷移,以下是需要修改的呼叫:

PyLate Sentence Transformers
pylate.models.ColBERT(model_name_or_path=...) MultiVectorEncoder(...)
model.encode(..., is_query=True) model.encode_query(...)
model.encode(..., is_query=False) model.encode_document(...)
pylate.scores.colbert_scores model.similarity
pylate.indexes.PLAID / pylate.retrieve.ColBERT 沒有對應項目;保留 PyLate 的 PLAID,或參閲建立索引
colpali-engine Sentence Transformers
ColQwen2.from_pretrained(...) + ColQwen2Processor MultiVectorEncoder(...)
processor.process_queries(...) + model(**batch) model.encode_query(queries)
processor.process_images(...) + model(**batch) model.encode_document(images)
processor.score_multi_vector(qs, ds) model.similarity(query_embeddings, document_embeddings)
mask_non_image_embeddings=True MultiVectorMask(keep_only_token_ids=[...])
HierarchicalTokenPooler HierarchicalTokenPooling
colpali_engine.interpretability sentence_transformers.multi_vector_encoder.interpretability

值得留意的差異出現在純粹(非 ColBERT)checkpoint:PyLate 的 ColBERT("bert-base-uncased") 預設採用經典設定,而 MultiVectorEncoder("bert-base-uncased") 只建立基本模組堆疊,前綴、查詢擴展和略過清單都要明確設定。訓練損失函式、評估器的對應項目,以及資料處理差異,請參閲遷移指南。

所有情況下,儲存相容性都只支援單向遷移。PyLate、Stanford-NLP ColBERT 和 colpali-engine checkpoint 都可載入 MultiVectorEncoder,但 MultiVectorEncoder.save_pretrained 的輸出無法由上述任何程式庫載入。

支援的模型

Hub 上帶有 multi-vector 和 sentence-transformers 標籤的模型清單會持續更新,我們正為所有相容模型加上這些標籤。以下表格列出我們直接測試過的模型,應視為起點而非完整清單。尤其是文字檢索方面,任何 PyLate 或 Stanford-NLP ColBERT checkpoint 都可載入,不論是否已加上標籤。

部分項目需要先在其 repository 加入少量 Sentence Transformers 設定;本文撰寫時,其中幾項仍是尚未合併的 pull request。以下列出 revision 的項目,在 pull request 合併前請傳入該值,合併後只需使用模型名稱:

model = MultiVectorEncoder("vidore/colqwen-omni-v0.1", revision="refs/pr/N")

文字檢索模型

這些模型會從已儲存的設定中還原訓練時的前綴 token、查詢擴展和標點符號略過清單。

NanoBEIR 欄列出 13 個 NanoBEIR 資料集的平均 NDCG@10(越高越好);每個資料集是某個 BEIR 資料集抽取 50 個查詢組成,可快速估算英文文字檢索品質。我們使用 MultiVectorNanoBEIREvaluator 計算以英文為主的模型分數。- 表示未有評估該模型。請留意,NanoBEIR 是小型基準測試,分數不能取代使用自己的資料進行評估;後者才是選擇模型的正確方法。

模型 參數量 維度 NanoBEIR 備註
lightonai/LateOn-regularized 149M 128 0.6897 -
lightonai/LateOn-hpool-regularized 149M 128 0.6876 -
lightonai/LateOn 149M 128 0.6868 -
LiquidAI/LFM2.5-ColBERT-350M 353M 128 0.6864 需要 trust_remote_code=True
lightonai/mLateOn 307M 128 0.6851 -
VAGOsolutions/SauerkrautLM-Multi-ModernColBERT 149M 128 0.6741 -
lightonai/GTE-ModernColBERT-v1 149M 128 0.6720 -
topk-io/Iso-ModernColBERT 149M 128 0.6687 -
perplexity-ai/pplx-embed-v1-late-0.6b 596M 128 0.6662 需要 trust_remote_code=True
VAGOsolutions/SauerkrautLM-Multi-Reason-ModernColBERT 149M 128 0.6616 -
lightonai/ColBERT-Zero 149M 128 0.6569 -
answerdotai/answerai-colbert-small-v1 33M 96 0.6550 -
mixedbread-ai/mxbai-edge-colbert-v0-32m 32M 64 0.6524 -
jinaai/jina-colbert-v2 559M 128 0.6517 需要 trust_remote_code=True
DataScience-UIBK/Reason-mxbai-colbert-v0.1-32m 32M 128 0.6486 -
LiquidAI/LFM2-ColBERT-350M 353M 128 0.6441 -
lightonai/ColBERT-Zero-unsupervised-noprompts 149M 128 0.6430 -
mixedbread-ai/mxbai-edge-colbert-v0-17m 17M 48 0.6407 -
lightonai/colbertv2.0 110M 128 0.6201 -
lightonai/LateOn-Code 149M 128 0.6169 -
lightonai/Agent-ModernColBERT 149M 128 0.6164 -
lightonai/Reason-ModernColBERT 149M 128 0.6078 -
colbert-ir/colbertv2.0 110M 128 0.6053 -
VAGOsolutions/SauerkrautLM-Reason-EuroColBERT 212M 128 0.6039 -
VAGOsolutions/SauerkrautLM-EuroColBERT 212M 128 0.5965 -
antoinelouis/colbert-xm 853M 128 0.5915 -
mixedbread-ai/mxbai-colbert-large-v1 335M 128 0.5733 -
lightonai/LateOn-Code-edge 17M 48 0.5274 -
NeuML/biomedbert-base-colbert 110M 128 0.4320 -
NeuML/colbert-bert-tiny 4M 128 0.4035 -
yjoonjang/colbert-ko-v1 149M 128 - -
ytu-ce-cosmos/turkish-colbert 111M 256 - -
samheym/GerColBERT 110M 128 - -
bclavie/JaColBERT 111M 128 - -
bclavie/JaColBERTv2 111M 128 - -
answerdotai/JaColBERTv2.4 111M 128 - revision="refs/pr/2"
answerdotai/JaColBERTv2.5 111M 128 - revision="refs/pr/5"

視覺文件檢索模型

ColPali 式模型會把頁面影像嵌入為文件,並以文字作為查詢。

NanoViDoRe 欄列出NanoViDoRe v3的平均 NDCG@10(越高越好);這是精簡的視覺文件檢索基準測試,涵蓋 8 個子集(電腦科學、能源、英語和法語金融、人力資源、工業、藥物及物理)。與 NanoBEIR 一樣,NanoViDoRe 是小型基準測試,不應取代以自己的資料進行評估。

模型 參數量 維度 NanoViDoRe 備註
webAI-Official/webAI-ColVec1.1-8b 8.4B 640 0.6580 需要 trust_remote_code=True
webAI-Official/webAI-ColVec1.1-4b 4.5B 640 0.6520 需要 trust_remote_code=True
vultr/VultronRetrieverPrime-Qwen3.5-8B 8.39B 320 0.6423 revision="refs/pr/2"
vultr/VultronRetrieverCore-Qwen3.5-4.5B 4.54B 320 0.6410 revision="refs/pr/1"
tencent/EVIE-Preview-4.5B 4.54B 128 0.6405 -
nvidia/nemotron-colembed-vl-8b-v2 8.77B 4096 0.6374 revision="refs/pr/4",需要 trust_remote_code=True
athrael-soju/colqwen3.5-4.5B-v3 4.54B 320 0.6358 -
TomoroAI/tomoro-colqwen3-embed-8b 8.8B 320 0.6206 需要 trust_remote_code=True
nvidia/nemotron-colembed-vl-4b-v2 4.83B 2560 0.6200 revision="refs/pr/7",需要 trust_remote_code=True
OpenSearch-AI/Ops-Colqwen3-4B 4.44B 2560 0.6150 revision="refs/pr/5",需要 trust_remote_code=True
nvidia/llama-nemotron-colembed-vl-3b-v2 4.41B 3072 0.6112 revision="refs/pr/3",需要 trust_remote_code=True
tsystems/colqwen2.5-3b-multilingual-v1.0 3.75B 128 0.6039 revision="refs/pr/3"
tsystems/colqwen2.5-3b-multilingual-v1.0-merged 3.75B 128 0.6027 revision="refs/pr/1"
TomoroAI/tomoro-colqwen3-embed-4b 4.4B 320 0.6019 需要 trust_remote_code=True
nomic-ai/colnomic-embed-multimodal-7b 8.29B 128 0.5942 revision="refs/pr/3"
nomic-ai/colnomic-embed-multimodal-3b 3.75B 128 0.5929 revision="refs/pr/6"
VAGOsolutions/SauerkrautLM-ColQwen3-8b-v0.1 8.15B 128 0.5819 revision="refs/pr/1"
Metric-AI/ColQwen2.5-3b-multilingual-v1.0 3.75B 128 0.5763 revision="refs/pr/2"
vultr/VultronRetrieverFlash-Qwen3.5-0.8B 853M 320 0.5693 revision="refs/pr/2"
VAGOsolutions/SauerkrautLM-ColQwen3-4b-v0.1 4.44B 128 0.5656 revision="refs/pr/1"
VAGOsolutions/SauerkrautLM-ColQwen3-2b-v0.1 2.13B 128 0.5530 revision="refs/pr/1"
Verm1ion/ColTurk-VDR-Qwen3VL-4B-v1.0 4.44B 320 0.5434 revision="refs/pr/1"
vidore/colqwen2.5-v0.2 3.8B 128 0.5402 -
vidore/colqwen2.5-v0.1 3.8B 128 0.5395 -
vidore/colqwen-omni-v0.1 4.4B 128 0.5309 -
VAGOsolutions/SauerkrautLM-ColQwen3-1.7b-Turbo-v0.1 1.76B 128 0.5035 revision="refs/pr/1"
vidore/colpali-v1.3 2.9B 128 0.4802 -
vidore/colpali-v1.3-hf 2.9B 128 0.4793 -
vidore/colpali-v1.2 2.9B 128 0.4691 -
vidore/colqwen2-v1.0 2.2B 128 0.4685 -
vidore/colqwen2-v0.1 2.2B 128 0.4526 -
vidore/colpali 2.9B 128 0.4516 -
vidore/colpali-v1.1 2.9B 128 0.4314 -
VAGOsolutions/SauerkrautLM-ColLFM2-450M-v0.1 451M 128 0.4249 revision="refs/pr/1"
vidore/colsmolvlm-v0.1 2.1B 128 0.4054 -
VAGOsolutions/SauerkrautLM-ColMinistral3-3b-v0.1 4.25B 128 0.3978 revision="refs/pr/1"
vidore/colpali-hard-v1.1 2.9B 128 0.3949 -
vidore/colSmol-500M 507M 128 0.3459 -
vidore/colSmol-256M 256M 128 0.2673 -
ModernVBERT/colmodernvbert 252M 128 0.2632 -
vidore/colpali-v1.2-hf 2.9B 128 - -
vidore/colqwen2-v1.0-hf 2.2B 128 - -

這些項目大多是 LoRA adapter repository,載入時會直接把 adapter 套用到基礎模型。部分項目在 Hub 亦有一個 -merged 版本(例如 vidore/colpali-v1.3-merged),其權重已整合 adapter。

三個 -hf 項目是原生採用 transformers 的 *ForRetrieval 移植版本。它們毋須任何配置即可載入,但會更多依賴 transformers 的模型實作,較少使用 sentence_transformers。一般而言,使用原始模型會較合適,因為這些移植版本的分數大致相同。

鳴謝

Sentence Transformers 的晚期交互功能建基於許多先前成果。感謝 Omar Khattab 和 Matei Zaharia 開發ColBERT,本文內容皆源自此項工作;亦感謝 LightOn 團隊(Antoine Chaffin、Raphael Sourty、Paulo Moura 和 Amélie Chatelain)開發 PyLate 和 fast-plaid,多年來持續推動晚期交互發展,亦塑造了上文介紹的許多 API。

感謝 ColPali 團隊(Manuel Faysse、Hugues Sibille、Tony Wu、Bilel Omrani、Gautier Viaud、Céline Hudelot 和 Pierre Colombo)開發ColPali 及 colpali-engine,把晚期交互帶到頁面影像檢索;亦感謝 Benjamin Clavié、Antoine Chaffin 和 Griffin Adams 提出token 池化。

亦感謝 MTEB 核心團隊,特別是 Kenneth Enevoldsen、Roman Solomatin 等成員開發 MTEB,以及維持資訊檢索研究運作的各項幕後工作。

最後,感謝所有訓練並發布支援模型中各個 checkpoint 的人。沒有他們,本文便沒有可供評估的模型。

延伸資源

文件

範例腳本

訓練

如要了解如何使用自己的資料訓練或微調這些模型:

請參閲配套網誌:使用 Sentence Transformers 訓練及微調多向量嵌入模型。

Hugging Face Hub

配套網誌

來源:Hugging Face Blog · huggingface.co