Pinecone pour agents IA : guide complet

Introduction

Un agent IA qui raisonne, agit et s'améliore au fil du temps a besoin d'une mémoire qui dépasse la fenêtre de contexte du LLM. Pinecone est une base de données vectorielle cloud qui stocke des embeddings et permet de les retrouver par similarité sémantique — exactement ce qu'il faut pour donner de la mémoire long terme à un agent. Ce guide couvre l'installation, la configuration, l'intégration dans un agent Python et les bonnes pratiques pour gérer les coûts. Pour une vue d'ensemble des outils pour agents IA, consultez notre guide dédié.

Résumé rapide

Critère	Pinecone
Type	Base vectorielle cloud managée (serverless)
Tier gratuit	1 index, 100k vecteurs, 2 Go de stockage
Latence	< 50 ms pour 1M de vecteurs
SDK	Python, Node.js, Go, REST API
Cas d'usage	Mémoire agent, RAG, recherche sémantique, recommandations

Pinecone en bref

Pinecone est une base vectorielle serverless — vous n'avez pas de serveur à gérer, pas d'infrastructure à maintenir. Vous envoyez des vecteurs via l'API, Pinecone les indexe et les rend disponibles pour la recherche par similarité en millisecondes.

Architecture

Pinecone organise les données en index (équivalent d'une base de données). Chaque index contient des vecteurs de dimension fixe (par exemple 1536 pour les embeddings OpenAI text-embedding-3-small). Les namespaces permettent de partitionner un index — utile pour séparer les données par utilisateur ou par projet sans multiplier les index.

Ce qui distingue Pinecone

Zero ops : pas de Docker, pas de cluster, pas de réplication à gérer
Scalabilité transparente : de 1k à 1 milliard de vecteurs sans migration
Metadata filtering : filtrer les résultats par attributs (date, catégorie, source) en plus de la similarité
Serverless : facturation à l'usage, pas de serveur inactif qui coûte

Limites

Cloud only : pas de version self-hosted, les données transitent par les serveurs Pinecone (US ou EU)
Coût à volume élevé : au-delà de 100k vecteurs, le tier payant démarre à ~70 $/mois
Vendor lock-in : l'API est propriétaire, migrer vers une alternative demande de réécrire le code d'intégration

Installation et configuration

Créer un compte

Créez un compte gratuit sur pinecone.io. Le tier Starter offre 1 index et 100k vecteurs — suffisant pour le développement et les petits projets.

Récupérez votre clé API dans le dashboard > API Keys.

Installer le SDK Python

pip install pinecone-client openai

Le SDK Pinecone v3+ a des breaking changes par rapport à v2. Ce guide utilise la v3. Si vous migrez depuis v2, les principales différences sont :

pinecone.init() remplacé par Pinecone(api_key=...)
pinecone.Index() remplacé par pc.Index()
Création d'index via pc.create_index() avec ServerlessSpec

Configurer les variables d'environnement

# .env
PINECONE_API_KEY=pcsk_votre_cle_ici
OPENAI_API_KEY=sk-proj-votre_cle_ici

import os
from pinecone import Pinecone
from dotenv import load_dotenv

load_dotenv()
pc = Pinecone(api_key=os.getenv("PINECONE_API_KEY"))

Créer et gérer un index

Créer un index serverless

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key=os.getenv("PINECONE_API_KEY"))

# Créer un index pour des embeddings OpenAI (dimension 1536)
pc.create_index(
    name="agent-memory",
    dimension=1536,
    metric="cosine",  # cosine pour la similarité sémantique
    spec=ServerlessSpec(cloud="aws", region="us-east-1")
)

index = pc.Index("agent-memory")

Choix de la métrique :

cosine : similarité de direction, indépendante de la magnitude — le choix par défaut pour les embeddings texte
euclidean : distance absolue, utile si la magnitude des vecteurs a du sens
dotproduct : produit scalaire, plus rapide mais nécessite des vecteurs normalisés

Indexer des documents (upsert)

from openai import OpenAI

client = OpenAI()

def embed(text: str) -> list[float]:
    response = client.embeddings.create(
        input=text,
        model="text-embedding-3-small"
    )
    return response.data[0].embedding

# Indexer des documents avec metadata
documents = [
    {"id": "doc-1", "text": "OpenClaw utilise des skills modulaires pour orchestrer des agents.", "source": "guide"},
    {"id": "doc-2", "text": "Pinecone est une base vectorielle cloud pour la recherche sémantique.", "source": "tutorial"},
    {"id": "doc-3", "text": "LangGraph modélise les agents comme des graphes d'états cycliques.", "source": "guide"},
]

vectors = [
    {
        "id": doc["id"],
        "values": embed(doc["text"]),
        "metadata": {"text": doc["text"], "source": doc["source"]}
    }
    for doc in documents
]

index.upsert(vectors=vectors, namespace="knowledge-base")

Namespace : utilisez un namespace par domaine (par utilisateur, par projet, par session). Cela permet de cloisonner les données sans créer plusieurs index.

Recherche sémantique dans l'agent

def search_memory(query: str, top_k: int = 3, source_filter: str = None) -> list[dict]:
    query_vector = embed(query)

    filter_dict = {}
    if source_filter:
        filter_dict = {"source": {"$eq": source_filter}}

    results = index.query(
        vector=query_vector,
        top_k=top_k,
        include_metadata=True,
        namespace="knowledge-base",
        filter=filter_dict if filter_dict else None
    )

    return [
        {"text": match.metadata["text"], "score": match.score}
        for match in results.matches
    ]

# Exemple
results = search_memory("comment orchestrer des agents IA")
for r in results:
    print(f"Score: {r['score']:.3f} — {r['text'][:80]}...")
# Score: 0.891 — OpenClaw utilise des skills modulaires pour orchestrer des agents.
# Score: 0.847 — LangGraph modélise les agents comme des graphes d'états cycliques.

Le score (0 à 1 en cosine) indique la proximité sémantique. Au-dessus de 0.8, le résultat est très pertinent. En dessous de 0.6, il est probablement hors sujet.

Intégrer Pinecone comme mémoire d'agent

Voici le pattern complet : l'agent stocke chaque fait appris et récupère les souvenirs pertinents à chaque tour de boucle.

from datetime import datetime
from uuid import uuid4

class AgentMemory:
    def __init__(self, index, namespace: str = "default"):
        self.index = index
        self.namespace = namespace

    def store(self, text: str, metadata: dict = None):
        """Mémoriser un fait."""
        vector = embed(text)
        meta = {"text": text, "timestamp": datetime.now().isoformat()}
        if metadata:
            meta.update(metadata)
        self.index.upsert(
            vectors=[{"id": str(uuid4()), "values": vector, "metadata": meta}],
            namespace=self.namespace
        )

    def recall(self, query: str, top_k: int = 5) -> list[str]:
        """Récupérer les souvenirs pertinents."""
        results = self.index.query(
            vector=embed(query),
            top_k=top_k,
            include_metadata=True,
            namespace=self.namespace
        )
        return [m.metadata["text"] for m in results.matches if m.score > 0.7]

# Utilisation dans la boucle agent
memory = AgentMemory(index, namespace="user-42")

# L'agent mémorise un fait appris
memory.store("L'utilisateur préfère les résumés en 3 points maximum.", {"type": "preference"})

# Au tour suivant, l'agent récupère les souvenirs pertinents
context = memory.recall("comment formater la réponse pour cet utilisateur")
# → ["L'utilisateur préfère les résumés en 3 points maximum."]

Ce pattern s'intègre dans n'importe quel framework. Dans OpenClaw, la mémoire est configurable dans le YAML. Dans LangGraph, elle s'ajoute comme état partagé. Pour les concepts de mémoire agent, consultez notre guide dédié.

Bonnes pratiques

Dimensionnez votre index dès le départ. La dimension des vecteurs doit correspondre au modèle d'embedding choisi. text-embedding-3-small (OpenAI) produit des vecteurs de 1536 dimensions. Changer de modèle d'embedding après indexation nécessite de réindexer tous les vecteurs.

Utilisez les metadata intelligemment. Stockez toujours le texte original dans les metadata (clé text). Ajoutez un timestamp pour pouvoir filtrer par fraîcheur et un type pour classer les souvenirs (fait, préférence, conversation).

Estimez les coûts avant de scaler. Tier gratuit : 100k vecteurs. Au-delà, Pinecone facture ~0,33 $/mois pour 100k vecteurs supplémentaires en serverless. Pour un agent avec 1M de souvenirs, comptez ~30 $/mois en stockage.

Nettoyez les vecteurs obsolètes. Pinecone n'a pas de TTL natif. Implémentez un cron qui supprime les vecteurs dont le timestamp dépasse votre politique de rétention.

Quand Pinecone est le bon choix : si vous voulez zéro infrastructure, que vos données peuvent aller dans le cloud, et que le volume dépasse ce que Chroma gère confortablement (> 500k vecteurs). Pour le prototypage local, Chroma est plus simple. Pour le self-hosted en production, Qdrant est plus performant.

Questions fréquentes

Pinecone est-il gratuit ?

Le tier Starter est gratuit : 1 index, 100k vecteurs, 2 Go de stockage. C'est suffisant pour le développement et les petits projets. Au-delà, le plan Standard démarre autour de 70 $/mois selon l'usage.

Peut-on utiliser Pinecone avec des modèles open source ?

Oui. Pinecone stocke des vecteurs bruts — peu importe le modèle qui les génère. Vous pouvez utiliser des embeddings de Sentence-Transformers, Cohere, Mistral ou tout autre modèle. La seule contrainte est que la dimension de l'index corresponde à celle du modèle.

Quelle est la latence de recherche ?

Moins de 50 ms pour 1M de vecteurs en serverless. La latence augmente peu avec le volume grâce à l'indexation ANN (Approximate Nearest Neighbor). Pour des volumes > 10M de vecteurs, les performances restent stables.

Pinecone est-il compatible RGPD ?

Pinecone propose une région EU (aws eu-west-1) pour le stockage des données en Europe. Vérifiez que votre plan inclut cette option. Les données en transit sont chiffrées (TLS) et au repos (AES-256).

Quelle alternative si je veux du self-hosted ?

Qdrant (Rust, haute performance) ou Chroma (Python, simple) en self-hosted. Les deux sont open source et gratuits. Qdrant est recommandé pour la production ; Chroma pour le prototypage.