.NET .NET Aspire integração do Qdrant

Inclui:integração de hospedagem e Client integração

qdrant é um mecanismo de pesquisa de similaridade de vetor de software livre que armazena, indexa e pesquisa dados de vetor em larga escala com eficiência. Normalmente, ele é usado em machine learning, inteligência artificial e aplicativos de ciência de dados.

Dados vetoriais codificam informações como vetores matemáticos, que são matrizes de números ou coordenadas. Os sistemas de machine learning e IA geralmente usam vetores para representar objetos não estruturados, como imagens, texto, áudio ou vídeo. Cada dimensão no vetor descreve uma característica específica do objeto. Comparando-os, os sistemas podem classificar, pesquisar e identificar clusters de objetos.

Neste artigo, você aprenderá a usar a integração do .NET.NET Aspire Qdrant. A integração do .NET.NET Aspire Qdrant permite que você se conecte a bancos de dados Qdrant existentes ou crie novas instâncias com a imagem de contêiner qdrant/qdrant.

Integração de hospedagem

A integração de hospedagem Qdrant modela o server como o tipo QdrantServerResource. Para acessar esse tipo e APIs, adicione o pacote NuGet 📦Aspire.Hosting.Qdrant no projeto de host do aplicativo .

dotnet add package Aspire.Hosting.Qdrant

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

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicativos .NET.

Adicionar recurso Qdrant

No projeto host do seu aplicativo, chame AddQdrant para adicionar e retornar um gerador de recursos 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...

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem qdrant/qdrant, ele cria uma nova instância Qdrant em seu computador local. O recurso é nomeado qdrant e, em seguida, adicionado ao ExampleProject.

O método WithReference configura uma conexão no ExampleProject denominado qdrant.

Manipulando chaves de API e passando outros parâmetros para o recurso Qdrant

Para se conectar ao Qdrant, um client deve passar a chave de API certa. No código acima, quando .NET.NET Aspire adiciona um recurso Qdrant à sua solução, ele define a chave de API como uma cadeia de caracteres aleatória. Se você quiser usar uma chave de API específica, poderá passá-la como um parâmetro apiKey:

var apiKey = builder.AddParameter("apiKey", secret: true);

var qdrant = builder.AddQdrant("qdrant", apiKey);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant);

O Qdrant dá suporte a chaves de API padrão baseadas em configuração usando a variável de ambiente QDRANT__SERVICE__API_KEY.

O código anterior obtém um parâmetro a ser passado para a API AddQdrant e atribui internamente o parâmetro à variável de ambiente QDRANT__SERVICE__API_KEY do contêiner Qdrant. O parâmetro apiKey geralmente é especificado como um segredo do usuário :

{
  "Parameters": {
    "apiKey": "Non-default-P@ssw0rd"
  }
}

Para obter mais informações, consulte Parâmetros externos.

Adicionar recurso Qdrant com volume de dados

Para adicionar um volume de dados ao recurso Qdrant, chame o método de extensão 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...

O volume de dados é usado para manter os dados Qdrant fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /qdrant/storage no contêiner Qdrant e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar recurso Qdrant com a montagem de associação de dados

Para adicionar uma montagem de associação de dados ao recurso Qdrant, chame o 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...

As montagens de ligação de dados dependem do sistema de arquivos do computador host para manter os dados do Qdrant durante as reinicializações de contêiner. A montagem de associação de dados está montada na pasta C:\Qdrant\Data no Windows (ou /Qdrant/Data no Unix) na máquina host dentro do contêiner Qdrant. Para obter mais informações sobre montagens de bind de dados, consulte Docker documentos: Montagens de bind.

Verificações de integridade de integração de hospedagem

A integração de hospedagem Qdrant adiciona automaticamente uma verificação de integridade para o recurso Qdrant. A verificação de saúde verifica se o Qdrant está em execução e se uma conexão pode ser estabelecida com ele.

integração Client

Para começar a usar a integração do Qdrant .NET Aspire com o client, instale o 📦Aspire.Qdrant.Client pacote NuGet no projeto consumidor client, ou seja, o projeto para o aplicativo que usa o Qdrant client. A integração do Qdrant client registra um Qdrant .Client. QdrantClient instância que você pode usar para interagir com dados de vetor Qdrant.

dotnet add package Aspire.Qdrant.Client

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

Adicionar um Qdrant client

No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddQdrantClient em qualquer IHostApplicationBuilder para registrar um QdrantClient para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddQdrantClient("qdrant");

Em seguida, você pode recuperar a instância QdrantClient usando injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar Qdrant client com chave

Pode haver situações em que você deseja registrar várias instâncias de QdrantClient com nomes de conexão diferentes. Para registrar clientes Qdrant chaveados, chame o método AddKeyedQdrantClient:

builder.AddKeyedQdrantClient(name: "mainQdrant");
builder.AddKeyedQdrantClient(name: "loggingQdrant");

Em seguida, você pode recuperar as instâncias de QdrantClient usando a injeção de dependência. Por exemplo, para recuperar as conexões de um serviço de exemplo:

public class ExampleService(
    [FromKeyedServices("mainQdrant")] QdrantClient mainQdrantClient,
    [FromKeyedServices("loggingQdrant")] QdrantClient loggingQdrantClient)
{
    // Use clients...
}

Para obter mais informações sobre serviços chaveados, consulte .NET injeção de dependência: serviços chaveados.

Configuração

A integração do .NET Aspire Qdrant client fornece várias opções para configurar a conexão com o Qdrant com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddQdrantClient():

builder.AddQdrantClient("qdrant");

Em seguida, .NET.NET Aspire recupera a cadeia de conexão da seção de configuração ConnectionStrings:

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

Por padrão, o QdrantClient usa o endpoint da API gRPC.

Usar provedores de configuração

A integração do .NET Aspire Qdrant client dá suporte a Microsoft.Extensions.Configuration. Ele carrega a QdrantClientSettings da configuração usando a chave Aspire:Qdrant:Client. Veja a seguir um exemplo de um appsettings.json que configura algumas das opções:

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

Para o esquema completo de integração do Qdrant clientJSON, consulte Aspire.Qdrant.Client/ConfigurationSchema.json.

Usar delegados em linha

Você também pode passar o delegado Action<QdrantClientSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para definir a chave de API a partir do código:

builder.AddQdrantClient(
    "qdrant", 
    settings => settings.Key = "12345!@#$%");

Client verificações de integridade de integração

Por padrão, as integrações .NET.NET Aspire habilitam verificações de saúde para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração do .NET Aspire Qdrant usa o registro padrão de .NET e você verá entradas de log nas seguintes categorias:

• Qdrant.Client

Rastreamento

Atualmente, a integração .NET.NET Aspire Qdrant não emite atividades de rastreamento, pois elas não são suportadas pela biblioteca Qdrant.Client.

Métricas

No momento, a integração do .NET.NET Aspire Qdrant não emite métricas porque elas não são compatíveis com a biblioteca de Qdrant.Client.

Consulte também

• Qdrant
• documentação do Qdrant
• Qdrant repositório GitHub
• Qdrant SDK .NET
• .NET .NET Aspire integrações
• .NET Aspire GitHub repo