Compartilhar via

integração de banco de dados .NET AspireMilvus

  • Artigo

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

Milvus é um sistema de banco de dados 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 de banco de dados .NET AspireMilvus. A integração do banco de dados .NET AspireMilvus permite que você se conecte a bancos de dados Milvus existentes ou crie novas instâncias com a imagem de contêiner milvusdb/milvus.

Integração de hospedagem

A integração de hospedagem do banco de dados Milvus modela o servidor como o tipo MilvusServerResource e o banco de dados como o tipo MilvusDatabaseResource. Para acessar esses tipos e APIs, adicione o pacote NuGet 📦Aspire.Hosting.Milvus no projeto host do aplicativo .

dotnet add package Aspire.Hosting.Milvus

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

Adicionar servidor Milvus e recursos de banco de dados

No projeto de host do aplicativo, chame AddMilvus para adicionar e retornar um construtor de recursos Milvus. Encadeie uma chamada ao construtor de recursos retornado para AddDatabase, a fim de adicionar um recurso de banco de dados Milvus.

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

// After adding all resources, run the app...

Nota

O contêiner de Milvus pode ser lento para iniciar, portanto, é melhor usar um ciclo 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, conforme mostrado no exemplo anterior com a imagem milvusdb/milvus, ele cria uma nova instância de Milvus em seu computador local. Uma referência ao construtor de recursos Milvus (a variável milvus) é usada para adicionar um banco de dados. O banco de dados é nomeado milvusdb e, em seguida, adicionado ao ExampleProject.

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

Dica

Se você preferir se conectar a um servidor Milvus existente, chame AddConnectionString em vez disso. Para obter mais informações, veja Recursos existentes de referência.

Manipulando credenciais e passando outros parâmetros para o recurso Milvus

O recurso Milvus inclui credenciais padrão, com um username de root e a senha Milvus. Milvus dá suporte a senhas padrão baseadas em configuração usando a variável de ambiente COMMON_SECURITY_DEFAULTROOTPASSWORD. Para alterar a senha padrão no contêiner, passe um parâmetro apiKey ao chamar a API de hospedagem AddMilvus:

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

var milvus = builder.AddMilvus("milvus", apiKey);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(milvus);

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

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

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

Adicionar um recurso Milvus com um volume de dados

Para adicionar um volume de dados ao recurso de serviço Milvus, chame o método WithDataVolume no recurso Milvus:

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataVolume();

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

// After adding all resources, run the app...

O volume de dados é utilizado para armazenar permanentemente os dados de Milvus, fora do ciclo de vida do contêiner. O volume de dados é montado no caminho /var/lib/milvus no contêiner SQL Server 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 vez de montagens bind, consulte a Docker documentação: Volumes.

Adicionar um recurso Milvus com uma montagem de associação de dados

Para adicionar uma montagem de associação de dados ao recurso Milvus, chame o método WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataBindMount(source: @"C:\Milvus\Data");

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

// After adding all resources, run the app...

Importante

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

Montagens de vinculação de dados dependem do sistema de arquivos da máquina host para persistir os dados Milvus durante as reinicializações do contêiner. A montagem de vinculação de dados é feita no caminho C:\Milvus\Data no Windows (ou /Milvus/Data no Unix) na máquina host no contêiner Milvus. Para obter mais informações sobre montagens de ligação de dados, consulte Docker documentação: Montagens de ligação.

Criar um recurso do Attu

Attu é uma GUI (interface gráfica do usuário) e uma ferramenta de gerenciamento projetada para interagir com Milvus e seus bancos de dados. Ele inclui recursos avançados de visualização que podem ajudá-lo a investigar e entender seus dados de vetor.

Se você quiser usar o Attu para gerenciar Milvus em sua solução .NET Aspire, chame o método de extensão WithAttu em seu recurso de Milvus. O método cria um contêiner a partir da imagem zilliz/attu:

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithAttu()
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(milvusdb)
       .WaitFor(milvusdb);

// After adding all resources, run the app...

Ao depurar a solução .NET.NET Aspire, você verá um contêiner Attu listado nos recursos da solução. Selecione o ponto de extremidade do recurso para abrir a GUI e começar a gerenciar bancos de dados.

integração Client (versão prévia)

Para começar com a integração com o cliente .NET AspireMilvus, instale o pacote NuGet 📦Aspire.Milvus.Client no projeto que faz uso do cliente, ou seja, o projeto do aplicativo que utiliza o cliente de banco de dados Milvus. A integração do cliente Milvus registra um Milvus.Client. MilvusClient instância que você pode usar para interagir com bancos de dados Milvus.

dotnet add package Aspire.Milvus.Client

Adicionar um cliente Milvus

No arquivo Program.cs do projeto que consome o cliente, chame o método de extensão AddMilvusClient em qualquer IHostApplicationBuilder para registrar um MilvusClient 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.AddMilvusClient("milvusdb");

Dica

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

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

public class ExampleService(MilvusClient client)
{
    // Use the Milvus Client...
}

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

Adicionar um cliente com chave Milvus

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

builder.AddKeyedMilvusClient(name: "mainDb");
builder.AddKeyedMilvusClient(name: "loggingDb");

Importante

Ao usar serviços com chave, espera-se que seu recurso de Milvus configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

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

public class ExampleService(
    [FromKeyedServices("mainDb")] MilvusClient mainDbClient,
    [FromKeyedServices("loggingDb")] MilvusClient loggingDbClient)
{
    // 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 AspireMilvus fornece várias opções para configurar a conexão com Milvus com base nos requisitos e convenções do seu projeto.

Dica

O uso padrão é root e a senha padrão é Milvus. Para configurar uma senha diferente no contêiner Milvus, consulte Manipulando credenciais e passando outros parâmetros para o recurso Milvus. Use as técnicas a seguir para configurar o consumo de aplicativos cliente em sua solução .NET.NET Aspire com a mesma senha ou outras configurações.

Usar uma string 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.AddMilvusClient():

builder.AddMilvusClient("milvus");

Em seguida, a cadeia de conexão será recuperada da seção de configuração do ConnectionStrings:

{
  "ConnectionStrings": {
    "milvus": "Endpoint=http://localhost:19530/;Key=root:Non-default-P@ssw0rd"
  }
}

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

Usar provedores de configuração

A integração do cliente .NET AspireMilvus dá suporte a Microsoft.Extensions.Configuration. Ele carrega o MilvusClientSettings a partir da configuração utilizando a chave Aspire:Milvus:Client. O snippet a seguir é um exemplo de um appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Milvus": {
      "Client": {
        "Endpoint": "http://localhost:19530/",
        "Database": "milvusdb",
        "Key": "root:Non-default-P@ssw0rd",
        "DisableHealthChecks": false
      }
    }
  }
}

Para obter o esquema Milvus de integração completa do cliente JSON, consulte Aspire.Milvus.Client/ConfigurationSchema.json.

Usar delegados embutidos

Além disso, você pode passar o delegado Action<MilvusSettings> configureSettings para definir algumas ou todas as opções diretamente, por exemplo, para definir a chave de API no código:

builder.AddMilvusClient(
    "milvus",
    static settings => settings.Key = "root:Non-default-P@ssw0rd");

Client checagens de saúde da integração

Por padrão, as integrações .NET.NET Aspire ativam 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.

A integração do banco de dados .NET AspireMilvus:

  • Adiciona a verificação de integridade quando MilvusClientSettings.DisableHealthChecks é false, que tenta se conectar ao servidor Milvus.
  • Usa o cliente configurado para executar um HealthAsync. Se o resultado for saudável, a verificação de saúde será considerada saudável, caso contrário, não será saudável. Da mesma forma, se houver uma exceção, a verificação de saúde será considerada não saudável, com o erro propagando-se através da falha na verificação de saúde.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente Registro, Rastreamento e Métricas, que às vezes são conhecidos 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 banco de dados .NET AspireMilvus usa o registro padrão .NET, e você verá entradas de log da seguinte categoria:

  • Milvus.Client

Rastreamento

No momento, a integração de banco de dados .NET AspireMilvus não emite atividades de rastreamento porque elas não têm suporte na biblioteca de Milvus.Client.

Métricas

No momento, a integração de banco de dados .NET AspireMilvus não emite métricas porque elas não têm suporte na biblioteca de Milvus.Client.

Consulte também