Weaviate 1.39 Release

from
datetime
import
timedelta
from
weaviate
.
classes
.
query
import
Boost
,
Filter
prefer_in_stock_and_recent
=
Boost
.
blend
(
[
Boost
.
filter
(
Filter
.
by_property
(
"in_stock"
)
.
equal
(
True
)
,
weight
=
2.0
)
,
Boost
.
time_decay
(
"released"
,
scale
=
timedelta
(
days
=
30
)
)
,
]
,
weight
=
0.3
,
# 30% boost, 70% original relevance
depth
=
200
,
# re-score the top 200 candidates
)
for
label
,
boost
in
(
(
"plain hybrid"
,
None
)
,
(
"with boost"
,
prefer_in_stock_and_recent
)
)
:
response
=
collection
.
query
.
hybrid
(
query
=
"wireless headphones"
,
limit
=
4
,
boost
=
boost
)
print
(
label
)
for
obj
in
response
.
objects
:
print
(
"  "
,
obj
.
properties
[
"title"
]
,
"| in stock:"
,
obj
.
properties
[
"in_stock"
]
)

plain hybrid
Kestrel 无线耳机 | 有货：True
Meridian 无线耳机 | 有货：False
Aurora 无线耳机 | 有货：False
Nimbus 无线耳机 | 有货：True
with boost
Kestrel 无线耳机 | 有货：True
Nimbus 无线耳机 | 有货：True
无线耳机 Pro | 有货：True
Meridian 无线耳机 | 有货：False

from
weaviate
.
classes
.
query
import
Diversity
for
balance
in
(
1.0
,
0.3
,
0.0
)
:
response
=
collection
.
query
.
hybrid
(
query
=
"carbon pricing"
,
limit
=
8
,
# candidate pool
diversity_selection
=
Diversity
.
mmr
(
limit
=
4
,
balance
=
balance
)
,
# 4 returned
)
print
(
f"balance=
{
balance
}
"
)
for
obj
in
response
.
objects
:
print
(
"  "
,
obj
.
properties
[
"title"
]
)

balance=1.0
碳税与配额交易
碳定价基础
碳定价常见问题
什么是碳价格？
balance=0.3
碳税与配额交易
碳定价常见问题
碳定价基础
沿海城市适应资金
balance=0.0
碳税与配额交易
油气甲烷规则
沿海城市适应资金
可再生能源补贴与电网建设

from
weaviate
.
classes
.
config
import
Configure
client
.
collections
.
create
(
"Doc"
,
vector_config
=
Configure
.
Vectors
.
text2vec_weaviate
(
name
=
"default"
,
source_properties
=
[
"title"
,
"body"
]
,
vector_index_config
=
Configure
.
VectorIndex
.
hnsw
(
quantizer
=
Configure
.
VectorIndex
.
Quantizer
.
rq
(
bits
=
4
,
rescore_limit
=
20
,
)
,
)
,
)
,
)

平面索引仍然会拒绝该设置，要求RQ位必须为1或8，这一规则同样适用于动态索引的平面侧。在HNSW索引中使用4位。

与其他RQ宽度类似，4位宽度支持余弦、点积和L2平方距离度量方式。

预览功能

4位宽度是预览功能，其行为和默认值可能在未来版本中发生变化。

- 概念：向量量化 - 旋转量化
- 概念：向量量化 - 重评分
- 配置参考：向量索引参数

## 搜索REST API（实验性） ​

Weaviate目前提供两种搜索API。gRPC速度快，但需要生成的客户端和HTTP/2支持。GraphQL需要手动构建查询字符串，并从_additional字段中提取元数据。对于shell脚本、Lambda函数、边缘工作器、API网关或没有Weaviate客户端的语言来说，这两种方式都不够友好。

v1.39版本新增了实验性的Search REST API。您可以通过纯HTTP/1.1发送JSON请求并接收JSON响应，所有端点都通过OpenAPI规范进行描述，与REST API的其他部分保持一致。这种设计也更适合LLM工具调用，因为模型需要的是文档化的HTTP端点而非客户端库。

v1.39.0版本发布了第一个端点POST /v1/search/{collection}/near-text。v1.39.1补丁版本又新增了三个搜索端点和一个对应的聚合端点，因此在1.39.1或更新版本中您将获得全部五个端点：

- POST /v1/search/{collection}/near-text
- POST /v1/search/{collection}/bm25
- POST /v1/search/{collection}/hybrid
- POST /v1/search/{collection}/near-object
- POST /v1/aggregate/{collection}

以下示例使用near-text端点。

这些端点默认是关闭的。通过在每个节点上设置EXPERIMENTAL_REST_SEARCH_ENABLED来启用：

可接受的真值包括on、enabled、1和true。一个开关即可控制所有端点。当功能关闭时，路由仍然存在，但会返回422状态码并提示需要设置的变量名称，而非令人困惑的404错误。

请求体中的所有字段均使用驼峰命名法。对于near-text查询，query是必需的字符串数组，每个字符串代表一个待搜索的文本片段。发送单个字符串进行普通搜索，发送多个字符串时Weaviate会将它们平均为一个搜索向量。您还可以指定certainty或distance（不可同时指定）、targetVector、where、limit、offset、autoLimit、returnProperties、returnMetadata、tenant和consistencyLevel参数。

响应格式为{results, tookMs}。每个搜索结果都以相同的平面结构返回{id, properties, references, metadata}：

当查询不涉及引用字段时，references字段会被省略；当仅请求id时，metadata字段会被省略。向量数据永远不会返回。

发生错误时，会返回标准格式的{"error": [{"message": "..."}]}响应体。

实验性功能意味着其结构仍可能发生变化

此 API 默认处于关闭状态，其请求和响应结构尚未固定。参考选择功能最有可能发生变化。在 v1.39 版本中，您需要通过在 returnProperties 中使用点号表示法（如 "hasAuthor.name"）来请求引用属性，且仅支持单层深度。这种格式即将被替换，因此请做好更新相关实现的准备。

目前尚无官方客户端封装此接口。所有 Weaviate 客户端均使用 gRPC 进行搜索，因此现阶段您需要通过 curl 或原始 HTTP 访问该接口。Boost、MMR、重排序、生成式搜索和 group-by 功能在 REST 接口上均不可用。

- 参考资料：RESTful API - 搜索端点
- 环境变量：EXPERIMENTAL_REST_SEARCH_ENABLED

## gRPC-Web

浏览器无法直接使用纯 gRPC 协议，因此前端代码一直无法直接调用 Weaviate 的 gRPC API。gRPC-Web 通过普通 HTTP 提供相同 API，填补了这一空白。该功能在 v1.38.3 版本中引入，此前的版本说明中未进行过介绍。

该接口位于与 REST API 相同端口（默认 8080）的 /v1/grpc-web/ 路径下。它不使用 gRPC 端口，也不使用独立端口，因此无需在防火墙或入口规则中额外开放端口。

该功能默认处于启用状态。如需关闭，将运行时配置键 grpc_web_enabled 设置为 false。该键使用 snake_case 命名格式，且没有对应的环境变量。配置变更无需重启即可生效。当接口关闭时，对 /v1/grpc-web/ 路径的请求将返回标准 404 错误，与 Weaviate 不提供服务的其他路径行为一致。REST API 的其余功能不受影响。

需要注意的是：目前所有 Weaviate 客户端库均通过纯 gRPC 连接，因此尚未使用此接口。

- 参考资料：gRPC API - gRPC-Web

## HNSW 快照，自动 - 一般可用性

HNSW 索引在启动时会通过重放其提交日志（记录图结构所有变更的仅追加写前日志）进行重建。快照是该图结构的压缩镜像，因此启动时只需加载一个文件，而无需重放数百万条记录。此前快照仅作为可选缓存：您需要通过少量环境变量进行调度，且日志文件会永久保留在磁盘上。这意味着您需要为相同图结构支付两次存储费用。

在 v1.39 版本中，快照功能已实现自动化并进入一般可用阶段。Weaviate 会在后台自动创建和刷新快照，当新快照安全写入磁盘后，会删除所有该快照覆盖的提交日志。您将获得以下优势：

- 更少磁盘占用：您只需保留快照文件和快照后的写入数据，而非快照文件和完整历史记录。在向量密集型集群中，这能带来显著的存储节省。
- 启动更快更稳定：加载快照在每次重启时耗时基本一致。而重放持续增长的日志文件耗时会不断变化。
- 无需调优：没有快照相关环境变量，也无需设置调度计划。Weaviate 会自主决定何时创建新快照。

关于磁盘节省的两个注意事项：清理操作仅针对已加载的分片执行，因此不活跃租户的旧文件会一直保留到下一次使用。快照期间磁盘使用量会暂时上升，因为 Weaviate 会在删除旧文件前先写入新文件。请保留当前的磁盘余量空间。

原先用于控制快照的五个配置项现已失效。Weaviate 仍会接受这些配置项，但将在未来版本中移除：

设置其中任何一个配置项会在启动时记录一条警告信息，而不是直接失败，因此升级时不会因过时的配置文件而中断。您可以在合适的时候删除这些配置项。唯一保留的HNSW持久化设置是：PERSISTENCE_HNSW_MAX_LOG_SIZE（默认值500MiB）。该配置项设置的是预写日志的轮转大小，与快照无关，且仍然有效。

- 概念：存储 - HNSW快照

- 环境变量：PERSISTENCE_HNSW_MAX_LOG_SIZE

## 性能改进与修复 ​

除主要特性外，v1.39版本还包含大量改进。其中几个值得关注：

- 更快的关键词搜索：经过评分路径优化后，bm25查询和混合搜索中的关键词部分响应速度显著提升。

- 跨属性关键词AND：新的AndCross搜索操作符要求每个查询词必须出现在对象的某个位置，而非全部出现在单个属性中。该功能在1.38版本中已发布，为可选功能，因此普通And操作仍保持当前行为。

- 更高效的异步复制：在多租户集群中，后台修复操作减少了冗余工作。修复功能现在可以防止首次扫描时删除对象重现、防止修复覆盖更新的本地写入、防止租户关闭时内存泄漏。

- 更轻量的HFresh：HFresh向量索引占用内存更少，磁盘写入频率更低。

- 更可靠的备份：在Azure上列出备份时不再扫描所有对象，恢复操作不再强制加载延迟加载的分片，现在可以设置增量备份去重的文件数量。

- 更安全的副本迁移：节点间迁移副本现在使用硬链接，不再暂停压缩操作。与正在进行的迁移冲突的模式变更会被拒绝，同一分片上的两个复制操作不再相互干扰。

- 毫秒级以下延迟指标：HTTP和gRPC请求持续时间直方图现在包含低至100µs的桶，快速查询不再全部落在单个桶中。

- 批量删除返回422：包含缺失匹配字段的批量删除现在返回422 Unprocessable Entity，而非500错误。

- Weaviate 1.39：GitHub发布说明

## 社区贡献 ​

Weaviate是开源项目，本次发布包含五位首次贡献者的成果。感谢以下贡献者：

- @hashkanna ：为text2vec-google模块添加位置配置（ #8418 ）

- @vjsai ：在分片配置中拒绝负数desiredCount（ #11824 ）

- @Joe-Weaviate ：使用automaxprocs设置GOMAXPROCS，添加cgroup v2支持（ #11918 ）

- @VihaanAgarwal ：修复命名向量集合的对象写入路径（ #11919 ）

- @apoorva-01 ：为包含缺失匹配字段的批量删除返回422（ #12049 ）

如需贡献代码，请查看贡献者指南和GitHub上的good-first-issue标签。

## 总结 ​

Weaviate v1.39将两项搜索功能提升为通用可用，预览第三项功能，并实现HNSW快照自动化。

主要亮点：

- 提升API（GA）：跨混合、关键词和向量搜索的查询时重新评分，可提升或降低结果排名而不丢失任何结果

- MMR多样性选择（GA）：在混合和near_*搜索中实现多样性选择，使第一页结果覆盖主题而非重复内容