Démarrage rapide avec Pinecone

Bienvenue ! Cette compétence vous guide lors de votre première expérience avec Pinecone en utilisant les outils disponibles. Dans ce démarrage rapide, vous apprendrez comment effectuer une simple recherche sémantique sur des exemples de données.

Prérequis

Avant de commencer, vérifiez que la clé API fonctionne en appelant list-indexes via le MCP Pinecone. Si cela réussit, continuez. Si cela échoue, demandez à l'utilisateur de définir sa clé :

Terminal : export PINECONE_API_KEY="votre-clé"
Ou créez un fichier .env à la racine du projet : PINECONE_API_KEY=votre-clé

Réessayez ensuite list-indexes pour confirmer.

Étape 0 : Choisissez votre chemin

Demandez à l'utilisateur quel chemin il souhaite emprunter :

Database – Créer un index de recherche vectorielle. Idéal pour les développeurs qui souhaitent stocker et rechercher des embeddings. Utilise le MCP Pinecone + un script Python d'upsert.
Assistant – Créer un assistant de questions-réponses sur documents. Idéal pour les utilisateurs qui souhaitent télécharger des fichiers et poser des questions avec réponses citées. Aucun code requis.

Chemin A : Démarrage rapide avec la base de données

Pour chaque étape, expliquez à l'utilisateur ce qui va se passer. Voici un aperçu :

Vérifier que le MCP est configuré
Créer un index intégré avec le MCP
Effectuer un upsert de données d'exemple à l'aide du script fourni (9 phrases sur les thèmes de la productivité, de la santé et de la nature)
Exécuter une requête de recherche sémantique et explorer d'autres requêtes
Essayer optionnellement le reranking
Proposer le script complet autonome

Étape 1 – Vérifier que le MCP est disponible

La vérification des prérequis a déjà appelé list-indexes. Si cela a réussi, le MCP fonctionne — passez à l'étape 2.

S'il a échoué parce que les outils MCP n'étaient pas disponibles (pas une erreur d'authentification) :

Dites à l'utilisateur que le serveur MCP doit être configuré
Pointez-le vers : https://docs.pinecone.io/reference/tools/mcp

Étape 2 – Créer un index intégré

Utilisez l'outil MCP create-index-for-model pour créer un index sans serveur avec embeddings intégrés :

name: quickstart-skills
cloud: aws
region: us-east-1
embed:
  model: llama-text-embed-v2
  fieldMap:
    text: chunk_text

Expliquez à l'utilisateur ce qui se passe :

Un index intégré utilise un modèle d'embedding Pinecone intégré (llama-text-embed-v2)
Cela signifie que vous envoyez du texte brut et Pinecone gère l'embedding automatiquement
Le field_map indique à Pinecone quel champ de vos enregistrements contient le texte à embarquer

Attendez que l'index soit prêt avant de continuer. Attendre quelques secondes est suffisant.

Étape 3 – Effectuer un upsert de données d'exemple

Exécutez le script d'upsert fourni pour alimenter l'index avec des enregistrements d'exemple.

Si PINECONE_API_KEY est défini dans l'environnement :

uv run scripts/upsert.py --index quickstart-skills

Si vous utilisez un fichier .env :

uv run --env-file .env scripts/upsert.py --index quickstart-skills

Expliquez à l'utilisateur ce qui se passe :

Le script télécharge 9 enregistrements d'exemple sur trois thèmes : productivité (accomplir du travail), santé (se sentir mal) et nature (en plein air/faune)
L'ensemble de données est intentionnellement varié pour montrer la valeur de la recherche sémantique — les requêtes ci-dessous utilisent des mots complètement différents des enregistrements, mais les bons surfaces sont toujours visibles
Chaque enregistrement a un _id, un champ chunk_text (le texte qui est embarqué) et un champ category
C'est la même structure que celle que vous utiliseriez pour vos propres données — remplacez simplement les enregistrements

Étape 4 – Effectuer une requête avec le MCP

Utilisez l'outil MCP search-records pour exécuter la première recherche sémantique :

index: quickstart-skills
namespace: example-namespace
query:
  topK: 3
  inputs:
    text: "accomplir les choses efficacement"

Affichez les résultats dans un tableau propre : ID, score et chunk_text.

Expliquez à l'utilisateur ce qui se passe :

Remarquez que la requête ne partage aucun mot-clé avec les enregistrements — mais elle affiche les phrases de productivité
C'est la recherche sémantique : elle trouve du sens, pas seulement des mots correspondants
Vous avez envoyé du texte brut — Pinecone a embarqué la requête en utilisant le même modèle que l'index

Proposez d'explorer davantage : Demandez à l'utilisateur s'il souhaite essayer une autre requête pour voir l'effet plus clairement :

Option A : "se sentir mal" — devrait afficher les enregistrements de santé
Option B : "observer la faune en plein air" — devrait afficher les enregistrements de nature
Option C : Non merci, passez à la suite

Exécutez la requête qu'ils choisissent et affichez les résultats de la même manière. S'ils veulent essayer les deux, faites les deux. Après chaque résultat, indiquez quel thème s'affiche et pourquoi.

S'ils refusent ou ont terminé l'exploration, passez à l'étape 5 ou proposez de sauter directement au script complet.

Étape 5 – Essayer le reranking (Optionnel)

Demandez à l'utilisateur s'il souhaite essayer le reranking.

Si oui, utilisez search-records à nouveau avec le reranking activé :

rerank:
  model: bge-reranker-v2-m3
  rankFields: [chunk_text]
  topN: 3

Expliquez : Le reranking exécute un modèle de deuxième passe sur les résultats pour améliorer l'ordre de pertinence.

Étape 6 – Conclure

Félicitez l'utilisateur d'avoir complété le démarrage rapide. Demandez s'il aimerait un script Python autonome qui fait tout en un — créer l'index, upsert, requête et reranking.

Si oui, copiez-le dans son répertoire de travail :

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

Dites à l'utilisateur :

Le script se trouve à ./pinecone_quickstart.py
Exécutez-le avec : uv run pinecone_quickstart.py
Il utilise les dépendances inline uv — aucune installation séparée requise
Il peut remplacer sa propre liste records pour créer quelque chose de réel

Chemin B : Démarrage rapide avec l'Assistant

Guidez l'utilisateur dans le flux de travail de l'Assistant Pinecone en utilisant les compétences d'assistant existantes :

Étape 1 – Vérifier les documents

Avant tout, demandez à l'utilisateur s'il a des fichiers à télécharger. Pinecone Assistant accepte les fichiers .pdf, .md, .txt et .docx — un seul fichier ou un dossier de fichiers fonctionnent tous les deux.

S'il a des fichiers : demandez le chemin et passez à l'étape 2.

S'il n'a pas de fichiers : proposez deux options :

Générer des documents d'exemple — créer quelques fichiers markdown courts dans ./sample-docs/ pour qu'il puisse terminer le démarrage rapide maintenant. Demandez quels sujets il souhaite (ou par défaut : une FAQ produit, un court guide pratique et un bref aperçu de l'entreprise). Écrivez 3 fichiers, chacun de 150 à 250 mots.
Revenir plus tard — informez-le qu'il peut revenir une fois qu'il a des documents et reprendre à partir de l'étape 2.

Étape 2 – Créer un assistant

Invoquez pinecone-assistant ou exécutez (ajoutez --env-file .env si vous utilisez un fichier .env) :

uv run ../pinecone-assistant/scripts/create.py --name my-assistant

Expliquez : L'assistant est un service RAG entièrement géré — téléchargez des documents, posez des questions, obtenez des réponses citées.

Étape 3 – Télécharger des documents

Invoquez pinecone-assistant ou exécutez (ajoutez --env-file .env si vous utilisez un fichier .env) :

uv run ../pinecone-assistant/scripts/upload.py --assistant my-assistant --source ./your-docs

Expliquez : Pinecone gère le chunking, l'embedding et l'indexation automatiquement — aucune configuration requise.

Étape 4 – Discuter avec l'Assistant

Invoquez pinecone-assistant ou exécutez (ajoutez --env-file .env si vous utilisez un fichier .env) :

uv run ../pinecone-assistant/scripts/chat.py --assistant my-assistant --message "Quels sont les thèmes principaux de ces documents ?"

Expliquez : Les réponses incluent des citations avec le fichier source et le numéro de page.

Étapes suivantes pour l'Assistant

Invoquez pinecone-assistant pour maintenir l'assistant à jour à mesure que les documents changent
Utilisez la compétence d'assistant pour récupérer des extraits de contexte bruts pour des flux de travail personnalisés
Chaque assistant est également un serveur MCP — voir https://docs.pinecone.io/guides/assistant/mcp-server

Dépannage

PINECONE_API_KEY non défini

Environnements de terminal :

export PINECONE_API_KEY="votre-clé"

IDEs qui n'héritent pas des variables de shell : créez un fichier .env à la racine du projet :

PINECONE_API_KEY=votre-clé

Utilisez ensuite uv run --env-file .env lors de l'exécution de scripts. Redémarrez votre session IDE/agent après la définition.

Outils MCP non disponibles

Vérifiez que le serveur MCP Pinecone est configuré dans les paramètres MCP de votre IDE
Vérifiez que PINECONE_API_KEY est défini avant le démarrage du serveur MCP

L'index existe déjà

Le script d'upsert est sûr à réexécuter — il effectuera un upsert sur les enregistrements existants
Ou supprimez et recréez : utilisez pc index delete -n quickstart-skills via l'interface de ligne de commande

uv n'est pas installé Consultez le guide d'installation de uv.

Lecture supplémentaire

Documentation de démarrage rapide : https://docs.pinecone.io/guides/get-started/quickstart
Index intégrés : https://docs.pinecone.io/guides/index-data/create-an-index
SDK Python : https://docs.pinecone.io/guides/get-started/python-sdk
Serveur MCP : https://docs.pinecone.io/reference/tools/mcp