интеграция Qdrant .NET.NET Aspire

Статья
01/18/2025

Включает:интеграция хостинга и Client интеграция

Qdrant — это поисковая система сходства с открытым исходным кодом, которая эффективно хранит, индексирует и выполняет поиск векторных данных крупного масштаба. Он часто используется в машинном обучении, искусственном интеллекте и приложениях для обработки и анализа данных.

Векторные данные кодируют сведения в виде математических векторов, которые являются массивами чисел или координат. Системы машинного обучения и искусственного интеллекта часто используют векторы для представления неструктурированных объектов, таких как изображения, текст, звук или видео. Каждое измерение в векторе описывает определенную характеристику объекта. Сравнивая их, системы могут классифицировать, искать и определять кластеры объектов.

Из этой статьи вы узнаете, как использовать интеграцию .NET.NET Aspire Qdrant. Интеграция Qdrant .NET.NET Aspire позволяет подключаться к существующим базам данных Qdrant или создавать новые экземпляры с помощью qdrant/qdrant образа контейнера.

Интеграция хостинга

Qdrant, в котором размещается интеграция, моделирует server в качестве типа QdrantServerResource. Чтобы получить доступ к этому типу и API, добавьте пакет NuGet 📦Aspire.Hosting.Qdrant в проекте хоста приложения .

.NET интерфейс командной строки
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 server, вместо этого вызовите AddConnectionString. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Совет

Образ контейнера qdrant/qdrant включает в себя веб-интерфейс, который можно использовать для изучения векторов и администрирования базы данных. Чтобы получить доступ к этому средству, запустите решение .NET Aspire, а затем на панели мониторинга .NET Aspire выберите конечную точку для ресурса Qdrant. В адресной строке браузера добавьте /dashboard и нажмите Enter.

Обработка ключей API и передача других параметров для ресурса Qdrant

Чтобы подключиться к Qdrant client, необходимо передать правильный ключ 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.

Приведенный выше код получает параметр для передачи в API AddQdrant и внутренне назначает параметр переменной среды QDRANT__SERVICE__API_KEY контейнера Qdrant. Параметр 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/storage в контейнере Qdrant, и если параметр 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 при перезапусках контейнера. Точка монтирования данных закреплена в папке C:\Qdrant\Data на Windows (или /Qdrant/Data на Unix) на хост-компьютере в контейнере Qdrant. Дополнительные сведения о монтировании привязки данных см. в документации Docker: Привязка монтирования.

Проверка работоспособности интеграции хостинга

Интеграция хостинга Qdrant автоматически добавляет проверку работоспособности для ресурса Qdrant. Проверка работоспособности проверяет, запущен ли Qdrant и что подключение можно установить к нему.

интеграция Client

Чтобы приступить к работе с интеграцией .NET Aspire Qdrant client, установите пакет 📦AspireQdrantClient NuGet в проект client, то есть в проект, который использует clientQdrant. Интеграция Qdrant client регистрирует QdrantClient, создавая экземпляр QdrantClient, который можно использовать для взаимодействия с данными векторов Qdrant.

.NET интерфейс командной строки
PackageReference

dotnet add package Aspire.Qdrant.Client

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

Добавить Qdrant client

В файле Program.cs проекта client-потребления вызовите метод расширения AddQdrantClient для любой IHostApplicationBuilder, чтобы зарегистрировать QdrantClient для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

builder.AddQdrantClient("qdrant");

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса Qdrant в проект узла приложения. Другими словами, при вызове AddQdrant и указании имени qdrant то же имя следует использовать при вызове AddQdrantClient. Дополнительные сведения см. в разделе Добавление ресурсов Qdrant.

Затем можно извлечь экземпляр QdrantClient с помощью инъекции зависимостей. Например, чтобы получить подключение из примера сервиса:

public class ExampleService(QdrantClient client)
{
    // Use client...
}

Для получения дополнительных сведений о внедрении зависимостей см. .NET внедрение зависимостей.

Добавить ключевой Qdrant client

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров 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 Aspire Qdrant client предоставляет несколько вариантов настройки подключения к Qdrant на основе требований и соглашений проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Затем .NET.NET Aspire извлекает строку подключения из раздела конфигурации ConnectionStrings:

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

По умолчанию QdrantClient использует конечную точку API gRPC.

Использование поставщиков конфигураций

Интеграция .NET Aspire Qdrant client поддерживает Microsoft.Extensions.Configuration. Он загружает QdrantClientSettings из конфигурации с помощью ключа Aspire:Qdrant:Client. Ниже приведен пример appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Qdrant": {
      "Client": {
        "Endpoint": "http://localhost:6334/",
        "Key": "123456!@#$%"
      }
    }
  }
}

Полный JSON схемы интеграции client Qdrant см. в 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 обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция Qdrant .NET Aspire использует стандартное ведение журнала .NET, и вы увидите записи журнала из следующей категории:

Qdrant.Client

Отслеживание

Интеграция Qdrant .NET.NET Aspire в настоящее время не выдает действия трассировки, так как они не поддерживаются библиотекой Qdrant.Client.

Метрика

Интеграция .NET.NET Aspire Qdrant в настоящее время не выдает метрики, так как они не поддерживаются библиотекой Qdrant.Client.

Поделиться через

интеграция Qdrant .NET.NET Aspire

Интеграция хостинга

Добавление ресурса Qdrant

Обработка ключей API и передача других параметров для ресурса Qdrant

Добавьте ресурс Qdrant с объемом данных

Добавление ресурса Qdrant с подключением привязки данных

Проверка работоспособности интеграции хостинга

интеграция Client

Добавить Qdrant client

Добавить ключевой Qdrant client

Конфигурация

Используйте строку подключения

Использование поставщиков конфигураций

Использование встроенных делегатов

Client проверки работоспособности интеграции

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Дополнительные ресурсы