Weaviate中MUVERA压缩与text2colbert-jinaai兼容问题排查

环境 #

• Weaviate：1.31.5（Docker运行）
• weaviate-client：4.10.2
• Python：3.13

代码 #

严格按照官方文档示例编写：

import weaviate
from weaviate.classes.config import Configure, Property, DataType
import os

# 连接Weaviate
client = weaviate.connect_to_local()

# 创建带MUVERA配置的集合
collection = client.collections.create(
    "DemoCollection",
    vectorizer_config=[
        Configure.NamedVectors.text2colbert_jinaai(
            name="jina_colbert",
            source_properties=["text"],
            vector_index_config=Configure.VectorIndex.hnsw(
                multi_vector=Configure.VectorIndex.MultiVector.multi_vector(
                    encoding=Configure.VectorIndex.MultiVector.Encoding.muvera(
                        # MUVERA调优可选参数
                        ksim=4,
                        dprojections=16,
                        repetitions=20,
                    )
                )
            )
        )
    ],
    properties=[
        Property(name="text", data_type=DataType.TEXT)
    ]
)


# 插入测试数据
collection.data.insert(
    properties={"text": "The quick brown fox jumps over the lazy dog"}
)

# 查询并检查向量格式
result = collection.query.fetch_objects(limit=1, include_vector=True)

if result.objects:
    obj = result.objects[0]
    vec_data = obj.vector['jina_colbert']
    
    if isinstance(vec_data[0], list):
        print(f"多向量: [{len(vec_data)}, {len(vec_data[0])}]")
    else:
        print(f"单向量: {len(vec_data)} 维度")

client.close()

预期结果 #

根据文档，MUVERA应该将ColBERT的多向量嵌入压缩为单向量。使用参数ksim=4、dprojections=16、repetitions=20时，预期得到5120维度的单向量（计算方式：2^4 × 16 × 20）。

实际结果 #

输出为多向量: [16, 128]，即原始的16个token×128维度的多向量，压缩并未生效。

Schema检查 #

创建的Schema显示MUVERA已启用：

{
  "multivector": {
    "aggregation": "maxSim",
    "enabled": true,
    "muvera": {
      "dprojections": 16,
      "enabled": true,
      "ksim": 4,
      "repetitions": 20
    }
  }
}

已确认Weaviate版本符合MUVERA要求（1.31+，当前为1.31.5），怀疑是对MUVERA工作原理存在误解。

解决方法 #

1. 明确MUVERA的作用阶段 #

MUVERA是索引阶段的压缩机制，它不会修改存储的原始多向量，而是在构建索引时生成压缩后的单向量用于检索加速。你通过fetch_objects获取的是存储的原始多向量，这是正常行为，并非MUVERA未生效。

2. 验证MUVERA实际生效的方式 #

要确认MUVERA是否在检索时起作用，可以通过以下操作验证：

• 对比启用/禁用MUVERA时的检索延迟，启用后速度应明显提升
• 查看Weaviate的运行日志，确认索引构建过程中存在MUVERA相关的处理记录
• 检查索引文件大小，启用MUVERA后索引体积会显著小于仅存储原始多向量的情况

3. 配置细节确认 #

当前你的Schema配置是正确的，但需要注意两个关键点：

• MUVERA仅适配HNSW索引，你的配置已使用Configure.VectorIndex.hnsw，符合要求
• ColBERT类向量器的设计逻辑是保留原始多向量用于精细匹配，MUVERA生成的压缩向量仅用于索引层的快速召回，两者各司其职

4. 关于获取压缩向量 #

Weaviate目前没有直接返回MUVERA压缩向量的API，因为该向量仅用于内部索引运算，不会单独存储。如果需要验证压缩效果，只能通过检索性能、索引体积等间接方式判断。

内容的提问来源于stack exchange，提问作者tat