integración Qdrant .NET.NET Aspire
incluye: integración de hospedaje de
e integración de Client
Qdrant es un motor de búsqueda de similitud de vectores de código abierto que almacena, indexa y busca datos vectoriales a gran escala de forma eficaz. Normalmente se usa en aplicaciones de aprendizaje automático, inteligencia artificial y ciencia de datos.
Los datos vectoriales codifican información como vectores matemáticos, que son matrices de números o coordenadas. Los sistemas de aprendizaje automático e inteligencia artificial suelen usar vectores para representar objetos no estructurados, como imágenes, texto, audio o vídeo. Cada dimensión del vector describe una característica específica del objeto. Al compararlos, los sistemas pueden clasificar, buscar e identificar clústeres de objetos.
En este artículo, aprenderás a usar la integración de Qdrant con .NET.NET Aspire. La integración de .NET.NET Aspire con Qdrant permite conectarse a bases de datos existentes de Qdrant o crear nuevas instancias utilizando la imagen de contenedor qdrant/qdrant.
Integración de hospedaje
La integración de alojamiento de Qdrant modela el servidor como el tipo QdrantServerResource. Para acceder a estos tipos y API, agregue el paquete NuGet 📦Aspire.Hosting.Qdrant en el proyecto host de la aplicación .
dotnet add package Aspire.Hosting.Qdrant
Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.
Adición de un recurso Qdrant
En el proyecto host de tu aplicación, llama a AddQdrant para que agregue y devuelva un constructor de recursos de 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...
Nota
El contenedor de Qdrant puede ser lento al iniciar, por lo que es mejor usar una duración de vida persistente para evitar reinicios innecesarios. Para obtener más información, consulte vida útil del recurso del contenedor.
Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de qdrant/qdrant, crea una nueva instancia de Qdrant en el equipo local. El recurso se denomina qdrant y, a continuación, se agrega al ExampleProject.
El método WithReference configura una conexión en el ExampleProject denominado qdrant.
Consejo (if the context is a piece of advice)
Si prefiere conectarse a un servidor Qdrant existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.
Propina
La imagen de contenedor qdrant/qdrant incluye una interfaz de usuario web que puede usar para explorar los vectores y administrar la base de datos. Para acceder a esta herramienta, inicie la solución de .NET Aspire y, a continuación, en el panel de .NET Aspire, seleccione el punto de conexión para el recurso Qdrant. En la barra de direcciones del explorador, anexe /dashboard y presione Entrar.
Controlar las claves de API y pasar otros parámetros para el recurso Qdrant
Para conectarse a Qdrant, un cliente debe pasar la clave de API correcta. En el código anterior, cuando .NET.NET Aspire agrega un recurso Qdrant a la solución, establece la clave de API en una cadena aleatoria. Si quiere usar una clave de API específica en su lugar, puede pasarla como parámetro apiKey:
var apiKey = builder.AddParameter("apiKey", secret: true);
var qdrant = builder.AddQdrant("qdrant", apiKey);
builder.AddProject<Projects.ExampleProject>()
.WithReference(qdrant);
Qdrant admite claves de API predeterminadas basadas en la configuración mediante la variable de entorno QDRANT__SERVICE__API_KEY.
El código anterior obtiene un parámetro para pasar a la API de AddQdrant y asigna internamente el parámetro a la variable de entorno QDRANT__SERVICE__API_KEY del contenedor de Qdrant. El parámetro apiKey normalmente se especifica como secreto de usuario:
{
"Parameters": {
"apiKey": "Non-default-P@ssw0rd"
}
}
Para obtener más información, vea Parámetros externos.
Añadir recurso Qdrant con volumen de datos
Para agregar un volumen de datos al recurso Qdrant, llame al método de extensión 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...
El volumen de datos se usa para conservar los datos de Qdrant fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /qdrant/storage en el contenedor de Qdrant y cuando no se proporciona un parámetro name, el nombre se genera aleatoriamente. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a montajes enlazados, consulte la Docker documentación: Volúmenes.
Adición de un recurso Qdrant con montaje de enlace de datos
Para añadir un punto de montaje de enlace de datos al recurso Qdrant, llame al método 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...
Importante
Los montajes de datos tienen una funcionalidad limitada en comparación con los volúmenes, que ofrecen mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los bind mounts permiten el acceso directo y la modificación de archivos en el sistema host, lo que es ideal para el desarrollo y las pruebas donde se necesitan cambios en tiempo real.
Los montajes vinculados de datos dependen del sistema de archivos de la máquina host para conservar los datos de Qdrant en los reinicios del contenedor. El montaje de enlace de datos se monta en la carpeta C:\Qdrant\Data de Windows (o en /Qdrant/Data dentro de Unix) en el equipo host del contenedor Qdrant. Para obtener más información sobre los montajes de enlace para datos, consulte Docker documentos: Montajes de enlace.
Realización de comprobaciones de estado de integración
La integración de hospedaje de Qdrant agrega automáticamente una comprobación de estado para el recurso Qdrant. La comprobación de estado comprueba que Qdrant se está ejecutando y que se puede establecer una conexión con él.
Client integración
Para iniciar con la integración del cliente .NET.NET Aspire Qdrant, instale el paquete NuGet 📦Aspire.Qdrant.Client en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente Qdrant. La integración del cliente de Qdrant registra un Qdrant.Client. QdrantClient instancia que puede usar para interactuar con los datos vectoriales de Qdrant.
dotnet add package Aspire.Qdrant.Client
Adición de un cliente Qdrant
En el archivo Program.cs de su proyecto cliente, llame al método de extensión AddQdrantClient en cualquier IHostApplicationBuilder para registrar un QdrantClient para su uso mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.
builder.AddQdrantClient("qdrant");
Propina
El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Qdrant en el proyecto host de la aplicación. Es decir, cuando se llama a AddQdrant y se proporciona un nombre de qdrant ese mismo nombre se debe usar al llamar a AddQdrantClient. Para obtener más información, consulte Agregar recurso Qdrant.
A continuación, puede recuperar mediante inyección de dependencias la instancia de QdrantClient. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:
public class ExampleService(QdrantClient client)
{
// Use client...
}
Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.
Adición de un cliente Qdrant con clave
Puede haber situaciones en las que quiera registrar varias instancias de QdrantClient con nombres de conexión diferentes. Para registrar clientes Qdrant con clave, llame al método AddKeyedQdrantClient:
builder.AddKeyedQdrantClient(name: "mainQdrant");
builder.AddKeyedQdrantClient(name: "loggingQdrant");
A continuación, puede recuperar las instancias de QdrantClient mediante la inyección de dependencias. Por ejemplo, para recuperar las conexiones de un servicio de ejemplo:
public class ExampleService(
[FromKeyedServices("mainQdrant")] QdrantClient mainQdrantClient,
[FromKeyedServices("loggingQdrant")] QdrantClient loggingQdrantClient)
{
// Use clients...
}
Para obtener más información sobre los servicios con clave, consulte .NET inserción de dependencias: Servicios con clave.
Configuración
La integración del cliente de Qdrant de .NET.NET Aspire proporciona varias opciones para configurar la conexión a Qdrant en función de los requisitos y convenciones del proyecto.
Uso de una cadena de conexión
Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a builder.AddQdrantClient():
builder.AddQdrantClient("qdrant");
A continuación, .NET.NET Aspire recupera la cadena de conexión de la sección de configuración de ConnectionStrings:
{
"ConnectionStrings": {
"qdrant": "Endpoint=http://localhost:6334;Key=123456!@#$%"
}
}
De forma predeterminada, el QdrantClient usa el endpoint de la API gRPC.
Uso de proveedores de configuración
La integración de cliente de .NET.NET Aspire Qdrant admite Microsoft.Extensions.Configuration. Carga el QdrantClientSettings desde la configuración mediante la clave Aspire:Qdrant:Client. A continuación se muestra un ejemplo de un appsettings.json que configura algunas de las opciones:
{
"Aspire": {
"Qdrant": {
"Client": {
"Endpoint": "http://localhost:6334/",
"Key": "123456!@#$%"
}
}
}
}
Para obtener el esquema completo de integración de cliente de Qdrant JSON, consulte Aspire. Qdrant.Client/ConfigurationSchema.json.
Usar delegados en línea
También puede pasar el delegado Action<QdrantClientSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para establecer la clave de la API desde el código.
builder.AddQdrantClient(
"qdrant",
settings => settings.Key = "12345!@#$%");
comprobaciones de estado de integración de Client
De forma predeterminada, las integraciones de .NET.NET Aspire activan las comprobaciones de salud de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.
Observabilidad y telemetría
.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.
Registro
La integración Qdrant .NET Aspire utiliza el registro estándar .NET, y usted verá entradas de registro de la siguiente categoría:
Qdrant.Client
Rastreo
La integración de .NET.NET Aspire Qdrant no emite actualmente actividades de seguimiento porque no son compatibles con la biblioteca de Qdrant.Client.
Métricas
La integración de Qdrant de .NET.NET Aspire no emite actualmente métricas porque no son compatibles con la biblioteca de Qdrant.Client.
