pinecone-quickstart

Pinecone クイックスタート

ようこそ！ このスキルでは、利用可能なツールを使って、Pinecone を初めて体験する手順を説明します。このクイックスタートでは、 サンプルデータを使った簡単なセマンティック検索の方法を学びます。

<<clarify_style>>

前提条件

どちらの手順を始める前にも、Pinecone MCP 経由で list-indexes を呼び出して、API キーが機能することを確認してください。成功した場合は先に進みます。失敗した場合は、キーを設定するようユーザーに依頼してください。

<<api_key_setup>>

その後、list-indexes を再試行して確認します。

ステップ 0：手順を選択する

どちらの手順にするか、ユーザーに尋ねてください。

• データベース – ベクトル検索インデックスを構築します。埋め込みを保存して検索したい開発者に最適です。Pinecone MCP と Python のアップサートスクリプトを使用します。
• アシスタント – ドキュメントの Q&A アシスタントを構築します。ファイルをアップロードし、引用付きの回答を得たいユーザーに最適です。コードは不要です。

---

手順 A：データベースのクイックスタート

各ステップで、何が行われるかをユーザーに説明してください。概要は次のとおりです。

1. MCP が設定されているか確認する
2. MCP で統合インデックスを作成する
3. 同梱のスクリプトを使ってサンプルデータをアップサートする（生産性、健康、自然をテーマにした 9 件の文）
4. セマンティック検索クエリを実行し、さらにクエリを試す
5. 必要に応じてリランキングを試す
6. 単独で実行できる完全なスクリプトを提示する

ステップ 1 – MCP が利用可能か確認する

前提条件の確認ですでに list-indexes を呼び出しています。成功した場合、MCP は動作しています。ステップ 2 に進んでください。

MCP ツールが利用できないために失敗した場合（認証エラーではない場合）：

• MCP サーバーの設定が必要であることをユーザーに伝える
• 次のページを案内する：https://docs.pinecone.io/reference/tools/mcp

ステップ 2 – 統合インデックスを作成する

MCP の create-index-for-model ツールを使って、統合埋め込み機能を備えたサーバーレスインデックスを作成します。

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

ユーザーに次の内容を説明してください。

• 統合インデックスは、組み込みの Pinecone 埋め込みモデル（llama-text-embed-v2）を使用します。
• つまり、プレーンテキストを送信するだけで、埋め込みは Pinecone が自動的に処理します。
• field_map は、埋め込み対象のテキストがレコード内のどのフィールドに含まれているかを Pinecone に伝えます。

インデックスの準備が整うまで待ってから、次に進んでください。数秒待てば十分です。

ステップ 3 – サンプルデータをアップサートする

同梱のアップサートスクリプトを実行して、サンプルレコードをインデックスに登録します。

環境変数 PINECONE_API_KEY が設定されている場合：

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

.env ファイルを使用する場合：

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

ユーザーに次の内容を説明してください。

• スクリプトは 3 つのテーマ、生産性（仕事を片付ける）、健康（体調不良）、自然（屋外／野生動物）にまたがる 9 件のサンプルレコードをアップロードします。
• セマンティック検索の価値が分かるよう、データセットには意図的に多様性を持たせています。以下のクエリでは、レコードとはまったく異なる単語を使いますが、それでも適切なレコードが見つかります。
• 各レコードには、_id、埋め込み対象のテキストを格納する chunk_text フィールド、category フィールドがあります。
• これは独自データにも使える構造です。レコードを置き換えるだけで利用できます。

ステップ 4 – MCP でクエリを実行する

MCP の search-records ツールを使って、最初のセマンティック検索を実行します。

index: quickstart-skills
namespace: example-namespace
query:
  topK: 3
  inputs:
    text: "getting things done efficiently"

結果を ID、スコア、chunk_text の見やすい表で表示します。

ユーザーに次の内容を説明してください。

• クエリにはレコードと共通するキーワードがありませんが、生産性に関する文が見つかっていることに注目してください。
• これがセマンティック検索です。単語の一致だけでなく、意味を見つけます。
• プレーンテキストを送信しました。Pinecone はインデックスと同じモデルを使ってクエリを埋め込みました。

さらに試すことを提案する： 効果をよりはっきり確認するために、別のクエリも試したいかユーザーに尋ねてください。

• オプション A：「体調がすぐれない」 — 健康に関するレコードが見つかるはずです
• オプション B：「屋外で野生動物を観察する」 — 自然に関するレコードが見つかるはずです
• オプション C：いいえ、次に進む

ユーザーが選んだクエリを実行し、同じ方法で結果を表示します。両方試したい場合は、どちらも実行してください。各結果の後に、どのテーマが見つかったか、またその理由を説明してください。

ユーザーが試すのを断った場合、または確認を終えた場合は、ステップ 5 に進むか、完全なスクリプトに進むかを提案してください。

ステップ 5 – リランキングを試す（任意）

リランキングを試してみたいかユーザーに尋ねます。

希望する場合は、リランキングを有効にして search-records をもう一度使用します。

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

説明：リランキングでは、結果に対して2回目のパスでモデルを実行し、関連度の高い順に並べ替えます。

ステップ 6 – 終了する

クイックスタートを完了したことをユーザーに伝えます。インデックスの作成、アップサート、クエリ、リランキングをすべて一度に行う、単独で実行できる Python スクリプトが必要か尋ねます。

希望する場合は、ユーザーの作業ディレクトリにコピーします。

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

ユーザーに次のことを伝えます。

• スクリプトは ./pinecone_quickstart.py にあります
• uv run pinecone_quickstart.py で実行できます
• インライン依存関係に uv を使用しているため、個別のインストールは不要です
• 独自の records リストに差し替えて、実用的なものを作成できます

---

パス B：アシスタントのクイックスタート

既存の pinecone-assistant スキルを使って、Pinecone Assistant のワークフローをユーザーに案内します。

ステップ 1 – ドキュメントの有無を確認する

最初に、アップロードするファイルがあるかユーザーに尋ねます。Pinecone Assistant は .pdf、.md、.txt、.docx ファイルを受け付けます。単一ファイルでも、複数のファイルが入ったフォルダーでも使用できます。

ファイルがある場合： パスを尋ねて、ステップ 2 に進みます。

ファイルがない場合： 次の2つの選択肢を提示します。

• サンプルドキュメントを生成する — すぐにクイックスタートを完了できるよう、./sample-docs/ に短い Markdown ファイルをいくつか作成します。希望するトピックを尋ねます（指定がなければ、製品の FAQ、短いハウツーガイド、会社概要の簡単な紹介を作成します）。各150～250語のファイルを3つ作成します。
• 後で再開する — ドキュメントが用意できたら戻って、ステップ 2 から続けられることを伝えます。

ステップ 2 – アシスタントを作成する

pinecone-assistant を呼び出すか、次を実行します（.env ファイルを使用している場合は --env-file .env を追加します）。

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

説明：アシスタントはフルマネージドの RAG サービスです。ドキュメントをアップロードして質問すると、引用付きの回答が得られます。

ステップ 3 – ドキュメントをアップロードする

pinecone-assistant を呼び出すか、次を実行します（.env ファイルを使用している場合は --env-file .env を追加します）。

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

説明：チャンク分割、埋め込み、インデックス作成は Pinecone が自動で処理するため、設定は不要です。

ステップ 4 – アシスタントとチャットする

pinecone-assistant を呼び出すか、次を実行します（.env ファイルを使用している場合は --env-file .env を追加します）。

uv run ../pinecone-assistant/scripts/chat.py --assistant my-assistant --message "What are the main topics in these documents?"

説明：回答には、ソースファイルとページ番号が記載された引用が含まれます。

アシスタントの次のステップ

• ドキュメントの変更に合わせてアシスタントを最新の状態に保つには、pinecone-assistant を呼び出します
• カスタムワークフローで生のコンテキストスニペットを取得するには、pinecone-assistant スキルを使用します
• すべてのアシスタントは MCP サーバーでもあります。https://docs.pinecone.io/guides/assistant/mcp-server を参照してください

---

トラブルシューティング

PINECONE_API_KEY が設定されていない

<<api_key_setup>>

キーを設定した後、IDE またはエージェントのセッションを再起動してください。

MCP ツールを利用できない

• IDE の MCP 設定で Pinecone MCP サーバーが構成されていることを確認します
• MCP サーバーの起動前に PINECONE_API_KEY が設定されていることを確認します

インデックスがすでに存在する

• アップサートスクリプトは安全に再実行できます。既存のレコードに対してアップサートします
• または、CLI から pc index delete -n quickstart-skills を使用して削除し、再作成します

uv がインストールされていない uv のインストールガイドを参照してください。

さらに読む

• クイックスタートのドキュメント：https://docs.pinecone.io/guides/get-started/quickstart
• 統合インデックス：https://docs.pinecone.io/guides/index-data/create-an-index
• Python SDK：https://docs.pinecone.io/guides/get-started/python-sdk
• MCP サーバー：https://docs.pinecone.io/reference/tools/mcp