pinecone-quickstart

Pinecone 快速入门

欢迎！本技能将引导你使用可用工具，开启 Pinecone 体验。在本快速入门中， 你将学习如何对一些示例数据进行简单的语义搜索。

<<clarify_style>>

前提条件

开始任一路径前，请通过 Pinecone MCP 调用 list-indexes，确认 API 密钥有效。如果调用成功，请继续。如果失败，请让用户设置密钥：

<<api_key_setup>>

然后重新调用 list-indexes 进行确认。

步骤 0：选择路径

询问用户想要选择哪条路径：

• 数据库 – 构建向量搜索索引。适合希望存储和搜索嵌入的开发者。使用 Pinecone MCP 和 Python upsert 脚本。
• 助手 – 构建文档问答助手。适合希望上传文件并提出问题、获取带引用答案的用户。无需编写代码。

---

路径 A：数据库快速入门

每一步都向用户说明将要进行的操作。步骤概览如下：

1. 检查是否已配置 MCP
2. 使用 MCP 创建集成索引
3. 使用附带的脚本 upsert 示例数据（涵盖效率、健康和自然主题的 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 – Upsert 示例数据

运行附带的 upsert 脚本，向索引填充示例记录。

如果环境中设置了 PINECONE_API_KEY：

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

如果使用 .env 文件：

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

向用户说明当前操作：

• 脚本会上传 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："feeling under the weather" — 应能找到健康主题的记录
• 选项 B："wildlife spotting outside" — 应能找到自然主题的记录
• 选项 C：不用了，继续

运行用户选择的查询，并以相同方式展示结果。如果用户想两种都试，就都运行。每次展示结果后，指出出现的是哪个主题，以及原因。

如果用户拒绝或已完成探索，请继续步骤 5，或询问是否跳到完整脚本。

步骤 5 – 尝试重排序（可选）

询问用户是否想尝试重排序。

如果想，启用重排序后再次使用 search-records：

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

说明：重排序会使用第二轮模型处理结果，以改善相关性排序。

步骤 6 – 收尾

祝贺用户完成快速入门。询问他们是否想要一个独立的 Python 脚本，一次性完成所有操作——创建索引、写入记录、查询和重排序。

如果想，将脚本复制到他们的工作目录：

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

告知用户：

• 脚本位于 ./pinecone_quickstart.py
• 使用以下命令运行：uv run pinecone_quickstart.py
• 脚本使用 uv 内联依赖——无需单独安装
• 他们可以替换为自己的 records 列表，构建实际应用

---

路径 B：Assistant 快速入门

使用现有的 pinecone-assistant 技能，引导用户完成 Pinecone Assistant 工作流：

步骤 1 – 检查文档

首先询问用户是否有要上传的文件。Pinecone Assistant 接受 .pdf、.md、.txt 和 .docx 文件——单个文件或文件夹中的多个文件均可。

**如果他们有文件：**询问路径，然后继续步骤 2。

**如果他们没有文件：**提供两个选项：

• 生成示例文档——在 ./sample-docs/ 中创建几个简短的 Markdown 文件，让他们立即完成快速入门。询问他们想要哪些主题（或者默认使用：产品常见问题、简短的操作指南和简要的公司介绍）。创建 3 个文件，每个文件 150–250 词。
• 稍后再来——告知他们准备好文档后，可以回来从步骤 2 继续。

步骤 2 – 创建 Assistant

调用 pinecone-assistant，或运行（如果使用 .env 文件，则添加 --env-file .env）：

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

说明：该 Assistant 是一项完全托管的 RAG 服务——上传文档、提问并获取带引用的答案。

步骤 3 – 上传文档

调用 pinecone-assistant，或运行（如果使用 .env 文件，则添加 --env-file .env）：

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

说明：Pinecone 会自动处理分块、嵌入和索引，无需配置。

步骤 4 – 与 Assistant 对话

调用 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?"

说明：回复会附带引用，标明源文件和页码。

Assistant 后续步骤

• 文档发生变化时，调用 pinecone-assistant 以保持 Assistant 内容更新
• 使用 pinecone-assistant 技能检索原始上下文片段，用于自定义工作流
• 每个 Assistant 也是一个 MCP 服务——参见 https://docs.pinecone.io/guides/assistant/mcp-server

---

故障排除

未设置 PINECONE_API_KEY

<<api_key_setup>>

设置密钥后，重启 IDE 或 Agent 会话。

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