Primeiros passos com Pinecone
Crie um índice no Pinecone, insira vetores com metadados, realize consultas de similaridade com filtros e gerencie espaços de nomes para separar diferentes coleções de dados.
Primeiros passos com Pinecone é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.
O que é o Pinecone?
Pinecone é um banco de dados vetorial totalmente gerenciado que cuida automaticamente da infraestrutura, da escalabilidade e das cópias de segurança. Você interage com ele por meio de um SDK Python, enviando vetores e metadados por chamadas de API. O Pinecone armazena esses dados em seus servidores e responde a consultas de similaridade com baixa latência, mesmo com bilhões de vetores.
Ele oferece um nível gratuito suficiente para aprendizado e pequenas cargas de trabalho em produção.
Instalando o SDK do Pinecone
Instale o cliente do Pinecone e inicialize-o com sua chave de API. Armazene a chave de API em uma variável de ambiente — nunca insira segredos diretamente em arquivos de código-fonte. A classe Pinecone é o principal ponto de entrada para todas as operações.
# pip install pinecone-client
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
# List existing indexes to verify connection
existing = pc.list_indexes().names()
print('Existing indexes:', existing)Criando um Index do Pinecone
Um index do Pinecone é a coleção que armazena seus vetores. Ao criar um Index, você precisa especificar a dimension (que deve corresponder ao seu modelo de embeddings) e a metric para o cálculo de similaridade. Para embeddings da OpenAI, use dimension=1536 e metric='cosine'.
A criação do Index é idempotente: a especificação serverless cria o Index sob demanda, sem pré-alocar capacidade.
from pinecone import Pinecone, ServerlessSpec
import os
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
index_name = 'my-rag-index'
if index_name not in pc.list_indexes().names():
pc.create_index(
name=index_name,
dimension=1536, # text-embedding-3-small dimension
metric='cosine',
spec=ServerlessSpec(
cloud='aws',
region='us-east-1'
)
)
print(f'Created index: {index_name}')
else:
print(f'Index already exists: {index_name}')
index = pc.Index(index_name)Inserindo ou atualizando vetores com metadados
O Pinecone usa operações de upsert (inserção ou atualização). Cada vetor exige uma string id exclusiva, os values (o embedding como uma lista de números de ponto flutuante) e metadata opcional (um dicionário de campos filtráveis). Se você executar upsert com um id existente, o vetor antigo será substituído.
from openai import OpenAI
oai = OpenAI()
documents = [
{'id': 'doc-001', 'text': 'What is RAG and how does it work?', 'category': 'faq'},
{'id': 'doc-002', 'text': 'Pinecone is a managed vector database.', 'category': 'docs'},
{'id': 'doc-003', 'text': 'OpenAI embeddings have 1536 dimensions.', 'category': 'docs'}
]
texts = [d['text'] for d in documents]
resp = oai.embeddings.create(model='text-embedding-3-small', input=texts)
vectors = [
{
'id': doc['id'],
'values': resp.data[i].embedding,
'metadata': {'text': doc['text'], 'category': doc['category']}
}
for i, doc in enumerate(documents)
]
index.upsert(vectors=vectors)
print(f'Upserted {len(vectors)} vectors')Consultando o Index do Pinecone
Para pesquisar, gere o embedding da sua consulta e chame index.query() com o vetor da consulta e top_k para especificar quantos resultados retornar. Defina include_metadata=True para receber os metadados armazenados junto com os ids e as pontuações das correspondências.
from openai import OpenAI
oai = OpenAI()
query = 'How many dimensions do OpenAI embeddings have?'
q_resp = oai.embeddings.create(model='text-embedding-3-small', input=query)
q_vec = q_resp.data[0].embedding
results = index.query(
vector=q_vec,
top_k=3,
include_metadata=True
)
for match in results['matches']:
score = match['score']
text = match['metadata']['text']
print(f'{score:.4f}: {text}')Filtrando por metadados
O Pinecone oferece pré-filtragem — restringindo a busca aos vetores que correspondem a uma condição de metadados antes de executar ANN. Use o parâmetro filter com operadores no estilo do MongoDB: $eq, $in, $gt, $lt, $and, $or.
Ao criar o Index, sempre Indexe os campos de metadados pelos quais você planeja filtrar, para garantir o desempenho da filtragem.
# Filter to only 'docs' category results
results = index.query(
vector=q_vec,
top_k=5,
filter={
'category': {'$eq': 'docs'}
},
include_metadata=True
)
print(f'Filtered results: {len(results["matches"])}')
for m in results['matches']:
print(f' [{m["metadata"]["category"]}] {m["metadata"]["text"][:60]}')Namespaces para isolamento de dados
Os namespaces do Pinecone particionam um único Index em segmentos isolados. Consultas em um namespace nunca retornam resultados de outro, o que torna os namespaces ideais para sistemas RAG multi-inquilino nos quais cada cliente deve pesquisar apenas seus próprios documentos.
Tanto upsert quanto query aceitam uma string namespace opcional. O namespace padrão é uma string vazia.
# Upsert into a specific namespace
index.upsert(
vectors=[{'id': 'doc-001', 'values': q_vec, 'metadata': {'text': 'Tenant A doc'}}],
namespace='tenant-a'
)
# Query only tenant-a's documents
results = index.query(
vector=q_vec,
top_k=5,
namespace='tenant-a',
include_metadata=True
)
print(f'Tenant-A results: {len(results["matches"])}')Inserção ou atualização em lotes para grandes conjuntos de documentos
Ao Indexar milhares de documentos, divida seus vetores em lotes de até 100 vetores por chamada de upsert (o tamanho de lote recomendado pelo Pinecone). Lotes maiores podem atingir os limites de tamanho devido à restrição de aproximadamente 4 MB por solicitação.
def batch_upsert(index, vectors, batch_size=100):
total = len(vectors)
for start in range(0, total, batch_size):
batch = vectors[start:start + batch_size]
index.upsert(vectors=batch)
print(f'Upserted {min(start + batch_size, total)}/{total}')
# Usage:
# batch_upsert(index, all_vectors, batch_size=100)Verificando as estatísticas do Index
Use index.describe_index_stats() para verificar quantos vetores estão armazenados em cada namespace e a quantidade total de vetores. Isso é útil para confirmar que um upsert foi concluído com sucesso e para monitorar o crescimento do Index ao longo do tempo.
stats = index.describe_index_stats()
print(f'Total vectors: {stats["total_vector_count"]}')
print(f'Namespaces:')
for ns, info in stats.get('namespaces', {}).items():
print(f' {ns!r}: {info["vector_count"]} vectors')Excluindo e atualizando vetores
Use index.delete(ids=[...]) para remover vetores específicos por id. Para atualizar um vetor (por exemplo, quando um documento é revisado), basta executar upsert com o mesmo id — o Pinecone substituirá a entrada existente.
Para excluir todos os vetores de um namespace (por exemplo, para re-Indexar após uma atualização completa), use index.delete(delete_all=True, namespace='...').
# Delete specific vectors by id
index.delete(ids=['doc-001', 'doc-002'])
# Update a vector (upsert overwrites by id)
index.upsert(vectors=[{
'id': 'doc-003',
'values': q_vec, # new embedding
'metadata': {'text': 'Updated content.'}
}])
# Delete all vectors in a namespace
# index.delete(delete_all=True, namespace='tenant-a')Preços e nível gratuito do Pinecone
O Pinecone oferece um nível serverless gratuito com 2 GB de armazenamento, suficiente para aproximadamente 300.000 vetores com 1536 dimensões. Acima disso, o preço serverless é calculado por unidade de leitura e unidade de escrita consumidas.
Para cargas de trabalho em produção, estime seu custo mensal calculando: (consultas por dia × 30 × custo por consulta) + (total de vetores × custo de armazenamento). O serverless costuma ser mais econômico que os planos baseados em pods para cargas de trabalho com tráfego variável.
Verificação rápida
Teste sua compreensão dos conceitos de Engenharia de IA desta lição.
Recapitulação da lição
Nesta lição, você aprendeu: os Indexes do Pinecone exigem dimensão e métrica compatíveis com seu modelo de embeddings, as operações de upsert usam um id exclusivo, portanto atualizar um documento basta fazer um novo upsert com o mesmo id e namespaces isolam coleções de vetores dentro de um único Index para casos de uso multi-inquilino. A seguir, vamos explorar o pgvector, que traz a busca vetorial diretamente para o PostgreSQL.
Perguntas Frequentes
A aula “Primeiros passos com Pinecone” é grátis?
Sim — o texto completo de “Primeiros passos com Pinecone” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.
O que vou aprender em “Primeiros passos com Pinecone”?
Crie um índice no Pinecone, insira vetores com metadados, realize consultas de similaridade com filtros e gerencie espaços de nomes para separar diferentes coleções de dados. Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Engineering Academy?
Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Primeiros passos com Pinecone”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Engineering Academy?
Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Por que você precisa de um banco de dados vetorial
- Primeiros passos com Pinecone
- pgvector: embeddings no PostgreSQL
- Escolhendo e avaliando armazenamentos vetoriais