使用 Weaviate Vector Store 连接器（预览版）

2025-05-20

警告

Weaviate Vector Store 功能处于预览状态，需要重大更改的改进可能在发布前的有限情况下发生。

警告

语义内核向量存储功能处于预览状态，可能导致重大变更的改进在发布前的某些情况下仍可能发生。

警告

语义内核向量存储功能处于预览状态，可能导致重大变更的改进在发布前的某些情况下仍可能发生。

概述

Weaviate Vector Store 连接器可用于访问和管理 Weaviate 中的数据。连接器具有以下特征。

功能区域	支持
集合映射到	Weaviate 集合
支持的键属性类型	Guid
支持的数据属性类型	字符串字节 (byte) 短整数 (int) 长双倍漂浮十进制布尔日期时间 DateTimeOffset（日期时间偏移） Guid 及各类型的可枚举对象
支持的向量属性类型	只读内存<float> <嵌入浮点> float[]
支持的索引类型	Hnsw 平面动态
支持的距离函数	CosineDistance 负点积相似度欧几里得平方距离 HammingDistance 曼哈顿距离
支持的过滤器语句	AnyTagEqualTo EqualTo
支持记录中的多个向量	是
是否支持 IsIndexed？	是
是否支持FullTextIndexed？	是
StorageName支持吗？	否，请使用 `JsonSerializerOptions` 和 `JsonPropertyNameAttribute`。有关详细信息，请参阅此处。
支持 HybridSearch？	是

功能区域	支持
集合映射到	Weaviate 集合
支持的键属性类型	Guid
支持的数据属性类型	字符串字节 (byte) 短整数 (int) 长双倍漂浮十进制布尔和这些类型中的每一种的可迭代对象
支持的向量属性类型	list[float] 列表[整数] ndarray
支持的索引类型	Hnsw 平面动态
支持的距离函数	CosineDistance 负点积相似度欧几里得平方距离汉明曼哈顿距离
支持的过滤器语句	AnyTagEqualTo EqualTo
支持记录中的多个向量	是
是否支持Filterable？	是
是否支持FullTextSearchable？	是

即将推出。

限制

值得注意的 Weaviate 连接器功能限制。

功能区域	解决方法
不支持对单个向量对象使用“vector”属性	支持改用“vectors”属性。

警告

Weaviate 要求集合名称以大写字母开头。如果未提供大写字母的集合名称，则尝试创建集合时，Weaviate 将返回错误。您将看到的错误是 Cannot query field "mycollection" on type "GetObjectsObj". Did you mean "Mycollection"?，其中 mycollection 是您的集合名称。在此示例中，如果将集合名称改为 Mycollection，则会修复错误。

入门

将 Weaviate Vector Store 连接器 NuGet 包添加到项目。

dotnet add package Microsoft.SemanticKernel.Connectors.Weaviate --prerelease

可以使用语义内核提供的扩展方法将向量存储添加到可用的 KernelBuilder 依赖项注入容器或 IServiceCollection 依赖项注入容器。 Weaviate 向量存储使用HttpClient与 Weaviate 服务进行通信。有两个选项可用于为 Weaviate 服务提供 URL/终结点。可以通过选项或通过设置该 HttpClient对象的基址来提供它。

第一个示例演示如何通过选项设置服务 URL。请注意，这些方法将从依赖项注入服务提供商中检索一个实例，以调用 Weaviate 服务。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddWeaviateVectorStore(new Uri("http://localhost:8080/v1/"), apiKey: null);

using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddWeaviateVectorStore(new Uri("http://localhost:8080/v1/"), apiKey: null);

提供了一些重载，您可以在其中指定自己的 HttpClient。在这种情况下，可以通过选项设置服务 URL HttpClientBaseAddress 。

using System.Net.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
using HttpClient client = new HttpClient { BaseAddress = new Uri("http://localhost:8080/v1/") };
kernelBuilder.Services.AddWeaviateVectorStore(_ => client);

using System.Net.Http;
using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
using HttpClient client = new HttpClient { BaseAddress = new Uri("http://localhost:8080/v1/") };
builder.Services.AddWeaviateVectorStore(_ => client);

也可以直接构造 Weaviate 矢量存储实例。

using System.Net.Http;
using Microsoft.SemanticKernel.Connectors.Weaviate;

var vectorStore = new WeaviateVectorStore(
    new HttpClient { BaseAddress = new Uri("http://localhost:8080/v1/") });

可以构造对命名集合的直接引用。

using System.Net.Http;
using Microsoft.SemanticKernel.Connectors.Weaviate;

var collection = new WeaviateCollection<Guid, Hotel>(
    new HttpClient { BaseAddress = new Uri("http://localhost:8080/v1/") },
    "Skhotels");

如果需要，可以使用上述任何机制（例如）将 Api 密钥作为选项传递。

using Microsoft.SemanticKernel;

var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddWeaviateVectorStore(new Uri("http://localhost:8080/v1/"), secretVar);

数据映射

Weaviate Vector Store 连接器在从数据模型映射到存储时提供默认映射器。 Weaviate 要求将属性映射为 ID、负载和向量分组。默认映射器使用模型注释或记录定义来确定每个属性的类型并执行此映射。

批注为键的数据模型属性将映射到 Weaviate id 属性。
数据模型中标记为数据的属性将映射到 Weaviate properties 对象。
作为向量批注的数据模型属性将映射到 Weaviate vectors 对象。

默认映射器使用System.Text.Json.JsonSerializer将其转换为存储架构。这意味着，如果需要与数据模型属性名称不同的存储名称，则支持使用该 JsonPropertyNameAttribute 名称。

下面是具有 JsonPropertyNameAttribute 集的数据模型示例，以及如何在 Weaviate 中表示这些数据模型。

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public Guid HotelId { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")]
    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.QuantizedFlat)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": "11111111-1111-1111-1111-111111111111",
    "properties": { "HotelName": "Hotel Happy", "Description": "A place where everyone can be happy." },
    "vectors": {
        "HOTEL_DESCRIPTION_EMBEDDING": [0.9, 0.1, 0.1, 0.1],
    }
}

入门指南

将 Weaviate Vector Store 连接器依赖项添加到项目。

pip install semantic-kernel[weaviate]

然后，可以创建矢量存储，它使用环境设置进行连接：

使用 Weaviate Cloud 的步骤如下

url：WEAVIATE_URL
api_key：WEAVIATE_API_KEY

若要使用 Weaviate Local（即 Docker 容器中的 Weaviate）：

local_host：WEAVIATE_LOCAL_HOST
local_port：WEAVIATE_LOCAL_PORT
local_grpc_port：WEAVIATE_LOCAL_GRPC_PORT

如果要使用嵌入式：

use_embed：WEAVIATE_USE_EMBED

这些应当以排他方式设置，以确保只存在上述其中一组，否则将引发异常。

from semantic_kernel.connectors.weaviate import WeaviateStore

store = WeaviateStore()

另外，你也可以传入你自己的 mongodb 客户端，以便对客户端构造有更好的控制。

import weaviate
from semantic_kernel.connectors.weaviate import WeaviateStore

client = weaviate.WeaviateAsyncClient(...)
store = WeaviateStore(async_client=client)

还可以直接创建集合，而无需通过商店。

from semantic_kernel.connectors.weaviate import WeaviateCollection

# `hotel` is a class created with the @vectorstoremodel decorator
collection = WeaviateCollection(
    collection_name="my_collection",
    record_type=hotel
)

序列化

Weaviate 客户端返回自己的对象，这些对象在常规流中被解析并转换为字典。有关此概念的更多详细信息，请参阅序列化文档。

即将推出

更多信息即将推出。

通过

使用 Weaviate Vector Store 连接器 （预览版）

概述

限制

入门

数据映射

入门指南

序列化

即将推出

其他资源

使用 Weaviate Vector Store 连接器（预览版）