integração de banco de dados .NET AspireMilvus
Inclui:
integração de hospedagem e integraçãoClient
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
O serviço de hospedagem do banco de dados Milvus integra modelos de server 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 do 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 applications.
Adicionar Milvusserver 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 Milvusserverexistente, 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
{
"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 preferenciais em vez de associar montagens, consulte Docker documentos: 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 de dados associam montagens 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 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.
As montagens de dados dependem do sistema de arquivos da máquina host para manter os dados Milvus durante as reinicializações do contêiner. A vinculação de dados está montada no caminho C:\Milvus\Data no Windows (ou /Milvus/Data no Unix) no computador 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
Para começar a usar a integração .NET AspireMilvusclient, instale o 📦Aspire.Milvus.Client pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o banco de dados Milvusclient. A integração Milvusclient registra uma instância Milvus.Client. MilvusClient que você pode usar para interagir com bancos de dados Milvus.
dotnet add package Aspire.Milvus.Client
Adicionar um Milvusclient
No arquivo Program.cs do seu projeto que consome client, 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 Milvusserver 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 Milvusclient com chave
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 .NET AspireMilvusclient 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 client na sua solução .NET Aspire usando a mesma senha ou outras configurações.
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.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 .NET AspireMilvusclient 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 JSON de integração Milvusclient completo, 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 Milvusserver. - Usa o client 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 de .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.
