.NET .NET Aspire Qdrant 集成

2025-04-30

包含： - Client 集成

Qdrant 是一个开源矢量相似性搜索引擎，可有效地存储、索引和搜索大规模矢量数据。它通常用于机器学习、人工智能和数据科学应用程序。

矢量数据将信息编码为数学向量，即数字或坐标数组。机器学习和 AI 系统通常使用矢量来表示非结构化对象，如图像、文本、音频或视频。矢量中的每个维度都描述对象的特定特征。通过比较它们，系统可以对对象群集进行分类、搜索和标识。

本文中，您将学习如何使用 .NET.NET Aspire Qdrant 集成。 .NET .NET Aspire通过 Qdrant 集成，可以连接到现有的 Qdrant 数据库，或使用容器映像创建新实例qdrant/qdrant。

托管集成

托管集成的 Qdrant 将服务器建模为 QdrantServerResource 类型。若要访问此类型和 API，请在应用主机项目中添加 Hosting.Qdrant NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Qdrant

<PackageReference Include="Aspire.Hosting.Qdrant"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或 .NET 应用程序中管理包依赖项。

添加 Qdrant 资源

在应用主机项目中，调用 AddQdrant 添加并返回 Qdrant 资源生成器。

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

// After adding all resources, run the app...

注意

Qdrant 容器启动速度可能很慢，因此最好使用 持久性 生存期来避免不必要的重启。有关详细信息，请参阅容器资源生存期。

当 .NET.NET Aspire 向应用程序宿主添加容器映像时，如前述示例中的 qdrant/qdrant 映像，它会在本地计算机上创建一个新的 Qdrant 实例。资源被命名为 qdrant，然后被添加到 ExampleProject中。

WithReference 方法在名为 ExampleProject 的 qdrant 中配置连接。

提示

如果想要连接到现有的 Qdrant 服务器，请改为调用 AddConnectionString。有关详细信息，请参阅引用现有资源。

提示

qdrant/qdrant 容器映像包括一个 Web UI，可用于浏览矢量和管理数据库。若要访问此工具，请启动 .NET Aspire 解决方案，然后在 .NET Aspire 仪表板中选择 Qdrant 资源的终结点。在浏览器的地址栏中，追加 /仪表板 ，然后按 Enter。

处理 API 密钥并传递 Qdrant 资源的其他参数

若要连接到 Qdrant，客户端必须传递正确的 API 密钥。在上面的代码中，当 .NET.NET Aspire 向解决方案添加 Qdrant 资源时，它将 API 密钥设置为随机字符串。如果想要改用特定的 API 密钥，可以将其作为 apiKey 参数传递：

var apiKey = builder.AddParameter("apiKey", secret: true);

var qdrant = builder.AddQdrant("qdrant", apiKey);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant);

Qdrant 使用环境变量 QDRANT__SERVICE__API_KEY支持基于配置的默认 API 密钥。

前面的代码获取传递给 AddQdrant API 的参数，并在内部将参数分配给 Qdrant 容器的 QDRANT__SERVICE__API_KEY 环境变量。参数 apiKey 通常指定为 用户密码：

{
  "Parameters": {
    "apiKey": "Non-default-P@ssw0rd"
  }
}

有关详细信息，请参阅外部参数。

添加具有数据量的 Qdrant 资源

若要向 Qdrant 资源添加数据卷，请调用 WithDataVolume 扩展方法：

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent)
                    .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

// After adding all resources, run the app...

数据卷用于在其容器生命周期之外保留 Qdrant 数据。数据卷装载在 Qdrant 容器中的 /qdrant/storage 路径上，如果未提供 name 参数，则会随机生成名称。有关数据卷的详细信息以及它们为何优先于绑定装载的详细信息，请参阅 Docker 文档：卷。

添加具有数据绑定挂载的 Qdrant 资源

若要将数据绑定装载添加到 Qdrant 资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithLifetime(ContainerLifetime.Persistent)
                    .WithDataBindMount(source: @"C:\Qdrant\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

// After adding all resources, run the app...

重要

与卷相比，数据绑定挂载的功能有限，卷提供更好的性能、可移植性和安全性，使其更适合于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定装载依赖于主机的文件系统在容器重启时保留 Qdrant 数据。数据绑定装载位于 Qdrant 容器的主机上的 Windows 的 C:\Qdrant\Data 文件夹中（或 /Qdrant/Data上的 Unix）。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

托管集成运行状况检查

Qdrant 托管服务集成会自动为 Qdrant 资源添加运行状况检查。运行状况检查验证 Qdrant 是否正在运行，并能够与其建立连接。

Client 集成

若要开始使用 .NET.NET Aspire Qdrant 客户端集成，请在使用 Qdrant 客户端的应用程序项目中安装 📦AspireQdrant.Client NuGet 包。 Qdrant 客户端集成会注册一个 Client 实例，可用于与 Qdrant 向量数据进行交互。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Qdrant.Client

<PackageReference Include="Aspire.Qdrant.Client"
                  Version="*" />

添加 Qdrant 客户端

在你的客户端项目的Program.cs文件中，对任意AddQdrantClient调用IHostApplicationBuilder扩展方法，以注册一个QdrantClient，以便通过依赖注入容器使用。该方法采用连接名称参数。

builder.AddQdrantClient("qdrant");

提示

connectionName 参数必须与在应用主机项目中添加 Qdrant 资源时使用的名称匹配。换句话说，当调用 AddQdrant 并提供 qdrant 的名称时，在调用 AddQdrantClient时应使用相同的名称。有关详细信息，请参阅 “添加 Qdrant 资源”。

然后，可以使用依赖项注入检索 QdrantClient 实例。例如，若要从示例服务检索连接，

public class ExampleService(QdrantClient client)
{
    // Use client...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加配置密钥的 Qdrant 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 QdrantClient 实例。若要注册密钥 Qdrant 客户端，请调用 AddKeyedQdrantClient 方法：

builder.AddKeyedQdrantClient(name: "mainQdrant");
builder.AddKeyedQdrantClient(name: "loggingQdrant");

然后，可以使用依赖项注入检索 QdrantClient 实例。例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("mainQdrant")] QdrantClient mainQdrantClient,
    [FromKeyedServices("loggingQdrant")] QdrantClient loggingQdrantClient)
{
    // Use clients...
}

有关密钥服务的详细信息，请参阅 .NET 依赖关系注入：密钥服务。

配置

.NET .NET Aspire Qdrant 客户端集成提供了多个选项，用于根据项目的要求和约定配置与 Qdrant 的连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 builder.AddQdrantClient()时提供连接字符串的名称：

builder.AddQdrantClient("qdrant");

然后 .NET.NET Aspire 从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "qdrant": "Endpoint=http://localhost:6334;Key=123456!@#$%"
  }
}

默认情况下，QdrantClient 使用 gRPC API 端点。

使用配置提供程序

.NET .NET Aspire Qdrant 客户端集成支持 Microsoft.Extensions.Configuration。它使用 QdrantClientSettings 键从配置中加载 Aspire:Qdrant:Client。下面是配置某些选项的 appsettings.json 的示例：

{
  "Aspire": {
    "Qdrant": {
      "Client": {
        "Endpoint": "http://localhost:6334/",
        "Key": "123456!@#$%"
      }
    }
  }
}

有关完整的 Qdrant 客户端集成 JSON 架构，请参阅 Aspire。Qdrant。Client/ConfigurationSchema.json.

使用内联代理

您也可以将 Action<QdrantClientSettings> configureSettings 委托传递过去，以内联方式设置部分或全部选项，例如直接从代码设置 API 密钥：

builder.AddQdrantClient(
    "qdrant", 
    settings => settings.Key = "12345!@#$%");

Client 集成健康检查

默认情况下，.NET.NET Aspire 集成会为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Qdrant 集成使用标准 .NET 日志记录，您将看到以下类别中的日志条目：

Qdrant.Client

追踪

.NET .NET Aspire Qdrant 集成当前不会发出追踪活动，因为 Qdrant.Client 库不支持它们。

指标

.NET .NET Aspire Qdrant 集成当前不生成指标，因为它们不受 Qdrant.Client 库的支持。

通过