Démarrage rapide Pinecone

Bienvenue ! Cette skill vous guide à travers votre première expérience Pinecone en utilisant les outils disponibles. Dans ce démarrage rapide, vous apprendrez comment effectuer une simple recherche sémantique sur des données d'exemple.

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="your-key"
• Ou créez un fichier .env à la racine du projet : PINECONE_API_KEY=your-key

Puis réessayez list-indexes pour confirmer.

Étape 0 : Choisissez votre parcours

Demandez à l'utilisateur quel parcours il souhaite :

• Base de données – Construire un index de recherche vectorielle. Idéal pour les développeurs qui souhaitent stocker et chercher des embeddings. Utilise le MCP Pinecone + un script Python d'upsert.
• Assistant – Construire un assistant Q&A pour documents. Idéal pour les utilisateurs qui souhaitent télécharger des fichiers et poser des questions avec des réponses citées. Aucun code requis.

Parcours A : Démarrage rapide Base de données

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

1. Vérifier que le MCP est configuré
2. Créer un index intégré avec le MCP
3. Faire un upsert des données d'exemple en utilisant le script fourni (9 phrases sur les thèmes productivité, santé et nature)
4. Exécuter une requête de recherche sémantique et explorer d'autres requêtes
5. Essayer facultativement le reranking
6. Proposer le script complet autonome

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

Le contrôle des prérequis a déjà appelé list-indexes. S'il a réussi, le MCP fonctionne — continuez à l'étape 2.

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

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

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

Utilisez l'outil MCP create-index-for-model pour créer un index serverless 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 dans vos enregistrements contient le texte à embedding

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

Étape 3 – Upsert des données d'exemple

Exécutez le script d'upsert fourni pour remplir 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 (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 de ceux des enregistrements, mais les bonnes réponses remontent quand même
• Chaque enregistrement a un _id, un champ chunk_text (le texte qui est embedding) et un champ category
• C'est la même structure que vous utiliseriez pour vos propres données — remplacez simplement les enregistrements

Étape 4 – 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: "getting things done efficiently"

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 remonte les phrases de productivité
• C'est la recherche sémantique : elle trouve le sens, pas seulement les mots correspondants
• Vous avez envoyé du texte brut — Pinecone a embedding la requête en utilisant le même modèle que l'index

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

• Option A : "feeling under the weather" — devrait faire remonter les enregistrements de santé
• Option B : "wildlife spotting outside" — devrait faire remonter les enregistrements de nature
• Option C : Non, continuons

Exécutez la requête qu'ils choisissent et affichez les résultats de la même façon. S'ils veulent essayer les deux, faites les deux. Après chaque résultat, pointez quel thème a remonté et pourquoi.

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

Étape 5 – Essayez le reranking (Facultatif)

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

Si oui, utilisez à nouveau search-records 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 passage sur les résultats pour améliorer l'ordre de pertinence.

Étape 6 – Conclusion

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

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 nécessaire
• Ils peuvent remplacer leur propre liste records pour construire quelque chose de réel

Parcours B : Démarrage rapide Assistant

Guidez l'utilisateur à travers le workflow Pinecone Assistant en utilisant les skills d'assistant existants :

Étape 1 – Vérifiez les documents

Avant toute chose, 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 compléter le démarrage rapide dès maintenant. Demandez les sujets qu'il préférerait (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 — faites savoir qu'il peut revenir une fois qu'il a des documents et reprendre à partir de l'étape 2.

Étape 2 – Créez 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 complètement géré — téléchargez des documents, posez des questions, obtenez des réponses citées.

Étape 3 – Téléchargez 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 nécessaire.

Étape 4 – Chattez 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 "What are the main topics in these 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 garder l'assistant à jour à mesure que les documents changent
• Utilisez la skill d'assistant pour récupérer les extraits de contexte brut pour des workflows personnalisés
• Chaque assistant est aussi un serveur MCP — voir https://docs.pinecone.io/guides/assistant/mcp-server

Dépannage

PINECONE_API_KEY non défini

Environnements terminal :

export PINECONE_API_KEY="your-key"

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

PINECONE_API_KEY=your-key

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

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 fera un upsert sur les enregistrements existants
• Ou supprimez et recréez : utilisez pc index delete -n quickstart-skills via la CLI

uv non installé Consultez le guide d'installation de uv.

Lectures supplémentaires

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