NMSLIB向cosinesimil HNSW索引插入csr_matrix报错及扩展性差问题

架构老林

2026-8-30

问题背景

处理对象为TfIdfVectorizer生成、以csr_matrix稀疏格式存储的文本嵌入，计划使用NMSLIB的cosinesimil/HNSW索引完成数据插入与最近邻搜索。
待插入嵌入规模超过100万条时，调用embeddings.toarray()转换为稠密数组再插入的方案无法正常扩展。根据官方issue说明，NMSLIB支持直接插入csr_matrix格式数据，无需调用toarray()做转换，参考示例代码如下：

test_features = sparse.csr_matrix(test_features)
train_features = sparse.csr_matrix(train_features)

nsw = nmslib.init(method = 'sw-graph', space = 'cosinesimil_sparse', data_type=nmslib.DataType.SPARSE_VECTOR)
nsw.addDataPointBatch(train_features)

实际使用如下代码尝试插入自有嵌入数据时触发报错：

self.similar_items_index = nmslib.init(space='cosinesimil', method='hnsw')
    self.similar_items_index.addDataPointBatch(self.embeddings)

对应报错信息：

Traceback (most recent call last):
  File "/home/pln/.local/share/JetBrains/Toolbox/apps/PyCharm-P/ch-0/213.7172.26/plugins/python/helpers/pydev/pydevd.py", line 1483, in _exec
    pydev_imports.execfile(file, globals, locals)  # execute the script
  File "/home/pln/.local/share/JetBrains/Toolbox/apps/PyCharm-P/ch-0/213.7172.26/plugins/python/helpers/pydev/_pydev_imps/_pydev_execfile.py", line 18, in execfile
    exec(compile(contents+"\n", file, 'exec'), glob, loc)
  File "/home/pln/Work/project/foo/bar/baz.py", line 140, in <module>
    cbf_model.train()
  File "/home/pln/Work/project/foo/bar/baz.py", line 152, in timing_wrapper
    value = func(*args, **kwargs)
  File "/home/pln/Work/project/foo/bar/baz.py", line 130, in train
    self.insert_datapoints()
  File "/home/pln/Work/project/foo/bar/baz.py", line 152, in timing_wrapper
    value = func(*args, **kwargs)
  File "/home/pln/Work/project/foo/bar/baz.py", line 159, in insert_datapoints
    self.similar_items_index.addDataPointBatch(self.embeddings)
ValueError: setting an array element with a sequence.
python-builtins.ValueError

核心疑问：
- 上述报错现象是否符合预期？
- cosinesimil类型的HNSW索引是否支持直接插入未经格式转换的csr_matrix数据？
- 为什么稠密转换的插入方案会出现扩展性差的问题？

解答

该报错完全符合预期。
cosinesimil类型的HNSW索引不支持直接插入未做格式转换的csr_matrix稀疏数据。
NMSLIB的空间类型与支持的数据格式是强绑定的：cosinesimil空间默认对应稠密向量类型，仅接受numpy稠密数组格式输入；如果要直接传入csr_matrix稀疏格式，必须使用专门适配稀疏向量的cosinesimil_sparse空间，同时显式指定参数data_type=nmslib.DataType.SPARSE_VECTOR，这也是官方示例的正确写法。
初始化代码使用space='cosinesimil'、未指定稀疏数据类型时，接口会默认按照稠密数组的解析逻辑处理输入的csr_matrix对象，类型不匹配就会抛出对应的错误。
转稠密数组的方案扩展性差，核心原因是内存占用呈量级式暴涨：
TF-IDF生成的文本嵌入维度通常在数万到数十万级别，单条向量的非零值占比极低（多数场景下不足1%）。调用toarray()转换为稠密数组时，会把所有零值也全部显式存储。以100万条、维度10万的嵌入为例，用单精度浮点数存储稠密数组需要的内存约为1e6 * 1e5 * 4字节 = 40TB，远超出普通服务器的内存上限，根本无法正常加载。
而直接使用csr_matrix稀疏格式配合cosinesimil_sparse空间时，仅需要存储非零值和对应的索引信息，同等数据规模下内存占用通常仅为几百MB到数GB，完全可以支撑百万甚至千万级别的数据插入与检索需求。

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