.NET .NET Aspire Qdrant 集成

發行項
2025/01/23

包括： 主機托管整合和 Client 整合

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

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

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

主機整合

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

.NET CLI
PackageReference

.NET CLI

dotnet add package Aspire.Hosting.Qdrant

XML

<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 參數通常指定為 用戶密碼：

JSON

{
  "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

.NET CLI

dotnet add package Aspire.Qdrant.Client

XML

<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 組態] 區段擷取連接字串：

JSON

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

根據預設，QdrantClient 會使用 gRPC API 端點。

使用組態提供者

.NET .NET Aspire Qdrant 用戶端整合支援 Microsoft.Extensions.Configuration。它會使用 Aspire:Qdrant:Client 鍵從設定中載入 QdrantClientSettings。以下是一個 appsettings.json 的範例，用來設定一些選項：

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 程式庫支援。

共用方式為

.NET .NET Aspire Qdrant 集成

主機整合

新增 Qdrant 資源

處理 API 金鑰並傳遞 Qdrant 資源的其他參數

新增具有數據量的 Qdrant 資源

使用數據系結掛接新增 Qdrant 資源

主機整合健檢

Client 整合

新增 Qdrant 用戶端

新增支援金鑰的 Qdrant 用戶端

配置

使用連接字串

使用組態提供者

使用行內委派

Client 整合健康檢查

可檢視性和遙測

伐木

追蹤

指標

另請參閱

其他資源