.NET Aspire Milvus 数据库集成

2025-04-30

包含： - Client 集成

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

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

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

托管集成

托管集成 Milvus 数据库将服务器建模为 MilvusServerResource 类型和数据库作为 MilvusDatabaseResource 类型。若要访问这些类型和 API，请在📦项目中添加AspireMilvus.Hosting. NuGet 包。

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

dotnet add package Aspire.Hosting.Milvus

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

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

添加 Milvus 服务器和数据库资源

在应用主机项目中，调用 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 方法在名为 ExampleProject 的 milvusdb 中配置连接。

提示

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

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

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

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

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

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

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

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

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

添加带有数据卷的 Milvus 资源

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

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 数据。数据卷在 /var/lib/milvus 容器中的 SQL Server 路径装载，当未提供 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（或 /Milvus/Data上的 Unix）路径，位于 Milvus 容器的主机上。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

创建 Attu 资源

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

如果要使用 Attu 管理 Milvus，请在 .NET Aspire 解决方案中的 WithAttu 资源上调用 Milvus 扩展方法。该方法从 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 AspireMilvus 客户端集成，请安装 📦Aspire.Milvus.Client 客户端使用项目中的 NuGet 包，即使用 Milvus 数据库客户端的应用程序的项目。 Milvus客户端集成会注册一个可用于与Milvus数据库交互的Milvus实例。

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

dotnet add package Aspire.Milvus.Client

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

添加 Milvus 客户端

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

builder.AddMilvusClient("milvusdb");

提示

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

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

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

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

添加带编号 Milvus 的客户端

在某些情况下，可能需要使用不同的连接名称注册多个 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 客户端集成提供了多个选项，用于根据项目的要求和约定配置与 Milvus 的连接。

提示

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

使用连接字符串

使用 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 客户端集成支持 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
      }
    }
  }
}

有关完整的 Milvus 客户端集成 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时，添加健康检查以尝试连接到 Milvus 服务器。
使用已配置的客户端来执行 HealthAsync。如果结果正常，则运行状况检查被视为正常，否则运行状况检查不正常。同样，如果存在异常，则认为健康检查不正常，并且错误会因健康检查失败而传播。

可观测性和遥测

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

伐木

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

Milvus.Client

描图

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

指标

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

通过