Pinecone Patterns

Patterns canoniques pour utiliser Pinecone Serverless (recommandé en 2026) en s'appuyant sur le MCP server officiel Pinecone déclaré dans plugins/atum-ai-ml/.mcp.json.

MCP server pinecone disponible : 7 outils — list-indexes, describe-index, describe-index-stats, search-records, create-index-for-model, upsert-records, rerank-documents. Plus les commands /pinecone:query et /pinecone:assistant-chat.

Prérequis utilisateur : Node.js installé + PINECONE_API_KEY env var configurée + compte Pinecone actif.

1. Setup Pinecone

# Install
pip install pinecone-client

from pinecone import Pinecone, ServerlessSpec
import os

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# Create index — Serverless (recommended)
pc.create_index(
    name="my-index",
    dimension=1536,  # OpenAI text-embedding-3-small
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

# Connect to index
index = pc.Index("my-index")

2. Upsert vectors

# Single upsert avec metadata
index.upsert(vectors=[
    {
        "id": "doc1",
        "values": embedding_1536d,
        "metadata": {
            "source": "guide.pdf",
            "page": 12,
            "category": "tutorial",
            "language": "fr",
        },
    },
])

# Batch upsert (recommended pour > 10 records)
records = [
    {"id": f"doc{i}", "values": embeddings[i], "metadata": metadata[i]}
    for i in range(len(embeddings))
]

# Pinecone recommends batches de 100 vectors max
for i in range(0, len(records), 100):
    index.upsert(vectors=records[i:i+100])

3. Query (vector search)

# Search top-k
query_embedding = embed("Comment configurer Postgres ?")

results = index.query(
    vector=query_embedding,
    top_k=10,
    include_metadata=True,
    filter={
        "category": {"$eq": "tutorial"},
        "language": {"$eq": "fr"},
    },
)

for match in results.matches:
    print(f"{match.score:.3f} - {match.metadata['source']}")

4. Multi-tenancy avec namespaces

# Au lieu d'un filter metadata "tenant_id", utiliser des namespaces
# = isolation forte + perf meilleure

# Upsert dans le namespace du tenant
index.upsert(vectors=records, namespace="tenant-acme-corp")

# Search dans le namespace
results = index.query(
    vector=query_embedding,
    top_k=10,
    namespace="tenant-acme-corp",
)

# Lister les namespaces existants
stats = index.describe_index_stats()
print(stats.namespaces)

Pourquoi namespaces vs metadata filters :

• Isolation forte (impossible de fuiter cross-tenant)
• Recherche plus rapide (chaque namespace est un sub-index)
• Stats par namespace
• Scaling horizontal naturel

5. Hybrid search (sparse + dense)

# Crée un index avec sparse + dense
pc.create_index(
    name="hybrid-index",
    dimension=1536,
    metric="dotproduct",  # OBLIGATOIRE pour sparse-dense
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

# Upsert avec sparse values (BM25 weights)
index.upsert(vectors=[
    {
        "id": "doc1",
        "values": dense_embedding_1536,
        "sparse_values": {
            "indices": [10, 45, 234, 1024],  # token IDs
            "values": [0.5, 0.8, 0.3, 0.9],   # BM25 weights
        },
        "metadata": metadata,
    },
])

# Query hybrid
results = index.query(
    vector=dense_query,
    sparse_vector={"indices": query_token_ids, "values": query_token_weights},
    top_k=20,
    include_metadata=True,
)

Hybrid search améliore typiquement +15-30% recall sur des queries qui contiennent des termes exacts (noms propres, codes, IDs).

6. Pinecone integrated inference

Pinecone héberge maintenant des embedding models directement → upsert sans embedding step côté client.

# Create index avec model intégré
pc.create_index_for_model(
    name="integrated-index",
    cloud="aws",
    region="us-east-1",
    embed={
        "model": "multilingual-e5-large",
        "field_map": {"text": "chunk_text"},  # quel field contient le texte
    },
)

# Upsert texte brut — Pinecone embed automatiquement
index = pc.Index("integrated-index")
index.upsert_records(
    namespace="default",
    records=[
        {"_id": "doc1", "chunk_text": "Comment configurer Postgres", "category": "db"},
        {"_id": "doc2", "chunk_text": "Migration d'une DB MySQL", "category": "db"},
    ],
)

# Search texte brut — Pinecone embed la query automatiquement
results = index.search_records(
    namespace="default",
    query={"inputs": {"text": "Configurer une base de données"}, "top_k": 5},
)

Avantage : pas besoin de gérer un embedding service côté client, latence réduite, coût simplifié.

7. Reranking

# Rerank des résultats top-50 avec le model Pinecone Rerank
results = index.query(vector=query_embedding, top_k=50, include_metadata=True)

reranked = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="Comment configurer Postgres ?",
    documents=[{"id": m.id, "text": m.metadata["text"]} for m in results.matches],
    top_n=5,
    return_documents=True,
)

for r in reranked.data:
    print(f"{r.score:.3f} - {r.document.text[:100]}")

8. Pinecone Assistants (managed RAG)

Pinecone Assistants = pipelines RAG full-managed (chunking, embedding, retrieval, generation, citations) sans écrire de code.

from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# Create assistant
assistant = pc.assistant.create_assistant(
    name="docs-bot",
    instructions="Tu es un expert technique. Réponds en français avec des citations.",
    region="us",
)

# Upload documents (PDF, DOCX, TXT, MD)
assistant.upload_file("guide.pdf")

# Chat with citations
response = assistant.chat(messages=[{"role": "user", "content": "Comment configurer Postgres ?"}])
print(response.message.content)
print(response.citations)  # liste des sources avec pages

Use case : POC RAG en 30 minutes sans écrire 1 ligne de pipeline.

9. Monitoring + cost optimization

• Pinecone Console : monitoring queries/sec, errors, latency
• Read units (RU) : facturé par read pour Serverless
• Write units (WU) : facturé par write
• Storage : facturé au GB/mois

Optimisations :

• Réduire top_k au minimum nécessaire (souvent 5-10 suffisent)
• Cache les embeddings de queries fréquentes côté app
• Utiliser des namespaces pour multi-tenant (vs un mega-index)
• Supprimer les vectors anciens via TTL metadata + cron job
• Quantization si supporté (réduit storage)

10. Anti-patterns

1. Top_k=100 par défaut — coûteux et inutile
2. Pas de namespaces pour multi-tenant — risque de fuite
3. Metric cosine au lieu de dotproduct pour hybrid — incompatible
4. Upsert 1 vector at a time — préférer batch de 100
5. Pas de retry/backoff sur les errors transient
6. Pas de monitoring RU/WU — facture surprise
7. Embedding model changé sans réindexation — distances incohérentes
8. Pas de cache embeddings query — coût OpenAI x100
9. Includes_values=True par défaut — bandwidth gaspillé
10. Pas de filter metadata — search sur tout le namespace = lent

Checklist

• PINECONE_API_KEY dans env
• Index Serverless créé avec dimension correcte
• Multi-tenant via namespaces
• Hybrid search si queries contiennent des termes exacts
• Reranker activé (Cohere / Pinecone Rerank / BGE)
• Metadata filters utilisés
• Batch upsert (100 par batch)
• Monitoring RU/WU dans Console
• Backup strategy (export régulier)
• Tests RAGAS pour la qualité

Quand déléguer

• Architecture RAG haut niveau → agent rag-architect (ce plugin)
• Weaviate → skill weaviate-patterns (ce plugin)
• Qdrant → skill qdrant-patterns (ce plugin)
• pgvector → skill supabase-patterns (atum-stack-backend)
• Embeddings HuggingFace → skills hugging-face-* (ce plugin)

Ressources

• https://docs.pinecone.io/
• https://github.com/pinecone-io/pinecone-claude-code-plugin
• https://docs.pinecone.io/guides/operations/mcp-server