Weaviate 1.40 发布

本次发布中有两项功能正式可用:删除命名向量——可释放未使用向量所占用的磁盘和索引内存,以及 4-bit Rotational Quantization。另有两项全新功能:HFresh 索引现在可通过 MUVERA 接收多向量嵌入,而 PathSeer 加入 ACORN 和 sweeping,成为 HNSW 的第三种过滤策略。本文还会补上 Search REST API 的内容,它在 1.39 补丁系列中变化很大。文中也会介绍向量配置默认值的一项破坏性变更,升级前请务必检查。
以下是本次发布的亮点!
如果你的服务器设置了 DEFAULT_VECTORIZER_MODULE,请在升级前阅读向量配置默认值部分。
集合中的向量会随时间不断增加。你为试用新的嵌入模型添加了一个命名向量,新模型胜出,但旧向量仍保留在每个对象、每个分片上,占用磁盘和索引内存。此前唯一的解决办法是重新创建集合并重新导入所有内容。
v1.40 将删除向量索引端点正式可用。该端点自 v1.37 起就作为实验性功能存在,默认关闭。在 v1.40 中它默认开启。
删除操作会删除该向量的索引,并从每个对象中移除其嵌入。集合中的其他命名向量以及所有对象数据保持不变。
若要恢复该向量,请重新添加它,然后对对象重新向量化或重新导入。
使用 Python 客户端(4.24.0 或更新版本)时,调用 delete_vector_index 并传入向量名称:
articles = client.collections.use("Article") articles.config.delete_vector_index("body_vector") 通过 REST 则只需一个 DELETE 请求:
curl -X DELETE \ http://localhost:8080/v1/schema/Article/vectors/body_vector/index 该调用在 Weaviate 接受删除操作后即返回。清理本身在后台运行,逐个分片进行,并在重启后从上次中断处继续。
清理运行期间,该向量仍会列在集合定义中,而针对它的写入会被拒绝。在批量操作中,只有携带被删除向量的对象会失败。当该向量从定义中消失时,删除即告完成。
还有几点需要了解:
Python 客户端是首个封装该接口的客户端。使用其他任何语言,请直接发送 REST 请求。
4-bit Rotational Quantization(RQ)在 v1.39 中为预览功能,现已正式可用。RQ 会先对每个向量做旋转,然后把每个维度存储为一个小整数,而不是完整的浮点数。
启用它的理由是内存。在 100 万个 1536 维向量上,4-bit RQ 比 8-bit RQ 少用约 45% 的内存。同样规模的集群可以容纳更多向量,或者你可以运行一个更小的集群。导入也会变得更快。
搜索质量得以保持,因为 Weaviate 会用原始向量对最优候选结果重新打分。
许多嵌入模型生成的向量会聚集在一个非零的点附近。Weaviate 自 v1.39.3 起提供的 Centering(中心化)会从你的数据样本中测出该点,并相对该点进行压缩。这使 4-bit 的召回率接近 8-bit。它默认关闭,因为一些模型已经做到了这一点。它仅适用于 4-bit。
在 HNSW 索引上设置 rq.bits = 4。使用 Python 客户端 4.23.1 或更新版本时,可在同一次调用中开启中心化:
from weaviate.classes.config import Configure client.collections.create( "Doc", vector_config=Configure.Vectors.self_provided( name="default", vector_index_config=Configure.VectorIndex.hnsw( quantizer=Configure.VectorIndex.Quantizer.rq(bits=4, centering=True), ), ), ) bits 会在向量上首次启用 RQ 时锁定,因此要在此之前选定位宽。你仍然可以稍后在未压缩的集合上启用 RQ。
运维人员可以设置 DEFAULT_QUANTIZATION=rq-4,使 4-bit RQ 成为新 HNSW 索引的默认值。Weaviate Cloud 仍将 8-bit RQ 作为默认值。4-bit 仅适用于 HNSW 索引。
具体数字和工程细节见《4-bit Rotational Quantization 深度解析》。
HFresh 是 Weaviate 基于磁盘的向量索引。它在内存中保留一个较小的质心索引,并将压缩后的向量存储在磁盘上,因此所需内存远少于 HNSW。到目前为止,它每个对象只接收一个向量。
诸如 ColBERT 和 ColPali 之类的后期交互模型会生成多向量嵌入:每个 Token 或图像块一个向量,而不是每个对象一个向量。它们的排序效果很好,但一页文本可能变成数百个向量,这类数据会给内存带来压力。在 v1.40 中,HFresh 可以为它们建立索引。
有一个前提条件。在 HFresh 上,多向量嵌入需要 MUVERA 编码。MUVERA 会把一组向量转换成一个固定长度的向量,这样 HFresh 就能像搜索其他向量一样搜索它。
在 HFresh 上执行一次多向量查询需要经过三个阶段:
searchProbe 和 rq.rescoreLimit 都在 HFresh 索引配置中设置,控制前两个阶段。searchProbe 设定扫描多少个倒排列表。rq.rescoreLimit 设定有多少候选能通过重打分存活下来。随后,幸存者会用 MaxSim 与其原始 token 向量进行精确打分。MaxSim 是一种延迟交互打分方式,把每个查询 token 匹配到与它最接近的文档 token。
要进行设置,需要创建一个命名向量,不指定 vectorizer、使用 MUVERA 编码,并配上 HFresh 索引:
from weaviate.classes.config import Configure client.collections.create( "Page", vector_config=Configure.MultiVectors.self_provided( name="colbert", encoding=Configure.VectorIndex.MultiVector.Encoding.muvera(), vector_index_config=Configure.VectorIndex.hfresh(), ), ) 约束条件如下:
如果你设置了 multivector.enabled 却没有用 MUVERA,集合会创建成功,但它的行为就像一个普通向量,不支持多向量,并且会拒绝多向量的导入和查询。请设置 multivector.muvera.enabled。
带过滤的向量搜索必须找到既离得最近、又能通过过滤条件的对象。在 HNSW 索引上,当大量邻居未能通过过滤条件时,filterStrategy 设置决定搜索如何遍历图。到目前为止你有两个选择:acorn(默认)和 sweeping。
v1.40 增加了第三种:pathseer。它来自 Zhiyue Li 等人在 SIGMOD 2026 上发表的论文,论文的第一作者 @lizhiyuell 贡献了该实现(#12137)。
在 Weaviate 的基准测试中,在随机、主题和组合过滤器上,PathSeer 是最快的策略,或者与最快者相差几个百分点。ACORN 仅在强负相关过滤器上保持领先,此时过滤器几乎排除了查询的邻域。PathSeer 博文包含完整的基准测试和该算法的详细解读。
PathSeer 像扫描一样遍历图的底层。当结果集仍在填充时,它还会像 ACORN 一样对每个候选的邻居的邻居进行过滤检查。一旦结果集已满,它就会跳过不匹配候选的不匹配邻居,而不计算它们的距离。它按节点做出该判断,因此没有需要调优的新参数。
它不存储任何额外内容。没有导入成本,没有内存开销,并且你可以将现有集合切换到它,或从它切走,而无需重建索引。平面搜索截断仍然首先适用:当过滤器匹配的对象少于 flatSearchCutoff 时,Weaviate 会扫描这些对象,而不是遍历图。
要将现有的命名向量切换过来:
from weaviate.classes.config import Reconfigure, VectorFilterStrategy articles = client.collections.use("Article") articles.config.update( vector_config=Reconfigure.Vectors.update( name="default", vector_index_config=Reconfigure.VectorIndex.hnsw( filter_strategy=VectorFilterStrategy.PATHSEER, ), ) ) 在通过 REST 发送的集合定义中,它是 HNSW vectorIndexConfig 中的一个字段:
{ "vectorIndexConfig": { "filterStrategy": "pathseer" } } 相关资源 概念:Filtering - PathSeer 博客:PathSeer,自适应过滤向量搜索 Search REST API(预览) Search REST API 让你通过 HTTP/1.1 使用纯 JSON 进行搜索,无需生成客户端,也无需 GraphQL 查询字符串。它在 v1.39 中作为实验性、默认关闭的功能推出。自那以后发生了很多变化。所有这些都已随 1.39 补丁发布,该 API 现在处于预览阶段。
这样一来就有六个端点:
下面是一个近向量搜索,它还会跟随指向每本书作者的引用:
curl -s -X POST http://localhost:8080/v1/search/Book/near-vector \ -H 'Content-Type: application/json' \ -d '{"vector":[0.1,0.9,0.2],"limit":1, "returnProperties":["title"], "returnReferences":[{"linkOn":"writtenBy","returnProperties":["name"]}], "returnMetadata":["distance"]}' 每个 returnReferences 条目都会在 linkOn 中指定引用属性,以及要从其指向的对象中返回什么。你还可以为多目标引用设置 targetCollection,为被引用对象设置 returnMetadata,并使用嵌套的 returnReferences 再前进一跳。被引用对象返回时,其属性和元数据形状与顶层命中结果相同:
原文较长,译文为节选;译文由英文原文机器翻译,术语按行业惯例统一,可在文末展开原文核对。
查看英文原文(Weaviate 1.40 Release)
Two features reach general availability in this release: dropping a named vector, which frees the disk and index memory an unused vector was holding, and 4-bit Rotational Quantization. Two more are new: the HFresh index now takes multi-vector embeddings through MUVERA, and PathSeer joins ACORN and sweeping as a third filter strategy for HNSW. This post also catches up on the Search REST API, which changed a lot over the 1.39 patch line. It also covers a breaking change to vector configuration defaults to check before you upgrade.
Here are the release highlights!

- Drop a named vector - General Availability
- 4-bit Rotational Quantization - General Availability
- Multi-vector embeddings on HFresh with MUVERA
- PathSeer filter strategy
- Search REST API (Preview)
- Vector configuration defaults (breaking change)
- Performance Improvements and Fixes
- Community Contributions
- Summary
If your server sets DEFAULT_VECTORIZER_MODULE, read Vector configuration defaults before you upgrade.
Drop a named vector - General Availability
Collections pick up vectors over time. You add a named vector to try a new embedding model, the new one wins, and the old one stays on every object, in every shard, taking up disk and index memory. Until now the only way out was to re-create the collection and re-import everything.
v1.40 makes the drop vector index endpoint generally available. It has existed since v1.37 as an experimental feature that was off by default. In v1.40 it is on by default.
A drop deletes the vector's index and removes its embedding from every object. The collection's other named vectors and all object data stay as they are.
To get the vector back, add it again and then re-vectorize or re-import your objects.
How it works
With the Python client (4.24.0 or newer), call delete_vector_index with the name of the vector:
articles = client.collections.use("Article")
articles.config.delete_vector_index("body_vector")
Over REST it is one DELETE request:
curl -X DELETE \
http://localhost:8080/v1/schema/Article/vectors/body_vector/index
The call returns once Weaviate has accepted the drop. The cleanup itself runs in the background, shard by shard, and picks up where it left off after a restart.
While the cleanup runs, the vector is still listed in the collection definition, and writes that target it are rejected. In a batch, only the objects that carry the dropped vector fail. The drop is finished when the vector disappears from the definition.
A few more things to know:
- Permissions: You need
updatepermission on the collection and on its data objects, because a drop rewrites every object. - Inactive tenants: A tenant that is inactive holds up completion until it is activated and a later cleanup round reaches it.
- Reusing the name: Once the drop is finished you can add a vector with the same name again, even with a different dimensionality. The new index starts empty.
- The last vector: Dropping the only vector leaves a collection with no vectors. Objects and properties stay.
The Python client is the first to wrap the endpoint. From any other language, send the REST request.
4-bit Rotational Quantization - General Availability
4-bit Rotational Quantization (RQ), a preview in v1.39, is now generally available. RQ rotates each vector, then stores every dimension as a small integer instead of a full float.
The reason to turn it on is memory. On a million 1536-dimension vectors, 4-bit RQ used about 45% less memory than 8-bit RQ. A cluster of the same size holds more vectors, or you run a smaller one. Imports get faster too.
Search quality holds up because Weaviate rescores the best candidates with the original vectors.
How it works
Many embedding models produce vectors that cluster around a point that is not zero. Centering, in Weaviate since v1.39.3, measures that point from a sample of your data and compresses relative to it. That brings 4-bit recall close to 8-bit. It is off by default because some models already do this. It only applies to 4-bit.
Set rq.bits = 4 on an HNSW index. With Python client 4.23.1 or newer, turn on centering in the same call:
from weaviate.classes.config import Configure
client.collections.create(
"Doc",
vector_config=Configure.Vectors.self_provided(
name="default",
vector_index_config=Configure.VectorIndex.hnsw(
quantizer=Configure.VectorIndex.Quantizer.rq(bits=4, centering=True),
),
),
)
bits locks when RQ is first enabled on a vector, so pick the width before then. You can still enable RQ later on an uncompressed collection.
Operators can set DEFAULT_QUANTIZATION=rq-4 to make 4-bit RQ the default for new HNSW indexes. Weaviate Cloud keeps 8-bit RQ as its default. 4-bit works on HNSW indexes only.
The numbers and the engineering are in the 4-bit Rotational Quantization deep dive.
Multi-vector embeddings on HFresh with MUVERA
HFresh is Weaviate's disk-based vector index. It keeps a small index of centroids in memory and stores compressed vectors on disk, so it needs far less memory than HNSW. Until now it only took one vector per object.
Late-interaction models such as ColBERT and ColPali produce a multi-vector embedding: one vector per token or image patch, instead of one vector per object. They rank well, but a page of text can turn into hundreds of vectors, which is the kind of data that strains memory. In v1.40, HFresh can index them.
There is one condition. On HFresh, multi-vector embeddings need MUVERA encoding. MUVERA turns a set of vectors into a single fixed-length vector, so HFresh can search it like any other.
How it works
A multi-vector query on HFresh runs in three passes:
searchProbe and rq.rescoreLimit, both set in the HFresh index config, control the first two passes. searchProbe sets how many posting lists are scanned. rq.rescoreLimit sets how many candidates survive the rescore. The survivors are then scored exactly against their original token vectors with MaxSim. MaxSim is the late-interaction score that matches each query token to its closest document token.
To set it up, create a named vector with no vectorizer, MUVERA encoding, and an HFresh index:
from weaviate.classes.config import Configure
client.collections.create(
"Page",
vector_config=Configure.MultiVectors.self_provided(
name="colbert",
encoding=Configure.VectorIndex.MultiVector.Encoding.muvera(),
vector_index_config=Configure.VectorIndex.hfresh(),
),
)
The constraints:
- The vector needs
"vectorizer": "none": You bring the token vectors yourself. - MUVERA is required, and fixed at creation:
multivector.muvera.enabledcannot be changed later. - The encoding is always compressed with 1-bit RQ: PQ, SQ and BQ are rejected, and RQ cannot be turned off.
multivector.enabled alone is not enough on HFreshIf you set multivector.enabled without MUVERA, the collection is created, but it behaves as a regular vector without multi-vector support and rejects multi-vector imports and queries. Set multivector.muvera.enabled.
PathSeer filter strategy
A filtered vector search has to find the nearest objects that also pass a filter. On an HNSW index, the filterStrategy setting decides how the search walks the graph when many neighbors fail the filter. Until now you had two choices: acorn (the default) and sweeping.
v1.40 adds a third, pathseer. It comes from the SIGMOD 2026 paper by Zhiyue Li et al., and the paper's first author, @lizhiyuell, contributed the implementation (#12137).
In Weaviate's benchmarks PathSeer was the fastest strategy, or within a few percent of it, on random, topical and combined filters. ACORN stays ahead only on strongly negatively correlated filters, where the filter all but excludes the query's neighborhood. The PathSeer post has the full benchmarks and a walkthrough of the algorithm.
How it works
PathSeer walks the bottom layer of the graph like sweeping. While the result set is still filling, it also filter-checks the neighbors of each candidate's neighbors, like ACORN. Once the result set is full, it skips the non-matching neighbors of a non-matching candidate without computing their distance. It makes that call per node, so there is no new parameter to tune.
It stores nothing extra. There is no import cost, no memory overhead, and you can switch an existing collection to it, or away from it, without reindexing. The flat-search cutoff still applies first: when a filter matches fewer objects than flatSearchCutoff, Weaviate scans those objects instead of walking the graph.
To switch an existing named vector over:
from weaviate.classes.config import Reconfigure, VectorFilterStrategy
articles = client.collections.use("Article")
articles.config.update(
vector_config=Reconfigure.Vectors.update(
name="default",
vector_index_config=Reconfigure.VectorIndex.hnsw(
filter_strategy=VectorFilterStrategy.PATHSEER,
),
)
)
In a collection definition sent over REST, it is one field in the HNSW vectorIndexConfig:
{ "vectorIndexConfig": { "filterStrategy": "pathseer" } }
Search REST API (Preview)
The Search REST API lets you search with plain JSON over HTTP/1.1, with no generated client and no GraphQL query strings. It arrived as an experimental, off-by-default feature in v1.39. A lot has changed since then. All of it shipped in 1.39 patches, and the API is now a preview.
- On by default from
v1.39.7 - Structured references from
v1.39.3: A newreturnReferencesfield replaces the dotted"hasAuthor.name"form the 1.39 post warned about. A dotted name inreturnPropertiesis now rejected. near-vectorfromv1.39.8: It takes a vector you supply, so it works on collections without a vectorizer.
That makes six endpoints:
POST /v1/search/{collection}/near-textPOST /v1/search/{collection}/bm25POST /v1/search/{collection}/hybridPOST /v1/search/{collection}/near-objectPOST /v1/search/{collection}/near-vectorPOST /v1/aggregate/{collection}(returns a count)
How it works
Here is a near-vector search that also follows a reference to each book's author:
curl -s -X POST http://localhost:8080/v1/search/Book/near-vector \
-H 'Content-Type: application/json' \
-d '{"vector":[0.1,0.9,0.2],"limit":1,
"returnProperties":["title"],
"returnReferences":[{"linkOn":"writtenBy","returnProperties":["name"]}],
"returnMetadata":["distance"]}'
Each returnReferences entry names the reference property in linkOn and what to return from the objects it points to. You can also set targetCollection for a multi-target reference, returnMetadata for the referenced objects, and a nested returnReferences to go one hop further. Referenced objects come back in the same properties and metadata shape as the top-level hits:
{
"results": [
{
"id": "ce442a4d-a704-46bd-b5c3-cf7b1b2ffdc0",
"metadata": { "distance": 0.00040352345 },
"properties": { "title": "The Left Hand of Darkness" },
"references": {
"writtenBy": [ { "properties": { "name": "Ursula K. Le Guin" } } ]
}
}
],
"tookMs": 1
}
A few things have not changed. The default limit is QUERY_DEFAULTS_LIMIT (10). targetVector takes a single vector name. No client library wraps these endpoints yet. Boost, MMR, reranking, generative search and grouped search are not available over REST.
The Search REST API is a preview feature. Its request and response shape may still change in future releases.
Vector configuration defaults (breaking change)
If your server sets DEFAULT_VECTORIZER_MODULE, collections you create on v1.40 without naming a vectorizer will not be vectorized. There is no error at creation time, only a warning at startup.
From v1.40, DEFAULT_VECTORIZER_MODULE is deprecated and ignored. Weaviate logs a warning at startup if it is set. The default top-level vectorizer is always none. Existing collections are not affected. What changes is what a new collection definition gives you:
| Your collection definition sets | Before v1.40 | From v1.40 |
|---|---|---|
| No vector parameters at all | A single-vector collection, filled in from the server defaults | A collection without a vector |
vectorIndexType or vectorIndexConfig, but no vectorizer | A single-vector collection, vectorized by DEFAULT_VECTORIZER_MODULE | A single-vector collection that does not vectorize |
| An explicit vectorizer | Unchanged | Unchanged |
Older clients that always send vectorIndexType, such as the Python client before 4.21.2, land in the second row. Auto-schema changed earlier: since v1.39.1 it creates a named vector called default with the vectorizer set to none.
What to do: name the vectorizer explicitly in every collection definition that needs one, before you upgrade.
Performance Improvements and Fixes
Beyond the headline features, v1.40 ships a long list of improvements. Some of the items below first shipped in 1.39 patches, and those say so. A few worth calling out:
- Shard status per replica:
GET /v1/schema/{collection}/shardsnow reports aper_node_statusobject that maps each node to the shard's status on that node. A replica that cannot be reached, or cannot serve reads, reportsUNAVAILABLE. The oldstatusandvectorQueueSizefields are deprecated. - Stricter MCP hybrid tool: the built-in MCP server's hybrid search tool now rejects an
alphaoutside0to1and a negativelimit. It combines results with relative score fusion, the same default as the other APIs, and it rejects unknown argument keys. - gRPC for Google Cloud Storage backups: the
backup-gcsmodule now talks to GCS over gRPC by default. A local emulator that only serves the JSON API needsGCS_MODULE_TRANSPORT=http. - Smaller HNSW graph in memory: each HNSW node is now a single heap object instead of three, which means less memory per node and fewer allocations. Shipped in
v1.39.6. - Leaner aggregations: aggregation scans now reuse their buffers and read each segment through a single reader, so they allocate much less. Shipped in
v1.39.3. - A
read_backupspermission: a role can now list backups and read backup and restore status without being able to create, restore or cancel one. Shipped inv1.39.10. - Two new generative modules: DigitalOcean arrived in
v1.39.2and Meta AI inv1.39.3.
Community Contributions
Weaviate is open source, and this release cycle includes work from four first-time contributors. Thank you to:
- @lizhiyuell: the PathSeer filter strategy for HNSW (#12137)
- @hamodywe: fetching
Boost.Depth-deep candidates in hybrid sub-searches (#12537) (sincev1.39.1) - @bharadwaj-pendyala: excluding LSM scratch files from the
offload-s3shard upload (#12884) - @ColtonRobak: passing the tenant to the re-vectorize check on
PATCH(#13345) (sincev1.39.8)
If you'd like to contribute, check out the contributor guide and the good-first-issue label on GitHub.
Summary
Weaviate v1.40 promotes two features to general availability, brings multi-vector embeddings to HFresh, and adds a third HNSW filter strategy.
Key highlights:
- Drop a named vector (GA): remove a vector you no longer need from every object, in the background, without re-creating the collection
- 4-bit Rotational Quantization (GA): close to half the memory of 8-bit RQ on HNSW indexes, with optional centering to keep recall high
- Multi-vector embeddings on HFresh with MUVERA: ColBERT and ColPali style embeddings on the disk-based index, through MUVERA encoding
- PathSeer filter strategy: a third way to walk the HNSW graph under a filter, from a SIGMOD 2026 paper, switchable on existing collections
- Search REST API (Preview): on by default, structured references, and a
near-vectorendpoint, all since the 1.39 patch line - Vector configuration defaults (breaking change):
DEFAULT_VECTORIZER_MODULEis ignored, so name your vectorizer in every collection definition before you upgrade
Ready to get started?
The release is available open-source on GitHub and on Weaviate Cloud, where you can spin up a cluster on the free tier.
Not all features may be available on Weaviate Cloud. Preview and experimental features, and anything that needs specific environment configuration, may not be enabled on managed clusters, or may arrive there on a different schedule.
If you are upgrading a self-hosted cluster, check the migration guide for version-specific notes.
Thanks for reading, and happy vector searching!
Ready to start building?
Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.
正文保留英文原文,标题与摘要由机器翻译。
原文发布于 Weaviate Blog(Weaviate 1.40 Release),标题、摘要与正文由机器翻译,术语按行业惯例统一,未经人工逐句校订。