Iniziare con Pinecone
Creerà un indice Pinecone, eseguirà l'upsert di vettori con metadati, effettuerà query di similarità con filtri e gestirà i namespace per separare raccolte di dati diverse.
Iniziare con Pinecone è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Che cos'è Pinecone?
Pinecone è un database vettoriale completamente gestito che si occupa automaticamente dell'infrastruttura, della scalabilità e dei backup. Vi si interagisce tramite un SDK Python, inviando vettori e metadati mediante chiamate API. Pinecone archivia i dati sui propri server e risponde alle query di similarità con bassa latenza, anche con miliardi di vettori.
Offre un piano gratuito sufficiente per l'apprendimento e per piccoli carichi di lavoro in produzione.
Installazione dell'SDK di Pinecone
Installi il client Pinecone e lo inizializzi con la Sua chiave API. Conservi la chiave API in una variabile d'ambiente: non inserisca mai segreti direttamente nei file sorgente. La classe Pinecone è il punto di accesso principale per tutte le operazioni.
# 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)Creazione di un indice Pinecone
Un indice Pinecone è la raccolta che memorizza i Suoi vettori. Quando crea un indice, deve specificare la dimension (che deve corrispondere al modello di embedding) e la metric per il calcolo della similarità. Per gli embedding OpenAI, utilizzi dimension=1536 e metric='cosine'.
La creazione dell'indice è idempotente: la specifica serverless crea l'indice su richiesta senza allocare capacità in anticipo.
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)Inserimento o aggiornamento di vettori con metadati
Pinecone utilizza operazioni di upsert (inserimento o aggiornamento). Ogni vettore richiede una stringa id univoca, i values (l'embedding come elenco di float) e metadata facoltativi (un dict di campi filtrabili). Se esegue un upsert con un id esistente, il vecchio vettore viene sostituito.
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')Esecuzione di query sull'indice Pinecone
Per eseguire una ricerca, trasformi la query in un embedding e chiami index.query() con il vettore della query e top_k, che indica quanti risultati restituire. Imposti include_metadata=True per ottenere i metadati memorizzati insieme agli id e ai punteggi delle corrispondenze.
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}')Filtraggio per metadati
Pinecone supporta il pre-filtraggio: restringe la ricerca ai vettori che corrispondono a una condizione sui metadati prima di eseguire ANN. Utilizzi il parametro filter con operatori nello stile di MongoDB: $eq, $in, $gt, $lt, $and, $or.
Quando crea l'indice, indicizzi sempre i campi dei metadati in base ai quali intende filtrare, per garantire buone prestazioni del filtraggio.
# 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]}')Namespace per l'isolamento dei dati
I namespace di Pinecone suddividono un singolo indice in segmenti isolati. Le query in un namespace non restituiscono mai risultati provenienti da un altro, rendendo i namespace ideali per i sistemi RAG multi-tenant in cui ogni cliente deve poter cercare solo nei propri documenti.
Sia l'upsert sia la query accettano una stringa namespace facoltativa. Il namespace predefinito è una stringa vuota.
# 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"])}')Upsert in batch per corpus di grandi dimensioni
Quando indicizza migliaia di documenti, suddivida i vettori in batch di massimo 100 vettori per chiamata di upsert (la dimensione di batch consigliata da Pinecone). I batch più grandi potrebbero superare i limiti a causa del vincolo di circa 4 MB sulla dimensione del payload per richiesta.
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)Controllo delle statistiche dell'indice
Utilizzi index.describe_index_stats() per controllare quanti vettori sono memorizzati in ciascun namespace e il numero totale di vettori. È utile per verificare che un upsert sia stato completato correttamente e per monitorare la crescita dell'indice nel 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')Eliminazione e aggiornamento dei vettori
Utilizzi index.delete(ids=[...]) per rimuovere vettori specifici in base all'id. Per aggiornare un vettore, ad esempio quando un documento viene modificato, esegua semplicemente un upsert con lo stesso id: Pinecone sovrascriverà la voce esistente.
Per eliminare tutti i vettori in un namespace, ad esempio per reindicizzare dopo un aggiornamento completo, utilizzi 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')Prezzi e piano gratuito di Pinecone
Pinecone offre un piano serverless gratuito con 2 GB di spazio di archiviazione, sufficienti per circa 300.000 vettori a 1536 dimensioni. Oltre tale soglia, il piano serverless applica un costo per ogni read unit e write unit consumata.
Per i carichi di lavoro in produzione, stimi il costo mensile calcolando: (query al giorno × 30 × costo per query) + (vettori totali × costo di archiviazione). Il serverless è spesso più conveniente dei piani basati su pod per i carichi di lavoro con traffico variabile.
Verifica rapida
Metta alla prova la Sua comprensione dei concetti di AI Engineering trattati in questa lezione.
Riepilogo della lezione
In questa lezione ha imparato: le dimensioni e la metrica degli indici Pinecone devono corrispondere al modello di embedding, le operazioni di upsert utilizzano un id univoco, quindi per aggiornare un documento è sufficiente eseguire nuovamente l'upsert con lo stesso id e i namespace isolano le raccolte di vettori all'interno di un singolo indice per i casi d'uso multi-tenant. Ora esploreremo pgvector, che porta la ricerca vettoriale direttamente in PostgreSQL.
Domande Frequenti
La lezione «Iniziare con Pinecone» è gratuita?
Sì — il testo completo di «Iniziare con Pinecone» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Iniziare con Pinecone»?
Creerà un indice Pinecone, eseguirà l'upsert di vettori con metadati, effettuerà query di similarità con filtri e gestirà i namespace per separare raccolte di dati diverse. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Iniziare con Pinecone»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Perché serve un database vettoriale
- Iniziare con Pinecone
- pgvector: embeddings in PostgreSQL
- Scegliere e valutare i vector store