Detalhamento das habilidades da Zilliz: Como agentes de IA dominam bancos de dados vetoriais

Originalmente por ShugeX, um profissional independente de AI-ops e colaborador ativo da comunidade Milvus. Traduzido e republicado com permissão.

Imagine que você está usando o Claude Code para criar um app RAG com Milvus. Cada etapa — criar uma coleção, definir um esquema, inserir vetores, executar busca híbrida — faz você ficar alternando para a documentação do pymilvus para encontrar a API certa, depois voltar ao editor para conectá-la. E se você estiver no Zilliz Cloud, também estará indo ao navegador para fazer login no console para gerenciamento de clusters, monitoramento e configuração de backup. O ambiente de desenvolvimento e o ambiente de operações são dois mundos diferentes.

As duas Skills recentes do Claude Code da Zilliz miram exatamente esse ponto de ruptura. Milvus Skill ensina o agente a operar o banco de dados vetorial por meio do SDK Python. Zilliz Cloud Skill ensina o agente a gerenciar tudo no lado da nuvem por meio do zilliz-cli. Cada Skill cuida de um domínio; juntas, elas transformam dev e ops em uma sessão contínua do Claude Code.

Depois de ler o código-fonte de ambas as Skills de ponta a ponta, encontrei muita coisa que vale destrinchar — design modular, padrões de segurança e onde Skill se encaixa ao lado do MCP. Este artigo percorre cada uma.

O que Milvus Skill e Zilliz Cloud Skill fazem

As duas Skills não são duas versões da mesma coisa. Elas miram duas falhas de correção diferentes.

Milvus Skill (zilliztech/milvus-skill) ensina ao agente pymilvus, o SDK Python para conectar, criar coleções, inserir vetores e executar buscas. É um assistente de codificação, e funciona com qualquer implantação do Milvus: Milvus Lite, Standalone/Cluster auto-hospedado ou Zilliz Cloud. A falha que ele corrige: código pymilvus que compila, mas não faz o que você pediu porque o agente usou um formato de API desatualizado.

Zilliz Cloud Skill (zilliztech/zilliz-skill) ensina ao agente zilliz-cli, a ferramenta de linha de comando que cobre clusters, backups, monitoramento e cobrança. É um assistente de DBA, e funciona apenas com Zilliz Cloud (Milvus auto-hospedado não tem plano de controle). A falha que ele corrige: comandos alucinados contra um sistema de produção ativo, em que um zilliz cluster delete ruim custa mais do que um erro de compilação.

Em uma frase:

• Milvus Skill → o agente escreve código que opera dados
• Zilliz Cloud Skill → o agente executa comandos que gerenciam serviços

Dimensão	Milvus Skill	Zilliz Cloud Skill
Interface	Python (pymilvus)	CLI (zilliz-cli)
Função	Assistente de codificação	Assistente de DBA
Funciona com	Todas as implantações Milvus + Zilliz Cloud	Apenas Zilliz Cloud
Arquivos	7 módulos de referência	14 sub-skills
Alvo de correção	APIs de SDK desatualizadas	Comandos de ops pouco documentados
Tarefa típica	Criar coleção, inserir, buscar	Provisionar cluster, configurar backup, verificar cobrança

Milvus Skill: ensinando o agente a escrever pymilvus confiável

A pasta references/ do Milvus Skill contém sete arquivos, cada um mapeado para uma área independente de capacidade do pymilvus. Quando o agente lida com uma tarefa específica, ele carrega apenas o arquivo relevante, em vez de despejar toda a documentação no contexto:

Arquivo	Abrange
collection.md	Tipos de dados, definições de campos, operações de coleção
vector.md	CRUD de vetores, busca híbrida, busca de texto completo, iteradores
index.md	Tipos de índice, tipos de métrica, gerenciamento de índices
partition.md	Gerenciamento de partições
database.md	Gerenciamento de bancos de dados
user-role.md	RBAC
patterns.md	Padrões comuns (RAG, busca híbrida etc.)

Construindo um esquema? O agente puxa collection.md. Executando uma busca? Ele puxa vector.md. O resto fica de fora. Janelas de contexto são finitas; o carregamento sob demanda supera despejar tudo.

Tipos de Dados Suportados: Mais Ricos do Que Você Esperaria

Folheando collection.md, o Milvus oferece suporte a mais tipos de vetores do que a maioria dos devs imagina:

• Escalares: BOOL, INT8/16/32/64, FLOAT, DOUBLE, VARCHAR, JSON, ARRAY
• Vetores:
• FLOAT_VECTOR — float de 32 bits, o padrão
• FLOAT16_VECTOR — meia precisão, economiza memória
• BFLOAT16_VECTOR — BF16, comum em pipelines de deep learning
• BINARY_VECTOR — binário
• SPARSE_FLOAT_VECTOR — esparso, para busca de texto completo
• INT8_VECTOR — quantizado, compressão adicional

Busca Híbrida: O Recurso Mais Notável que Essas Skills Cobrem

patterns.md documenta quatro padrões comuns. A busca híbrida tem o maior número de partes. A busca por vetores densos (semântica) e a busca por vetores esparsos (palavra-chave) são executadas em paralelo, então RRF (Reciprocal Rank Fusion) ou ranqueamento ponderado mescla as duas listas.

Três blocos de construção:

1. AnnSearchRequest — um por ramificação de busca
2. RRFRanker / WeightedRanker — estratégia de fusão
3. SPARSE_FLOAT_VECTOR — o campo de vetor esparso

RRF é simples: para cada resultado, pontuação = 1/rank, somada entre as ramificações. Itens ranqueados mais acima vencem. WeightedRanker é uma soma ponderada por ramificação. A Skill explica isso, então o agente gera código de busca híbrida utilizável sem que o desenvolvedor leia o paper do RRF.

Busca de Texto Completo BM25 Integrada do Milvus

A Skill do Milvus também codifica: a busca de texto completo Sparse-BM25 integrada do Milvus 2.5. Combinado com Function e FunctionType.BM25, o Milvus converte texto bruto em vetores esparsos internamente, dispensando modelos de embedding externos e pipelines manuais de TF-IDF.

Antes da versão 2.5, busca de texto completo significava que você precisava lidar com um tokenizer, calcular TF-IDF manualmente e gerar o vetor esparso por conta própria. Agora você diz ao agente o que quer, e a Skill o orienta a gerar a collection com a Function BM25 configurada corretamente.

Iteradores de Busca: Paginação para Collections com Milhões de Linhas

vector.md também cobre search_iterator e query_iterator, paginação em estilo cursor para collections com milhões ou bilhões de linhas. Um search simples retorna um conjunto de resultados de tamanho fixo. Iteradores percorrem páginas sem perdas nem duplicatas, que é o que uma enumeração completa exige.

Zilliz Cloud Skill: Ensinando o Agente a Ser Seu DBA de Cloud

O trabalho da Zilliz Cloud Skill é diferente do da Milvus Skill. Em vez de escrever Python, o agente compõe invocações de CLI contra um control plane ativo — e, como um comando ruim pode apagar a produção, a Skill envolve essas invocações em regras de segurança.

Modo de Comando: Como o Agente Compõe Invocações de CLI

A Skill codifica um formato de comando consistente:

zilliz <resource> <action> --flag <value>

Exemplos:

• zilliz cluster list — listar todos os clusters
• zilliz collection create --name my_collection — criar uma collection
• zilliz backup create --name daily-backup — criar um backup

Três formatos de saída: json (legível por máquina), table (amigável para humanos), text (simples). O agente escolhe o que se encaixar melhor.

14 Sub-Skills Cobrindo Todo o Ciclo de Vida na Cloud

O repo zilliz-plugin fornece 14 sub-skills, cada uma em skills/<name>/SKILL.md:

Módulo	Abrange
setup	Instalação, autenticação (OAuth / Chave de API / variável de ambiente), configuração de contexto
cluster	Criar, listar, modificar, suspender, retomar, excluir
collection	CRUD de coleções, carregar/liberar, aliases
vector	Operações vetoriais via CLI
index	Gerenciamento de índices
database	Gerenciamento de bancos de dados (apenas Dedicated)
partition	Gerenciamento de partições
user-role	RBAC (apenas Dedicated)
backup	Criar, restaurar, exportar, políticas de backup
import	Importação em massa a partir de armazenamento em nuvem (Parquet / JSON / CSV)
billing	Uso, faturas, métodos de pagamento
monitoring	Status do cluster, estatísticas, estados de carga
project-region	Gerenciamento de projetos e regiões
job	Rastreamento de tarefas assíncronas

Criar um cluster, configurar a retenção de backups, verificar uma fatura: 14 módulos cobrem todas as operações do console do Zilliz Cloud.

A consciência de tiers é integrada. database e user-role são marcados como apenas Dedicated. A Skill sabe que os tiers Free, Serverless e Dedicated têm recursos diferentes, então o agente não tentará operações que um tier de cluster não possa suportar.

Três regras de segurança, uma em todos os módulos

O design de segurança da Zilliz Cloud Skill vai várias camadas além do da Milvus Skill. Três regras principais aparecem nos arquivos SKILL.md individuais:

1. Operações destrutivas exigem confirmação explícita do usuário. A orientação do módulo de cluster diz: "Antes de excluir um cluster, sempre confirme com o usuário — isso é irreversível." Toda operação destrutiva (coleções, backups, bancos de dados, usuários) carrega a mesma instrução.
2. Comandos sensíveis são executados no terminal do próprio usuário. O módulo setup é explícito: "Comandos de login (zilliz login, zilliz configure) exigem um terminal interativo e NÃO PODEM ser executados dentro do Claude Code. Sempre instrua o usuário a executá-los em seu próprio terminal." Credenciais não passam pelo agente.
3. Credenciais nunca são expostas. A autenticação ocorre por fluxo OAuth no navegador, uma chave de API do console ou uma variável de ambiente ZILLIZ_API_KEY. A Skill nunca imprime segredos.

Isso parece básico, mas um agente com credenciais da Cloud e sem camada de confirmação poderia interpretar "limpe os clusters de teste" e destruir a produção. A Skill fecha essa lacuna na camada de instrução, antes que qualquer comando destrutivo chegue à API.

O gate de pré-requisitos: três verificações antes de qualquer comando executar

Cada sub-skill executa uma verificação em três etapas, definida em skills/setup/SKILL.md:

1. zilliz-cli instalado? Se não, instalar.
2. Usuário logado? Se não, direcionar para autenticação.
3. Contexto do cluster definido? Se não, solicitar seleção.

O gate garante que o ambiente esteja pronto antes que qualquer comando seja disparado, o que é mais confiável do que disparar às cegas e depurar erros depois.

Por que são Zilliz Skills, e não apenas MCP?

A Zilliz fornece ambos porque resolvem problemas diferentes. Uma Skill injeta conhecimento que o agente consulta ao escrever código. Um servidor MCP expõe endpoints chamáveis que o agente pode invocar. mcp-server-milvus é o braço MCP; a Milvus Skill é o braço de conhecimento. Eles se sobrepõem em camadas, em vez de competir.

Skill é um carregador de prompts

A Skill mínima é uma pasta e um SKILL.md:

my-skill/
├── SKILL.md        # instruções + metadados
├── references/     # documentação de referência (opcional)
├── scripts/        # scripts executáveis (opcional)
└── assets/         # modelos, recursos (opcional)

SKILL.md é um manual de instruções. Ele diz ao agente como lidar com uma determinada tarefa. Sem código executável, sem processo de servidor. Apenas conhecimento estruturado injetado no contexto do modelo sob demanda.

Uma Skill é um carregador de prompts. Conhecimento de domínio empacotado como um prompt estruturado, carregado dinamicamente.

MCP é um protocolo de ferramentas

MCP (Model Context Protocol) assume uma forma diferente. É um protocolo padronizado que permite que um agente chame ferramentas externas por meio de uma interface uniforme. mcp-server-milvus é um servidor MCP que expõe endpoints de ferramentas como milvus_text_search, milvus_create_collection e assim por diante.

O MCP foi descrito como "a porta USB-C para agentes de IA." Ele resolve o problema de padronização da interface de ferramentas.

Zilliz Skill vs zilliz MCP

Dimensão	Skill	MCP
Essência	Injeção de conhecimento (prompt)	Invocação de ferramentas (protocolo)
O que faz	Modifica como o agente se comporta	Dá ao agente uma nova capacidade
Custo de implantação	Soltar arquivos, pronto	Processo de servidor necessário
Adequa-se a	Ensinar o agente a usar ferramentas que ele já tem	Dar ao agente ferramentas que ele não tem
Dependência	O agente suporta carregamento de Skill	O agente suporta MCP

A distinção essencial: Milvus Skill ensina o agente a usar pymilvus. pymilvus já existe. A Skill não adiciona capacidade. Ela corrige a precisão para uma capacidade que o agente já tem. MCP, por outro lado, dá ao agente endpoints chamáveis que ele não conseguiria alcançar de outra forma.

Uma Skill é um manual de operação para uma máquina que você já possui. MCP é um controle remoto que faz uma nova máquina se mover. A Zilliz disse isso diretamente em "Is MCP Dead? MCP vs CLI vs Agent Skills Compared": ambos os padrões persistem.

Dito isso, Skills estão ganhando adoção rapidamente. Rastreadores da comunidade colocam a contagem em mais de 700.000 pacotes entre registros, com o ClawHub sozinho listando mais de 5.700 skills. Um projeto de pacote de skills no GitHub recebeu 6.600 estrelas em cinco dias em abril de 2026.

Cenários do mundo real: como os desenvolvedores realmente as usam

Cenário 1: Construindo uma aplicação RAG

Você está construindo um app RAG. Com Milvus Skill instalada, você diz:

"Crie uma coleção de recuperação de documentos: vetores de 768 dimensões, busca de texto completo BM25, campos para title, body e embedding."

O agente consulta collection.md e patterns.md e escreve:

from pymilvus import MilvusClient, DataType, Function, FunctionType

client = MilvusClient(uri="<URI>", token="<TOKEN>")

schema = client.create_schema(auto_id=True)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("title", DataType.VARCHAR, max_length=512)
schema.add_field("body", DataType.VARCHAR, max_length=4096, enable_analyzer=True)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=768)
schema.add_field("body_sparse", DataType.SPARSE_FLOAT_VECTOR)

# Wire BM25 full-text search
schema.add_function(Function(
    name="body_bm25",
    input_field_names=["body"],
    output_field_names=["body_sparse"],
    function_type=FunctionType.BM25,
))

index_params = client.prepare_index_params()
index_params.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="COSINE")
index_params.add_index(field_name="body_sparse", index_type="AUTOINDEX", metric_type="BM25")

client.create_collection("documents", schema=schema, index_params=index_params)

enable_analyzer=True, a fiação da Function BM25, a combinação AUTOINDEX com métrica BM25: nenhuma dessas são coisas que você quer que o agente adivinhe. A Skill as codifica.

Cenário 2: Gerenciando um cluster Zilliz Cloud

"Crie um cluster Serverless em us-east-1 e, em seguida, crie uma coleção com vetores de 768 dimensões."

O agente executa a verificação de pré-requisitos e, em seguida, emite os comandos da CLI em ordem. Ou:

"Mostre-me o status e o uso de recursos de todos os meus clusters."

O agente executa zilliz cluster list e os comandos zilliz monitoring correspondentes, depois resume. As credenciais nunca saem do seu terminal.

Cenário 3: Backups e migração de dados

"Configure uma política de backup diária para produção, manter por 7 dias."

backup.md documenta a sintaxe completa da política. O agente configura a política diretamente.

"Exporte a coleção orders do cluster de teste para o S3."

import.md cobre importação e exportação em massa a partir do armazenamento em nuvem, incluindo os formatos compatíveis (Parquet, JSON, CSV).

Cenário 4: Atualizando para busca híbrida

"Atualize minha busca para híbrida densa + esparsa com RRF."

O agente extrai as notas de vector.md sobre AnnSearchRequest e RRFRanker e escreve o código de busca híbrida. Você não precisa estudar os parâmetros de RRF.

Stack de Agentes da Zilliz: Onde as Duas Skills se Encaixam

Essas duas Skills ficam dentro de um esforço mais amplo da Zilliz em todos os padrões de integração de agentes:

Projeto	Tipo	Abrange
mcp-server-milvus	Servidor MCP	Operações de banco de dados Milvus
claude-context	Servidor MCP	Busca semântica de código
milvus-skill	Skill	SDK pymilvus
zilliz-skill	Skill	Gerenciamento do Zilliz Cloud
DeepSearcher	Framework de agentes	RAG agêntico em várias etapas

claude-context é o destaque. Ele indexa uma base de código em um banco de dados vetorial, recupera código relevante sob demanda com busca híbrida (BM25 + densa) e relata ~40% de redução de tokens com qualidade de recuperação equivalente.

De MCP a Skill, de busca de código a frameworks de agentes, a estratégia da Zilliz é consistente: seja qual for o padrão de integração de agentes que vença, um banco de dados vetorial deve ter um ponto de entrada de primeira classe. As duas Skills são a entrada da Zilliz nesse caminho.

Conclusão

Milvus Skill e Zilliz Cloud Skill se apoiam em quatro escolhas de design em comum:

1. As duas Skills têm papéis claros e não sobrepostos. Milvus Skill lida com a camada de codificação do SDK; Zilliz Cloud Skill lida com a camada de operações via CLI. Juntas, elas cobrem todo o ciclo de vida do banco de dados vetorial sem interferirem uma na outra.
2. O carregamento modular de conhecimento mantém o contexto enxuto. Dividir o conhecimento em 7 e 14 arquivos de referência permite que o agente puxe apenas o arquivo que corresponde à tarefa atual, em vez de inundar a janela de contexto com toda a documentação.
3. Zilliz Cloud Skill incorpora segurança na camada de instruções. Confirmação de operações destrutivas, proteção de credenciais e verificações de pré-requisitos mostram que a equipe pensou cuidadosamente sobre o que um agente com chaves da Cloud pode fazer a um banco de dados em produção.
4. A Zilliz está se protegendo em vários paradigmas, não escolhendo um vencedor. Ao lançar implementações tanto MCP quanto Skill, a Zilliz tem cobertura qualquer que seja a direção que o ecossistema de integração de agentes tome.

Se você está criando agentes usando um banco de dados vetorial, instale as duas Skills na próxima vez que iniciar um app RAG ou gerenciar um cluster.

Comece

Instale as duas Skills na sua próxima sessão do Claude Code:

• Milvus Skill — correção com pymilvus. Funciona com Milvus Lite, Standalone/Cluster auto-hospedado e Zilliz Cloud.
• Zilliz Cloud Skill — gerenciamento de cluster em produção por meio do zilliz-cli. Instale a CLI junto.

Se você ainda não tem um cluster, cadastre-se no Zilliz Cloud (novas contas com e-mail corporativo recebem créditos gratuitos) ou faça login, depois cole a Skill no Claude Code, e o agente continua a partir daí.

Leitura Adicional

• "O MCP morreu?" — o enquadramento da Zilliz sobre onde CLIs e Skills se situam ao lado do MCP.
• Milvus SDK Code Helper — contraparte MCP do Milvus Skill, o mesmo problema do pymilvus desatualizado por um ângulo diferente.
• claude-context — busca semântica em base de código relatando ~40% de redução de tokens.
• documentação do Milvus e Zilliz Cloud para toda a superfície do produto.