Cloudflare Vectorize grátis: busca semântica em 30 minutos

Você quer adicionar uma busca inteligente ao blog, mas descobre que o plano mais barato do Pinecone custa US$ 50 por mês. Bancos de dados vetoriais entendem significado, encontram conteúdo semelhante e fornecem bases de conhecimento à IA, mas costumam parecer caros demais para um projeto pessoal.
A cota gratuita do Cloudflare Vectorize é suficiente para começar, e 1 milhão de vetores com 30 mil consultas custam apenas US$ 0,31. A seguir, você verá o que é o Vectorize, por que ele custa tão pouco e como colocar uma demonstração completa de busca semântica no ar em 30 minutos.
Parte 1: entendendo os conceitos
O que é um banco de dados vetorial? A explicação em três frases
Quando vi a expressão “vetor de 768 dimensões” pela primeira vez, também fiquei confuso. Ela parece saída de uma aula de matemática do ensino médio, mas o conceito é mais simples do que o nome sugere.
Bancos de dados tradicionais armazenam valores fáceis de reconhecer, como texto, números e datas. Um banco de dados vetorial, por outro lado, armazena o “significado” por trás do texto. Se você digitar “celular da Apple” em uma busca tradicional, ela encontra apenas resultados com essas palavras exatas. A busca vetorial entende que “iPhone”, “novo aparelho da Apple” e “smartphone topo de linha da Apple” descrevem a mesma ideia.
Como isso funciona? Você envia o texto a um modelo de IA, como um modelo de embeddings da OpenAI, e recebe uma sequência de números semelhante a [0.23, -0.45, 0.78, ...], com 768 valores. Essa sequência é o vetor: uma forma de transformar o significado do texto em coordenadas. Textos semanticamente próximos também ficam próximos no espaço matemático.
Em um teste no meu blog, a busca por “notebook barato” encontrou um artigo sobre “laptop com bom custo-benefício”. Nenhuma palavra era igual, mas o significado correspondia. Esse é o principal valor da busca semântica.
Por que escolher o Vectorize? Comparativo entre três opções populares
Existem vários bancos de dados vetoriais conhecidos, como Pinecone, Weaviate e Milvus. Depois de comparar as opções, concluí que o Vectorize é especialmente interessante para projetos pequenos e desenvolvedores independentes.
Primeiro, o custo — a diferença mais concreta
O Pinecone é uma das opções mais conhecidas, mas o preço pode afastar projetos pequenos. O plano padrão mais barato tem consumo mínimo de US$ 50 por mês, e armazenar 1 milhão de vetores custa cerca de US$ 41 mensais. A versão serverless do Weaviate começa em US$ 25 por mês; armazenar e consultar 1 milhão de vetores de 1.536 dimensões pode elevar a conta a US$ 153, enquanto a versão compactada parte de US$ 25.
E o Vectorize? No meu teste, 1 milhão de vetores de 768 dimensões e 1.000 consultas por dia, ou 30 mil por mês, custaram apenas US$ 0,31. Segundo o blog oficial da Cloudflare, os custos de consulta caíram 75% e os de armazenamento, 98%.
Além disso, o Vectorize oferece uma cota gratuita suficiente para executar um projeto pequeno ou validar um MVP. Você só precisa pensar em cobrança depois que o uso realmente crescer.
Depois, a dificuldade de integração
Pinecone e Weaviate exigem cadastro separado, gerenciamento de chaves de API e configuração de acesso à rede. Se você já implanta aplicações com Cloudflare Workers, o Vectorize se integra diretamente: adicione algumas linhas ao wrangler.toml e use env.VECTORIZE_INDEX no código, sem criar outra variável de ambiente.
Quando testei o Pinecone, levei cerca de meia hora apenas para entender como armazenar a chave de API com segurança no Workers. Com o Vectorize, essa etapa desaparece.
Por fim, os cenários adequados
É importante reconhecer que o Vectorize não resolve tudo:
- Projetos pequenos, MVPs e blogs pessoais: o Vectorize se destaca pelo baixo custo e pela configuração rápida
- Ambientes corporativos e escala muito grande, com centenas de milhões de vetores: o Pinecone é mais adequado porque sua infraestrutura e seu suporte empresarial são mais maduros
- Necessidades multimodais, com imagens, vídeos e áudio: o Weaviate oferece mais recursos e suporte nativo a entradas multimodais
Segundo os dados oficiais da Cloudflare, atualmente um índice do Vectorize aceita até 5 milhões de vetores. Para a maioria das aplicações, isso é bastante: meu blog tem pouco mais de 200 artigos após três anos e ainda está muito longe do limite.
O raciocínio central é simples: se você está começando com busca vetorial ou tem orçamento limitado, o Vectorize é um ótimo ponto de partida. Se o negócio crescer de verdade, ainda será possível migrar mais adiante.
Para que serve o Vectorize? Quatro casos práticos
Depois da teoria, vale observar onde essa tecnologia resolve problemas reais.
1. Busca inteligente em documentos
Esse é o uso mais comum. Imagine uma empresa com centenas de documentos técnicos, manuais de produto e normas legais. Uma busca tradicional com Ctrl+F não entende bem a intenção. Com uma busca semântica no Vectorize, a consulta “como solicitar reembolso” pode localizar “processo de reembolso de despesas” e “guia para envio de despesas de viagem”. Em uma base interna que criei para a equipe, já na primeira semana diminuíram bastante as perguntas repetidas sobre onde encontrar cada documento.
2. Sistema de recomendação de artigos
Muitos sites implementam a seção “leia também” com correspondência rígida de tags ou recomendações aleatórias. O Vectorize encontra automaticamente artigos realmente relacionados ao conteúdo atual. Se o usuário estiver lendo “boas práticas com React Hooks”, o sistema pode recomendar “erros comuns com useEffect” em vez de “introdução ao Vue”. No meu blog, esse recurso aumentou a taxa de cliques em 40% em comparação com as recomendações aleatórias.
3. Aplicações RAG, para fornecer uma base de conhecimento à IA
RAG é a sigla de Retrieval-Augmented Generation. Em termos simples, permite que o ChatGPT responda a perguntas com base nos seus dados privados. Se você tem 100 documentos de produto e alguém pergunta “este recurso aceita importação em lote?”, o sistema primeiro encontra os documentos relevantes no Vectorize e depois envia o conteúdo ao GPT para gerar a resposta. Assim, a IA reduz invenções e responde com base nos documentos reais. Muitos robôs de atendimento atuais funcionam dessa maneira.
4. Deduplicação e classificação de conteúdo
Em um sistema de feedback, centenas de mensagens diárias podem descrever o mesmo problema. O Vectorize pode agrupar automaticamente frases como “falha ao entrar”, “não consigo fazer login” e “acesso indisponível”, evitando a revisão manual de cada item. Em fluxos de moderação, ele também ajuda a localizar artigos duplicados e textos de marketing semelhantes.
Esses quatro cenários cobrem grande parte dos usos comuns de bancos de dados vetoriais. Sempre que você precisa encontrar conteúdo semelhante, essa tecnologia pode ajudar.
Parte 2: implementação prática
Preparação: configure o ambiente em 5 minutos
Antes de escrever o código, prepare o ambiente. O processo leva cerca de 5 minutos.
Primeira etapa: crie uma conta na Cloudflare
Crie gratuitamente uma conta em cloudflare.com. Se você já usa outros serviços da Cloudflare, como CDN ou DNS, pode usar a conta existente.
Segunda etapa: instale o Wrangler CLI
Wrangler é a ferramenta de linha de comando da Cloudflare para gerenciar Workers e Vectorize. Abra o terminal e execute:
npm install -g wrangler
Se você usa yarn ou pnpm, substitua pelo comando correspondente. Depois da instalação, confira a versão:
wrangler --version
Se o número da versão aparecer, a instalação foi concluída.
Terceira etapa: entre na Cloudflare
No terminal, execute:
wrangler login
O navegador abrirá para você autorizar o acesso. Clique em “Permitir”. Ao voltar ao terminal, a mensagem Successfully logged in deverá aparecer.
Quarta etapa: crie o projeto
Crie uma pasta para o projeto:
mkdir vectorize-demo
cd vectorize-demo
wrangler init
O Wrangler fará algumas perguntas. Você pode pressionar Enter para aceitar os valores padrão. Se ele perguntar sobre TypeScript, recomendo escolher “Yes”, embora JavaScript também funcione.
O diretório do projeto deve conter estes arquivos:
wrangler.toml— arquivo de configuraçãosrc/index.ts— código do Workerspackage.json— gerenciamento de dependências
Com isso, o ambiente está pronto. Agora podemos criar o primeiro índice vetorial.
Etapa principal: crie seu primeiro índice vetorial
O índice é onde os vetores ficam armazenados. Você pode criá-lo com um único comando.
Crie o índice
No diretório do projeto, execute:
wrangler vectorize create my-search-index --preset @cf/baai/bge-small-en-v1.5
my-search-index é o nome do índice. Você pode escolher outro, desde que use apenas letras, números e hífens. O parâmetro --preset define o modelo de embeddings; neste exemplo, usamos o modelo BGE integrado da Cloudflare, com 768 dimensões.
Ao final, você deverá ver uma saída semelhante a esta:
✅ Successfully created index my-search-index
O preset simplifica a escolha do modelo. A Cloudflare oferece vários modelos de embeddings integrados, sem exigir a compra de uma API da OpenAI. O bge-small-en-v1.5 é um modelo pequeno de 768 dimensões, com bom equilíbrio entre desempenho, velocidade e custo. Para buscas em chinês, use @cf/baai/bge-base-zh-v1.5.
Configure o wrangler.toml
Em seguida, informe ao Workers qual índice deve ser usado. Abra o arquivo wrangler.toml e adicione estas linhas ao final:
[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "my-search-index"
binding é o nome da variável usada para acessar o índice no código. index_name deve ser igual ao nome criado no comando anterior.
Confirme a criação
Para conferir se o índice foi criado, liste todos os índices:
wrangler vectorize list
O resultado deverá incluir my-search-index.
Erros frequentes
Estes são alguns problemas que encontrei no início:
- Se aparecer
Index already exists, você já criou um índice com esse nome. Escolha outro ou usewrangler vectorize deletepara excluir o antigo - Se você esquecer a configuração
[[vectorize]]nowrangler.toml,env.VECTORIZE_INDEXseráundefinedno código - O nome do modelo no preset precisa estar correto; consulte a lista de modelos compatíveis na documentação da Cloudflare
Agora o índice está pronto. O próximo passo é inserir dados e fazer consultas.
Código: busca semântica em cerca de 30 linhas
Vamos implementar uma busca semântica completa da forma mais direta possível, dividindo o código em etapas que podem ser testadas separadamente.
Primeira etapa: insira os dados
Suponha que você tenha alguns artigos e queira permitir a busca semântica. Primeiro, transforme o conteúdo em vetores e salve-os no índice.
Abra src/index.ts e adicione este código:
export interface Env {
VECTORIZE_INDEX: VectorizeIndex;
AI: Ai; // Cloudflare Workers AI
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
// Endpoint para inserir dados
if (url.pathname === '/insert') {
const articles = [
{
id: '1',
title: 'Introdução ao Cloudflare Workers',
content: 'Cloudflare Workers é uma plataforma de computação serverless que executa código na borda da rede'
},
{
id: '2',
title: 'Guia de arquitetura serverless',
content: 'A computação serverless simplifica a implantação e a escalabilidade sem exigir gerenciamento de servidores'
},
{
id: '3',
title: 'Programação assíncrona em JavaScript',
content: 'Promise e async/await são as formas modernas de lidar com operações assíncronas'
}
];
// Gera os vetores em lote
const embeddings = await Promise.all(
articles.map(async (article) => {
const embedding = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
text: `${article.title} ${article.content}`
});
return {
id: article.id,
values: embedding.data[0], // Vetor de 768 dimensões
metadata: {
title: article.title,
content: article.content
}
};
})
);
// Insere os dados no Vectorize
await env.VECTORIZE_INDEX.upsert(embeddings);
return new Response('Dados inseridos com sucesso!', { status: 200 });
}
return new Response('Not found', { status: 404 });
}
};
O código executa três ações:
- Define três artigos de exemplo
- Usa o modelo de IA da Cloudflare para transformar cada artigo em um vetor de 768 dimensões
- Chama
upsertpara salvar os vetores no índice do Vectorize
Observe o campo metadata: ele guarda o título e o conteúdo originais, que podem ser recuperados diretamente na busca.
Segunda etapa: faça a consulta
Agora que os dados estão no índice, adicione um endpoint de busca:
// Adicione este trecho dentro da função fetch
if (url.pathname === '/search') {
const query = url.searchParams.get('q');
if (!query) {
return new Response('O parâmetro de consulta q é obrigatório', { status: 400 });
}
// Transforma o texto da consulta em vetor
const queryEmbedding = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
text: query
});
// Busca os cinco resultados mais semelhantes no índice
const results = await env.VECTORIZE_INDEX.query(queryEmbedding.data[0], {
topK: 5,
returnMetadata: true
});
// Formata os resultados
const formattedResults = results.matches.map((match) => ({
id: match.id,
score: match.score, // Pontuação de similaridade entre 0 e 1
title: match.metadata?.title,
content: match.metadata?.content
}));
return new Response(JSON.stringify(formattedResults, null, 2), {
headers: { 'Content-Type': 'application/json' }
});
}
Esse endpoint faz quatro coisas:
- Recebe o parâmetro
q, por exemplo “plataforma sem servidor” - Transforma o texto da consulta em vetor
- Chama
querypara encontrar os cinco resultados mais semelhantes - Retorna os resultados com suas pontuações
Terceira etapa: teste localmente
Depois de salvar o código, execute:
wrangler dev
O Wrangler iniciará um servidor local, normalmente em http://localhost:8787.
Primeiro, insira os dados:
curl http://localhost:8787/insert
Se a mensagem Dados inseridos com sucesso! aparecer, está funcionando.
Em seguida, teste a busca:
curl "http://localhost:8787/search?q=plataforma%20sem%20servidor"
Você deverá receber um resultado semelhante a este:
[
{
"id": "1",
"score": 0.89,
"title": "Introdução ao Cloudflare Workers",
"content": "Cloudflare Workers é uma plataforma de computação serverless..."
},
{
"id": "2",
"score": 0.85,
"title": "Guia de arquitetura serverless",
"content": "A computação serverless simplifica a implantação e a escalabilidade..."
}
]
Observe o campo score, que varia de 0 a 1: quanto maior, mais relevante é o resultado. Mesmo pesquisando por “plataforma sem servidor”, a consulta encontrou artigos sobre Cloudflare Workers e serverless. Esse é o efeito da busca semântica.
Detalhes do código
Alguns pontos merecem explicação:
- Por que não usar a API da OpenAI? O Cloudflare Workers AI já inclui modelos de embeddings, oferece uma cota gratuita suficiente para começar e dispensa o gerenciamento de outra chave de API
- O que é upsert? É a combinação de atualizar e inserir: se o ID já existe, o item é atualizado; caso contrário, é inserido
- Qual valor usar em topK? Em geral, de 5 a 10 resultados são suficientes; uma lista maior costuma ser pouco útil para o usuário
Até aqui, você já tem a maior parte da funcionalidade. Agora vamos melhorar a precisão da busca.
Técnicas avançadas: três formas de melhorar os resultados
A implementação básica funciona, mas alguns ajustes podem melhorar bastante a qualidade.
1. Filtro por metadados: limite o escopo da busca
Imagine que o blog tenha categorias como “tecnologia”, “cotidiano” e “resenhas de livros”. Ao pesquisar “Python”, o usuário provavelmente quer artigos técnicos. Um filtro por metadados resolve isso.
Adicione uma categoria a cada artigo na inserção:
metadata: {
title: article.title,
content: article.content,
category: 'tech' // Novo campo de categoria
}
Depois, aplique o filtro na busca:
const results = await env.VECTORIZE_INDEX.query(queryEmbedding.data[0], {
topK: 5,
returnMetadata: true,
filter: { category: 'tech' } // Busca somente conteúdo técnico
});
Assim, uma busca por “Python” não retorna um texto da categoria cotidiano sobre uma cobra píton.
2. Busca híbrida: semântica e palavras-chave juntas
Às vezes, a busca puramente semântica deixa passar correspondências exatas. Se alguém pesquisar “React 18”, é natural esperar que artigos com “React 18” no título apareçam primeiro.
Combine a busca vetorial com um ajuste por palavra-chave:
// Primeiro, faz a busca semântica
const vectorResults = await env.VECTORIZE_INDEX.query(queryEmbedding.data[0], {
topK: 20, // Obtém mais candidatos
returnMetadata: true
});
// Depois, filtra e ajusta o peso pelas palavras-chave
const finalResults = vectorResults.matches
.map((match) => {
let boostedScore = match.score;
// Aumenta a pontuação quando o título contém a consulta exata
if (match.metadata?.title.includes(query)) {
boostedScore += 0.2;
}
return { ...match, score: boostedScore };
})
.sort((a, b) => b.score - a.score)
.slice(0, 5); // Mantém os cinco primeiros
Essa combinação usa o significado para encontrar candidatos e as palavras-chave para ajustar a ordem, melhorando a precisão.
3. Operações em lote: melhore o desempenho
Inserir centenas ou milhares de itens um por um é lento. O Vectorize aceita operações em lote, o que aumenta bastante o desempenho.
// Divide os artigos em lotes de 100 itens
const batchSize = 100;
for (let i = 0; i < allArticles.length; i += batchSize) {
const batch = allArticles.slice(i, i + batchSize);
const embeddings = await Promise.all(
batch.map(async (article) => {
// ... Gera os vetores
})
);
await env.VECTORIZE_INDEX.upsert(embeddings);
}
Em um teste com 500 artigos, a inserção individual levou 20 minutos. Em lotes, terminou em 3 minutos.
Há mais uma otimização: se você armazenar os resultados de consultas populares no Workers KV, pode adicionar uma camada de cache. Consultas repetidas serão lidas do KV sem executar novamente o cálculo vetorial.
Parte 3: problemas comuns
Erros frequentes e suas soluções
Estes são os problemas que encontrei com mais frequência ao usar o Vectorize.
Problema 1: incompatibilidade na dimensão dos vetores
A mensagem de erro é Dimension mismatch: expected 768, got 1536.
A causa é simples: o índice foi criado para um modelo de 768 dimensões, como o bge-small, mas depois os vetores foram gerados com um modelo de 1.536 dimensões, como o text-embedding-3-small da OpenAI. Todos os vetores de um mesmo índice do Vectorize precisam ter a mesma dimensão.
Soluções:
- Opção 1: recrie o índice com um preset compatível com o modelo de embeddings
- Opção 2: troque o modelo de embeddings para manter a mesma dimensão
Minha recomendação é escolher o modelo no início e não mudá-lo durante o projeto.
Problema 2: saber se a cota gratuita é suficiente
Essa é uma dúvida comum. A Cloudflare não informa um único número explícito para toda a cota, mas é possível estimá-la pela fórmula de preços:
Armazenamento: aproximadamente 5 milhões de vetores de 768 dimensões
Consultas: cerca de 3 milhões por mês
Para projetos pequenos, isso é mais que suficiente. Meu blog tem 200 artigos, recebe 300 visitas diárias e registra cerca de 30 buscas por dia. Depois de um mês, a cobrança ficou em US$ 0, dentro da cota gratuita.
Mesmo se você ultrapassar a cota, a cobrança por uso continua muito baixa: 1 milhão de vetores e 30 mil consultas custam apenas US$ 0,31.
Problema 3: escolher o modelo de embeddings
A Cloudflare oferece vários modelos integrados, e a escolha depende do cenário:
- Conteúdo em chinês:
@cf/baai/bge-base-zh-v1.5, otimizado especificamente para chinês - Conteúdo em inglês:
@cf/baai/bge-small-en-v1.5, com bom equilíbrio entre desempenho e custo - Conteúdo multilíngue:
@cf/baai/bge-m3, compatível com mais de 100 idiomas
Se você busca a melhor qualidade possível, também pode usar o text-embedding-3-small da OpenAI, com 1.536 dimensões. Nesse caso, será necessário chamar a API por conta própria e o custo será um pouco maior.
Na minha experiência, os modelos BGE integrados da Cloudflare já oferecem boa qualidade na maioria dos casos.
Problema 4: migrar dados de outro banco de dados vetorial
Se você já usa o Pinecone e quer migrar para o Vectorize para reduzir custos, o processo é direto:
- Exporte todos os vetores e metadados do Pinecone
- Converta-os para o formato do Vectorize
- Faça o upsert em lote no novo índice
Este pseudocódigo mostra o fluxo:
// Obtém todos os vetores do Pinecone
const pineconeVectors = await pineconeIndex.fetch({ ids: allIds });
// Converte o formato
const vectorizeFormat = Object.entries(pineconeVectors.vectors).map(
([id, vector]) => ({
id,
values: vector.values,
metadata: vector.metadata
})
);
// Insere os dados no Vectorize em lotes
const batchSize = 100;
for (let i = 0; i < vectorizeFormat.length; i += batchSize) {
const batch = vectorizeFormat.slice(i, i + batchSize);
await env.VECTORIZE_INDEX.upsert(batch);
}
A dimensão dos vetores precisa ser igual. Se o índice do Pinecone usa 1.536 dimensões, o índice do Vectorize também precisa de um preset com 1.536 dimensões.
Problema 5: resultados de busca pouco precisos
Quando os resultados ficam muito diferentes do esperado, verifique três causas comuns:
- O modelo de embeddings não é adequado ao domínio: um modelo genérico pode não funcionar bem com conteúdo médico, por exemplo; nesse caso, considere um modelo especializado
- O texto de entrada é curto demais: vetores precisam de contexto suficiente para representar o significado; título e resumo funcionam melhor do que apenas o título
- Os dados não foram limpos: muitas tags HTML e caracteres especiais prejudicam a qualidade dos vetores
Minha abordagem é combinar título, resumo e os primeiros 200 caracteres do corpo. O resultado fica claramente melhor do que usar apenas o título.
Quando vale a pena migrar para outra solução
O Vectorize é econômico, mas não resolve todos os cenários. Estes sinais indicam que talvez seja hora de avaliar outra opção.
Sinal 1: mais de 5 milhões de vetores
Atualmente, cada índice do Vectorize aceita no máximo 5 milhões de vetores. Para conjuntos maiores, como dezenas de milhões de produtos em uma plataforma de comércio eletrônico, considere o Pinecone ou um cluster próprio do Milvus. A maioria das aplicações, porém, não chega perto dessa escala.
Sinal 2: necessidade de busca multimodal
Atualmente, o Vectorize trabalha com vetores de texto. Se você também precisa pesquisar imagens, áudio e vídeo, o Weaviate é uma opção melhor porque oferece suporte nativo a dados multimodais.
Sinal 3: consultas complexas em grafo
Se a aplicação combina um grafo de conhecimento com filtros complexos, como “encontre todos os artigos relacionados a XX, publicados em 2024 e escritos por YY”, o Vectorize pode não ser suficiente. Uma alternativa é usar GraphRAG, combinando um banco de dados em grafo como o Neo4j com busca vetorial.
Sinal 4: exigência de latência extremamente baixa
As consultas do Vectorize costumam levar de 50 a 200 ms, o que já é rápido para a maioria das aplicações. Para recomendações em tempo real que precisam responder em até 10 ms, talvez seja necessária uma solução em memória com Redis e Faiss.
Minha recomendação
Não busque a solução perfeita logo no início. Primeiro, implemente o recurso com o Vectorize e valide a direção do produto. Se o negócio crescer e surgirem gargalos, avalie uma migração. O custo de mudança não é tão alto: o formato dos dados vetoriais é parecido entre as plataformas, e um script pode transferi-los em poucas horas.
Já vi pessoas passarem um mês escolhendo a tecnologia sem começar o projeto. É melhor implementar primeiro e ajustar quando os problemas reais aparecerem.
Conclusão
Voltando à pergunta inicial: bancos de dados vetoriais são caros?
Depende da opção escolhida. O Pinecone custa no mínimo US$ 50 por mês, mas a cota gratuita do Vectorize é suficiente para executar uma aplicação de porte razoável. A busca semântica do meu blog está ativa há dois meses e a cobrança continua em US$ 0.
Partimos dos conceitos e chegamos a uma implementação completa, incluindo técnicas avançadas e soluções para os erros mais comuns. Se você quer adicionar busca semântica ao seu projeto, vale testar: em 30 minutos é possível colocar uma demonstração no ar com custo praticamente zero.
Próximos passos:
- Siga o exemplo oficial da Cloudflare e teste o recurso em 5 minutos
- Entre no Discord da Cloudflare para tirar dúvidas
- Conecte seus próprios dados e crie uma aplicação útil, como busca em uma base de conhecimento da empresa, pesquisa em notas pessoais ou um robô de atendimento inteligente
A busca semântica não é tão difícil quanto parece; o principal é começar. Quando você a colocar em uso, perceberá quantos problemas práticos ela pode resolver.
Se este artigo foi útil, compartilhe com outras pessoas que também estão desenvolvendo aplicações de IA. Assim, todos economizam e aprendem juntos.
Implemente uma busca semântica com Vectorize em 30 minutos
Da preparação do ambiente e criação do índice vetorial até uma busca semântica completa em cerca de 30 linhas de código, com técnicas avançadas e soluções para erros comuns
Estimated time: PT30M
-
1
Step 1: Prepare o ambiente em 5 minutos: crie uma conta na Cloudflare e instale o Wrangler CLI
Primeira etapa: crie uma conta na Cloudflare -
2
Step 2: Crie o primeiro índice vetorial com um único comando
Crie o índice: -
3
Step 3: Implemente a busca semântica em cerca de 30 linhas: inserção e consulta
Primeira etapa, inserir dados: abra src/index.ts e escreva o código que define três artigos de exemplo, usa o modelo de IA da Cloudflare para transformar cada um em um vetor de 768 dimensões e chama upsert para salvá-los no índice do Vectorize. O campo metadata pode armazenar o título e o conteúdo originais para recuperá-los na busca. Segunda etapa, consultar: adicione um endpoint à função fetch, receba o parâmetro q, transforme o texto em vetor, chame query para localizar os cinco resultados mais semelhantes e devolva os itens com suas pontuações. Terceira etapa, testar localmente: execute wrangler dev. O Wrangler iniciará um servidor local, normalmente em http://localhost:8787. Insira os dados com curl http://localhost:8787/insert e, quando a mensagem de sucesso aparecer, teste a busca com curl “http://localhost:8787/search?q=plataforma%20sem%20servidor”. A resposta será um JSON com id, score, title e content. Quanto maior o score, mais relevante é o resultado. Mesmo pesquisando por “plataforma sem servidor”, a consulta encontra artigos sobre Cloudflare Workers e serverless: esse é o efeito da busca semântica. Por que não usar a API da OpenAI? O Cloudflare Workers AI já inclui modelos de embeddings, oferece cota gratuita e dispensa outra chave de API. O que é upsert? É a combinação de atualizar e inserir: se o ID já existe, o item é atualizado; caso contrário, é inserido. Qual valor usar em topK? Em geral, de 5 a 10 resultados são suficientes. -
4
Step 4: Use técnicas avançadas: filtros por metadados, busca híbrida e operações em lote
1. Filtro por metadados: limite o escopo da busca. Se o blog tem categorias como tecnologia, cotidiano e resenhas de livros, uma busca por Python provavelmente deve retornar apenas artigos técnicos. Adicione category aos metadados e inclua filter na consulta para limitar a busca à categoria técnica. Assim, Python não encontra um texto do cotidiano sobre uma cobra píton. 2. Busca híbrida: combine semântica e palavras-chave. A busca puramente semântica pode deixar passar correspondências exatas. Para React 18, obtenha mais candidatos com topK igual a 20, aumente a pontuação quando o título contiver a consulta e mantenha os cinco primeiros. Essa combinação usa o significado para encontrar candidatos e as palavras-chave para ajustar a ordem. 3. Operações em lote: melhore o desempenho. Inserir centenas ou milhares de itens um por um é lento. Divida os artigos em lotes de 100 e processe cada lote. Em um teste com 500 artigos, a inserção individual levou 20 minutos; em lotes, terminou em 3 minutos. Você também pode guardar consultas populares no Workers KV e usar uma camada de cache para evitar novos cálculos vetoriais em buscas repetidas. -
5
Step 5: Evite problemas comuns
Problema 1, incompatibilidade na dimensão dos vetores: a mensagem é Dimension mismatch: expected 768, got 1536. O índice foi criado para um modelo de 768 dimensões, como o bge-small, mas os vetores foram gerados com um modelo de 1.536 dimensões, como o text-embedding-3-small da OpenAI. Todos os vetores de um índice precisam ter a mesma dimensão. Recrie o índice com um preset compatível ou troque o modelo de embeddings. O melhor é escolher o modelo no início e não mudá-lo. Problema 2, cota gratuita: pela fórmula de preços, o armazenamento comporta aproximadamente 5 milhões de vetores de 768 dimensões e cerca de 3 milhões de consultas mensais. Meu blog tem 200 artigos, 300 visitas diárias e cerca de 30 buscas por dia; depois de um mês, a cobrança ficou em US$ 0. Se a cota for ultrapassada, 1 milhão de vetores e 30 mil consultas custam apenas US$ 0,31. Problema 3, escolha do modelo: para conteúdo em chinês, use @cf/baai/bge-base-zh-v1.5; para inglês, @cf/baai/bge-small-en-v1.5; para conteúdo multilíngue, @cf/baai/bge-m3, compatível com mais de 100 idiomas. O text-embedding-3-small da OpenAI, com 1.536 dimensões, também é uma opção de maior custo que exige uma chamada própria de API. Na maioria dos casos, os modelos BGE integrados da Cloudflare já oferecem boa qualidade. Problema 4, resultados pouco precisos: verifique se o modelo é adequado ao domínio, se o texto de entrada contém contexto suficiente e se os dados foram limpos. Minha abordagem é combinar título, resumo e os primeiros 200 caracteres do corpo; o resultado fica claramente melhor do que usar apenas o título.
FAQ
Quais são as vantagens do Vectorize em relação ao Pinecone e ao Weaviate? Quanto custa?
Pinecone:
• O plano mais barato custa pelo menos US$ 50 por mês
• Armazenar 1 milhão de vetores custa cerca de US$ 41 por mês
Weaviate:
• A versão serverless começa em US$ 25 por mês
• Armazenar e consultar 1 milhão de vetores de 1.536 dimensões pode elevar a conta a US$ 153; a versão compactada custa menos, a partir de US$ 25
Vectorize no teste:
• 1 milhão de vetores de 768 dimensões, com 1.000 consultas por dia, ou 30 mil por mês, custaram apenas US$ 0,31
• Isso mesmo: trinta e um centavos de dólar
• Segundo o blog oficial da Cloudflare, o custo de consulta caiu 75% e o de armazenamento, 98%
• O Vectorize ainda oferece uma cota gratuita suficiente para um projeto pequeno ou para validar um MVP
Dificuldade de integração:
• Pinecone e Weaviate exigem cadastro separado, gerenciamento de chaves de API e configuração de acesso à rede
• Se você já implanta aplicações com Cloudflare Workers, basta adicionar algumas linhas ao wrangler.toml para vincular o Vectorize; no código, use env.VECTORIZE_INDEX sem configurar outra variável de ambiente
Cenários adequados:
• Para projetos pequenos, MVPs e blogs pessoais, o Vectorize se destaca pelo baixo custo e pela configuração rápida
• Para ambientes corporativos e escala muito grande, com centenas de milhões de vetores, o Pinecone é mais adequado por oferecer infraestrutura e suporte empresarial mais maduros
• Para necessidades multimodais, com imagens, vídeos e áudio, o Weaviate oferece mais recursos e suporte nativo
Qual é a cota gratuita do Vectorize? Ela é suficiente?
• O armazenamento comporta aproximadamente 5 milhões de vetores de 768 dimensões
• São cerca de 3 milhões de consultas por mês
Parece bastante, e para projetos pequenos realmente é. Meu blog tem 200 artigos, recebe 300 visitas por dia e registra cerca de 30 buscas diárias; depois de um mês, a conta ficou em US$ 0, dentro da cota gratuita.
Mesmo se você ultrapassar a cota, a cobrança por uso continua muito baixa: 1 milhão de vetores e 30 mil consultas custam apenas US$ 0,31.
Segundo os dados oficiais da Cloudflare, atualmente um índice do Vectorize aceita até 5 milhões de vetores. Para a maioria das aplicações, 5 milhões de registros são suficientes; meu blog tem pouco mais de 200 artigos após três anos e ainda está muito longe desse limite.
Se você está começando com busca vetorial ou tem orçamento limitado, o Vectorize é um ótimo ponto de partida. Se o projeto realmente crescer, ainda será possível considerar uma migração mais adiante.
Como implementar busca semântica em 30 minutos? Quais são as etapas?
Primeira etapa: crie uma conta gratuita em cloudflare.com
Segunda etapa: instale o Wrangler CLI com npm install -g wrangler e confira a instalação com wrangler --version
Terceira etapa: execute wrangler login no terminal; o navegador abrirá para você autorizar o acesso
Quarta etapa: crie o projeto com mkdir vectorize-demo, cd vectorize-demo e wrangler init
Criação do primeiro índice vetorial:
• No diretório do projeto, execute wrangler vectorize create my-search-index --preset @cf/baai/bge-small-en-v1.5
Configuração do wrangler.toml:
• Abra o arquivo wrangler.toml e adicione a configuração [[vectorize]] ao final
• binding = "VECTORIZE_INDEX"
• index_name = "my-search-index"
Busca semântica em cerca de 30 linhas de código:
Primeira etapa: inserir dados
• Defina artigos de exemplo, use o modelo de IA da Cloudflare para transformar cada um em um vetor de 768 dimensões e chame upsert para salvá-los no índice do Vectorize
Segunda etapa: consultar
• Receba o parâmetro q, transforme o texto da consulta em vetor, chame query para localizar os cinco resultados mais semelhantes e retorne os itens com suas pontuações
Terceira etapa: testar localmente
• Execute wrangler dev
• Insira os dados com curl http://localhost:8787/insert
• Teste a busca com curl "http://localhost:8787/search?q=plataforma%20sem%20servidor"
Para que serve o Vectorize? Quais são os casos de uso práticos?
• É o uso mais comum
• Imagine uma empresa com centenas de documentos técnicos, manuais de produto e normas legais; uma busca tradicional com Ctrl+F não encontra bem o que o usuário realmente quer
• Com uma busca semântica no Vectorize, a consulta ‘como solicitar reembolso’ pode localizar documentos como ‘processo de reembolso de despesas’ e ‘guia para envio de despesas de viagem’
• Em uma base interna que criei para a equipe, já na primeira semana diminuíram bastante as perguntas repetidas sobre onde encontrar cada documento
2. Sistema de recomendação de artigos:
• Muitos sites implementam ‘leia também’ com correspondência rígida de tags ou recomendações aleatórias
• O Vectorize encontra automaticamente artigos realmente relacionados ao conteúdo atual
• Ao ler ‘boas práticas com React Hooks’, por exemplo, o usuário pode receber ‘erros comuns com useEffect’ em vez de ‘introdução ao Vue’
• No meu blog, esse recurso aumentou a taxa de cliques em 40% em comparação com as recomendações aleatórias
3. Aplicações RAG, para fornecer uma base de conhecimento à IA:
• RAG significa Retrieval-Augmented Generation; em termos simples, permite que o ChatGPT responda a perguntas com base nos seus dados privados
• Se você tem 100 documentos de produto e alguém pergunta se um recurso aceita importação em lote, o sistema primeiro encontra os documentos relevantes no Vectorize e depois envia esse conteúdo ao GPT para gerar a resposta
• Assim, a resposta se baseia nos documentos reais e reduz invenções da IA
• Muitos robôs de atendimento atuais funcionam dessa maneira
4. Deduplicação e classificação de conteúdo:
• Em um sistema de feedback, centenas de mensagens diárias podem descrever o mesmo problema
• O Vectorize pode agrupar automaticamente frases como ‘falha ao entrar’, ‘não consigo fazer login’ e ‘acesso indisponível’, evitando a revisão manual de cada item
• Também pode localizar rapidamente artigos duplicados e textos de marketing semelhantes durante a moderação de conteúdo
Quais são os problemas mais comuns ao usar o Vectorize e como resolvê-los?
• A mensagem é Dimension mismatch: expected 768, got 1536
• A causa é simples: o índice foi criado para um modelo de 768 dimensões, como o bge-small, mas depois os vetores foram gerados com um modelo de 1.536 dimensões, como o text-embedding-3-small da OpenAI
• Todos os vetores de um mesmo índice do Vectorize precisam ter a mesma dimensão
• Soluções:
Opção 1: recrie o índice com um preset compatível com o modelo de embeddings
Opção 2: troque o modelo de embeddings para manter a mesma dimensão
• O melhor é escolher o modelo no início e não mudá-lo durante o projeto
Problema 2: saber se a cota gratuita é suficiente
• A Cloudflare não informa um único número explícito para toda a cota, mas é possível estimá-la pela fórmula de preços
• Armazenamento: aproximadamente 5 milhões de vetores de 768 dimensões
• Consultas: cerca de 3 milhões por mês
• Para projetos pequenos, isso é mais que suficiente. Meu blog tem 200 artigos, 300 visitas diárias e cerca de 30 buscas por dia; após um mês, a cobrança foi de US$ 0
• Se a cota for ultrapassada, 1 milhão de vetores e 30 mil consultas custam apenas US$ 0,31
Problema 3: escolher o modelo de embeddings
• A Cloudflare oferece vários modelos integrados; a escolha depende do cenário
• Para conteúdo em chinês, use @cf/baai/bge-base-zh-v1.5
• Para conteúdo em inglês, use @cf/baai/bge-small-en-v1.5
• Para conteúdo multilíngue, use @cf/baai/bge-m3, que aceita mais de 100 idiomas
• Para buscar a melhor qualidade possível, também é possível usar o text-embedding-3-small da OpenAI, com 1.536 dimensões, mas isso exige uma chamada própria de API e tem custo maior
• Na maioria dos casos, os modelos BGE integrados da Cloudflare já oferecem boa qualidade
Problema 4: resultados de busca pouco precisos
• Há três causas frequentes:
1) O modelo de embeddings não é adequado ao domínio, como ocorre quando um modelo genérico é usado em conteúdo médico
2) O texto de entrada é curto demais; vetores precisam de contexto suficiente, então título e resumo funcionam melhor do que apenas o título
3) Os dados não foram limpos; muitas tags HTML e caracteres especiais prejudicam a qualidade dos vetores
• Minha abordagem é combinar título, resumo e os primeiros 200 caracteres do corpo; o resultado fica claramente melhor do que usar apenas o título
Quando vale a pena migrar para outra solução? Quais são os limites do Vectorize?
• Atualmente, cada índice do Vectorize aceita no máximo 5 milhões de vetores
• Para conjuntos maiores, como dezenas de milhões de produtos em uma plataforma de comércio eletrônico, considere o Pinecone ou um cluster próprio do Milvus
• A maioria das aplicações, porém, não chega perto dessa escala
Sinal 2: necessidade de busca multimodal
• Atualmente, o Vectorize trabalha com vetores de texto; se você também precisa pesquisar imagens, áudio e vídeo, o Weaviate é uma opção melhor por oferecer suporte multimodal nativo
Sinal 3: consultas complexas em grafo
• Se a aplicação precisa combinar um grafo de conhecimento com filtros complexos, como localizar todos os artigos relacionados a determinado tema, publicados em 2024 e escritos por um autor específico, o Vectorize pode não ser suficiente
• Uma alternativa é usar GraphRAG, combinando um banco de dados em grafo como o Neo4j com busca vetorial
Sinal 4: exigência de latência extremamente baixa
• As consultas do Vectorize costumam levar de 50 a 200 ms, o que já é rápido para a maioria das aplicações
• Para recomendações em tempo real que precisam responder em até 10 ms, talvez seja necessária uma solução em memória com Redis e Faiss
Minha recomendação é não buscar a solução perfeita logo no início. Primeiro, implemente o recurso com o Vectorize e valide a direção do produto. Se o negócio crescer e surgirem gargalos, avalie uma migração. A estrutura dos dados vetoriais é parecida entre as plataformas, e um script pode transferi-los em poucas horas. É melhor começar e ajustar quando necessário do que passar um mês escolhendo a tecnologia sem tirar o projeto do papel.
23 min de leitura · Publicado em: 1 dez 2025 · Atualizado em: 4 set 2026
Guia Cloudflare AI Stack
Se você chegou pela busca, o caminho mais rápido é ir para o post anterior ou próximo desta série.
Anterior
Trocar de provedor de IA dá trabalho? Um AI Gateway resolve monitoramento, cache e failover (40% menos custos)
Aprenda passo a passo a usar um AI Gateway para gerenciar OpenAI, Claude, Gemini e outros provedores de IA em um só lugar, com failover automático, cache inteligente e monitoramento global, reduzindo os custos em 40% e elevando a disponibilidade a 99,9%. Inclui a comparação de três soluções e exemplos completos de código.
Parte 2 de 4
Próximo
Base de conhecimento com IA em 20 minutos? Aprenda RAG com Workers AI e Vectorize (código completo)
Quer criar uma base de conhecimento com IA, mas ainda não entende RAG? Aprenda passo a passo a desenvolver uma aplicação RAG com Cloudflare Workers AI e Vectorize, da teoria à implantação em 20 minutos, com código completo, análise de custos e dicas práticas.
Parte 4 de 4



Comentários
Entre com GitHub para comentar