🚀 Prova Zilliz Cloud, la versione completamente gestita di Milvus, gratuitamente—sperimenta prestazioni 10 volte più veloci! Prova Ora>>

Inizia

Home BlogsCome contribuire a Milvus: una guida rapida per gli sviluppatori

Come contribuire a Milvus: una guida rapida per gli sviluppatori

Engineering

December 01, 2024

Shaoting Huang

Milvus è un database vettoriale open-source progettato per gestire dati vettoriali ad alta dimensionalità. Se state costruendo motori di ricerca intelligenti, sistemi di raccomandazione o soluzioni AI di nuova generazione come la retrieval augmented generation(RAG), Milvus è uno strumento potente a portata di mano.

Ma ciò che fa progredire Milvus non è solo la sua tecnologia avanzata: è la vivace e appassionata comunità di sviluppatori che lo sostiene. Come progetto open-source, Milvus prospera e si evolve grazie ai contributi di sviluppatori come voi. Ogni correzione di bug, aggiunta di funzionalità e miglioramento delle prestazioni da parte della comunità rende Milvus più veloce, più scalabile e più affidabile.

Se siete appassionati di open-source, desiderosi di imparare o di avere un impatto duraturo sull'IA, Milvus è il luogo ideale per contribuire. Questa guida vi guiderà attraverso il processo, dalla configurazione dell'ambiente di sviluppo all'invio della vostra prima richiesta di pull. Evidenzieremo anche le sfide più comuni che potreste incontrare e forniremo le soluzioni per superarle.

Pronti a tuffarvi? Rendiamo Milvus ancora migliore insieme!

Impostazione dell'ambiente di sviluppo Milvus

Prima di tutto, la configurazione dell'ambiente di sviluppo. Potete installare Milvus sul vostro computer locale o usare Docker: entrambi i metodi sono semplici, ma dovrete anche installare alcune dipendenze di terze parti per far funzionare tutto.

Costruire Milvus in locale

Se vi piace costruire le cose da zero, costruire Milvus sul vostro computer locale è un gioco da ragazzi. Milvus semplifica le cose raggruppando tutte le dipendenze nello script install_deps.sh. Ecco la configurazione rapida:

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

# Compile Milvus.
$ make

Costruire Milvus con Docker

Se si preferisce Docker, ci sono due modi per farlo: si possono eseguire i comandi in un container precostituito o creare un container dev per un approccio più pratico.

# 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

Note sulla piattaforma: Se si utilizza Linux, i problemi di compilazione sono piuttosto rari. Tuttavia, gli utenti Mac, specialmente con i chip M1, potrebbero incontrare qualche problema lungo il percorso. Non preoccupatevi, però: abbiamo una guida che vi aiuterà a risolvere i problemi più comuni.

Figura: Configurazione del sistema operativo

Per la guida completa alla configurazione, consultate la Guida ufficiale allo sviluppo di Milvus.

Problemi comuni e come risolverli

A volte la configurazione dell'ambiente di sviluppo Milvus non va come previsto. Non preoccupatevi: ecco una rapida carrellata di problemi comuni che potreste incontrare e come risolverli rapidamente.

Homebrew: Disconnessione inattesa durante la lettura del pacchetto Sideband

Se state usando Homebrew e vedete un errore come questo:

==> 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~ %

Correggere: aumentare la dimensione di http.postBuffer:

git config --global http.postBuffer 1M

Se anche voi vi imbattete in Brew: command not found dopo aver installato Homebrew, potrebbe essere necessario impostare la configurazione dell'utente Git:

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

Docker: errore nell'ottenere le credenziali

Quando si lavora con Docker, si può vedere questo errore:

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

Correzione: Aprire~/.docker/config.json e rimuovere il campo credsStore.

Python: Nessun modulo chiamato 'imp'

Se Python lancia questo errore, è perché Python 3.12 ha rimosso il modulo imp, che alcune vecchie dipendenze utilizzano ancora.

Correggere: Passare a Python 3.11:

brew install python@3.11

Conan: Argomenti non riconosciuti o Comando non trovato

Problema: Se viene visualizzato Unrecognized arguments: --install-folder conan, è probabile che si stia utilizzando una versione di Conan non compatibile.

Correggere: Aggiornare a Conan 1.61:

pip install conan==1.61

Problema: Se si vede Conan command not found, significa che l'ambiente Python non è configurato correttamente.

Correggere: Aggiungere la directory bin di Python a PATH:

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

LLVM: Use of Undeclared Identifier 'kSecFormatOpenSSL' (Uso di un identificatore non dichiarato)

Questo errore di solito indica che le dipendenze di LLVM sono obsolete.

Correggere: Reinstallare LLVM 15 e aggiornare le variabili d'ambiente:

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

Suggerimenti utili

Controllate sempre due volte le versioni degli strumenti e le dipendenze.
Se qualcosa ancora non funziona, la pagina Milvus GitHub Issues è un ottimo posto per trovare risposte o chiedere aiuto.

Configurazione di VS Code per l'integrazione di C++ e Go

Far lavorare insieme C++ e Go in VS Code è più facile di quanto sembri. Con la giusta configurazione, è possibile semplificare il processo di sviluppo per Milvus. Basta modificare il file user.settings con la configurazione qui sotto:

{
   "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"
}

Ecco cosa fa questa configurazione:

Variabili d'ambiente: Imposta i percorsi per PKG_CONFIG_PATH, LD_LIBRARY_PATH e RPATH, che sono fondamentali per individuare le librerie durante la compilazione e i test.
Integrazione degli strumenti di Go: Abilita il server linguistico di Go (gopls) e configura strumenti come gofumpt per la formattazione e golangci-lint per il linting.
Configurazione dei test: Aggiunge testTags e aumenta il timeout per l'esecuzione dei test a 10 minuti.

Una volta aggiunto, questo setup assicura una perfetta integrazione tra i flussi di lavoro di C++ e Go. È perfetto per costruire e testare Milvus senza dover modificare continuamente l'ambiente.

Suggerimento

Dopo averla impostata, eseguire una rapida compilazione di prova per verificare che tutto funzioni. Se qualcosa non funziona, ricontrollate i percorsi e la versione dell'estensione Go di VS Code.

Distribuzione di Milvus

Milvus supporta tre modalità di distribuzione: Lite, Standalone e Distributed.

Milvus Lite è una libreria Python e una versione ultra-leggera di Milvus. È perfetta per la prototipazione rapida in ambienti Python o notebook e per esperimenti locali su piccola scala.
Milvus Standalone è l'opzione di distribuzione a singolo nodo di Milvus, che utilizza un modello client-server. È l'equivalente Milvus di MySQL, mentre Milvus Lite è come SQLite.
Milvus Distributed è la modalità distribuita di Milvus, ideale per gli utenti aziendali che costruiscono sistemi di database vettoriali su larga scala o piattaforme di dati vettoriali.

Tutte queste implementazioni si basano su tre componenti fondamentali:

Milvus: il motore del database vettoriale che gestisce tutte le operazioni.
Etcd: Il motore di metadati che gestisce i metadati interni di Milvus.
MinIO: il motore di archiviazione che garantisce la persistenza dei dati.

Quando viene eseguito in modalità distribuita, Milvus incorpora anche Pulsar per l'elaborazione distribuita dei messaggi utilizzando un meccanismo Pub/Sub, che lo rende scalabile per ambienti ad alta produttività.

Milvus Standalone

La modalità Standalone è adatta a configurazioni a singola istanza, ed è quindi perfetta per i test e le applicazioni su piccola scala. Ecco come iniziare:

# 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 (precedentemente noto come Milvus Cluster)

Per i set di dati più grandi e il traffico più elevato, la modalità distribuita offre una scalabilità orizzontale. Combina più istanze Milvus in un unico sistema coeso. L'implementazione è facilitata da Milvus Operator, che gira su Kubernetes e gestisce l'intero stack Milvus per voi.

Volete una guida passo passo? Consultate la Guida all'installazione di Milvus.

Esecuzione dei test end-to-end (E2E)

Una volta che la distribuzione di Milvus è attiva e funzionante, la verifica della sua funzionalità è un gioco da ragazzi con i test E2E. Questi test coprono ogni parte della configurazione per garantire che tutto funzioni come previsto. Ecco come eseguirli:

# Navigate to the test directory  
cd tests/python_client  

# Install dependencies  
pip install -r requirements.txt  

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

Per istruzioni approfondite e suggerimenti per la risoluzione dei problemi, consultate la Guida allo sviluppo di Milvus.

Suggerimento professionale

Se siete alle prime armi con Milvus, iniziate con la modalità Milvus Lite o Standalone per capire le sue capacità prima di passare alla modalità Distributed per i carichi di lavoro di produzione.

Invio del codice

Congratulazioni! Avete superato tutti i test unitari e E2E (o avete eseguito il debug e la ricompilazione, se necessario). Anche se la prima compilazione può richiedere un po' di tempo, quelle successive saranno molto più veloci, quindi non c'è da preoccuparsi. Se tutto è stato superato, siete pronti a inviare le vostre modifiche e a contribuire a Milvus!

Collegate la vostra richiesta di pull (PR) a un problema

Ogni PR a Milvus deve essere collegata a un problema pertinente. Ecco come fare:

Verificare la presenza di problemi esistenti: Cercate nel tracker dei problemi di Milvus per vedere se c'è già un problema relativo alle vostre modifiche.
Creare un nuovo problema: Se non esiste un problema pertinente, apritene uno nuovo e spiegate il problema che state risolvendo o la funzionalità che state aggiungendo.

Inviare il codice

Fare il fork del repository: Iniziate con il fork del repository Milvus sul vostro account GitHub.
Creare un ramo: Clonate il fork localmente e create un nuovo ramo per le vostre modifiche.
Impegnarsi con una firma firmata: Assicuratevi che i vostri commit includano una firma Signed-off-by per rispettare le licenze open-source:

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

Questo passaggio certifica che il vostro contributo è in linea con il Developer Certificate of Origin (DCO).

Risorse utili

Per i passi dettagliati e le migliori pratiche, consultate la Guida ai contributi di Milvus.

Opportunità di contribuire

Congratulazioni, Milvus è pronto e funzionante! Avete esplorato le modalità di distribuzione, eseguito i test e forse anche scavato nel codice. Ora è il momento di salire di livello: contribuite a Milvus e aiutate a plasmare il futuro dell'intelligenza artificiale e dei dati non strutturati.

Indipendentemente dalle tue competenze, c'è un posto per te nella comunità Milvus! Che tu sia uno sviluppatore che ama risolvere sfide complesse, un tech writer che ama scrivere documentazione pulita o blog di ingegneria, o un appassionato di Kubernetes che vuole migliorare le distribuzioni, c'è un modo per avere un impatto.

Date un'occhiata alle opportunità qui di seguito e trovate la vostra corrispondenza perfetta. Ogni contributo aiuta a far progredire Milvus e chi lo sa? La vostra prossima richiesta di pull potrebbe dare il via alla prossima ondata di innovazione. Quindi, cosa state aspettando? Cominciamo! 🚀

I progetti	Adatto per	Linee guida
milvus, milvus-sdk-go	Sviluppatori Go	/
milvus, knowhere	Sviluppatori CPP	/
pymilvus, milvus-sdk-node, milvus-sdk-java	Sviluppatori interessati ad altri linguaggi	Contribuire a PyMilvus
milvus-helm	Appassionati di Kubernetes	/
Milvus-docs, milvus-io/community/blog	Scrittori tecnici	Contribuire ai documenti di milvus
milvus-insight	Sviluppatori web	/

Una parola finale

Milvus offre diversi SDK - Python (PyMilvus), Java, Go e Node.js - cherendono semplice iniziare a costruire. Contribuire a Milvus non è solo una questione di codice, ma è anche unirsi a una comunità vibrante e innovativa.

🚀Benvenuti nella comunità di sviluppatori Milvus e buon lavoro! Non vediamo l'ora di vedere cosa creerete.