Pinha: o que é e como utilizá-la

O nosso interesse é praticamente nulo, mas vale a pena referi-lo na mesma: somos a Geonode e comercializamos proxies, que nada têm a ver com bases de dados vetoriais. A única ligação é que um sistema de pesquisa precisa de algo sobre o qual pesquisar e, se esse conteúdo provém da Web pública, alguém tem de o recolher — o que constitui a nossa parte do processo e é totalmente independente da base de dados. Nada neste artigo obriga a comprar-nos nada, e a secção que argumenta contra uma base de dados vetorial gerida está incluída porque, frequentemente, essa é a resposta certa.

O que faz uma base de dados vetorial

As bases de dados comuns fazem correspondências exatas. Uma base de dados vetorial faz correspondências com base na semelhança.

O mecanismo: um modelo de incorporação converte texto, imagens ou outros conteúdos numa lista de números — um vetor — posicionados de forma a que elementos semelhantes fiquem próximos uns dos outros. Encontrar resultados relevantes passa a ser uma questão de localizar pontos próximos, o que constitui um problema de geometria, em vez de uma questão de correspondência de cadeias de caracteres.

A Pinecone descreve-se como «a base de dados vetorial para agentes e aplicações de IA, concebida para pesquisa semântica, recuperação de conhecimento e memória de longo prazo em grande escala», com a capacidade de pesquisar «entre milhares de milhões de itens para encontrar correspondências semelhantes a qualquer objeto, em milésimos de segundo».

A razão pela qual isto se tornou uma infraestrutura, em vez de uma biblioteca, é a escala. Comparar uma consulta com um milhão de vetores por força bruta é simples, mas lento; fazê-lo em milissegundos requer índices aproximados de vizinho mais próximo, e executá-los de forma fiável em grande escala é um problema operacional. É isso que um serviço gerido oferece.

O caso de utilização dominante é a geração aumentada por recuperação: dada a pergunta de um utilizador, encontrar as passagens mais relevantes nos seus próprios documentos e fornecê-las a um modelo de linguagem como contexto. A base de dados fornece a etapa de «encontrar as passagens relevantes».

Índices, documentos e registos

O modelo de dados do Pinecone sofreu alterações e vale a pena compreendê-lo tal como se apresenta atualmente.

Um índice é onde os dados residem. A documentação explica que «um índice sem servidor armazena os seus dados como documentos ou registos, dependendo da forma como o índice foi criado: um índice criado com um esquema de documento armazena documentos, enquanto um índice criado com um tipo de vetor denso ou esparso armazena registos».

Um esquema de documento permite que um único índice desempenhe várias funções. De acordo com a documentação, «um único índice com um esquema de documento pode combinar vários tipos de campos de classificação: um campo «dense_vector» para pesquisa semântica, um campo «sparse_vector» para recuperação de vetores esparsos e um ou mais campos de cadeia de caracteres com «full_text_search» ativado para pesquisa de texto completo com consultas BM25 e Lucene.»

Os metadados não necessitam de declaração. «Quaisquer outros campos que insira ou atualize são armazenados como metadados, indexados automaticamente para filtragem — não é necessária qualquer declaração de esquema.»

A orientação de conceção é clara: «Um índice por caso de utilização é o padrão típico. Como um documento pode combinar vetores, texto e metadados no mesmo registo, um único índice abrange frequentemente o que anteriormente exigia dois — escolha o sinal de classificação por consulta com score_by.»

Este último ponto é o mais significativo. A pesquisa de texto completo está disponível a par da pesquisa vetorial no mesmo índice — «correspondência de tokens BM25 com sintaxe de consulta Lucene sobre campos de texto no seu esquema», sendo que o Pinecone trata da «tokenização, IDF e normalização do comprimento no momento da indexação e da pontuação BM25 no momento da consulta». Não é necessário um motor de pesquisa separado, nem qualquer modelo para a parte das palavras-chave.

A consequência prática é que a pesquisa híbrida — que combina a semelhança semântica com a correspondência exata de palavras-chave — é uma escolha feita no momento da consulta, em vez de uma questão de arquitetura. O que é importante, porque a pesquisa vetorial pura é notoriamente fraca em identificadores exatos, códigos de produto e nomes próprios raros, e o BM25 é excelente precisamente nesses aspetos.

Espaços de nomes

A funcionalidade que mais influencia a forma como se concebe uma aplicação multitenant.

A documentação: «Dentro de um índice, os registos são particionados em espaços de nomes, e todas as operações de upsert, consultas e outras operações de leitura e escrita de dados têm sempre como alvo um único espaço de nomes.»

São referidas duas vantagens. Multilocação — «quando é necessário isolar dados entre clientes, pode utilizar um espaço de nomes por cliente e direcionar as gravações e consultas de cada cliente para o seu espaço de nomes dedicado.» E consultas mais rápidas — «ao dividir os registos em espaços de nomes de forma lógica, acelera as consultas, garantindo que apenas os registos relevantes são analisados.»

Três notas operacionais.

São criados implicitamente. «Os namespaces são criados automaticamente durante o upsert. Se um namespace não existir, é criado implicitamente.» É prático e significa que um erro ortográfico no nome de um namespace resulta numa pesquisa silenciosamente vazia, em vez de um erro.

O limite depende do plano. «O número de namespaces por índice sem servidor varia consoante o plano. Nos planos Standard e Enterprise, o Pinecone pode acomodar namespaces na ordem dos milhões e mais, para casos de utilização específicos. Se a sua aplicação necessitar de mais de 100 000 namespaces, contacte o Suporte.»

O isolamento é o objetivo. Para qualquer coisa que contenha dados de vários clientes, um namespace por cliente é a norma, e isso faz com que a fuga de dados entre inquilinos se resuma a acertar num único parâmetro, em vez de ter de acertar num filtro.

Embeddings: os seus ou os deles

Duas abordagens, e a escolha tem consequências reais.

Embedding integrado. A documentação descreve-o em quatro passos: «Crie um índice integrado com um dos modelos de embedding alojados pelo Pinecone. Insira ou atualize o seu texto de origem. O Pinecone utiliza o modelo integrado para converter automaticamente o texto em vetores. Efetue uma pesquisa com um texto de consulta. Mais uma vez, o Pinecone utiliza o modelo integrado para converter automaticamente o texto num vetor.»

Mais simples — envia o texto e recebe os resultados, sem precisar de um pipeline de embedding próprio. Uma restrição documentada: «Os índices com incorporação integrada não suportam a atualização ou importação de texto.»

Traga os seus próprios vetores. Executa o modelo de incorporação, cria um índice que corresponda às suas características e insere ou atualiza vetores diretamente, utilizando «o mesmo modelo de incorporação externo para converter uma consulta num vetor».

Mais trabalho e mais controlo. Permite-lhe utilizar um modelo que a Pinecone não hospeda, executar a incorporação localmente por motivos de privacidade ou de custos e — o que é crucial — alterar os modelos de acordo com o seu próprio calendário.

A consideração que é decisiva para muitas pessoas: alterar os modelos de incorporação significa reincorporar tudo. Os vetores de modelos diferentes não são comparáveis, pelo que uma mudança implica uma reindexação completa. A incorporação integrada facilita a construção inicial e vincula a decisão ao catálogo de modelos do fornecedor; utilizar o seu próprio modelo torna a construção mais difícil, mas mantém a escolha nas suas mãos. Nenhuma das opções está errada, e vale a pena decidir de forma deliberada, em vez de se basear no primeiro tutorial que tiver seguido.

Carregamento de dados em grande escala

Uma questão de custos que é fácil de ignorar e dispendiosa de descobrir.

A documentação é clara: «Para controlar os custos ao importar grandes conjuntos de dados (mais de 10 000 000 de registos), utilize a função “import” em vez de “upsert”.»

Existem duas formas de importação. O «upsert» envia registos através da API. A importação lê ficheiros Parquet a partir do armazenamento de objetos, e a documentação refere-a como «a forma mais eficiente e económica de carregar um grande número de registos num índice».

Dado que as gravações são faturadas por milhão de unidades de gravação, a diferença entre estas duas vias numa grande carga inicial é um valor real e não um erro de arredondamento. Se estiver a criar um índice com milhões de registos, planeie a via de importação desde o início — adaptá-la após uma primeira carga dispendiosa é uma lição pela qual ninguém precisa de pagar duas vezes.

Introdução prática

A estrutura de uma primeira implementação e as decisões nela incorporadas.

Criar um índice e fazer um upsert. Com a incorporação integrada, o fluxo é curto — nunca se lida diretamente com um vetor:

from pinecone import Pinecone

pc = Pinecone(api_key=API_KEY)

index = pc.Index(host=INDEX_HOST)

index.upsert_records(
    namespace="customer-42",
    records=[
        {"_id": "doc-1", "chunk_text": "Refunds are processed within 14 days.",
         "source": "policy.pdf", "page": 3},
        {"_id": "doc-2", "chunk_text": "Shipping to the EU takes 3-5 working days.",
         "source": "shipping.pdf", "page": 1},
    ],
)

Note-se que source

e page

nunca foram declarados. Tudo o que for além dos campos de classificação é armazenado como metadados e indexado para filtragem automática, o que significa que pode adicionar campos posteriormente sem necessidade de migração.

Consulta com um filtro:

results = index.search(
    namespace="customer-42",
    query={"inputs": {"text": "how long do refunds take?"}, "top_k": 5,
           "filter": {"source": {"$eq": "policy.pdf"}}},
)

Há três decisões nesse trecho que vale a pena tomar deliberadamente.

Tamanho do bloco. O texto que insere ou atualiza é a unidade que é devolvida, pelo que a divisão em blocos determina o que o seu modelo vê. Blocos demasiado pequenos perdem o contexto que lhes confere significado; se forem demasiado grandes, recupera-se principalmente texto irrelevante juntamente com a frase relevante. Não existe uma resposta universal — algumas centenas de palavras com alguma sobreposição constituem um ponto de partida razoável, e medir é melhor do que adivinhar.

Os metadados são a sua superfície de filtragem. Armazene tudo aquilo que possa vir a querer utilizar para restringir a pesquisa: documento de origem, data, secção, idioma, nível de acesso. Adicioná-los no momento da inserção ou atualização não custa nada; adicioná-los posteriormente implica uma nova inserção ou atualização.

Espaço de nomes por inquilino, sempre, desde o início. Implementar o isolamento num índice de espaço de nomes único significa re-upsertar tudo com o destino correto. Começar com espaços de nomes custa um parâmetro e elimina toda uma categoria de incidentes futuros.

E guarde o texto de origem. Armazene os documentos originais num local sob o seu controlo, juntamente com o código de fragmentação. Se alterar o modelo de incorporação, o tamanho dos fragmentos ou a estratégia de fragmentação — e irá fazê-lo —, a reconstrução do índice será uma simples repetição, em vez de um exercício de arqueologia.

Preços, verificados

Extraídos da própria página de preços da Pinecone, consultada em setembro de 2026. Verifique antes de elaborar o orçamento.

Quatro observações importantes para o planeamento.

O nível gratuito é verdadeiramente útil para avaliação. Dois gigabytes de armazenamento e um milhão de unidades de leitura mensais são suficientes para construir um protótipo real com base num conjunto substancial de documentos.

O plano «Builder» tem uma tarifa fixa, não um mínimo. A 20 dólares/mês com limites máximos fixos, é previsível de uma forma que os planos baseados na utilização não são — útil para uma pequena aplicação de produção em que se prefere ter uma fatura que se possa prever.

Os planos Standard e Enterprise têm valores mínimos com sobretaxa. Os valores de 50 e 500 dólares são limites mínimos, não máximos. O custo real é calculado com base na utilização acima desses valores.

As leituras custam aproximadamente quatro vezes mais do que as gravações por milhão de unidades. A 16–18 dólares por milhão de unidades de leitura, contra 4–4,50 dólares para gravações, uma aplicação com grande volume de leituras — como é o caso da maioria dos sistemas de recuperação — verá as consultas a dominarem a fatura. O armazenamento em cache de consultas frequentes é, portanto, uma alavanca de custo direta, e não apenas uma questão de latência.

O plano Enterprise inclui um SLA de 99,95% de tempo de atividade, implementação «bring-your-own-cloud», pontos de extremidade privados e registos de auditoria — o conjunto habitual de aspetos que importam num processo de aquisição, mas que não têm qualquer relevância para um protótipo.

Quando não é necessário utilizar uma base de dados de vetores gerida

A secção que um fornecedor não escreveria, incluída porque é frequentemente a resposta.

Quando o seu corpus é pequeno. Abaixo de cerca de cem mil vetores, a pesquisa de similaridade por força bruta na memória é suficientemente rápida em hardware comum. Uma matriz NumPy e um produto escalar fornecem o resultado em milissegundos, não têm qualquer custo e eliminam uma dependência externa da sua arquitetura. O limiar a partir do qual a indexação aproximada se torna necessária é mais elevado do que a maioria das pessoas supõe.

Quando já utiliza o Postgres. A extensão pgvector adiciona a pesquisa de similaridade vetorial a uma base de dados que já está a utilizar e da qual já faz cópias de segurança. Para muitas aplicações, esta é a resposta certa: menos um sistema, consistência transacional com os seus outros dados e sem custos adicionais.

Quando uma biblioteca incorporada é suficiente. Bibliotecas como o FAISS ou um armazenamento vetorial local processam milhões de vetores num único processo. Se os seus dados cabem numa única máquina e o seu volume de consultas é modesto, um serviço gerido está a resolver um problema operacional que você nem tem.

Quando a pesquisa por palavra-chave funcionaria. Uma parte significativa dos casos em que se diz «precisamos de pesquisa semântica» acaba por ser bem atendida pelo BM25, que é mais barato, mais rápido, totalmente explicável e melhor em identificadores exatos. Experimente-o primeiro — e tenha em conta que, se acabar por optar pelo Pinecone, a sua pesquisa de texto completo abrange isto no mesmo índice.

Quando ainda não avaliou a qualidade da recuperação. A base de dados não é, normalmente, o fator limitante num sistema de recuperação. A estratégia de fragmentação, a escolha do modelo de incorporação e a formulação da consulta são muito mais importantes, e todas as três podem ser testadas com uma centena de linhas de código local antes de se tomar qualquer decisão relativa à infraestrutura.

Os argumentos a favor de um serviço gerido são reais e específicos: muitos milhões de vetores, um volume de consultas que exige uma baixa latência consistente, isolamento multitenant e uma equipa que prefere não gerir um índice distribuído. Se dois ou mais destes fatores se aplicarem, o custo justifica-se.

Perguntas frequentes

Para que serve o Pinecone?

Pesquisa semântica, recuperação de conhecimento e memória de longo prazo para aplicações de IA. O padrão dominante é a «geração aumentada por recuperação»: identificar as passagens dos seus próprios documentos mais relevantes para uma pergunta e fornecê-las a um modelo de linguagem como contexto.

O Pinecone é gratuito?

Existe um plano Starter gratuito com até 2 GB de armazenamento, 2 milhões de unidades de escrita e 1 milhão de unidades de leitura por mês, e 1 GB de tráfego de saída. É realmente suficiente para construir e avaliar um protótipo real antes de optar por um plano pago.

Quanto custa o Pinecone?

O plano Starter é gratuito; o Builder tem um preço fixo de 20 $/mês com limites máximos fixos; o Standard tem um mínimo de utilização de 50 $/mês e o Enterprise de 500 $/mês, ambos cobrando o armazenamento a 0,33 $/GB/mês, as gravações a 4–4,50 dólares por milhão de unidades e as leituras a 16–18 dólares por milhão, com saída a 0,10 dólares/GB após 100 GB.

O que é um namespace no Pinecone?

Uma partição dentro de um índice. Cada operação de leitura e gravação tem como alvo exatamente um namespace, o que o torna o mecanismo padrão para o isolamento multilocatário — um namespace por cliente — e uma otimização de desempenho, uma vez que as consultas analisam apenas a partição relevante.

Devo utilizar a incorporação integrada ou os meus próprios vetores?

A incorporação integrada é mais simples: basta enviar o texto e o Pinecone converte-o. Utilizar os seus próprios vetores oferece-lhe liberdade na escolha do modelo e portabilidade, o que é importante porque alterar os modelos de incorporação requer a reincorporação de tudo. Além disso, os índices integrados não suportam a atualização ou importação com texto.

O Pinecone consegue fazer pesquisa por palavra-chave, bem como pesquisa por vetor?

Sim. Os campos de cadeia de caracteres com a opção «full_text_search» ativada suportam a classificação BM25 com sintaxe de consulta Lucene, no mesmo índice que os vetores densos e esparsos, com o método de pontuação escolhido por consulta. Isto é importante porque a pesquisa vetorial pura lida mal com identificadores exatos e termos raros.

Como posso carregar milhões de registos de forma eficiente?

Utilize a importação a partir do armazenamento de objetos em vez do «upsert». A documentação recomenda explicitamente esta abordagem para conjuntos de dados com mais de dez milhões de registos e descreve-a como a opção mais económica, o que é importante, dado que as gravações são faturadas por milhão de unidades.

Preciso mesmo de uma base de dados vetorial?

Na maioria das vezes, não. Para menos de cerca de cem mil vetores, a pesquisa por força bruta na memória é suficientemente rápida e gratuita. Se já utiliza o Postgres, o «pgvector» evita a necessidade de um sistema separado. Além disso, uma boa parte dos requisitos de «pesquisa semântica» é bem atendida pela pesquisa por palavra-chave, que é mais económica e mais fácil de explicar.

Conclusão

O Pinecone é uma base de dados de vetores gerida que evoluiu para algo mais abrangente: um índice pode agora conter vetores densos, vetores esparsos e campos de texto completo em simultâneo, sendo o método de classificação escolhido para cada consulta. Essa consolidação é a alteração recente mais útil, porque a recuperação híbrida deixa de ser uma decisão de arquitetura e passa a ser um parâmetro.

Há três aspetos que determinam como se deve projetar em função disso. Os namespaces são o mecanismo de isolamento e desempenho, e são criados implicitamente — pelo que um namespace digitado incorretamente devolve um resultado vazio em vez de um erro. A escolha da incorporação é mais complicada do que parece, uma vez que mudar de modelo implica reincorporar todo o seu corpus. Além disso, as leituras custam várias vezes mais do que as gravações, o que torna o armazenamento em cache das consultas uma alavanca de custo direta num sistema com elevado volume de leituras.

A estrutura de preços é transparente e o nível gratuito é suficientemente amplo para responder à verdadeira questão, que é se a qualidade da recuperação é boa o suficiente para o seu caso de utilização. Essa questão não diz respeito à base de dados — a divisão em blocos, a escolha da incorporação e a formulação da consulta são os fatores determinantes — e pode ser respondida localmente antes mesmo de existir qualquer infraestrutura.

E este é, na verdade, o ponto final. Uma base de dados vetorial gerida justifica a sua existência em grande escala, com multilocação, ou quando se prefere não gerir um índice distribuído. Abaixo desse nível, uma matriz na memória ou uma extensão no Postgres que já utiliza dará conta do recado sem qualquer custo, e vale a pena determinar em que situação se encontra antes de aderir a qualquer uma das opções.