.NET Aspire Milvus 資料庫整合

發行項
01/11/2025

Milvus 是開放原始碼向量資料庫系統，可有效率地儲存、索引和搜尋大規模的向量數據。它通常用於機器學習、人工智慧和數據科學應用程式。

向量數據會將資訊編碼為數學向量，也就是數位或座標的陣列。機器學習和 AI 系統通常會使用向量來代表影像、文字、音訊或視訊等非結構化物件。向量中的每個維度都會描述物件的特定特性。藉由比較它們，系統可以分類、搜尋及識別物件的叢集。

在本文中，您將瞭解如何使用 .NET AspireMilvus 資料庫整合。 .NET Aspire Milvus 資料庫整合可讓您連線到現有的 Milvus 資料庫，或使用 milvusdb/milvus 容器映像建立新的實例。

主機託管整合

在 Milvus 的資料庫中，整合過程將 server 模型化為 MilvusServerResource 類型，並將資料庫本身模型化為 MilvusDatabaseResource 類型。若要存取這些類型和 API，請在應用程式主機專案中新增 📦Aspire.Hosting.Milvus NuGet 套件。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Hosting.Milvus

<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。若要變更容器中的默認密碼，請在呼叫裝載 API AddMilvus 時傳遞 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 數據保存在其容器生命週期之外。數據磁碟區會掛接在 /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 數據。數據綁定掛載會在 Milvus 容器中，主機的 C:\Milvus\Data 路徑上（或 Unix的 /Milvus/Data 路徑上）掛載。如需資料系結掛接的詳細資訊，請參閱 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 整合，請在 client使用的專案中安裝 NuGet 套件 📦Aspire。Milvus。Client ，也就是使用 Milvus 資料庫的應用程式專案 client。 Milvus client 整合會註冊 Milvus.Client.MilvusClient 實例，可用來與 Milvus 資料庫互動。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Milvus.Client

<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 函式庫不支持它們。

共用方式為