Partilhar via

.NET .NET Aspire Integração com Qdrant

  • Artigo

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

Qdrant é um mecanismo de pesquisa de semelhança vetorial de código aberto que armazena, indexa e pesquisa dados vetoriais em grande escala de forma eficiente. É comumente usado em aplicações de aprendizado de máquina, inteligência artificial e ciência de dados.

Os dados vetoriais codificam informações como vetores matemáticos, que são matrizes de números ou coordenadas. Os sistemas de aprendizado de máquina 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. Ao compará-los, os sistemas podem classificar, pesquisar e identificar clusters de objetos.

Neste artigo, você aprenderá a usar a integração .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 servidor como o tipo QdrantServerResource. Para acessar esse tipo e APIs, adicione o 📦Aspire. Hosting.Qdrant pacote NuGet no aplicativo hospedar projeto.

dotnet add package Aspire.Hosting.Qdrant

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

Adicionar recurso Qdrant

Em seu projeto de host de aplicativo, chame AddQdrant para adicionar e retornar um construtor 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...

Observação

O contêiner Qdrant pode ser lento a iniciar, por isso é melhor utilizar um tempo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso de contêiner.

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

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

Dica

Se você preferir se conectar a um servidor Qdrant existente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Dica

A imagem de contêiner qdrant/qdrant inclui uma interface do usuário da Web que você pode usar para explorar seus vetores e administrar o banco de dados. Para aceder a essa ferramenta, inicie a sua solução .NET Aspire e, em seguida, no dashboard .NET Aspire, selecione o endpoint para o recurso Qdrant. Na barra de endereço do navegador, adicione /dashboard e pressione Enter.

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

Para se conectar ao Qdrant um cliente deve passar a chave de API correta. No código acima, quando .NET.NET Aspire adiciona um recurso Qdrant à sua solução, ele define a chave da 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 suporta 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 para passar 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 de 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 persistir os dados do 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 preferidos em relação a montagens bind , consulte a documentação Docker: Volumes.

Adicionar recurso Qdrant com montagem de ligação de dados

Para adicionar uma montagem de ligaçã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...

Importante

Montagens de ligação de dados têm funcionalidade limitada em comparação com volumes , que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos da máquina host para manter os dados do Qdrant nas reinicializações do contêiner. A montagem de ligação de dados é montada na pasta C:\Qdrant\Data no Windows (ou /Qdrant/Data no Unix) na máquina host no contêiner Qdrant. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

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

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

Client integração

Para começar com a integração do cliente Qdrant .NET.NET Aspire, instale o pacote NuGet 📦Aspire.Qdrant.Client no projeto que consome o cliente, ou seja, no projeto do aplicativo que utiliza o cliente Qdrant. A integração do cliente Qdrant regista uma instância de Qdrant.Client.QdrantClient que pode ser usada para interagir com dados vetoriais do Qdrant.

dotnet add package Aspire.Qdrant.Client

Adicionar um cliente Qdrant

No arquivo Program.cs do seu projeto que utiliza clientes, chame o método de extensão AddQdrantClient em qualquer IHostApplicationBuilder para registar um QdrantClient para uso através do contentor de injeção de dependências. O método usa um parâmetro de nome de conexão.

builder.AddQdrantClient("qdrant");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Qdrant no projeto de host do aplicativo. Em outras palavras, quando você chama AddQdrant e fornece um nome de qdrant esse mesmo nome deve ser usado ao chamar AddQdrantClient. Para obter mais informações, consulte Adicionar recurso Qdrant.

Em seguida, você pode recuperar a instância QdrantClient usando a 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 a injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente Qdrant com chave

Pode haver situações em que você queira 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, poderás recuperar as instâncias 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 com chave, consulte .NET injeção de dependência: Serviços com chave.

Configuração

A integração do cliente .NET.NET Aspire Qdrant 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 string de conexão

Ao usar uma cadeia de conexão da seção de configuração de 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 utiliza o endpoint da API gRPC.

Usar provedores de configuração

A integração do cliente .NET.NET Aspire Qdrant suporta Microsoft.Extensions.Configuration. Ele carrega o QdrantClientSettings da configuração usando a chave Aspire:Qdrant:Client. Segue-se 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 cliente Qdrant JSON, consulte Aspire.Qdrant.Client/ConfigurationSchema.json.

Usar delegados embutidos

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

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

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

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

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção de Configuração .

Registo

A integração do .NET Aspire Qdrant utiliza registo padrão de .NET e verá entradas de log da seguinte categoria:

  • Qdrant.Client

Rastreio

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

Métricas

Atualmente, a integração do .NET.NET Aspire Qdrant não emite métricas porque elas não são suportadas pela biblioteca Qdrant.Client.

Ver também