Blog
Como migrar seus dados para o Milvus sem problemas: um guia abrangente

Como migrar seus dados para o Milvus sem problemas: um guia abrangente

Oct 02, 20238 min read

Milvus é um banco de dados vetorial robusto e de código aberto para busca por similaridade, capaz de armazenar, processar e recuperar bilhões e até trilhões de dados vetoriais com latência mínima. Ele também é altamente escalável, confiável, nativo da nuvem e rico em recursos. A versão mais recente do Milvus apresenta ainda mais recursos e melhorias empolgantes, incluindo suporte a GPU para desempenho mais de 10x mais rápido e MMap para maior capacidade de armazenamento em uma única máquina.

Em setembro de 2023, o Milvus conquistou quase 23.000 estrelas no GitHub e tem dezenas de milhares de usuários de diversos setores com necessidades variadas. Ele está se tornando ainda mais popular à medida que a tecnologia de IA generativa, como o ChatGPT, se torna mais prevalente. É um componente essencial de várias pilhas de IA, especialmente a estrutura de geração aumentada por recuperação, que aborda o problema de alucinação dos grandes modelos de linguagem.

Para atender à crescente demanda de novos usuários que desejam migrar para o Milvus e de usuários existentes que desejam atualizar para as versões mais recentes do Milvus, desenvolvemos o Milvus Migration. Neste blog, exploraremos os recursos do Milvus Migration e guiaremos você na rápida transição de seus dados para o Milvus a partir do Milvus 1.x, FAISS e Elasticsearch 7.0 e versões posteriores.

Milvus Migration, uma poderosa ferramenta de migração de dados

Milvus Migration é uma ferramenta de migração de dados escrita em Go. Ela permite que os usuários movam seus dados de forma contínua de versões mais antigas do Milvus (1.x), FAISS e Elasticsearch 7.0 e posteriores para versões do Milvus 2.x.

O diagrama abaixo demonstra como construímos o Milvus Migration e como ele funciona.

Como o Milvus Migration migra dados

Do Milvus 1.x e FAISS para o Milvus 2.x

A migração de dados do Milvus 1.x e FAISS envolve analisar o conteúdo dos arquivos de dados originais, transformá-los no formato de armazenamento de dados do Milvus 2.x e gravar os dados usando o bulkInsert do Milvus SDK. Todo esse processo é baseado em fluxo, teoricamente limitado apenas pelo espaço em disco, e armazena arquivos de dados em seu disco local, S3, OSS, GCP ou Minio.

Do Elasticsearch para o Milvus 2.x

Na migração de dados do Elasticsearch, a recuperação de dados é diferente. Os dados não são obtidos de arquivos, mas buscados sequencialmente usando a API scroll do Elasticsearch. Em seguida, os dados são analisados e transformados no formato de armazenamento do Milvus 2.x, seguidos pela gravação usando bulkInsert. Além de migrar vetores do tipo dense_vector armazenados no Elasticsearch, o Milvus Migration também oferece suporte à migração de outros tipos de campo, incluindo long, integer, short, boolean, keyword, text e double.

Conjunto de recursos do Milvus Migration

O Milvus Migration simplifica o processo de migração por meio de seu conjunto robusto de recursos:

Fontes de dados compatíveis:
- Milvus 1.x para Milvus 2.x
- Elasticsearch 7.0 e posteriores para Milvus 2.x
- FAISS para Milvus 2.x

Múltiplos modos de interação:
- Interface de linha de comando (CLI) usando o framework Cobra
- API Restful com uma Swagger UI integrada
- Integração como um módulo Go em outras ferramentas

Suporte versátil a formatos de arquivo:
- Arquivos locais
- Amazon S3
- Object Storage Service (OSS)
- Google Cloud Platform (GCP)

Integração flexível com Elasticsearch:
- Migração de vetores do tipo dense_vector do Elasticsearch
- Suporte para migrar outros tipos de campo, como long, integer, short, boolean, keyword, text e double

Definições de interface

O Milvus Migration fornece as seguintes interfaces principais:

/start: Inicia um job de migração (equivalente a uma combinação de dump e load, atualmente compatível apenas com migração do ES).
/dump: Inicia um job de dump (grava os dados de origem no meio de armazenamento de destino).
/load: Inicia um job de load (grava os dados do meio de armazenamento de destino no Milvus 2.x).
/get_job: Permite que os usuários visualizem os resultados da execução do job. (Para mais detalhes, consulte o server.go do projeto)

Em seguida, vamos usar alguns dados de exemplo para explorar como usar o Milvus Migration nesta seção. Você pode encontrar esses exemplos aqui no GitHub.

Migração do Elasticsearch para o Milvus 2.x

Preparar os dados do Elasticsearch

Para migrar dados do Elasticsearch, você já deve ter configurado seu próprio servidor Elasticsearch. Você deve armazenar dados vetoriais no campo dense_vector e indexá-los com outros campos. Os mapeamentos de índice são mostrados abaixo.

Compilar e construir

Primeiro, baixe o código-fonte do Milvus Migration no GitHub. Em seguida, execute os seguintes comandos para compilá-lo.

go get
go build

Esta etapa gerará um arquivo executável chamado milvus-migration.

Configurar migration.yaml

Antes de iniciar a migração, você deve preparar um arquivo de configuração chamado migration.yaml que inclua informações sobre a fonte de dados, o destino e outras configurações relevantes. Aqui está um exemplo de configuração:

# Configuration for Elasticsearch to Milvus 2.x migration

dumper:
  worker:
    workMode: Elasticsearch
    reader:
      bufferSize: 2500
meta:
  mode: config
  index: test_index
  fields:
    - name: id
      pk: true
      type: long
    - name: other_field
      maxLen: 60
      type: keyword
    - name: data
      type: dense_vector
      dims: 512
  milvus:
      collection: "rename_index_test"
      closeDynamicField: false
      consistencyLevel: Eventually
      shardNum: 1

source:
  es:
    urls:
      - http://localhost:9200
    username: xxx
    password: xxx

target:
  mode: remote
  remote:
    outputDir: outputPath/migration/test1
    cloud: aws
    region: us-west-2
    bucket: xxx
    useIAM: true
    checkBucket: false
  milvus2x:
    endpoint: {yourMilvusAddress}:{port}
    username: ******
    password: ******

Para uma explicação mais detalhada do arquivo de configuração, consulte esta página no GitHub.

Executar o job de migração

Agora que você configurou seu arquivo migration.yaml, pode iniciar a tarefa de migração executando o seguinte comando:

./milvus-migration start --config=/{YourConfigFilePath}/migration.yaml

Observe a saída do log. Quando você vir logs semelhantes aos seguintes, isso significa que a migração foi bem-sucedida.

[task/load_base_task.go:94] ["[LoadTasker] Dec Task Processing-------------->"] [Count=0] [fileName=testfiles/output/zwh/migration/test_mul_field4/data_1_1.json] [taskId=442665677354739304][task/load_base_task.go:76] ["[LoadTasker] Progress Task --------------->"] [fileName=testfiles/output/zwh/migration/test_mul_field4/data_1_1.json] [taskId=442665677354739304][dbclient/cus_field_milvus2x.go:86] ["[Milvus2x] begin to ShowCollectionRows"][loader/cus_milvus2x_loader.go:66] ["[Loader] Static: "] [collection=test_mul_field4_rename1] [beforeCount=50000] [afterCount=100000] [increase=50000][loader/cus_milvus2x_loader.go:66] ["[Loader] Static Total"] ["Total Collections"=1] [beforeTotalCount=50000] [afterTotalCount=100000] [totalIncrease=50000][migration/es_starter.go:25] ["[Starter] migration ES to Milvus finish!!!"] [Cost=80.009174459][starter/starter.go:106] ["[Starter] Migration Success!"] [Cost=80.00928425][cleaner/remote_cleaner.go:27] ["[Remote Cleaner] Begin to clean files"] [bucket=a-bucket] [rootPath=testfiles/output/zwh/migration][cmd/start.go:32] ["[Cleaner] clean file success!"]

Além da abordagem por linha de comando, o Milvus Migration também oferece suporte à migração usando Restful API.

Para usar a Restful API, inicie o servidor da API usando o seguinte comando:

./milvus-migration server run -p 8080

Depois que o serviço estiver em execução, você poderá iniciar a migração chamando a API.

curl -XPOST http://localhost:8080/api/v1/start

Quando a migração estiver concluída, você poderá usar o Attu, uma ferramenta completa de administração de banco de dados vetorial, para visualizar o número total de linhas migradas com sucesso e realizar outras operações relacionadas a coleções.

A interface do Attu

Migração do Milvus 1.x para o Milvus 2.x

Prepare os dados do Milvus 1.x

Para ajudar você a experimentar rapidamente o processo de migração, colocamos 10.000 registros de dados de teste do Milvus 1.x no código-fonte do Milvus Migration. No entanto, em casos reais, você deve exportar seu próprio arquivo meta.json da sua instância do Milvus 1.x antes de iniciar o processo de migração.

Você pode exportar os dados com o seguinte comando.

./milvus-migration export -m "user:password@tcp(adderss)/milvus?charset=utf8mb4&parseTime=True&loc=Local" -o outputDir

Certifique-se de:

Substituir os placeholders pelas suas credenciais reais do MySQL.
Parar o servidor Milvus 1.x ou interromper as gravações de dados antes de realizar esta exportação.
Copiar a pasta tables do Milvus e o arquivo meta.json para o mesmo diretório.

Observação: Se você usa o Milvus 2.x no Zilliz Cloud (o serviço totalmente gerenciado do Milvus), pode iniciar a migração usando o Cloud Console.

Compile e faça o build

Primeiro, baixe o código-fonte do Milvus Migration no GitHub. Em seguida, execute os seguintes comandos para compilá-lo.

go get
go build

Esta etapa gerará um arquivo executável chamado milvus-migration.

Configure migration.yaml

Prepare um arquivo de configuração migration.yaml, especificando detalhes sobre a origem, o destino e outras configurações relevantes. Aqui está um exemplo de configuração:

# Configuration for Milvus 1.x to Milvus 2.x migration

dumper:
  worker:
    limit: 2
    workMode: milvus1x
    reader:
      bufferSize: 1024
    writer:
      bufferSize: 1024
loader:
  worker:
    limit: 16
meta:
  mode: local
  localFile: /outputDir/test/meta.json

source:
  mode: local
  local:
    tablesDir: /db/tables/

target:
  mode: remote
  remote:
    outputDir: "migration/test/xx"
    ak: xxxx
    sk: xxxx
    cloud: aws
    endpoint: 0.0.0.0:9000
    region: ap-southeast-1
    bucket: a-bucket
    useIAM: false
    useSSL: false
    checkBucket: true
  milvus2x:
    endpoint: localhost:19530
    username: xxxxx
    password: xxxxx

Para uma explicação mais detalhada do arquivo de configuração, consulte esta página no GitHub.

Execute o Job de Migração

Você deve executar os comandos dump e load separadamente para concluir a migração. Esses comandos convertem os dados e os importam para o Milvus 2.x.

Observação: Em breve, simplificaremos esta etapa e permitiremos que os usuários concluam a migração usando apenas um comando. Fique atento.

Comando Dump:

./milvus-migration dump --config=/{YourConfigFilePath}/migration.yaml

Comando Load:

./milvus-migration load --config=/{YourConfigFilePath}/migration.yaml

Após a migração, a coleção gerada no Milvus 2.x conterá dois campos: id e data. Você pode ver mais detalhes usando o Attu, uma ferramenta completa de administração de bancos de dados vetoriais.

Migração do FAISS para o Milvus 2.x

Prepare os Dados do FAISS

Para migrar dados do Elasticsearch, você deve ter seus próprios dados do FAISS prontos. Para ajudar você a experimentar rapidamente o processo de migração, colocamos alguns dados de teste do FAISS no código-fonte do Milvus Migration.

Compile e Faça o Build

Primeiro, baixe o código-fonte do Milvus Migration no GitHub. Em seguida, execute os seguintes comandos para compilá-lo.

go get
go build

Esta etapa gerará um arquivo executável chamado milvus-migration.

Configure migration.yaml

Prepare um arquivo de configuração migration.yaml para a migração do FAISS, especificando detalhes sobre a origem, o destino e outras configurações relevantes. Aqui está um exemplo de configuração:

# Configuration for FAISS to Milvus 2.x migration

dumper:
  worker:
    limit: 2
    workMode: FAISS
    reader:
      bufferSize: 1024
    writer:
      bufferSize: 1024
loader:
  worker:
    limit: 2
source:
  mode: local
  local:
    FAISSFile: ./testfiles/FAISS/FAISS_ivf_flat.index

target:
  create:
    collection:
      name: test1w
      shardsNums: 2
      dim: 256
      metricType: L2
  mode: remote
  remote:
    outputDir: testfiles/output/
    cloud: aws
    endpoint: 0.0.0.0:9000
    region: ap-southeast-1
    bucket: a-bucket
    ak: minioadmin
    sk: minioadmin
    useIAM: false
    useSSL: false
    checkBucket: true
  milvus2x:
    endpoint: localhost:19530
    username: xxxxx
    password: xxxxx

Para uma explicação mais detalhada do arquivo de configuração, consulte esta página no GitHub.

Execute o Job de Migração

Assim como na migração do Milvus 1.x para o Milvus 2.x, a migração do FAISS exige a execução dos comandos dump e load. Esses comandos convertem os dados e os importam para o Milvus 2.x.

Observação: Em breve, simplificaremos esta etapa e permitiremos que os usuários concluam a migração usando apenas um comando. Fique atento.

Comando Dump:

./milvus-migration dump --config=/{YourConfigFilePath}/migration.yaml

Comando Load:

./milvus-migration load --config=/{YourConfigFilePath}/migration.yaml

Você pode ver mais detalhes usando o Attu, uma ferramenta completa de administração de bancos de dados vetoriais.

Fique atento aos futuros planos de migração

No futuro, daremos suporte à migração de mais fontes de dados e adicionaremos mais recursos de migração, incluindo:

Suporte à migração do Redis para o Milvus.
Suporte à migração do MongoDB para o Milvus.
Suporte à migração retomável.
Simplificação dos comandos de migração ao mesclar os processos de dump e load em um só.
Suporte à migração de outras fontes de dados populares para o Milvus.

Conclusão

O Milvus 2.3, a versão mais recente do Milvus, traz novos recursos empolgantes e melhorias de desempenho que atendem às necessidades crescentes de gerenciamento de dados. Migrar seus dados para o Milvus 2.x pode liberar esses benefícios, e o projeto Milvus Migration torna o processo de migração simplificado e fácil. Experimente, e você não ficará decepcionado.

Nota: As informações neste blog são baseadas no estado dos projetos Milvus e Milvus Migration em setembro de 2023. Consulte a documentação do Milvus oficial para obter as informações e instruções mais atualizadas.

Atualizado em Jul 13, 2026

Wenhui Zhang
Senior Software Engineer at Zilliz

Continue lendo

Zilliz Cloud Now Available in AWS Asia Pacific (Seoul)

Zilliz Cloud is now available in AWS Seoul — low-latency vector search, in-country data residency, and one-step migration for Korean AI teams. 31 regions across 5 clouds.

The AWS Outage Was a Wake-Up Call for Vector Database Cross-Region Disaster Recovery

Zilliz Cloud Had the Answer Before the Crisis. Zilliz Cloud is the world's first vector database with native cross-region disaster recovery.

How to Use Anthropic MCP Server with Milvus

MCP + Milvus: Streamline AI agent development with standardized data access, eliminating integration hassles while enhancing context and flexibility.