.NET Aspire Milvus 数据库集成

包括：托管集成 和 Client 集成

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

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

本文介绍如何使用 .NET AspireMilvus 数据库集成。 通过 .NET AspireMilvus 数据库集成，可以连接到现有 Milvus 数据库，或使用 milvusdb/milvus 容器映像创建新实例。

托管集成

托管集成的 Milvus 数据库将 server 建模为 MilvusServerResource 类型，并且将数据库建模为 MilvusDatabaseResource 类型。 若要访问这些类型和 API，请在 应用主机 项目中添加 📦Aspire.Hosting.Milvus NuGet 包。

.NET CLI

dotnet add package Aspire.Hosting.Milvus

PackageReference

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

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

添加 Milvusserver 和数据库资源

在应用主机项目中，调用 AddMilvus 添加并返回 Milvus 资源生成器。 将返回的资源生成器的调用链接到 AddDatabase，以添加 Milvus 数据库资源。

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

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

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

注意

Milvus 容器启动可能较慢，因此最好使用 持久的 生命周期以避免不必要的重启。 有关详细信息，请参阅 容器资源生存期。

当 .NET.NET Aspire 向应用主机添加容器映像时，就像前面的例子中添加了 milvusdb/milvus 映像一样，它会在你的本地计算机上创建一个新的 Milvus 实例。 对 Milvus 资源生成器（milvus 变量）的引用用于添加数据库。 数据库命名为 milvusdb，然后添加到 ExampleProject。

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

提示

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

处理凭据并传递 Milvus 资源的其他参数

Milvus 资源包括默认凭据，凭据为rootusername，密码为Milvus。 Milvus 通过使用环境变量 COMMON_SECURITY_DEFAULTROOTPASSWORD支持基于配置的默认密码。 若要更改容器中的默认密码，在调用 AddMilvus 托管 API 时传递 apiKey 参数：

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

var milvus = builder.AddMilvus("milvus", apiKey);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(milvus);

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

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

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

用数据卷添加 Milvus 资源

若要将数据卷添加到 Milvus 服务资源，请在 Milvus 资源上调用 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataVolume();

var milvusdb = milvus.AddDatabase("milvusdb");

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

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

数据卷用于在容器的生命周期之外保留 Milvus 数据。 数据卷在 SQL Server 容器中的 /var/lib/milvus 路径装载，当未提供 name 参数时，名称将被随机生成。 有关数据卷的详细信息，以及它们为何优先于 绑定装载的详细信息，请参阅 Docker 文档：卷。

为 Milvus 资源添加一个数据绑定装载

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

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataBindMount(source: @"C:\Milvus\Data");

var milvusdb = milvus.AddDatabase("milvusdb");

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

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

重要

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

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

创建 Attu 资源

Attu 是一种图形用户界面（GUI）和管理工具，旨在与 Milvus 及其数据库进行交互。 它包含丰富的可视化功能，可帮助你调查和了解矢量数据。

如果要使用 Attu 管理 .NET Aspire 解决方案中的 Milvus，请在 Milvus 资源上调用 WithAttu 扩展方法。 该方法从 zilliz/attu 映像创建容器：

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithAttu()
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

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

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

调试 .NET.NET Aspire 解决方案时，会看到解决方案资源中列出的 Attu 容器。 选择资源的终结点以打开 GUI 并开始管理数据库。

Client 集成

若要开始 .NET AspireMilvusclient 集成，请安装 📦Aspire。Milvus。Client 使用 client项目中的 NuGet 包，即使用 Milvus 数据库 client的应用程序的项目。 Milvus client 集成会注册一个 Milvus、Client、MilvusClient 实例，你可以用它与 Milvus 数据库进行交互。

.NET CLI

dotnet add package Aspire.Milvus.Client

PackageReference

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

添加 Milvusclient

在 client消耗项目的 Program.cs 文件中，对任何 IHostApplicationBuilder 调用 AddMilvusClient 扩展方法，以注册 MilvusClient，以便通过依赖项注入容器使用。 该方法采用连接名称参数。

builder.AddMilvusClient("milvusdb");

提示

connectionName 参数必须与在应用主机项目中添加 Milvus 数据库资源时使用的名称匹配。 换句话说，当你调用 AddDatabase 并提供 milvusdb 的名称时，应该在调用 AddMilvusClient时使用相同的名称。 有关详细信息，请参阅 添加 Milvusserver 资源和数据库资源。

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

public class ExampleService(MilvusClient client)
{
    // Use the Milvus Client...
}

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

添加键 Milvusclient

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

builder.AddKeyedMilvusClient(name: "mainDb");
builder.AddKeyedMilvusClient(name: "loggingDb");

重要

使用密钥服务时，预期 Milvus 资源配置了两个命名数据库，一个用于 mainDb，一个用于 loggingDb。

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

public class ExampleService(
    [FromKeyedServices("mainDb")] MilvusClient mainDbClient,
    [FromKeyedServices("loggingDb")] MilvusClient loggingDbClient)
{
    // Use clients...
}

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

配置

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

提示

默认使用 root，默认密码 Milvus。 若要在 Milvus 容器中配置其他密码，请参阅 处理凭据并传递 Milvus 资源的其他参数。 使用以下技术，在您的 .NET Aspire 解决方案中以相同密码或其他设置配置消费 client 应用。

使用连接字符串

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

builder.AddMilvusClient("milvus");

然后，将从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "milvus": "Endpoint=http://localhost:19530/;Key=root:Non-default-P@ssw0rd"
  }
}

默认情况下，MilvusClient 使用 gRPC API 终结点。

使用配置提供程序

.NET Aspire Milvus client 集成支持 Microsoft.Extensions.Configuration。 它使用 MilvusClientSettings 键从配置中加载 Aspire:Milvus:Client。 以下代码片段是配置某些选项的 appsettings.json 示例：

{
  "Aspire": {
    "Milvus": {
      "Client": {
        "Endpoint": "http://localhost:19530/",
        "Database": "milvusdb",
        "Key": "root:Non-default-P@ssw0rd",
        "DisableHealthChecks": false
      }
    }
  }
}

有关完整的 Milvusclient 集成 JSON 架构，请参阅 Aspire。Milvus。Client/ConfigurationSchema。json。

使用内联委托

还可以传递 Action<MilvusSettings> configureSettings 委托来设置一些或所有内联选项，例如，通过代码设置 API 密钥：

builder.AddMilvusClient(
    "milvus",
    static settings => settings.Key = "root:Non-default-P@ssw0rd");

Client 集成运行状况检查

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

.NET Aspire Milvus 数据库集成：

• 在 MilvusClientSettings.DisableHealthChecks 是 false时，添加运行状况检查，尝试连接到 Milvusserver。
• 使用配置的 client 执行 HealthAsync。 如果结果 是健康的，则该健康检查被视为健康，否则被视为不健康。 同样，如果存在异常，则认为健康检查不正常，并且错误会因健康检查失败而传播。

可观测性和遥测

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

伐木

.NET Aspire Milvus 数据库集成使用标准 .NET 日志记录，你将看到以下类别中的日志条目：

• Milvus.Client

描图

.NET Aspire Milvus 数据库集成目前不会生成跟踪活动，因为 Milvus.Client 库不支持这一功能。

指标

.NET Aspire Milvus 数据库集成当前不会发出指标，因为它们不受 Milvus.Client 库支持。

另请参阅

• Milvus
• Milvus GitHub 存储库
• Milvus .NET SDK
• .NET .NET Aspire 集成
• .NET Aspire GitHub 存储库