向量索引

Vector indexes 促进高效、向量优先的数据存储和检索。支持三种向量索引类型

• HNSW index
• Flat index
• Dynamic index

Index configuration parameters

实验特性

从 v1.25 开始可用。动态索引是一个实验性特性。请谨慎使用。

使用这些参数配置索引类型及其属性。它们可以在 collection configuration 中设置。

参数	类型	默认值	Details
vectorIndexType	字符串	hnsw	Optional. 索引类型 - 可以是 hnsw、flat 或 dynamic。
vectorIndexConfig	object	-	Optional. 设置特定于向量索引类型的参数。

如何选择索引类型

通常，建议在大多数用例中使用 hnsw 索引类型。对于数据量少的用例，例如多租户用例，建议使用 flat 索引类型。您还可以选择 dynamic 索引，它最初会配置一个 flat 索引，一旦对象数量超过指定阈值，它将自动转换为 hnsw 索引。

有关不同索引类型以及如何选择它们的更多信息，请参阅 this section。

如果需要更快的导入速度，asynchronous indexing 允许将索引与对象创建解耦。

HNSW index

HNSW 索引具有可扩展性和查询时的超快速度，但在索引构建过程中添加数据时，HNSW 算法的成本很高。

HNSW index parameters

一些 HNSW 参数是可变的，但其他参数在创建集合后无法修改。

参数	类型	描述	默认值	Mutable
cleanupIntervalSeconds	整数	清理频率。通常不需要调整此值。较高的值意味着清理运行的频率较低，但每次运行处理的数据量更多。较低的值意味着清理更频繁，但每次运行的效率可能较低。	300	是
distance	字符串	距离度量。衡量两个任意向量之间距离的度量标准。有关可用距离度量，请参阅 supported distance metrics。	cosine	否
ef	整数	平衡搜索速度和召回率。ef 是 HNSW 在搜索期间使用的动态列表的大小。当 ef 较高时，搜索更准确，但速度也较慢。ef 值大于 512 对召回率的改进 diminishing。 动态 ef。当 ef 设置为 -1 时，Weaviate 会自动调整 ef 值并创建一个动态 ef 列表。有关详细信息，请参阅 dynamic ef。	-1	是
efConstruction	整数	平衡索引搜索速度和构建速度。较高的 efConstruction 值意味着您可以降低 ef 设置，但导入速度较慢。 efConstruction 必须大于 0。	128	否
HNSWGeoIndexEF	整数	平衡地理索引搜索速度和召回率。此值控制基于地理位置的查询的搜索深度。	800	是
maxConnections	整数	每个元素的最大连接数。maxConnections 是高于零层各层的每层连接限制。零层可以有 (2 * maxConnections) 个连接。 maxConnections 必须大于 0。	32	否
dynamicEfMin	整数	用于 dynamic ef 的下限。防止创建过短的搜索列表。 仅当 ef 为 -1 时才使用此设置。	100	是
dynamicEfMax	整数	用于 dynamic ef 的上限。防止创建过长的搜索列表。 如果 dynamicEfMax 高于限制，则 dynamicEfMax 不起作用。在这种情况下，ef 是限制。 仅当 ef 为 -1 时才使用此设置。	500	是
dynamicEfFactor	整数	用于 dynamic ef 的乘数。设置搜索列表的潜在长度。 仅当 ef 为 -1 时才使用此设置。	8	是
filterStrategy	字符串	用于过滤搜索结果的过滤策略。过滤策略可以设置为 acorn（从 v1.34 开始的默认值）或 sweeping。	acorn	是
flatSearchCutoff	整数	Optional. 用于 flat-search cutoff 的阈值。要强制向量索引搜索，请设置 "flatSearchCutoff": 0。	40000	是
skip	boolean	如果为 true，则不索引集合。 Weaviate 将向量创建和向量存储解耦。如果您跳过向量索引，但配置了向量化器（或手动提供了向量），Weaviate 会在每次导入时记录警告。 要跳过索引和向量生成，请在设置 "skip": true 时设置 "vectorizer": "none"。 参阅 When to skip indexing。	false	否
vectorCacheMaxObjects	整数	内存缓存中对象的最大数量。默认情况下，当创建新集合时，此限制设置为一万亿 (1e12) 个对象。有关大小建议，请参阅 Vector cache considerations。	1e12	是
rq	object	启用并配置 rotational quantization (RQ) 压缩。 有关 RQ 配置详细信息，请参阅 RQ configuration parameters。	--	是
pq	object	启用并配置 product quantization (PQ) 压缩。 PQ 假定已经加载了一些数据。在启用 PQ 之前，您应该加载每个分片 10,000 到 100,000 个向量。 有关 PQ 配置详细信息，请参阅 PQ configuration parameters。	--	是
bq	object	启用并配置 binary quantization (BQ) 压缩。 有关 BQ 配置详细信息，请参阅 BQ configuration parameters。	--	是
sq	object	启用并配置 product quantization (SQ) 压缩。 有关 SQ 配置详细信息，请参阅 SQ configuration parameters。	--	是

HNSW 的数据库参数

请注意，一些数据库级别参数可用于配置 HNSW 索引行为。

• PERSISTENCE_HNSW_MAX_LOG_SIZE 是数据库级别参数，用于设置 HNSW 写前日志的最大大小。默认值为 500MiB。

  增加此值可以提高压缩过程的效率，但请注意，这将增加数据库的内存使用量。相反，减小此值将减少内存使用量，但可能会减慢压缩过程。

  优选地，PERSISTENCE_HNSW_MAX_LOG_SIZE 应设置为接近 HNSW 图大小的值。

• DEFAULT_QUANTIZATION 是数据库级别参数，用于定义创建新集合时将使用的默认量化技术。

Tombstone cleanup parameters

环境变量可用性

• TOMBSTONE_DELETION_CONCURRENCY 在 v1.24.0 及更高版本中可用。
• TOMBSTONE_DELETION_MIN_PER_CYCLE 和 TOMBSTONE_DELETION_MAX_PER_CYCLE 在 v1.24.15 / v1.25.2 及更高版本中可用。

Tombstones 是标记已删除对象的记录。在 HNSW 索引中，Tombstones 会定期清理，由 cleanupIntervalSeconds 参数定期触发。

随着索引大小的增长，清理过程可能需要更长的时间才能完成，并需要更多资源。对于非常大的索引，这可能会导致性能问题。

为了控制每个清理周期删除的 Tombstones 数量并防止性能问题，请设置 TOMBSTONE_DELETION_MAX_PER_CYCLE 和 TOMBSTONE_DELETION_MIN_PER_CYCLE 环境变量。

• 设置 TOMBSTONE_DELETION_MIN_PER_CYCLE 以防止不必要的清理周期发生。
• 设置 TOMBSTONE_DELETION_MAX_PER_CYCLE 以防止清理过程花费过长时间并消耗过多资源。

例如，对于每个分片有 3 亿个对象的集群，TOMBSTONE_DELETION_MIN_PER_CYCLE 值为 1000000（100 万）和 TOMBSTONE_DELETION_MAX_PER_CYCLE 值为 10000000（1000 万）可能是很好的起点。

您还可以设置 TOMBSTONE_DELETION_CONCURRENCY 环境变量来限制用于墓碑清理的线程数量。这可以帮助防止清理过程不必要地消耗过多资源，或者清理过程花费过长时间。

TOMBSTONE_DELETION_CONCURRENCY 的默认值设置为 Weaviate 可用 CPU 核心数量的一半。

在具有大量核心的集群中，您可能希望将 TOMBSTONE_DELETION_CONCURRENCY 设置为较低的值，以防止清理过程消耗过多资源。相反，在具有少量核心和大量删除的集群中，您可能希望将 TOMBSTONE_DELETION_CONCURRENCY 设置为较高的值，以加快清理过程。

HNSW 配置技巧

要确定适合您用例的合理设置，请考虑以下问题，并在下表中比较您的答案

1. 您预计每秒有多少查询？
2. 您预计有多少导入或更新？
3. 召回率应该有多高？

查询数量	大量导入或更新	召回率水平	配置建议
不多	没有	低	这是理想的情况。将 ef 和 efConstruction 设置都保持较低。您不需要一台大型机器，并且仍然会对结果感到满意。
不多	没有	高	棘手之处在于您的召回率需要很高。由于您预计没有大量的请求或导入，您可以增加 ef 和 efConstruction 设置。继续增加它们，直到您对召回率感到满意。在这种情况下，您可以非常接近 100%。
不多	是	低	棘手之处在于大量的导入和更新。请确保将 efConstruction 保持较低。由于您不需要高召回率，并且预计没有大量的查询，您可以调整 ef 设置，直到达到所需的召回率。
不多	是	高	权衡变得更加困难。您需要高召回率并且处理大量的导入或更新。这意味着您需要将 efConstruction 设置保持较低，但您可以显著增加 ef 设置，因为您的每秒查询速率较低。
很多	没有	低	每秒大量的查询意味着您需要较低的 ef 设置。幸运的是，您不需要高召回率，因此您可以显著增加 efConstruction 值。
很多	没有	高	每秒大量的查询意味着较低的 ef 设置。由于您需要高召回率，但预计没有大量的导入或更新，您可以增加 efConstruction，直到达到所需的召回率。
很多	是	低	每秒大量的查询意味着您需要较低的 ef 设置。大量的导入和更新也意味着您需要较低的 efConstruction 设置。幸运的是，您的召回率不必尽可能接近 100%。您可以将 efConstruction 设置为相对较低的值以支持您的输入或更新吞吐量，并且可以使用 ef 设置来调节每秒查询速度。
很多	是	高	啊哈，这意味着您是完美主义者或者您有一个用例需要兼顾所有三个方面的优势。增加您的 efConstruction 值，直到达到导入和更新的时间限制。接下来，增加您的 ef 设置，直到达到每秒查询速度与召回率之间的期望平衡。 虽然许多人认为他们需要最大化所有三个维度，但在实践中通常并非如此。我们让您自己决定，并且您可以随时在我们的论坛上寻求帮助。

提示

这组值是许多用例的良好起点。

参数	值
ef	64
efConstruction	128
maxConnections	32

Flat 索引

在 v1.23 中添加

Flat 索引建议用于每个索引的对象数量较少的用例，例如多租户用例。

参数	类型	默认值	可更改	Details
vectorCacheMaxObjects	整数	1e12	是	内存缓存中对象的最大数量。默认情况下，当创建新集合时，此限制设置为一万亿 (1e12) 个对象。有关大小建议，请参阅 Vector cache considerations。
bq	object	--	否	启用并配置 二元量化 (BQ) 压缩。 有关 BQ 配置详细信息，请参阅 BQ configuration parameters。

动态索引

实验特性

从 v1.25 开始可用。动态索引是一个实验性特性。请谨慎使用。

动态索引需要 ASYNC_INDEXING

动态索引需要异步索引。要在自托管的 Weaviate 实例中启用异步索引，请将 ASYNC_INDEXING 环境变量 设置为 true。如果您的实例托管在 Weaviate Cloud 中，请使用 Weaviate Cloud 控制台启用异步索引。

使用 dynamic 索引最初会创建一个 Flat 索引，一旦对象数量超过某个阈值（默认情况下为 10,000 个对象），它将自动切换到 HNSW 索引。

这是一个单向切换，将 Flat 索引转换为 HNSW，即使对象数量由于删除而低于阈值，索引也不支持切换回 Flat 索引。

dynamic 索引的目标是在查询时间缩短延迟，以牺牲更大的内存占用为代价。

动态索引参数

参数	类型	默认值	Details
distance	字符串	cosine	距离度量。衡量两个任意向量之间距离的度量标准。
hnsw	object	默认 HNSW	HNSW 索引配置 将被使用。
flat	object	默认 Flat	Flat 索引配置 将被使用。
阈值	整数	10000	发生 flat 到 hnsw 转换的对象数量阈值

量化参数

RQ 参数

以下参数适用于 RQ 压缩，位于 vectorIndexConfig 下

参数	类型	默认值	Details
rq: bits	整数	8	用于量化每个数据点的位数。值可以是 8 或 1。 了解更多关于 8 位 和 1 位 RQ。
rq: rescoreLimit	整数	-1	在重新评分之前要获取的最小候选者数量。
rq : cache	boolean	false	是否将向量缓存到内存中。 (仅在使用 flat 向量索引类型时)
vectorCacheMaxObjects	整数	1e12	内存缓存中对象的最大数量。默认情况下，当创建新集合时，此限制设置为一万亿 (1e12) 个对象。有关大小建议，请参阅 Vector cache considerations。

SQ 参数

以下参数适用于 SQ 压缩，位于 vectorIndexConfig 下

参数	类型	默认值	Details
sq: enabled	boolean	false	当 true 时，使用 SQ。 Python 客户端不使用 enabled 参数。要在 v4 客户端中启用 SQ，请在集合定义中设置 quantizer。
sq: rescoreLimit	整数	-1	在重新评分之前要获取的最小候选者数量。
sq: trainingLimit	整数	100000	确定标量桶边界的训练集大小。
vectorCacheMaxObjects	整数	1e12	内存缓存中对象的最大数量。默认情况下，当创建新集合时，此限制设置为一万亿 (1e12) 个对象。有关大小建议，请参阅 Vector cache considerations。

PQ 参数

以下参数适用于 PQ 压缩，位于 vectorIndexConfig 下

参数	类型	默认值	Details
enabled	boolean	false	当 true 时，启用 PQ。 Python v4 客户端不使用 enabled 参数。要在 v4 客户端中启用 PQ，请在集合定义中设置 quantizer。
trainingLimit	整数	100000	用于拟合质心的每个分片的最大对象数量。较大的值会增加拟合质心所需的时间。较大的值也需要更多的内存。
segments	整数	--	要使用的分段数。向量维数必须可被分段数整除。 从 v1.23 开始，Weaviate 使用维度数来优化分段数。
centroids	整数	256	要使用的质心数（最大值：256）。 我们通常建议您不要更改此值。 由于使用的数据结构，较小的质心值不会导致较小的向量，但可能会以牺牲召回率为代价来提高压缩速度。
encoder	字符串	kmeans	编码器规范。有两种编码器。您可以将编码器 type 指定为 kmeans（默认值）或 tile。
distribution	字符串	log-normal	编码器分布类型。仅与 tile 编码器一起使用。如果您使用 tile 编码器，您可以将 distribution 指定为 log-normal（默认值）或 normal。

BQ 参数

以下参数适用于 BQ 压缩，位于 vectorIndexConfig 下

参数	类型	默认值	Details
bq : enabled	boolean	false	启用 BQ。当 true 时，Weaviate 使用二元量化 (BQ) 压缩。 Python 客户端不使用 enabled 参数。要在 v4 客户端中启用 BQ，请在集合定义中设置 quantizer。
bq : rescoreLimit	整数	-1	在重新评分之前要获取的最小候选者数量。
bq : cache	boolean	false	是否将向量缓存到内存中。 (仅在使用 flat 向量索引类型时)
vectorCacheMaxObjects	整数	1e12	内存缓存中对象的最大数量。默认情况下，当创建新集合时，此限制设置为一万亿 (1e12) 个对象。有关大小建议，请参阅 Vector cache considerations。

新集合的默认量化

在 v1.33 中添加

从 Weaviate v1.33 开始，您可以设置一个量化方法，该方法将默认启用所有新的集合**。现有集合（例如从备份恢复的集合）不受影响，并保留其原始配置。

在启动 Weaviate 之前，设置 DEFAULT_QUANTIZATION 环境变量 以更改默认量化技术或禁用它。

配置语义索引

Weaviate 可以使用 模型提供商集成 为对象生成向量嵌入。

例如，文本嵌入集成（例如，Cohere 的 text2vec-cohere，或 Ollama 的 text2vec-ollama）可以从文本对象生成向量。Weaviate 遵循集合配置和一组预定义的规则来向量化对象。

除非在集合定义中另有说明，否则默认行为是

• 仅向量化使用 text 或 text[] 数据类型的属性（除非 跳过）
• 在连接值之前，按字母顺序 (a-z) 对属性进行排序
• 如果 vectorizePropertyName 为 true (默认值为 false)，则将属性名称前缀添加到每个属性值
• 用空格连接（前缀）属性值
• 前缀类名（除非 vectorizeClassName 为 false）
• 将生成的字符串转换为小写

例如，这个数据对象，

Article = {
  summary: "Cows lose their jobs as milk prices drop",
  text: "As his 100 diary cows lumbered over for their Monday...",
};

将被向量化为

article cows lose their jobs as milk prices drop as his 100 diary cows lumbered over for their monday...

默认情况下，计算包括集合名称和所有属性值，但不索引属性名称。

要以每个集合为基础配置向量化行为，请使用 vectorizeClassName。

要以每个属性为基础配置向量化，请使用 skip 和 vectorizePropertyName。

异步索引

要启用异步索引，请在您的 Weaviate 配置中（如果您使用 Docker Compose，则是在 docker-compose.yml 文件中）将 ASYNC_INDEXING 环境变量设置为 true。此设置将为所有集合启用异步索引。

示例 Docker Compose 配置

---
services:
  weaviate:
    command:
      - --host
      - 0.0.0.0
      - --port
      - "8080"
      - --scheme
      - http
    image: cr.weaviate.io/semitechnologies/weaviate:1.35.3
    restart: on-failure:0
    ports:
      - 8080:8080
      - 50051:50051
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      QUERY_MAXIMUM_RESULTS: 10000
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true"
      PERSISTENCE_DATA_PATH: "/var/lib/weaviate"
      CLUSTER_HOSTNAME: "node1"
      AUTOSCHEMA_ENABLED: "false"
      ASYNC_INDEXING: "true"

要获取索引状态，请检查 节点状态 端点。

节点状态 示例用法

nodes/shards/vectorQueueLength 字段显示仍需索引的对象数量。

PythonJavaScript/TypeScriptGoJava v6Java v5 (已弃用)Curl

  API 文档

更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。

import weaviate

client = weaviate.connect_to_local()

nodes_info = client.cluster.nodes(
    collection="JeopardyQuestion",  # If omitted, all collections will be returned
    output="verbose",  #  If omitted, will be "minimal"
)
print(nodes_info)

client.close()

import weaviate from 'weaviate-client';

const client = await weaviate.connectToLocal()

const response = await client.cluster.nodes({
  collection: 'JeopardyQuestion',
  output: 'minimal'
})

console.log(response)

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  nodesStatus, err := client.Cluster().
    NodesStatusGetter().
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", nodesStatus)
}

WeaviateClient client = WeaviateClient
    .connectToLocal(config -> config.host("127.0.0.1").port(8080));

System.out.println(client.cluster.listNodes()); // all
System.out
    .println(client.cluster.listNodes(n -> n.collection("MyCollection")
        .shard("MyShard")
        .verbosity(NodeVerbosity.MINIMAL)));

client.close(); // Free up resources
WeaviateClient client = WeaviateClient.connectToLocal();

System.out.println(client.meta()); // all

client.close(); // Free up resources

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.cluster.model.NodesStatusResponse;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<NodesStatusResponse> result = client.cluster()
      .nodesStatusGetter()
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

curl https://:8080/v1/nodes

然后，您可以检查输出以查看向量索引队列的状态。

vectorQueueLength 字段将显示剩余要索引的对象数量。在下面的示例中，向量索引队列在 TestArticle 分片上仍有 425 个对象需要索引，总共 1000 个对象。

{
  "nodes": [
    {
      "batchStats": {
        "ratePerSecond": 0
      },
      "gitHash": "e6b37ce",
      "name": "weaviate-0",
      "shards": [
        {
          "class": "TestArticle",
          "name": "nq1Bg9Q5lxxP",
          "objectCount": 1000,
          "vectorIndexingStatus": "INDEXING",
          "vectorQueueLength": 425
        }
      ],
      "stats": {
        "objectCount": 1000,
        "shardCount": 1
      },
      "status": "HEALTHY",
      "version": "1.22.1"
    }
  ]
}

多个向量嵌入（命名向量）

于 v1.24.0 中添加

Weaviate 集合支持多个命名向量。

集合可以有多个 命名向量。

集合中的向量可以有自己的配置。每个向量空间可以设置自己的索引、自己的压缩算法和自己的向量化器。这意味着您可以对同一个对象使用不同的向量化模型，并应用不同的距离度量。

要使用命名向量，请调整您的查询以指定 向量搜索 或 混合搜索 查询的目标向量。

更多资源

• 概念：向量索引
• 操作指南：配置集合

问题和反馈

如果您有任何问题或反馈，请在 用户论坛 中告诉我们。

技术问题

如果您有任何问题，请在我们的 社区论坛 上发帖。

文档反馈

通过打开 GitHub issue 提供反馈。