pinecone-quickstart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pinecone Quickstart

Pinecone 快速入门

Welcome! This skill walks you through your first Pinecone experience using the tools available to you. In this quickstart, you will learn how to do a simple form of semantic search over some example data.

<<clarify_style>>

欢迎！本 skill 将引导你使用可用工具完成首次 Pinecone 体验。在这个快速入门中，你将学习如何对一些示例数据执行一种简单的 semantic search。

<<clarify_style>>

Prerequisites

前提条件

Before starting either path, verify the API key works by calling

list-indexes

via the Pinecone MCP. If it succeeds, proceed. If it fails, ask the user to set their key:

<<api_key_setup>>

Then retry

list-indexes

to confirm.

开始任一路径前，通过 Pinecone MCP 调用

list-indexes

，验证 API key 是否有效。如果成功，继续操作。如果失败，请用户设置其 key：

<<api_key_setup>>

然后重试

list-indexes

以确认。

Step 0: Choose Your Path

步骤 0：选择你的路径

Ask the user which path they want:

Database – Build a vector search index. Best for developers who want to store and search embeddings. Uses the Pinecone MCP + a Python upsert script.
Assistant – Build a document Q&A assistant. Best for users who want to upload files and ask questions with cited answers. No code required.

询问用户希望选择哪条路径：

Database – 构建 vector search 索引。适合希望存储和搜索 embeddings 的开发者。使用 Pinecone MCP + Python upsert 脚本。
Assistant – 构建文档问答助手。适合希望上传文件、提出问题并获得带引用答案的用户。无需编写代码。

Path A: Database Quickstart

路径 A：Database 快速入门

For each step, explain to the user what will happen. An overview is here:

Check if MCP is set
Create an integrated index with MCP
Upsert sample data using the bundled script (9 sentences across productivity, health, and nature themes)
Run a semantic search query and explore further queries
Optionally try reranking
Offer the complete standalone script

对于每个步骤，向用户解释将要发生什么。概览如下：

检查是否已设置 MCP
使用 MCP 创建 integrated index
使用随附脚本 upsert 示例数据（涵盖效率、健康和自然主题的 9 个句子）
运行 semantic search 查询并探索更多查询
可选：尝试 reranking
提供完整的独立脚本

Step 1 – Verify MCP is Available

步骤 1 – 验证 MCP 是否可用

The prerequisite check already called

list-indexes

. If it succeeded, the MCP is working — proceed to Step 2.

If it failed because MCP tools were unavailable (not an auth error):

Tell the user the MCP server needs to be configured
Point them to: https://docs.pinecone.io/reference/tools/mcp

前提检查已调用

list-indexes

。如果调用成功，说明 MCP 正常工作——继续执行步骤 2。

如果失败是因为 MCP 工具不可用（而不是身份验证错误）：

告知用户需要配置 MCP server
指向以下文档：https://docs.pinecone.io/reference/tools/mcp

Step 2 – Create an Integrated Index

步骤 2 – 创建 integrated index

Use the MCP

create-index-for-model

tool to create a serverless index with integrated embeddings:

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

Explain to the user what's happening:

An integrated index uses a built-in Pinecone embedding model (
```
llama-text-embed-v2
```
)
This means you send plain text and Pinecone handles the embedding automatically
The
```
field_map
```
tells Pinecone which field in your records contains the text to embed

Wait for the index to become ready before proceeding. Waiting a few seconds is sufficient.

使用 MCP

create-index-for-model

工具创建一个带有集成 embedding 的 serverless index：

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

向用户解释正在发生什么：

integrated index 使用 Pinecone 内置的 embedding 模型（
```
llama-text-embed-v2
```
）
这意味着你只需发送纯文本，Pinecone 便会自动处理 embedding
```
field_map
```
告诉 Pinecone 记录中的哪个字段包含需要 embedding 的文本

继续操作前，请等待索引进入就绪状态。等待几秒即可。

Step 3 – Upsert Sample Data

步骤 3 – Upsert 示例数据

Run the bundled upsert script to seed the index with sample records.

PINECONE_API_KEY

is set in the environment:

bash

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

If using a

.env

file:

bash

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

Explain to the user what's happening:

The script uploads 9 sample records across three themes: productivity (getting work done), health (feeling unwell), and nature (outdoors/wildlife)
The dataset is intentionally varied so semantic search can show its value — the queries below use completely different words than the records, but the right ones still surface
Each record has an
```
_id
```
, a
```
chunk_text
```
field (the text that gets embedded), and a
```
category
```
field
This is the same structure you'd use for your own data — just replace the records

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

如果环境中已设置

PINECONE_API_KEY

：

bash

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

如果使用

.env

文件：

bash

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

向用户解释正在发生什么：

脚本会上传涵盖三个主题的 9 条示例记录：效率（完成工作）、健康（身体不适）和自然（户外/野生动物）
数据集有意设计得多样化，以展示 semantic search 的价值——下面的查询使用的词与记录完全不同，但仍能检索出正确的结果
每条记录都有一个
```
_id
```
、一个
```
chunk_text
```
字段（需要 embedding 的文本）和一个
```
category
```
字段
这与处理自有数据时会使用的结构相同——只需替换记录即可

Step 4 – Query with the MCP

步骤 4 – 使用 MCP 查询

Use the MCP

search-records

tool to run the first semantic search:

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

Display the results in a clean table: ID, score, and

chunk_text

Explain to the user what's happening:

Notice the query shares no keywords with the records — but it surfaces the productivity sentences
That's semantic search: it finds meaning, not just matching words
You sent plain text — Pinecone embedded the query using the same model as the index

Offer to explore further: Ask the user if they'd like to try another query to see the effect more clearly:

Option A:
```
"feeling under the weather"
```
— should surface the health records
Option B:
```
"wildlife spotting outside"
```
— should surface the nature records
Option C: No thanks, move on

Run whichever query they choose and display the results the same way. If they want to try both, do both. After each result, point out which theme surfaced and why.

If they decline or are done exploring, proceed to Step 5 or offer to skip ahead to the complete script.

使用 MCP

search-records

工具运行第一次 semantic search：

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

以清晰的表格展示结果：ID、score 和

chunk_text

。

向用户解释正在发生什么：

请注意，该查询与记录没有任何共同关键词——却检索出了效率主题的句子
这就是 semantic search：它查找的是含义，而不只是匹配的词语
你发送的是纯文本——Pinecone 使用与索引相同的模型对查询进行了 embedding

提供进一步探索的选项： 询问用户是否愿意尝试另一个查询，以更清楚地看到效果：

选项 A：
```
"feeling under the weather"
```
——应该会检索出健康主题的记录
选项 B：
```
"wildlife spotting outside"
```
——应该会检索出自然主题的记录
选项 C：不用了，继续

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

如果用户拒绝探索或已完成探索，请继续执行步骤 5，或提供直接跳转到完整脚本的选项。

Step 5 – Try Reranking (Optional)

步骤 5 – 尝试 reranking（可选）

Ask the user if they want to try reranking.

If yes, use

search-records

again with reranking enabled:

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

Explain: Reranking runs a second-pass model over the results to improve relevance ordering.

询问用户是否想尝试 reranking。

如果愿意，再次使用

search-records

并启用 reranking：

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

解释：reranking 会对结果运行第二遍模型，以改善相关性排序。

Step 6 – Wrap Up

步骤 6 – 收尾

Congratulate the user on completing the quickstart. Ask if they'd like a standalone Python script that does everything in one go — create index, upsert, query, and rerank.

If yes, copy it to their working directory:

bash

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

Tell the user:

The script is at
```
./pinecone_quickstart.py
```
Run it with:
```
uv run pinecone_quickstart.py
```
It uses
```
uv
```
inline dependencies — no separate install needed
They can swap in their own
```
records
```
list to build something real

恭喜用户完成快速入门。询问用户是否希望使用一个独立的 Python 脚本一次完成所有操作——创建索引、upsert、查询和 rerank。

如果用户同意，请将其复制到工作目录：

bash

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

告诉用户：

脚本位于
```
./pinecone_quickstart.py
```
使用以下命令运行：
```
uv run pinecone_quickstart.py
```
它使用
```
uv
```
内联依赖——无需单独安装
用户可以替换自己的
```
records
```
列表，以构建真正实用的功能

Path B: Assistant Quickstart

路径 B：Assistant 快速入门

Guide the user through the Pinecone Assistant workflow using the existing pinecone-assistant skill:

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

Step 1 – Check for Documents

步骤 1 – 检查文档

Before anything else, ask the user if they have files to upload. Pinecone Assistant accepts

.pdf

.md

.txt

, and

.docx

files — a single file or a folder of files both work.

If they have files: ask for the path and proceed to Step 2.

If they don't have files: offer two options:

Generate sample docs — create a few short markdown files in
```
./sample-docs/
```
so they can complete the quickstart right now. Ask what topics they'd like (or default to: a product FAQ, a short how-to guide, and a brief company overview). Write 3 files, each 150–250 words.
Come back later — let them know they can return once they have documents and pick up from Step 2.

在进行任何其他操作之前，询问用户是否有要上传的文件。Pinecone Assistant 接受

.pdf

、

.md

、

.txt

和

.docx

文件——单个文件或文件文件夹都可以。

如果用户有文件： 询问文件路径并继续执行步骤 2。

如果用户没有文件： 提供两个选项：

生成示例文档——在
```
./sample-docs/
```
中创建几个简短的 Markdown 文件，让用户现在就能完成快速入门。询问用户希望涉及哪些主题（或默认使用：产品 FAQ、简短操作指南和公司简介概览）。编写 3 个文件，每个 150–250 词。
稍后返回——告知用户可以在准备好文档后返回，并从步骤 2 继续。

Step 2 – Create an Assistant

步骤 2 – 创建 Assistant

Invoke

pinecone-assistant

or run (add

--env-file .env

if using a

.env

file):

bash

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

Explain: The assistant is a fully managed RAG service — upload documents, ask questions, get cited answers.

调用

pinecone-assistant

或运行以下命令（如果使用

.env

文件，则添加

--env-file .env

）：

bash

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

解释：该 Assistant 是一个完全托管的 RAG 服务——上传文档、提出问题，获得带引用的答案。

Step 3 – Upload Documents

步骤 3 – 上传文档

Invoke

pinecone-assistant

or run (add

--env-file .env

if using a

.env

file):

bash

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

Explain: Pinecone handles chunking, embedding, and indexing automatically — no configuration needed.

调用

pinecone-assistant

或运行以下命令（如果使用

.env

文件，则添加

--env-file .env

）：

bash

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

解释：Pinecone 会自动完成 chunking、embedding 和 indexing——无需进行任何配置。

Step 4 – Chat with the Assistant

步骤 4 – 与 Assistant 对话

Invoke

pinecone-assistant

or run (add

--env-file .env

if using a

.env

file):

bash

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

Explain: Responses include citations with source file and page number.

调用

pinecone-assistant

或运行以下命令（如果使用

.env

文件，则添加

--env-file .env

）：

bash

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

解释：回答中包含引用，并会标出来源文件和页码。

Next Steps for Assistant

Assistant 的后续步骤

Invoke
```
pinecone-assistant
```
to keep the assistant up to date as documents change
Use the pinecone-assistant skill to retrieve raw context snippets for custom workflows
Every assistant is also an MCP server — see https://docs.pinecone.io/guides/assistant/mcp-server

调用
```
pinecone-assistant
```
，以便在文档发生变化时持续更新 Assistant
使用 pinecone-assistant skill 获取原始上下文片段，以构建自定义工作流
每个 Assistant 同时也是一个 MCP server——请参阅 https://docs.pinecone.io/guides/assistant/mcp-server

Troubleshooting

故障排查

PINECONE_API_KEY
not set

<<api_key_setup>>

Restart your IDE or agent session after setting the key.

MCP tools not available

Verify the Pinecone MCP server is configured in your IDE's MCP settings
Check that
```
PINECONE_API_KEY
```
is set before the MCP server starts

Index already exists

The upsert script is safe to re-run — it will upsert over existing records
Or delete and recreate: use
```
pc index delete -n quickstart-skills
```
via the CLI

uv
not installed See the uv installation guide.

未设置
PINECONE_API_KEY

<<api_key_setup>>

设置 key 后，请重启 IDE 或 Agent 会话。

MCP 工具不可用

验证 Pinecone MCP server 是否已在 IDE 的 MCP 设置中配置
检查 MCP server 启动前是否已设置
```
PINECONE_API_KEY
```

索引已存在

upsert 脚本可安全地重复运行——它会在现有记录上执行 upsert
或删除并重新创建：通过 CLI 使用
```
pc index delete -n quickstart-skills
```

未安装
uv
请参阅 uv 安装指南。

pinecone-quickstart

Original

Translation

Pinecone Quickstart

Pinecone 快速入门

Prerequisites

前提条件

Step 0: Choose Your Path

步骤 0：选择你的路径

Path A: Database Quickstart

路径 A：Database 快速入门

Step 1 – Verify MCP is Available

步骤 1 – 验证 MCP 是否可用

Step 2 – Create an Integrated Index

步骤 2 – 创建 integrated index

Step 3 – Upsert Sample Data

步骤 3 – Upsert 示例数据

Step 4 – Query with the MCP

步骤 4 – 使用 MCP 查询

Step 5 – Try Reranking (Optional)

步骤 5 – 尝试 reranking（可选）

Step 6 – Wrap Up

步骤 6 – 收尾

Path B: Assistant Quickstart

路径 B：Assistant 快速入门

Step 1 – Check for Documents

步骤 1 – 检查文档

Step 2 – Create an Assistant

步骤 2 – 创建 Assistant

Step 3 – Upload Documents

步骤 3 – 上传文档

Step 4 – Chat with the Assistant

步骤 4 – 与 Assistant 对话

Next Steps for Assistant

Assistant 的后续步骤

Troubleshooting

故障排查

Further Reading

延伸阅读