.NET .NET Aspire Qdrant 整合方案

發行項
01/23/2025

Qdrant 是開放原始碼向量相似度搜尋引擎，可有效儲存、索引和搜尋大規模的向量數據。它通常用於機器學習、人工智慧和數據科學應用程式。

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

在本文中，您將學習如何使用 .NET.NET Aspire Qdrant 整合功能。 .NET .NET Aspire Qdrant 整合可讓您連線到現有的 Qdrant 資料庫，或使用 qdrant/qdrant 容器映射建立新的實例。

主機代管整合

Qdrant 的託管整合將伺服器建模為 QdrantServerResource 類型。若要存取此類型和 API，請新增 📦Aspire。應用程式主機專案中的 Hosting.Qdrant NuGet 套件。

.NET CLI
PackageReference

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 資源的端點。在瀏覽器的網址列中，附加 /dashboard，然後按 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 支援以組態為基礎的預設 API 金鑰，方法是使用環境變數 QDRANT__SERVICE__API_KEY。

上述程式代碼會取得要傳遞至 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 數據。數據綁定掛載會掛載在 Windows 上的 C:\Qdrant\Data 資料夾（或 /Qdrant/Data上的 Unix 資料夾），在主機的 Qdrant 容器中。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

主機整合健檢

Qdrant 託管整合會自動新增 Qdrant 資源的健康檢查。健康情況檢查會驗證 Qdrant 是否正在執行，而且可以建立與其連線。

Client 整合

若要開始使用 .NET.NET Aspire Qdrant 用戶端整合，請在取用 Qdrant 用戶端的應用程式專案中，安裝 📦Aspire.Qdrant.Client NuGet 套件。 Qdrant 用戶端整合會註冊 QdrantClient的 QdrantClient 實例，可用來與 Qdrant 向量數據互動。

.NET CLI
PackageReference

dotnet add package Aspire.Qdrant.Client

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

新增 Qdrant 用戶端

在用戶端的 Program.cs 檔案中，呼叫任何 IHostApplicationBuilder 上的 AddQdrantClient 擴充方法，以透過相依性插入容器註冊 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 程式庫支援。

共用方式為