Como contribuir para o Milvus: um início rápido para os programadores

O Milvus é uma base de dados vetorial de código aberto concebida para gerir dados vectoriais de elevada dimensão. Quer esteja a construir motores de pesquisa inteligentes, sistemas de recomendação ou soluções de IA de última geração, como a geração aumentada de recuperação(RAG), o Milvus é uma ferramenta poderosa na ponta dos dedos.

Mas o que realmente faz avançar o Milvus não é apenas a sua tecnologia avançada - é a vibrante e apaixonada comunidade de programadores que está por detrás dele. Sendo um projeto de código aberto, o Milvus prospera e evolui graças às contribuições de programadores como você. Cada correção de erros, adição de funcionalidades e melhoria de desempenho da comunidade torna o Milvus mais rápido, mais escalável e mais fiável.

Quer seja um apaixonado pelo código aberto, esteja ansioso por aprender ou queira ter um impacto duradouro na IA, o Milvus é o local perfeito para contribuir. Este guia irá guiá-lo através do processo - desde a configuração do seu ambiente de desenvolvimento até à submissão do seu primeiro pull request. Também destacaremos os desafios comuns que poderá enfrentar e forneceremos soluções para os ultrapassar.

Pronto para mergulhar? Vamos tornar o Milvus ainda melhor juntos!

Configurando seu ambiente de desenvolvimento Milvus

A primeira coisa a fazer é configurar o seu ambiente de desenvolvimento. Você pode instalar o Milvus em sua máquina local ou usar o Docker - ambos os métodos são simples, mas você também precisará instalar algumas dependências de terceiros para colocar tudo em funcionamento.

Construindo o Milvus localmente

Se você gosta de construir coisas do zero, construir o Milvus em sua máquina local é muito fácil. O Milvus torna-o fácil ao juntar todas as dependências no script install_deps.sh. Aqui está a configuração rápida:

# Install third-party dependencies.
$ cd milvus/
$ ./scripts/install_deps.sh

# Compile Milvus.
$ make

Construindo o Milvus com Docker

Se preferir o Docker, há duas maneiras de o fazer: pode executar comandos num contentor pré-construído ou criar um contentor de desenvolvimento para uma abordagem mais prática.

# Option 1: Run commands in a pre-built Docker container  
build/builder.sh make  

# Option 2: Spin up a dev container  
./scripts/devcontainer.sh up  
docker-compose -f docker-compose-devcontainer.yml ps  
docker exec -ti milvus-builder-1 bash  
make milvus  

Notas sobre a plataforma: Se você está no Linux, você está pronto para ir - problemas de compilação são muito raros. No entanto, os utilizadores de Mac, especialmente com chips M1, podem deparar-se com alguns problemas ao longo do caminho. Mas não se preocupe - nós temos um guia para o ajudar a resolver os problemas mais comuns.

Figura: Configuração do SO

Para obter o guia de configuração completo, consulte o Guia de desenvolvimento oficial do Milvus.

Problemas comuns e como resolvê-los

Por vezes, a configuração do seu ambiente de desenvolvimento Milvus não corre tão bem como planeado. Não se preocupe - aqui está um resumo rápido dos problemas comuns que pode encontrar e como os resolver rapidamente.

Homebrew: Desconexão inesperada ao ler pacote de banda lateral

Se estiver a utilizar o Homebrew e vir um erro como este:

==> Tapping homebrew/core
remote: Enumerating objects: 1107077, done.
remote: Counting objects: 100% (228/228), done.
remote: Compressing objects: 100% (157/157), done.
error: 545 bytes of body are still expected.44 MiB | 341.00 KiB/s
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: index-pack failed
Failed during: git fetch --force origin refs/heads/master:refs/remotes/origin/master
myuser~ %

Correção: Aumente o tamanho do http.postBuffer:

git config --global http.postBuffer 1M

Se também se deparar com Brew: command not found depois de instalar o Homebrew, poderá ter de definir a configuração do seu utilizador Git:

git config --global user.email xxxgit config --global user.name xxx

Docker: Erro ao obter credenciais

Ao trabalhar com o Docker, você pode ver isso:

error getting credentials - err: exit status 1, out: ``  

Correção: Abra~/.docker/config.json e remova o campo credsStore.

Python: Nenhum módulo com o nome 'imp'

Se o Python lançar este erro, é porque o Python 3.12 removeu o módulo imp, que algumas dependências mais antigas ainda usam.

Correção: Faça downgrade para Python 3.11:

brew install python@3.11  

Conan: argumentos não reconhecidos ou comando não encontrado

Problema: Se vir Unrecognized arguments: --install-folder conan, é provável que esteja a utilizar uma versão incompatível do Conan.

Correção: Faça o downgrade para Conan 1.61:

pip install conan==1.61  

Problema: Se você vir Conan command not found, significa que seu ambiente Python não está configurado corretamente.

Correção: adicione o diretório bin do Python ao seu PATH:

export PATH="/path/to/python/bin:$PATH"

LLVM: Uso de identificador não declarado 'kSecFormatOpenSSL'

Este erro normalmente significa que suas dependências LLVM estão desatualizadas.

Correção: Reinstale o LLVM 15 e atualize suas variáveis de ambiente:

brew reinstall llvm@15
export LDFLAGS="-L/opt/homebrew/opt/llvm@15/lib"
export CPPFLAGS="-I/opt/homebrew/opt/llvm@15/include"

Dicas profissionais

• Sempre verifique novamente as versões e dependências de suas ferramentas.

• Se algo ainda não funcionar, a página de problemas do Milvus GitHub é um ótimo lugar para encontrar respostas ou pedir ajuda.

Configurando o VS Code para integração do C++ e Go

Fazer com que o C++ e o Go trabalhem juntos no VS Code é mais fácil do que parece. Com a configuração correta, pode simplificar o seu processo de desenvolvimento para o Milvus. Basta ajustar o seu ficheiro user.settings com a configuração abaixo:

{
   "go.toolsEnvVars": {
       "PKG_CONFIG_PATH": "/Users/zilliz/milvus/internal/core/output/lib/pkgconfig:/Users/zilliz/workspace/milvus/internal/core/output/lib64/pkgconfig",
       "LD_LIBRARY_PATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64",
       "RPATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64"
   },
   "go.testEnvVars": {
       "PKG_CONFIG_PATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib/pkgconfig:/Users/zilliz/workspace/milvus/internal/core/output/lib64/pkgconfig",
       "LD_LIBRARY_PATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64",
       "RPATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64"
   },
   "go.buildFlags": [
       "-ldflags=-r /Users/zilliz/workspace/milvus/internal/core/output/lib"
   ],
   "terminal.integrated.env.linux": {
       "PKG_CONFIG_PATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib/pkgconfig:/Users/zilliz/workspace/milvus/internal/core/output/lib64/pkgconfig",
       "LD_LIBRARY_PATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64",
       "RPATH": "/Users/zilliz/workspace/milvus/internal/core/output/lib:/Users/zilliz/workspace/milvus/internal/core/output/lib64"
   },
   "go.useLanguageServer": true,
   "gopls": {
       "formatting.gofumpt": true
   },
   "go.formatTool": "gofumpt",
   "go.lintTool": "golangci-lint",
   "go.testTags": "dynamic",
   "go.testTimeout": "10m"
}

Veja o que essa configuração faz:

• Variáveis de ambiente: Define caminhos para PKG_CONFIG_PATH, LD_LIBRARY_PATH, e RPATH, que são críticos para localizar bibliotecas durante compilações e testes.

• Integração de ferramentas Go: Habilita o servidor de linguagem Go (gopls) e configura ferramentas como gofumpt para formatação e golangci-lint para linting.

• Configuração de teste: Adiciona o testTags e aumenta o tempo limite para a execução de testes para 10 minutos.

Uma vez adicionada, essa configuração garante uma integração perfeita entre os fluxos de trabalho C++ e Go. É perfeita para construir e testar o Milvus sem ajustes constantes no ambiente.

Dica profissional

Depois de configurar isso, execute uma compilação de teste rápida para confirmar que tudo funciona. Se algo parecer errado, verifique novamente os caminhos e a versão da extensão Go do VS Code.

Implantando o Milvus

O Milvus suporta três modos de implantação - Lite, Standalone e Distributed.

• Milvus Lite é uma biblioteca Python e uma versão ultra-leve do Milvus. É perfeito para prototipagem rápida em ambientes Python ou notebook e para experiências locais de pequena escala.

• Milvus Standalone é a opção de implantação de nó único para Milvus, usando um modelo cliente-servidor. É o equivalente Milvus do MySQL, enquanto o Milvus Lite é como o SQLite.

• O Milvus Distributed é o modo distribuído do Milvus, ideal para utilizadores empresariais que criam sistemas de bases de dados vectoriais em grande escala ou plataformas de dados vectoriais.

Todas estas implementações dependem de três componentes principais:

• Milvus: O motor de base de dados vetorial que conduz todas as operações.

• Etcd: O mecanismo de metadados que gerencia os metadados internos do Milvus.

• MinIO: O mecanismo de armazenamento que garante a persistência dos dados.

Quando executado no modo Distribuído, o Milvus também incorpora o Pulsar para processamento de mensagens distribuídas usando um mecanismo Pub/Sub, tornando-o escalável para ambientes de alto rendimento.

Milvus Autónomo

O modo Standalone é feito sob medida para configurações de instância única, tornando-o perfeito para testes e aplicações de pequena escala. Veja como começar:

# Deploy Milvus Standalone  
sudo docker-compose -f deployments/docker/dev/docker-compose.yml up -d
# Start the standalone service  
bash ./scripts/start_standalone.sh

Milvus Distributed (anteriormente conhecido como Milvus Cluster)

Para conjuntos de dados maiores e maior tráfego, o modo Distribuído oferece escalabilidade horizontal. Ele combina várias instâncias do Milvus em um único sistema coeso. A implantação é facilitada com o Milvus Operator, que é executado no Kubernetes e gerencia toda a pilha do Milvus para você.

Deseja orientação passo a passo? Confira o Guia de instalação do Milvus.

Executando testes de ponta a ponta (E2E)

Depois que a implantação do Milvus estiver em funcionamento, testar sua funcionalidade é muito fácil com os testes E2E. Estes testes cobrem todas as partes da sua configuração para garantir que tudo funciona como esperado. Veja como executá-los:

# Navigate to the test directory  
cd tests/python_client  

# Install dependencies  
pip install -r requirements.txt  

# Run E2E tests  
pytest --tags=L0 -n auto  

Para obter instruções detalhadas e dicas de resolução de problemas, consulte o Guia de desenvolvimento do Milvus.

Dica profissional

Se for novo no Milvus, comece com o Milvus Lite ou o modo Standalone para ter uma ideia das suas capacidades antes de passar para o modo Distributed para cargas de trabalho ao nível da produção.

Enviando seu código

Parabéns! Você passou por todos os testes unitários e E2E (ou depurou e recompilou conforme necessário). Embora a primeira compilação possa levar algum tempo, as futuras serão muito mais rápidas - portanto, não precisa se preocupar. Com tudo aprovado, está pronto para submeter as suas alterações e contribuir para o Milvus!

Ligar o seu Pull Request (PR) a uma Issue

Cada PR para o Milvus precisa de estar ligado a uma issue relevante. Aqui está como lidar com isso:

• Verifique se há problemas existentes: Procure no rastreador de problemas do Milvus para ver se já existe um problema relacionado com as suas alterações.

• Criar um novo problema: Se não existir um problema relevante, abra um novo e explique o problema que está a resolver ou a funcionalidade que está a adicionar.

Submeter o seu código

1. Bifurcar o repositório: Comece por bifurcar o repositório Milvus na sua conta GitHub.

2. Criar uma ramificação: Clone o seu fork localmente e crie um novo branch para as suas alterações.

3. Faça o commit com a assinatura de desligamento: Certifique-se de que os seus commits incluem uma assinatura Signed-off-by para cumprir o licenciamento de código aberto:

git commit -m "Commit of your change" -s

Esta etapa certifica que sua contribuição está de acordo com o Certificado de Origem do Desenvolvedor (DCO).

Recursos úteis

Para obter passos detalhados e melhores práticas, consulte o Guia de Contribuição Milvus.

Oportunidades para contribuir

Parabéns - você tem o Milvus instalado e funcionando! Explorou os seus modos de implementação, executou os seus testes e talvez até tenha aprofundado o código. Agora está na altura de subir de nível: contribuir para o Milvus e ajudar a moldar o futuro da IA e dos dados não estruturados.

Independentemente das suas competências, há um lugar para si na comunidade Milvus! Quer seja um programador que adora resolver desafios complexos, um escritor de tecnologia que adora escrever documentação limpa ou blogues de engenharia, ou um entusiasta de Kubernetes que procura melhorar as implementações, há uma forma de causar impacto.

Dê uma vista de olhos às oportunidades abaixo e encontre a sua combinação perfeita. Cada contribuição ajuda a fazer avançar o Milvus - e quem sabe? O seu próximo pull request pode ser o motor da próxima onda de inovação. Então, de que está à espera? Vamos começar! 🚀

Projectos	Adequado para	Diretrizes
milvus, milvus-sdk-go	Programadores Go	/
milvus, knowhere	Programadores CPP	/
pymilvus, milvus-sdk-node, milvus-sdk-java	Desenvolvedores interessados em outras linguagens	Contribuindo para o PyMilvus
milvus-helm	Entusiastas de Kubernetes	/
Milvus-docs, milvus-io/community/blog	Escritores técnicos	Contribuir para os documentos do milvus
milvus-insight	Programadores Web	/

Uma palavra final

Milvus oferece vários SDKs-Python (PyMilvus), Java, Go, e Node.js-quetornam simples começar a construir. Contribuir para o Milvus não se trata apenas de código - trata-se de se juntar a uma comunidade vibrante e inovadora.

Bem-vindo à comunidade de programadores Milvus e boa codificação! Mal podemos esperar para ver o que vais criar.

Ler mais

• Junte-se à comunidade Milvus de programadores de IA

• O que são bases de dados vectoriais e como funcionam?

• Milvus Lite vs. Autónomo vs. Distribuído: Qual é o modo certo para si?

• Crie aplicativos de IA com o Milvus: tutoriais e notebooks

• Modelos de IA de alto desempenho para seus aplicativos GenAI | Zilliz

• O que é RAG?

• Centro de recursos de IA generativa | Zilliz