集合定义 (schemas)

本教程将指导您定义数据的 schema 的过程，包括常用设置和关键注意事项。

先决条件

• (推荐) 完成 快速入门教程。
• 具有管理员 API 密钥的 Weaviate 实例。
• 安装您首选的 Weaviate 客户端库。

集合定义：简介

集合定义指定了 Weaviate 中数据的存储、组织和检索方式。

如果启用了 自动 schema，Weaviate 可以推断缺失的元素并将其添加到集合定义中。但是，手动定义尽可能多的数据 schema 是最佳实践，因为手动定义可以为您提供最大的控制权。

让我们从一个简单的示例开始，然后再深入了解细节。

基本集合创建

此示例创建一个名为 Question 的集合。该集合具有三个属性，answer、question 和 category。该定义指定了 text2vec-openai 向量化器和 generative-cohere 模块用于 RAG。

PythonJava v6C#

  API 文档

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

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

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
    headers={
        "X-OpenAI-Api-Key": os.environ["OPENAI_APIKEY"]  # Replace with your inference API key
    }
)

try:
    questions = client.collections.create(
        name="Question",
        vector_config=wvc.config.Configure.Vectors.text2vec_openai(),    # Set the vectorizer to "text2vec-openai" to use the OpenAI API for vector-related operations
        generative_config=wvc.config.Configure.Generative.cohere(),             # Set the generative module to "generative-cohere" to use the Cohere API for RAG
        properties=[
            wvc.config.Property(
                name="question",
                data_type=wvc.config.DataType.TEXT,
            ),
            wvc.config.Property(
                name="answer",
                data_type=wvc.config.DataType.TEXT,
            ),
            wvc.config.Property(
                name="category",
                data_type=wvc.config.DataType.TEXT,
            )
        ]
    )

    print(questions.config.get(simple=False))

finally:
    client.close()

String openaiApiKey = System.getenv("OPENAI_APIKEY");
client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-OpenAI-Api-Key", openaiApiKey)));

Optional<CollectionConfig> questionsConfig =
    client.collections.create("Question",
        col -> col.vectorConfig(VectorConfig.text2vecWeaviate()) // Set the vectorizer to use the OpenAI API for vector-related operations
            .generativeModule(Generative.cohere()) // Set the generative module to use the Cohere API for RAG
            .properties(Property.text("question"), Property.text("answer"),
                Property.text("category"))).config.get();

System.out.println(questionsConfig);

client = await Connect.Local();
var questionsCollection = await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Question",
        VectorConfig = Configure.Vector("default", v => v.Text2VecWeaviate()),
        GenerativeConfig = Configure.Generative.Cohere(), // Set the generative module
        Properties =
        [
            Property.Text("question"),
            Property.Text("answer"),
            Property.Text("category"),
        ],
    }
);

Console.WriteLine(questionsCollection);

返回的配置如下所示

查看返回的集合定义

{
  "classes": [
    {
      "class": "Question",
      "description": "Information from a Jeopardy! question",
      "invertedIndexConfig": {
        "bm25": {
          "b": 0.75,
          "k1": 1.2
        },
        "cleanupIntervalSeconds": 60,
        "stopwords": {
          "additions": null,
          "preset": "en",
          "removals": null
        }
      },
      "moduleConfig": {
        "text2vec-openai": {
          "model": "ada",
          "modelVersion": "002",
          "type": "text",
          "vectorizeClassName": true
        }
      },
      "properties": [
        {
          "dataType": ["text"],
          "description": "The question",
          "moduleConfig": {
            "text2vec-openai": {
              "skip": false,
              "vectorizePropertyName": false
            }
          },
          "name": "question",
          "tokenization": "word"
        },
        {
          "dataType": ["text"],
          "description": "The answer",
          "moduleConfig": {
            "text2vec-openai": {
              "skip": false,
              "vectorizePropertyName": false
            }
          },
          "name": "answer",
          "tokenization": "word"
        },
        {
          "dataType": ["text"],
          "description": "The category",
          "moduleConfig": {
            "text2vec-openai": {
              "skip": false,
              "vectorizePropertyName": false
            }
          },
          "name": "category",
          "tokenization": "word"
        }
      ],
      "replicationConfig": {
        "factor": 1
      },
      "shardingConfig": {
        "virtualPerPhysical": 128,
        "desiredCount": 1,
        "actualCount": 1,
        "desiredVirtualCount": 128,
        "actualVirtualCount": 128,
        "key": "_id",
        "strategy": "hash",
        "function": "murmur3"
      },
      "vectorIndexConfig": {
        "skip": false,
        "cleanupIntervalSeconds": 300,
        "maxConnections": 32,
        "efConstruction": 128,
        "ef": -1,
        "dynamicEfMin": 100,
        "dynamicEfMax": 500,
        "dynamicEfFactor": 8,
        "vectorCacheMaxObjects": 1000000000000,
        "flatSearchCutoff": 40000,
        "distance": "cosine"
      },
      "vectorIndexType": "hnsw",
      "vectorizer": "text2vec-openai"
    }
  ]
}

虽然我们只指定了集合名称和属性，但返回的定义包含更多信息。

这是因为 Weaviate 基于数据 schema 和默认设置推断定义。这些选项中的每一个都可以在集合创建时手动指定。

常见问题：集合定义是否可变？

是的，在一定程度上。对于添加新集合或属性没有限制。但是，并非所有设置都可以在现有集合中修改。例如，您无法更改向量化器或生成模块。您可以在 集合定义参考 中了解更多信息。

集合定义详解

从概念上讲，将每个 Weaviate 实例视为由多个集合组成可能是有用的，每个集合都是共享通用结构的对象的集合。

例如，您可能有一个电影数据库，其中包含 Movie 和 Actor 集合，每个集合都有自己的属性。或者，您可能有一个新闻数据库，其中包含 Article、Author 和 Publication 集合。

可用设置

对于大多数情况，每个集合都应被视为与其他集合隔离的（事实上，它们是隔离的！）。因此，它们可以独立配置。每个集合都有

• 一组 properties，用于指定对象数据结构。
• 多租户设置。
• 向量化器和生成模块。
• 索引设置（用于向量索引和倒排索引）。
• 复制和分片设置。

根据您的需求，您可能需要更改其中任何一个。

属性

每个属性都有许多可以配置的设置，例如 dataType、tokenization 和 vectorizePropertyName。您可以在 集合定义参考 中了解更多信息。

因此，例如，您可能会指定如下集合定义，并为 question 和 answer 属性添加其他选项

PythonJava v6C#JavaScript/TypeScript

  API 文档

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

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

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
    headers={
        "X-OpenAI-Api-Key": os.environ["OPENAI_APIKEY"]  # Replace with your inference API key
    }
)

try:
    questions = client.collections.create(
        name="Question",
        vector_config=wvc.config.Configure.Vectors.text2vec_openai(),    # Set the vectorizer to "text2vec-openai" to use the OpenAI API for vector-related operations
        generative_config=wvc.config.Configure.Generative.cohere(),             # Set the generative module to "generative-cohere" to use the Cohere API for RAG
        properties=[
            wvc.config.Property(
                name="question",
                data_type=wvc.config.DataType.TEXT,
                vectorize_property_name=True,  # Include the property name ("question") when vectorizing
                tokenization=wvc.config.Tokenization.LOWERCASE  # Use "lowecase" tokenization
            ),
            wvc.config.Property(
                name="answer",
                data_type=wvc.config.DataType.TEXT,
                vectorize_property_name=False,  # Skip the property name ("answer") when vectorizing
                tokenization=wvc.config.Tokenization.WHITESPACE  # Use "whitespace" tokenization
            ),
        ]
    )

finally:
    client.close()

String openaiApiKey = System.getenv("OPENAI_APIKEY");
client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-OpenAI-Api-Key", openaiApiKey)));

client.collections.create("Question",
    col -> col.vectorConfig(VectorConfig.text2vecWeaviate())
        .generativeModule(Generative.cohere())
        .properties(Property.text("question", p -> p
            .vectorizePropertyName(true) // Include the property name ("question") when vectorizing
            .tokenization(Tokenization.LOWERCASE) // Use "lowercase" tokenization
        ), Property.text("answer", p -> p
            .vectorizePropertyName(false) // Skip the property name ("answer") when vectorizing
            .tokenization(Tokenization.WHITESPACE) // Use "whitespace" tokenization
        )));

client = await Connect.Local();
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Question",
        VectorConfig = Configure.Vector("default", v => v.Text2VecWeaviate()),
        GenerativeConfig = Configure.Generative.Cohere(),
        Properties =
        [
            Property.Text("question", tokenization: PropertyTokenization.Lowercase),
            Property.Text("answer", tokenization: PropertyTokenization.Whitespace),
        ],
    }
);

import weaviate from 'weaviate-client';

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  'WEAVIATE_INSTANCE_URL', { // Replace WEAVIATE_INSTANCE_URL with your instance URL
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'),
  }
)

// Define the 'Question' collection
const collectionObj = {
  name: 'Question',
  properties: [
    {
      name: 'question',
      dataType: 'text' as const,
      description: 'Category of the question' as const,
      tokenization: 'lowercase' as const,
      vectorizePropertyName: true,

    },
    {
      name: 'answer',
      dataType: 'text' as const,
      description: 'The question',
      tokenization: 'whitespace' as const,
      vectorizePropertyName: false,
    }
  ],
  vectorizers: weaviate.configure.vectorizer.text2VecOpenAI(),
  generative: weaviate.configure.generative.openAI()
}

// Add the class to the schema
const newCollection = await client.collections.create(collectionObj)

交叉引用

交叉引用和查询性能

涉及交叉引用的查询可能比不涉及交叉引用的查询慢，尤其是在大规模情况下，例如对于多个对象或复杂查询。

首先，我们强烈建议您考虑是否可以避免在数据模式中使用交叉引用。作为可扩展的 AI 数据库，Weaviate 擅长使用向量、关键词和混合搜索进行复杂查询，包括过滤器。您可以通过重新思考数据模式来避免交叉引用，从而受益匪浅。

例如，与其创建带有交叉引用的单独的“作者”和“书籍”集合，不如考虑将作者信息直接嵌入到书籍对象中，并使用搜索和过滤器按作者特征查找书籍。

您还可以在此处指定交叉引用，这是一种特殊的属性类型，用于链接到另一个集合。

交叉引用对于在对象之间创建关系非常有用。例如，您可能有一个 Movie 集合，其中包含一个指向 Actor 集合的 withActor 交叉引用属性。这将允许您检索每部电影的相关演员。

但是，交叉引用在性能方面可能代价高昂。谨慎使用它们。此外，交叉引用属性不会影响对象的向量。因此，如果您希望相关属性在向量搜索中被考虑，它们应包含在对象的向量化属性中。

您可以在 此处 找到有关如何定义和使用交叉引用的示例。

向量化器和生成模块

可以为每个集合配置向量化器和生成模块。向量化器用于为每个对象以及任何未向量化的查询生成向量，而生成模块用于执行检索增强生成 (RAG) 查询。

如果您不确定从哪里开始，与流行的基于 API 的模型提供商（如 Cohere 或 OpenAI）集成的模块是很好的起点。您可以在 此处 找到可用的模型集成列表。

多租户设置

从 v1.20.0 版本开始，可以配置每个集合作为多租户集合。这允许在租户（通常是最终用户）之间以比为每个租户创建单独集合更低的开销来分离数据。

如果您想将 Weaviate 用作多租户（例如 SaaS）应用程序的后端，或者出于任何其他原因需要数据隔离，这将非常有用。

有多少集合太多了？

要了解有关与为每个租户创建单独集合相比，多租户的性能优势，请访问 本指南。

PythonJava v6C#JavaScript/TypeScript

  API 文档

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

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

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
    headers={
        "X-OpenAI-Api-Key": os.environ["OPENAI_APIKEY"]  # Replace with your inference API key
    }
)

try:
    questions = client.collections.create(
        name="Question",
        vector_config=wvc.config.Configure.Vectors.text2vec_openai(),    # Set the vectorizer to "text2vec-openai" to use the OpenAI API for vector-related operations
        generative_config=wvc.config.Configure.Generative.cohere(),             # Set the generative module to "generative-cohere" to use the Cohere API for RAG
        properties=[
            wvc.config.Property(
                name="question",
                data_type=wvc.config.DataType.TEXT,
            ),
            wvc.config.Property(
                name="answer",
                data_type=wvc.config.DataType.TEXT,
            ),
        ],
        multi_tenancy_config=wvc.config.Configure.multi_tenancy(enabled=True),  # Enable multi-tenancy
    )

finally:
    client.close()

String openaiApiKey = System.getenv("OPENAI_APIKEY");
client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-OpenAI-Api-Key", openaiApiKey)));

client.collections.create("Question",
    col -> col.vectorConfig(VectorConfig.text2vecWeaviate())
        .generativeModule(Generative.cohere())
        .properties(Property.text("question"), Property.text("answer"))
        .multiTenancy(c -> c.autoTenantCreation(true)) // Enable multi-tenancy
);

client = await Connect.Local();
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Question",
        VectorConfig = Configure.Vector("default", v => v.Text2VecWeaviate()),
        GenerativeConfig = Configure.Generative.Cohere(),
        Properties = [Property.Text("question"), Property.Text("answer")],
        MultiTenancyConfig = new MultiTenancyConfig
        {
            Enabled = true,
            AutoTenantCreation = true,
        }, // Enable multi-tenancy
    }
);

import weaviate from 'weaviate-client';

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  'WEAVIATE_INSTANCE_URL', { // Replace WEAVIATE_INSTANCE_URL with your instance URL
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'),
  }
)

// Define the 'Question' class
const collectionObj = {
  name: 'Question',
  properties: [
    {
      name: 'question',
      dataType: 'text' as const,
      description: 'Category of the question',
      tokenization: 'lowercase' as const,
      vectorizePropertyName: true,

    },
    {
      name: 'answer',
      dataType: 'text' as const,
      description: 'The question',
      tokenization: 'whitespace' as const,
      vectorizePropertyName: false,
    }
  ],
  vectorizers: weaviate.configure.vectorizer.text2VecOpenAI(),
  generative: weaviate.configure.generative.openAI(),
  multiTenancy: weaviate.configure.multiTenancy({enabled: true})
}

// Add the class to the schema
const newCollection = await client.collections.create(collectionObj)

索引设置

Weaviate 使用两种类型的索引：向量索引 和 倒排索引。向量索引用于存储和组织向量，以便进行快速的基于向量相似性的搜索。倒排索引用于存储数据，以便进行快速的过滤和关键字搜索。

默认向量索引类型是 HNSW。其他选项是 flat，它适用于小型集合，例如多租户集合中的集合，或者 dynamic，它从 flat 索引开始，如果其大小超过预定阈值，则切换到 HNSW 索引。

PythonJava v6C#JavaScript/TypeScript

  API 文档

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

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

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
    headers={
        "X-OpenAI-Api-Key": os.environ["OPENAI_APIKEY"]  # Replace with your inference API key
    }
)

try:
    questions = client.collections.create(
        name="Question",
        vector_config=wvc.config.Configure.Vectors.text2vec_openai(
            name="default",  # Set the name of the vector configuration
            # Configure the vector index
            vector_index_config=wvc.config.Configure.VectorIndex.hnsw(  # Or `flat` or `dynamic`
                distance_metric=wvc.config.VectorDistances.COSINE,
                quantizer=wvc.config.Configure.VectorIndex.Quantizer.bq(),
            ),
        ),    # Set the vectorizer to "text2vec-openai" to use the OpenAI API for vector-related operations
        generative_config=wvc.config.Configure.Generative.cohere(),             # Set the generative module to "generative-cohere" to use the Cohere API for RAG
        properties=[
            wvc.config.Property(
                name="question",
                data_type=wvc.config.DataType.TEXT,
            ),
            wvc.config.Property(
                name="answer",
                data_type=wvc.config.DataType.TEXT,
            ),
        ],
        # Configure the inverted index
        inverted_index_config=wvc.config.Configure.inverted_index(
            index_null_state=True,
            index_property_length=True,
            index_timestamps=True,
        ),
    )

finally:
    client.close()

String openaiApiKey = System.getenv("OPENAI_APIKEY");
client = WeaviateClient.connectToLocal(
    config -> config.setHeaders(Map.of("X-OpenAI-Api-Key", openaiApiKey)));

client.collections.create("Question",
    col -> col.vectorConfig(VectorConfig.text2vecWeaviate("default", // Set the name of the vector configuration
        vc -> vc
            .vectorIndex(Hnsw.of(hnsw -> hnsw.distance(Distance.COSINE))) // Configure the vector index
            .quantization(Quantization.rq()) // Enable vector compression (quantization)
    ))
        .generativeModule(Generative.cohere())
        .properties(Property.text("question"), Property.text("answer"))
        // Configure the inverted index
        .invertedIndex(iic -> iic.indexNulls(true)
            .indexPropertyLength(true)
            .indexTimestamps(true))
);

client = await Connect.Local();
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Question",
        VectorConfig = Configure.Vector(
            "default",
            v => v.Text2VecWeaviate(),
            new VectorIndex.HNSW
            {
                Distance = VectorIndexConfig.VectorDistance.Cosine, // Configure the vector index
                Quantizer = new VectorIndex.Quantizers.BQ(), // Enable vector compression (quantization)
            }
        ),
        GenerativeConfig = Configure.Generative.Cohere(),
        Properties = [Property.Text("question"), Property.Text("answer")],
        // Configure the inverted index
        InvertedIndexConfig = new InvertedIndexConfig
        {
            IndexNullState = true,
            IndexPropertyLength = true,
            IndexTimestamps = true,
        },
    }
);

import weaviate from 'weaviate-client';
import { vectorizer, generative, configure, dataType } from 'weaviate-client';

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  'WEAVIATE_INSTANCE_URL', { // Replace WEAVIATE_INSTANCE_URL with your instance URL
    authCredentials: new weaviate.ApiKey('WEAVIATE_INSTANCE_API_KEY'),
  }
)

// Define the 'Question' class
const collectionObj = {
  name: 'Question',
  properties: [
    {
      name: 'question',
      dataType: 'text' as const,
      description: 'Category of the question',
      tokenization: 'lowercase' as const,
      vectorizePropertyName: true,

    },
    {
      name: 'answer',
      dataType: 'text' as const,
      description: 'The question',
      tokenization: 'whitespace' as const,
      vectorizePropertyName: false,
    }
  ],
  vectorizers: vectorizer.text2VecOpenAI({
    vectorIndexConfig: configure.vectorIndex.hnsw({  // Or `flat` or `dynamic`
      distanceMetric: 'cosine',
      quantizer: configure.vectorIndex.quantizer.bq(),
    })
  }),
  generative: generative.openAI(),
  invertedIndex: configure.invertedIndex({
    indexNullState: true,
    indexPropertyLength: true,
    indexTimestamps: true,
  }),
}

// Add the class to the schema
const newCollection = await client.collections.create(collectionObj)

复制和分片设置

复制

复制设置确定存储数据的副本数量。例如，复制设置 3 表示每个对象存储在 3 个不同的副本上。这对于在生产环境中提供冗余和容错能力非常重要。（默认复制因子为 1。）

这与一致性设置密切相关，它确定在操作被视为成功之前必须响应的副本数量。

我们建议您阅读 有关 Weaviate 中复制工作原理的概念页面。要指定复制因子，请遵循 本操作指南。

分片

分片设置确定每个集合如何分片并在节点之间分布。这通常不是您会更改的设置，但您可以使用它来控制集群中创建多少个分片，以及每个物理分片创建多少个虚拟分片（在此处了解更多信息）。

集合别名

在 v1.32 中添加

集合别名是 Weaviate 集合的替代名称（指针），允许您使用多个名称引用一个集合。当您使用别名进行查询时，Weaviate 会自动将请求路由到目标集合。您可以通过客户端库以编程方式或通过REST 端点设置集合别名。

集合别名的使用

Weaviate 会自动将别名请求路由到目标集合，用于对象相关操作。您可以在任何需要集合名称的地方使用别名，例如：

• 管理对象：通过集合别名创建、批量导入、读取、更新和删除对象。
• 查询对象：通过别名获取对象并执行搜索（向量、关键词、混合、图像、生成式/RAG）和聚合。

备注

集合和属性名称

集合名称始终以大写字母开头。属性始终以小写字母开头。您可以使用 PascalCase 类名，并且属性名称允许使用下划线。更多信息请阅读此处。

更多资源

以下资源包含有关集合定义设置及其使用方法的更详细信息

• 参考：配置 - 集合定义：所有可用集合定义设置的参考。
• 教程：管理集合：创建和管理集合的代码示例，包括如何使用客户端库配置各种设置。
• 参考：REST - Schema：REST API 所有可用集合定义设置的参考。

问题和反馈

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

技术问题

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

文档反馈

通过打开 GitHub issue 提供反馈。