企业官网建设流程全解析

• AI 技能
• 人工智能
• 大模型
• 深度学习

Pinecone 是面向生产环境的全托管向量数据库，在本仓库 15-rag/pinecone/SKILL.md 中作为 RAG（检索增强生成）与大规模语义搜索的核心 Skill 被收录。本文以该文档为主体，结合 生产部署指南 以及 LangChain、LlamaIndex 侧的集成示例，完整讲解从建索引、写入向量、元数据过滤、命名空间隔离到稠密+稀疏混合检索的端到端用法，并给出性能指标、成本模型与生产落地的最佳实践，读完即可在真实 RAG 系统中直接落地使用。

何时选择 Pinecone：适用场景与替代方案

Pinecone 是云上的全托管向量数据库服务（SaaS），其定位是"生产级 AI 应用"：

适合使用 Pinecone 的场景

• 需要托管化、Serverless 的向量数据库，不想自己运维基础设施；
• 构建生产级 RAG 应用，要求稳定、低延迟检索；
• 需要自动扩容，数据量可增长到数十亿向量级别；
• 对延迟敏感，要求 p95 延迟低于 100ms；
• 需要混合检索（稠密向量 + 稀疏向量结合语义与关键词匹配）。

关键指标（来自 SKILL.md）：

• 全托管 SaaS 服务；
• 自动扩容至数十亿向量；
• p95 查询延迟低于 100ms；
• 99.9% 的可用性 SLA。

什么情况应该改用替代方案：

• Chroma：自托管、开源，适合本地开发与原型验证；
• FAISS：离线纯相似度检索，无元数据过滤能力；
• Weaviate：自托管、功能更丰富的方案。

选择原则很简单：追求零运维、自动伸缩、生产级 SLA 选 Pinecone；追求开源可控、本地离线选 Chroma/FAISS。仓库在 15-rag 目录下按此维度划分了多个 Skill，可对照选择。

快速开始：安装与最小可用示例

安装客户端

Pinecone 官方 Python 客户端通过 pip 安装（这也是本 Skill 声明的唯一依赖，见 SKILL.md frontmatter 中的dependencies: [pinecone-client]）：

pip install pinecone-client

最小可用代码

from pinecone import Pinecone, ServerlessSpec # 初始化（在 Pinecone Console 获取 API Key） pc = Pinecone(api_key="your-api-key") # 创建索引：维度必须与所用嵌入模型的输出维度一致 pc.create_index( name="my-index", dimension=1536, # 例如 OpenAI text-embedding-3-small 的输出维度 metric="cosine", # 可选 "euclidean"、"dotproduct" spec=ServerlessSpec(cloud="aws", region="us-east-1") ) # 连接索引 index = pc.Index("my-index") # 写入（Upsert）向量 index.upsert(vectors=[ {"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "A"}}, {"id": "vec2", "values": [0.3, 0.4, ...], "metadata": {"category": "B"}} ]) # 查询 results = index.query( vector=[0.1, 0.2, ...], top_k=5, include_metadata=True ) print(results["matches"])

这段代码覆盖了 Pinecone 使用的四个核心环节：初始化客户端 → 创建索引 → Upsert 写入 → Query 查询。值得注意的是dimension必须与你的嵌入模型输出维度严格一致，这是最容易踩的坑之一；metric决定相似度算法，语义检索通常用cosine。

核心操作详解

创建索引：Serverless 与 Pod 两种模式

Pinecone 支持两种索引规格，创建方式差异较大，选择直接影响成本与性能特征。

Serverless 模式（推荐，随用随付）：

pc.create_index( name="my-index", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", # 可选 "gcp"、"azure" region="us-east-1" ) )

Pod 模式（面向稳定性能的独占资源）：

from pinecone import PodSpec pc.create_index( name="my-index", dimension=1536, metric="cosine", spec=PodSpec( environment="us-east1-gcp", pod_type="p1.x1" # 或 p1.x2、p1.x4、p1.x8 ) )

两种模式的选择依据，部署指南 有更细的展开：

Pod 模式还支持通过pods=2、replicas=2参数提升吞吐与高可用（deployment.md）。部署指南给出的总体策略是：开发阶段用 Serverless 省钱，生产阶段对延迟敏感的业务切 Pod 保证一致性。

Upsert 写入向量

写入支持单条与批量两种方式：

# 单条写入（携带元数据） index.upsert(vectors=[ { "id": "doc1", "values": [0.1, 0.2, ...], # 1536 维 "metadata": { "text": "Document content", "category": "tutorial", "timestamp": "2025-01-01" } } ]) # 批量写入（生产推荐，性能更高） vectors = [ {"id": f"vec{i}", "values": embedding, "metadata": metadata} for i, (embedding, metadata) in enumerate(zip(embeddings, metadatas)) ] index.upsert(vectors=vectors, batch_size=100)

要点：id必须唯一（重复写入同一 id 会覆盖旧向量）；batch_size=100是文档推荐的默认批量大小；元数据随向量一起写入，是后续过滤与租户隔离的基础。文档的最佳实践建议每批 100~200 条向量，兼顾吞吐与稳定性。

Query 查询向量

# 基础查询 results = index.query( vector=[0.1, 0.2, ...], top_k=10, include_metadata=True, include_values=False ) # 带元数据过滤的查询 results = index.query( vector=[0.1, 0.2, ...], top_k=5, filter={"category": {"$eq": "tutorial"}} ) # 指定命名空间查询 results = index.query( vector=[0.1, 0.2, ...], top_k=5, namespace="production" ) # 遍历结果 for match in results["matches"]: print(f"ID: {match['id']}") print(f"Score: {match['score']}") print(f"Metadata: {match['metadata']}")

top_k控制返回条数；include_metadata决定是否回传元数据（默认不回传，需要时务必显式开启）；include_values决定是否回传原始向量（一般查询场景可关闭以节省带宽）。

元数据过滤

元数据过滤支持完整的操作符体系（SKILL.md）：

# 精确匹配 filter = {"category": "tutorial"} # 比较运算：$gt、$gte、$lt、$lte、$ne filter = {"price": {"$gte": 100}} # 逻辑运算：$and、$or filter = { "$and": [ {"category": "tutorial"}, {"difficulty": {"$lte": 3}} ] } # 集合成员判断 filter = {"tags": {"$in": ["python", "ml"]}}

部署指南 还补充了范围查询与复合过滤的写法，例如{"price": {"$gte": 100, "$lte": 500}}，以及将$in、$lte、$gte组合进$and的三重条件过滤。过滤能显著缩小搜索空间、提升检索精度，代价是每次过滤约增加 10~20ms 延迟（见性能表）。

命名空间：多租户数据隔离

命名空间（Namespace）是 Pinecone 在同一索引内部做逻辑分区的主要手段（SKILL.md）：

# 按命名空间写入，实现数据分区 index.upsert( vectors=[{"id": "vec1", "values": [...]}], namespace="user-123" ) # 在指定命名空间内查询 results = index.query( vector=[...], namespace="user-123", top_k=5 ) # 列出索引内所有命名空间 stats = index.describe_index_stats() print(stats['namespaces'])

典型应用场景（deployment.md）：

• 多租户 SaaS：每个租户一个命名空间，实现数据隔离；
• 用户个性化数据隔离：如user-123只查询自己的内容；
• A/B 测试：prod / staging 分别放在不同命名空间。

命名空间查询无需过滤开销即可天然隔离数据，是多租户架构的首选方案。

混合检索：稠密向量 + 稀疏向量

混合检索同时利用稠密向量（语义匹配）与稀疏向量（关键词精确匹配，如 TF-IDF/BM25），是提升检索召回质量的关键能力（SKILL.md）：

# 写入时同时携带稠密与稀疏向量 index.upsert(vectors=[ { "id": "doc1", "values": [0.1, 0.2, ...], # 稠密向量（语义） "sparse_values": { "indices": [10, 45, 123], # 词元 ID "values": [0.5, 0.3, 0.8] # TF-IDF / BM25 分数 }, "metadata": {"text": "..."} } ]) # 混合查询，alpha 控制两种信号的权重 results = index.query( vector=[0.1, 0.2, ...], sparse_vector={ "indices": [10, 45], "values": [0.5, 0.3] }, top_k=5, alpha=0.5 # 0=纯稀疏，1=纯稠密，0.5=均衡混合 )

alpha是混合检索的核心超参数：alpha=0退化为纯关键词检索，alpha=1退化为纯语义检索，中间值则融合两者。其收益正如 部署指南 所总结的：语义 + 关键词双重匹配，召回率优于单独使用任何一种方式——这对 RAG 场景中同时存在同义改写（语义）与专有名词/代码片段（关键词）的查询尤其有效。

与 LangChain 的集成

Pinecone 可作为 LangChain 的向量存储（VectorStore）直接接入 RAG 链路。本仓库 LangChain RAG 指南 中同样使用langchain_pinecone.PineconeVectorStore：

from langchain_pinecone import PineconeVectorStore from langchain_openai import OpenAIEmbeddings # 从文档构建向量存储（内部会切分、嵌入并写入索引） vectorstore = PineconeVectorStore.from_documents( documents=docs, embedding=OpenAIEmbeddings(), index_name="my-index" ) # 相似度检索 results = vectorstore.similarity_search("query", k=5) # 带元数据过滤的检索 results = vectorstore.similarity_search( "query", k=5, filter={"category": "tutorial"} ) # 转为检索器接入 Agent/Chain retriever = vectorstore.as_retriever(search_kwargs={"k": 10})

as_retriever生成的 retriever 可以直接挂到 RAG 链或 Agent 工具上，是 langchain 生态中最常见的接入方式。

与 LlamaIndex 的集成

Pinecone 同样可以作为 LlamaIndex 的向量存储后端（SKILL.md），本仓库 LlamaIndex Skill 中也有对应调用：

from llama_index.vector_stores.pinecone import PineconeVectorStore # 连接 Pinecone pc = Pinecone(api_key="your-key") pinecone_index = pc.Index("my-index") # 创建向量存储 vector_store = PineconeVectorStore(pinecone_index=pinecone_index) # 接入 LlamaIndex 的 StorageContext 与 VectorStoreIndex from llama_index.core import StorageContext, VectorStoreIndex storage_context = StorageContext.from_defaults(vector_store=vector_store) index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

之后便可通过index.as_query_engine()获得完整的查询引擎，将 Pinecone 作为 llamaindex 检索增强应用的持久化底座。

索引管理与向量删除

索引生命周期管理（SKILL.md）：

# 列出所有索引 indexes = pc.list_indexes() # 查看索引详情 index_info = pc.describe_index("my-index") print(index_info) # 查看统计信息（向量总量、命名空间列表） stats = index.describe_index_stats() print(f"Total vectors: {stats['total_vector_count']}") print(f"Namespaces: {stats['namespaces']}") # 删除索引 pc.delete_index("my-index")

向量删除（SKILL.md）：

# 按 ID 删除 index.delete(ids=["vec1", "vec2"]) # 按过滤条件删除 index.delete(filter={"category": "old"}) # 删除某命名空间下的全部向量 index.delete(delete_all=True, namespace="test") # 清空整个索引 index.delete(delete_all=True)

describe_index_stats()是日常运维中最常用的观察入口，可用于监控索引增长与命名空间分布。

生产最佳实践清单

综合 SKILL.md 与 部署指南 的最佳实践，整理如下：

1. 优先 Serverless：自动扩容、按用量计费、零运维，成本最优；
2. 批量 Upsert：每批 100~200 条向量，吞吐远高于逐条写入；
3. 策略性添加元数据：元数据是过滤与检索精度的基础，但也不必过度冗余；
4. 善用命名空间：按用户/租户隔离数据，天然支持多租户；
5. 监控用量：定期查看 Pinecone 控制台与describe_index_stats()；
6. 为高频过滤字段建立索引：优化过滤性能（deployment.md 中亦建议验证过滤性能）；
7. 先用免费层验证：免费层提供 1 个 Serverless 索引、10 万条向量（1536 维），足够原型验证；
8. 启用混合检索：稠密 + 稀疏可显著提升检索质量；
9. 维度与嵌入模型匹配：维度必须与嵌入模型输出严格一致；
10. 定期备份：导出重要数据，避免单一服务商依赖；
11. 设置用量/成本告警：生产环境对费用阈值设置告警（deployment.md）；
12. 测试过滤性能：复合过滤在数据量增长后需验证延迟表现。

性能指标与成本模型

文档给出了参考性能数据（SKILL.md），注意这些数据与索引规模、pod 配置相关，实际以你的环境测量为准：

成本模型（文档记载的 2025 年参考价，实际以官方定价页为准）：

• Serverless 读单元：每百万次约 $0.096；
• Serverless 写单元：每百万次约 $0.06；
• 存储：每 GB 每月约 $0.06；
• 免费层：1 个 Serverless 索引、10 万条 1536 维向量，适合原型验证。

延伸阅读

• 15-rag/pinecone/SKILL.md：本文主体，完整的 API 用法速查；
• 15-rag/pinecone/references/deployment.md：Serverless vs Pod 生产部署模式深度对比；
• 14-agents/langchain/references/rag.md：LangChain RAG 链路中的 Pinecone 集成示例；
• 14-agents/llamaindex/SKILL.md：LlamaIndex 侧 Pinecone 接入代码；
• 15-rag/chroma/SKILL.md：开源自托管替代方案，用于本地开发与原型；
• 15-rag/faiss/SKILL.md：离线纯相似度检索替代方案。

• AI 技能
• 人工智能
• 大模型
• 深度学习