使用 Pinecone Canopy 构建智能应用：初学者指南

Edo Liberty 曾任 AWS 和 Yahoo 的研究总监。在此期间，他很快意识到，将人工智能（AI）模型与向量搜索结合，能够显著提升推荐系统、垃圾信息检测器等应用的效果，蕴藏着巨大的力量。

随着他在大规模自定义向量搜索系统上的深入研究，他注意到，对于那些不具备 AWS 和 Yahoo 同等工程与数据科学资源的团队，并没有打包好的解决方案。于是，他在 2019 年创立了 Pinecone，这个向量数据库由此诞生。

Pinecone 的宗旨是提供开发与运行最前沿 AI 应用所需的关键存储与检索基础设施。根据 Pinecone 的说法，其创立原则是“让各类规模、不同 AI 专业水平的工程团队都能轻松使用该解决方案”。

这促成了如今易于使用、全托管的 Pinecone 服务。时间快进四年，我们迎来了 Pinecone Canopy —— 一个利用检索增强生成（RAG）的框架，让开发者能够轻松打造生成式 AI 应用。

在本教程的其余部分，我们将深入探讨：

什么是 Pinecone Canopy？
核心特性与优势
如何设置您的环境
您的第一个 Pinecone Canopy 项目
构建自定义应用
扩展 Canopy

什么是 Pinecone Canopy？

Canopy 的文档将其描述为“一个开源的检索增强生成（RAG）框架与上下文，构建在 Pinecone 向量数据库之上。”

需要注意的是，RAG 是 Meta（当时为 Facebook）AI Research 于 2020 年提出的一种高级 AI 框架。借助动态的、特定领域的数据，RAG 能在无需重新训练模型的情况下优化大语言模型（LLM）的输出。

Canopy 处理开发 RAG 应用所涉及的所有繁重工作。这包括管理聊天记录、对文本数据进行切分与嵌入、查询优化、上下文检索（含提示工程）以及增强式生成。

因此，开发者可以使用 Canopy 快速、轻松地试验并创建 RAG 应用。根据 2023 年 11 月的发布博文，“借助 Canopy，您可以在一小时内让一款可用于生产的 RAG 驱动应用运行起来。而且因为它由 Pinecone 构建并提供支持，您将获得与我们全托管向量数据库同样优秀的开发体验与性能。”

Pinecone Canopy 的核心特性与优势

对于希望试验 RAG 的开发者，Canopy 提供了这样一套解决方案：

免费

用户可以免费在 Pinecone 中存储最多 10 万个嵌入。这大约相当于 1500 万字或 3 万页文本。此外，发布博文提到，“嵌入模型与 LLM 的免费选项即将推出。”

易于落地

文本数据可以是 JSONL、Parquet 或纯文本格式，剩下的交给 Canopy 处理。需要注意的是，后续也将增加对 PDF 的支持。任何 OpenAI 的 LLM（包括 GPT-4 Turbo）都与 Canopy 兼容。其他 LLM 与嵌入模型的支持（如来自 Anyscale Endpoints 的知名开源模型）也将很快加入。希望将文本数据转换为 JSONL 格式的用户可使用 Pinecone 的notebook 进行转换。

大规模可靠

依托 Pinecone 的向量数据库，您可以快速、准确且可靠地构建可用于生产的生成式 AI 应用。

模块化且可扩展

Canopy 库可用于创建独特的应用。用户也可以通过简单的 REST API 将 Canopy 作为 Web 服务或应用运行。您还可以将其添加至现有的 OpenAI 应用中，只需将 Chat Completions API 替换为 Canopy 的服务器端点即可。

交互式与迭代式

Canopy CLI 可通过简单命令与文本数据进行交互。这使用户能够轻松将 RAG 与非 RAG 工作流进行对比，在投入生产之前以交互方式评估增强后的结果。

设置您的 Pinecone Canopy 环境

开始使用 Pinecone Canopy 相对直接。在动手之前，您需要注册 Standard 或 Enterprise 版本。新用户将获得 100 美元的无服务器额度，用于上手和熟悉该工具。

如果您不想提供信用卡信息，可以创建一个免费的基于 pod 的索引。

步骤 1：安装 Canopy 包

注册账户后，您就可以开始了……

使用以下命令安装 Canopy 包：

pip install canopy-sdk技术支持

如果您希望在虚拟环境中进行安装，请在安装包之前运行以下命令：

python3 -m venv canopy-env
source canopy-env/bin/activate技术支持

这将创建一个虚拟环境并将其激活。查看我们的Python 虚拟环境教程，了解其工作原理。

步骤 2：获取您的 API 密钥

接下来，您需要设置环境变量。为此，您需要准备几个 API 密钥。

要找到您的 PINECONE_API_KEY，只需：

打开 Pinecone 控制台。
进入 API Keys。
复制您的 API 密钥。

其他必需的环境变量包括：

OPENAI_API_KEY → 用于对 OpenAI 的嵌入与聊天 API 进行身份验证。请在此处获取。注意，您可能需要事先登录或注册 OpenAI 服务。
INDEX_NAME → 这是 Canopy 将使用的 Pinecone 索引名称——稍后在本教程中会详细介绍。
CANOPY_CONFIG_FILE → 指向 Canopy 服务器所使用配置 yaml 文件的路径。如果未提供，将使用默认配置。

以下是设置环境变量的方法——在终端中运行：

export PINECONE_API_KEY="<PINECONE_API_KEY>"
export OPENAI_API_KEY="<OPENAI_API_KEY>"
export CANOPY_CONFIG_FILE="<CANOPY_CONFIG_FILE >"
export INDEX_NAME="<INDEX_NAME>"技术支持

步骤 3：检查安装是否成功

如果您已经完成以上步骤，Canopy 应该已安装在您的系统中。

为确认无误，运行以下命令：

canopy 技术支持

您应会看到类似以下输出：

Canopy: Ready

Usage: canopy [OPTIONS] COMMAND [ARGS]...
# rest of the help message技术支持

现在，您已准备好开始您的第一个 Pinecone Canopy 项目。

您的第一个 Pinecone Canopy 项目

创建新的 Canopy 索引

在 Pinecone 中，向量嵌入存储在索引中——这是平台中向量数据的最高级组织单元。索引用于接收并存储向量，为其中包含的向量提供查询服务，并对其内容执行其他向量操作。

在使用 Canopy 时，您需要设置一个配置为与 Canopy 协作的新 Pinecone 索引。通过运行以下命令完成：

canopy new技术支持

运行该命令后，按照 CLI 的指引进行操作。

创建的索引将带有前缀 canopy--<INDEX_NAME>。

请注意，每个要创建的 Canopy 索引，该流程只需执行一次。

数据准备与 Upsert

创建索引后，您就可以将数据加载至 Canopy 索引中了。

根据您的数据情况，以下是几种不同的方式：

canopy upsert /path/to/data_directory
# or
canopy upsert /path/to/data_directory/file.parquet
# or
canopy upsert /path/to/data_directory/file.jsonl
# or
canopy upsert /path/to/directory_of_txt_files/
# ...技术支持

根据文档，“Canopy 支持 jsonl、parquet 和 csv 格式的文件。此外，您还可以加载 .txt 格式的纯文本数据文件。在这种情况下，每个文件将被视为一个独立文档。文档 ID 将是文件名，来源将是文件的完整路径。”

请注意 upsert 命令的使用。upsert 操作用于将记录写入索引的命名空间。如果某条记录 ID 已存在，则 upsert 操作会覆盖整条记录。

如果您希望进行部分更新，请使用 update 操作修改记录的一部分。

启动 Canopy 服务器

Canopy 服务器通过 REST API 提供其功能。具体而言，它使您能够与数据对话、上传文档，并为特定查询获取相关文档。任何聊天应用都可以轻松对接服务器的 /chat.completion 端点。

要启动服务器，运行：

canopy start技术支持

随后您会看到标准的 Uvicorn 提示信息：

...

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)技术支持

出现该提示后，您即可开始将支持 /chat.completion 端点的任意聊天应用与 Canopy 服务器配合使用。

理解 Canopy 的架构

Canopy 既可作为 Web 服务（通过 Canopy Server）使用，也是一个可用于创建自定义应用的库。该库由三个组件（类）构成，可单独使用，也可组合成完整方案。每个组件负责 RAG 工作流中的不同部分：

知识库（Knowledge Base）

知识库用于为 RAG 工作流准备数据。文本输入会被自动切分并转换为文本嵌入，然后 upsert 至 Pinecone 向量数据库。

上下文引擎（Context Engine）

RAG 中的“检索”部分由上下文引擎负责。借助知识库，上下文引擎从 Pinecone 中定位最相关的文档，并将它们组织为可用于 LLM 提示的上下文。

Canopy 聊天引擎（Canopy Chat Engine）

Canopy 聊天引擎实现了完整的 RAG 工作流。它能够理解先前的聊天历史、识别多部分问题、从单个提示生成多个相关查询并将其转换为嵌入。完成后，终端用户将基于上下文引擎为 LLM 生成的上下文，获得高度相关的回复。

展示 Canopy 聊天引擎如何实现完整 RAG 工作流的示意图。来源 - Introducing Canopy: An easy, free, and flexible RAG framework powered by Pinecone

Pinecone Canopy 的高级特性与最佳实践

管理大型数据集

Canopy 用户可以借助 Pinecone 对索引进行纵向或横向扩展。纵向扩展（即向上扩展）可提供更多计算资源，横向扩展（即向外扩展）可提供更多机器以分担负载。

另一个高级特性是将索引中的记录分区到不同的命名空间。这样可以将查询和其他操作限定在某个命名空间内，不同请求即可搜索索引的不同子集。

例如，您可以为按曲风索引歌曲定义一个命名空间，再为按发行年份索引歌曲定义另一个命名空间。这里有一篇深入教程介绍如何实现。

最后但同样重要的是批量 upsert。需要注意的是，upsert 操作使用户能够将记录写入命名空间。然而，当您需要 upsert 大量数据时，文档建议“将记录以不超过 100 条为一批进行 upsert，并通过多次 upsert 请求完成。”

示例如下：

# Source: https://docs.pinecone.io/docs/upsert-data
import random
import itertools
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")
index = pc.Index("pinecone-index")

def chunks(iterable, batch_size=100):
    """A helper function to break an iterable into chunks of size batch_size."""
    it = iter(iterable)
    chunk = tuple(itertools.islice(it, batch_size))
    while chunk:
        yield chunk
        chunk = tuple(itertools.islice(it, batch_size))

vector_dim = 128
vector_count = 10000

# Example generator that generates many (id, vector) pairs
example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count))

# Upsert data with 100 vectors per upsert request
for ids_vectors_chunk in chunks(example_data_generator, batch_size=100):
    index.upsert(vectors=ids_vectors_chunk) 技术支持

优化 RAG 性能

尽管 LLM 是伟大的发明，但它们有一个主要缺陷：会“臆造”内容。RAG 可通过为其提供事实性上下文来回答问题，从而提升其实用性。

您可以尝试的一项技术是“切分”（chunking），以优化 RAG 工作流的性能与准确性。这是开发 RAG 系统的基础环节，但像 Canopy 这样的框架通常会将此过程抽象化，用户无需刻意思考。不过，切分粒度确实很重要，您应当予以考虑以提升 RAG 性能——请参阅这篇 Pinecone 博文了解切分方法。

总结

Pinecone 的 Canopy 通过处理开发 RAG 应用所涉及的所有繁重任务（如管理聊天历史、对文本数据进行切分与嵌入、查询优化、上下文检索［包括提示工程］以及增强式生成），简化了 RAG 应用的构建过程。这让任何希望构建与试验 RAG 的人都能更轻松地起步。

在本教程中，我们介绍了开始试验与创建 RAG 应用所需了解的一切。Canopy 的开发者承诺，您可以在一小时内让一款可用于生产的 RAG 驱动应用运行起来。不妨亲自试一试。

继续学习，请查看：

作者

Kurtis Pykes

主题

人工智能

主题

技术