前言
官方把 Retrieval 插件的代码开源了，我们可以根据官方示例与这个仓库的代码查个所以然。插件由以下组件组成：
•一个 API•一个 API 模式（OpenAPI JSON 或 YAML 格式）•一个清单（JSON 文件），用于定义插件的相关元数据
每个插件只需要提供一份标准的、接口描述准确的 OpenAPI 规范文件即可让 ChatGPT了解你的 API 的入参出参并加以调用。它使用 YAML 或 JSON 格式的文档，包括 API 的所有端点、操作和参数，并提供了对每个端点和操作的详细说明。现在的 OpenAPI 文件都可以自动生成了，你可以使用 Apifox 利用可视化的界面来编写你的 API 文档，并且加以自然语言的接口描述信息，选择导出 OpenAPI 格式就可以得到一份非常标准的 OpenAPI 格式描述文件，大大提升你的效率。
实际上，这和之前介绍的一些本地知识库的大模型使用案例类似，主要分为搜索内容转embedding、相似插件/内容片段搜索、上下文填充、大模型处理这几步。具体如下：
•用户使用自然语言向 ChatGPT 提问。•ChatGPT 根据用户的需求去查找符合描述的插件系统。•根据插件系统的 API 描述文档来选择符合当前上下文的 API 进行调用。（和sql自动生成场景中传递库、表元数据描述信息类似）。•得到结果后会将它继续传递给上下文，由此判断需不需要进行使用下一个插件。•最终会得到一个满足用户预期的自然语言回答。这里借用网上的一句话：插件系统的出现，说的通俗一点就像是给AI配了一个DLC，让 ChatGPT 从一个单机版 AI 升级为联网版 AI，他能上网了，并且对实时信息的检索大大补全加强，让 ChatGPT 功能再度提升一整个数量级。
ChatGPT 检索插件
在这里加入 ChatGPT 插件等待名单[1]!
您可以在此处[2]找到一个使用检索插件访问2018年至2022年联合国年度报告的示例视频。
介绍
ChatGPT 检索插件存储库提供了一种灵活的解决方案，通过自然语言查询对个人或组织文档进行语义搜索和检索。该存储库分为多个目录：
目录 | 描述 |
|---|---|
datastore[3] | 包含使用各种向量数据库提供程序存储和查询文档嵌入的核心逻辑。 |
docs[4] | 包括设置和使用每个向量数据库提供程序、webhooks 以及删除未使用的依赖项的文档。 |
examples[5] | 提供示例配置、身份验证方法和特定于提供程序的示例。 |
local_server[6] | 包含为本地主机测试配置的检索插件的实现。 |
models[7] | 包含插件使用的数据模型，例如文档和元数据模型。 |
scripts[8] | 提供用于处理和上传来自不同数据源的文档的脚本。 |
server[9] | 包含主要的 FastAPI 服务器实现。 |
services[10] | 包含用于任务的实用程序服务，例如分块、元数据提取和 PII 检测。 |
tests[11] | 包括针对各种向量数据库提供程序的集成测试。 |
.well-known[12] | 存储插件清单文件和 OpenAPI 架构，这些文件定义了插件配置和 API 规范。 |
本 README 提供了关于如何设置、开发和部署 ChatGPT 检索插件的详细信息。
目录
•快速开始[13]•关于[14]•插件[15]•检索插件[16]•记忆功能[17]•安全性[18]•API 端点[19]•开发[20]•设置[21]•通用环境变量[22]•选择向量数据库[23]•Pinecone[24]•Weaviate[25]•Zilliz[26]•Milvus[27]•Qdrant[28]•Redis[29]•Llama Index[30]•Chroma[31]•Azure Cognitive Search[32]•Supabase[33]•Postgres[34]•AnalyticDB[35]•在本地运行 API[36]•在 ChatGPT 中测试本地主机插件[37]•个性化[38]•身份验证方法[39]•部署[40]•安装开发者插件[41]•Webhooks[42]•脚本[43]•限制[44]•贡献者[45]•未来方向[46]
快速开始
按照以下步骤快速设置和运行 ChatGPT 检索插件：
1.如果尚未安装，请安装 Python 3.10。2.克隆存储库：git clone https://github.com/openai/chatgpt-retrieval-plugin.git3.进入克隆的存储库目录：cd /path/to/chatgpt-retrieval-plugin4.安装 poetry：pip install poetry5.使用 Python 3.10 创建一个新的虚拟环境：poetry env use python3.106.激活虚拟环境：poetry shell7.安装应用程序依赖项：poetry install8.创建一个 bearer token[47]9.设置所需的环境变量：
export DATASTORE=<your_datastore> export BEARER_TOKEN=<your_bearer_token> export OPENAI_API_KEY=<your_openai_api_key>Optional environment variables used when running Azure OpenAI
export OPENAI_API_BASE=https://<AzureOpenAIName>.openai.azure.com/
export OPENAI_API_TYPE=azure
export OPENAI_EMBEDDINGMODEL_DEPLOYMENTID=<Name of text-embedding-ada-002 model deployment>
export OPENAI_METADATA_EXTRACTIONMODEL_DEPLOYMENTID=<Name of deployment of model for metatdata>
export OPENAI_COMPLETIONMODEL_DEPLOYMENTID=<Name of general model deployment used for completion>
export OPENAI_EMBEDDING_BATCH_SIZE=<Batch size of embedding, for AzureOAI, this value need to be set as 1>Add the environment variables for your chosen vector DB.
Some of these are optional; read the provider's setup docs in /docs/providers for more information.
Pinecone
export PINECONE_API_KEY=<your_pinecone_api_key>
export PINECONE_ENVIRONMENT=<your_pinecone_environment>
export PINECONE_INDEX=<your_pinecone_index>Weaviate
export WEAVIATE_URL=<your_weaviate_instance_url>
export WEAVIATE_API_KEY=<your_api_key_for_WCS>
export WEAVIATE_CLASS=<your_optional_weaviate_class>Zilliz
export ZILLIZ_COLLECTION=<your_zilliz_collection>
export ZILLIZ_URI=<your_zilliz_uri>
export ZILLIZ_USER=<your_zilliz_username>
export ZILLIZ_PASSWORD=<your_zilliz_password>Milvus
export MILVUS_COLLECTION=<your_milvus_collection>
export MILVUS_HOST=<your_milvus_host>
export MILVUS_PORT=<your_milvus_port>
export MILVUS_USER=<your_milvus_username>
export MILVUS_PASSWORD=<your_milvus_password>Qdrant
export QDRANT_URL=<your_qdrant_url>
export QDRANT_PORT=<your_qdrant_port>
export QDRANT_GRPC_PORT=<your_qdrant_grpc_port>
export QDRANT_API_KEY=<your_qdrant_api_key>
export QDRANT_COLLECTION=<your_qdrant_collection>AnalyticDB
export PG_HOST=<your_analyticdb_host>
export PG_PORT=<your_analyticdb_port>
export PG_USER=<your_analyticdb_username>
export PG_PASSWORD=<your_analyticdb_password>
export PG_DATABASE=<your_analyticdb_database>
export PG_COLLECTION=<your_analyticdb_collection>Redis
export REDIS_HOST=<your_redis_host>
export REDIS_PORT=<your_redis_port>
export REDIS_PASSWORD=<your_redis_password>
export REDIS_INDEX_NAME=<your_redis_index_name>
export REDIS_DOC_PREFIX=<your_redis_doc_prefix>
export REDIS_DISTANCE_METRIC=<your_redis_distance_metric>
export REDIS_INDEX_TYPE=<your_redis_index_type>Llama
export LLAMA_INDEX_TYPE=<gpt_vector_index_type>
export LLAMA_INDEX_JSON_PATH=<path_to_saved_index_json_file>
export LLAMA_QUERY_KWARGS_JSON_PATH=<path_to_saved_query_kwargs_json_file>
export LLAMA_RESPONSE_MODE=<response_mode_for_query>Chroma
export CHROMA_COLLECTION=<your_chroma_collection>
export CHROMA_IN_MEMORY=<true_or_false>
export CHROMA_PERSISTENCE_DIR=<your_chroma_persistence_directory>
export CHROMA_HOST=<your_chroma_host>
export CHROMA_PORT=<your_chroma_port>Azure Cognitive Search
export AZURESEARCH_SERVICE=<your_search_service_name>
export AZURESEARCH_INDEX=<your_search_index_name>
export AZURESEARCH_API_KEY=<your_api_key> (optional, uses key-free managed identity if not set)Supabase
export SUPABASE_URL=<supabase_project_url>
export SUPABASE_ANON_KEY=<supabase_project_api_anon_key>Postgres
export PG_HOST=<postgres_host>
export PG_PORT=<postgres_port>
export PG_USER=<postgres_user>
export PG_PASSWORD=<postgres_password>
export PG_DATABASE=<postgres_database>
1.在本地运行 API：poetry run start2.在 http://0.0.0.0/docs 上访问 API 文档，并测试 API 端点（确保添加你的 bearer token）。
在 ChatGPT 中进行测试
要在 ChatGPT 中测试本地托管的插件，请按照以下步骤进行操作：
1.在本地运行 API：poetry run dev2.遵循 README 中的 在 ChatGPT 中测试本地主机插件[48] 部分中的说明。
有关设置、开发和部署 ChatGPT 检索插件的更详细信息，请参阅下面的完整开发部分。
关于
插件
插件是专为 ChatGPT 等语言模型设计的聊天扩展，使它们能够在用户请求时访问最新信息、运行计算或与第三方服务进行交互。它们为语言模型解锁了广泛的潜在用例，并增强了语言模型的能力。
开发人员可以通过在其网站上公开 API 并提供一个描述 API 的标准化清单文件来创建插件。ChatGPT 使用这些文件，并允许 AI 模型调用由开发人员定义的 API。
插件由以下组件组成：
•一个 API•一个 API 模式（OpenAPI JSON 或 YAML 格式）•一个清单（JSON 文件），用于定义插件的相关元数据
检索插件已经包含了所有这些组件。在 这里[49] 阅读 Chat 插件的博文，并在 这里[50] 找到文档。
检索插件
这是一个用于 ChatGPT 的插件，可以实现对个人或组织文件的语义搜索和检索。它允许用户通过自然语言提问或表达需求，从数据源（如文件、笔记或电子邮件）中获取最相关的文档片段。企业可以使用该插件通过 ChatGPT 向员工提供其内部文档。
该插件使用 OpenAI 的 text-embedding-ada-002 嵌入模型生成文档块的嵌入，然后在后端使用矢量数据库进行存储和查询。作为一个开源的自托管解决方案，开发人员可以部署自己的检索插件，并在 ChatGPT 中注册。检索插件支持多个矢量数据库提供商，开发人员可以从列表中选择他们首选的提供商。
一个 FastAPI 服务器公开了插件的端点，用于插入、查询和删除文档。用户可以通过使用来自源、日期、作者或其他条件的元数据过滤器来细化搜索结果。该插件可以托管在任何支持 Docker 容器的云平台上，如 Fly.io、Heroku、Render 或 Azure Container Apps。为了使矢量数据库与最新文档保持同步，插件可以使用传入的 Webhooks 连续处理和存储来自各种数据源的文档，使用 upsert 和 delete 端点。诸如 Zapier[51] 或 Make[52] 的工具可以根据事件或计划配置 Webhooks。
记忆功能
检索插件的一个显著功能是其能够为 ChatGPT 提供记忆。通过利用插件的 upsert 端点，ChatGPT 可以将对话中的片段保存到矢量数据库中以供以后参考（仅在用户提示时才这样做）。这个功能有助于实现更具上下文感知的聊天体验，使 ChatGPT 能够记住并从之前的对话中检索信息。在此处了解如何配置具有记忆功能的检索插件/examples/memory。
安全性
检索插件允许 ChatGPT 在内容的矢量数据库中进行搜索，并将最佳结果添加到 ChatGPT 会话中。这意味着它不会产生任何外部影响，主要的风险考虑是数据授权和隐私保护。开发人员应仅将授权的内容添加到其检索插件中，并允许其出现在用户的 ChatGPT 会话中。您可以选择多种不同的身份验证方法来保护插件（更多信息here[53]）。
API 接口
Retrieval 插件使用 FastAPI 构建，FastAPI 是一个用于构建 Python API 的 Web 框架。FastAPI 可以方便地开发、验证和文档化 API 接口。在此处可以找到 FastAPI 文档 链接[54]。
使用 FastAPI 的一个好处是自动生成带有 Swagger UI 的交互式 API 文档。当 API 在本地运行时，可以使用 /docs 路径的 Swagger UI 与 API 接口进行交互、测试其功能，并查看预期的请求和响应模型。
插件公开以下接口，用于向向量数据库插入、查询和删除文档。所有请求和响应均为 JSON 格式，并需要一个有效的 bearer token 作为授权头。
•/upsert：该接口允许上传一个或多个文档，并将其文本和元数据存储在向量数据库中。文档被分成大约 200 个令牌的块，每个块都有一个唯一的 ID。该接口在请求体中期望一个文档列表，每个文档都有一个 text 字段，以及可选的 id 和 metadata 字段。metadata 字段可以包含以下可选子字段：source、source_id、url、created_at 和 author。该接口返回插入文档的 ID 列表（如果没有提供 ID，则生成一个 ID）。•/upsert-file：该接口允许上传单个文件（PDF、TXT、DOCX、PPTX 或 MD），并将其文本和元数据存储在向量数据库中。文件将被转换为纯文本，并分成大约 200 个令牌的块，每个块都有一个唯一的 ID。该接口返回包含插入文件的生成 ID 的列表。•/query：该接口允许使用一个或多个自然语言查询和可选的元数据过滤器查询向量数据库。该接口在请求体中期望一个查询列表，每个查询都有一个 query 字段，以及可选的 filter 和 top_k 字段。filter 字段应包含以下子字段的子集：source、source_id、document_id、url、created_at 和 author。top_k 字段指定对于给定的查询返回多少个结果，默认值为 3。该接口返回一个对象列表，每个对象都包含给定查询的最相关文档块的列表，以及它们的文本、元数据和相似性分数。•/delete：该接口允许使用文档的 ID、元数据过滤器或 delete_all 标志从向量数据库中删除一个或多个文档。该接口在请求体中至少需要以下参数之一：ids、filter 或 delete_all。ids参数应为要删除的文档的 ID 列表；将删除具有这些 ID 的文档的所有文档块。filter参数应包含以下子字段的子集：source、source_id、document_id、url、created_at和author。delete_all参数应为一个布尔值，指示是否从向量数据库中删除所有文档。该接口返回一个布尔值，指示删除是否成功。
可以通过在本地运行应用程序并导航到 http://0.0.0.0/openapi.json，或者在 OpenAPI 架构链接[55]中找到请求和响应模型的详细规格和示例。请注意，OpenAPI 架构仅包含 /query 接口，因为 ChatGPT 只需要访问该函数来检索基于自然语言查询或需求的相关文档。但是，如果开发人员还希望 ChatGPT 具有记住后续操作的功能，可以使用 /upsert 接口将对话中的片段保存到向量数据库中。可以在此处[56]找到允许 ChatGPT 访问 /upsert 接口的清单和 OpenAPI 架构的示例。
要包含自定义元数据字段，请编辑 此处[57] 的 DocumentMetadata 和 DocumentMetadataFilter 数据模型，并更新此处[58]的 OpenAPI 架构。您可以通过在本地运行应用程序并复制在 http://0.0.0.0/sub/openapi.json 找到的 JSON，并使用 Swagger Editor[59] 将其转换为 YAML 格式，轻松更新此内容。或者，您可以将 openapi.yaml 文件替换为 openapi.json 文件。
开发
设置
此应用程序使用 Python 3.10 和 poetry[60] 进行依赖管理。
如果您的计算机尚未安装 Python 3.10，请从官方 Python 网站[61] 或使用类似于 brew 或 apt 的软件包管理器进行下载和安装。
从 GitHub 克隆仓库：
进入克隆的仓库目录：
cd /path/to/chatgpt-retrieval-plugin安装 poetry：
pip install poetry创建一个使用 Python 3.10 的新虚拟环境：
poetry env use python3.10
poetry shell使用 poetry 安装应用程序的依赖项：
poetry install注意： 如果在 pyproject.toml 中添加了依赖项，请确保运行 poetry lock 和 poetry install。
通用环境变量
API 需要以下环境变量才能正常工作：
名称 | 必需 | 描述 |
|---|---|---|
DATASTORE | 是 | 这指定了您要使用的向量数据库提供程序，用于存储和查询嵌入。您可以从 chroma、pinecone、weaviate、zilliz、milvus、qdrant、redis、azuresearch、supabase、postgres、analyticdb 中选择。 |
BEARER_TOKEN | 是 | 这是一个用于对 API 发出的请求进行身份验证的密钥。您可以使用任何工具或方法生成一个密钥，比如 jwt.io[62]。 |
OPENAI_API_KEY | 是 | 这是您的 OpenAI API 密钥，用于使用 text-embedding-ada-002 模型生成嵌入。您可以通过在 OpenAI[63] 上创建一个帐户来获取 API 密钥。 |
使用 Azure OpenAI 插件
Azure Open AI 使用特定于您的资源的 URL，并且不通过模型名称而是通过部署 ID 引用模型。因此，您需要为此情况设置额外的环境变量。
除了 OPENAI_API_BASE（您的特定 URL）和 OPENAI_API_TYPE（azure）之外，您还应该设置 OPENAI_EMBEDDINGMODEL_DEPLOYMENTID，该变量指定用于在 upsert 和 query 时获取嵌入的模型。为此，我们建议部署 text-embedding-ada-002 模型，并在此处使用部署名称。
如果您希望使用数据准备脚本，还需要设置 OPENAI_METADATA_EXTRACTIONMODEL_DEPLOYMENTID，用于元数据提取，以及 OPENAI_COMPLETIONMODEL_DEPLOYMENTID，用于 PII 处理。
选择向量数据库
该插件支持多个向量数据库提供程序，每个提供程序具有不同的功能、性能和定价。根据您选择的提供程序，您需要使用不同的 Dockerfile 并设置不同的环境变量。以下部分简要介绍了每个向量数据库提供程序。
有关设置和使用每个向量数据库提供程序的详细说明，请参阅 /docs/providers/<datastore_name>/setup.md 文件中的相应文档（此处的文件夹[64]）。
Pinecone
Pinecone[65] 是一个专为速度、规模和快速部署到生产环境而设计的托管型向量数据库。它支持混合搜索，并且是目前唯一本地支持 SPLADE 稀疏向量的数据存储。有关详细的设置说明，请参阅 /docs/providers/pinecone/setup.md[66]。
Weaviate
Weaviate[67] 是一个开源的向量搜索引擎，可以轻松扩展到数十亿个数据对象。它支持开箱即用的混合搜索，适用于需要高效关键字搜索的用户。Weaviate 可以自托管或托管方式部署，提供了灵活性。有关详细的设置说明，请参阅 /docs/providers/weaviate/setup.md[68]。
Zilliz
Zilliz[69] 是一个专为亿级数据设计的托管式云原生向量数据库。它提供多种索引算法、距离度量、标量过滤、时间旅行搜索、快照回滚、完整的 RBAC、99.9% 的正常运行时间、分离的存储和计算以及多语言 SDK 等多种功能。有关详细的设置说明，请参阅 /docs/providers/zilliz/setup.md[70]。
Milvus
Milvus[71] 是一个开源的、云原生的向量数据库，可以扩展到数十亿个向量。它是 Zilliz 的开源版本，并且与其共享许多功能，如各种索引算法、距离度量、标量过滤、时间旅行搜索、多语言 SDK、存储和计算分离以及云端扩展性。有关详细的设置说明，请参阅 /docs/providers/milvus/setup.md[72]。
Qdrant
Qdrant[73] 是一个能够存储文档和向量嵌入的向量数据库。它提供自托管和托管的 Qdrant Cloud[74] 部署选项，为具有不同需求的用户提供了灵活性。有关详细的设置说明，请参阅 /docs/providers/qdrant/setup.md[75]。
Redis
Redis[76] 是一个实时数据平台，适用于各种用例，包括日常应用程序和 AI/ML 工作负载。通过使用 Redis Stack docker container[77] 创建 Redis 数据库，可以将其用作低延迟向量引擎。另外，还提供托管/托管解决方案 Redis Cloud[78]。有关详细的设置说明，请参阅 /docs/providers/redis/setup.md[79]。
LlamaIndex
LlamaIndex[80] 是一个中央接口，用于连接您的 LLM（语言模型）与外部数据。它提供一套适用于 ChatGPT 的针对非结构化和结构化数据的内存索引套件。与标准的向量数据库不同，LlamaIndex 支持各种针对不同用例进行优化的索引策略（例如树状结构、关键词表、知识图谱）。它体积轻巧、易于使用，并且不需要额外的部署。您只需要指定几个环境变量（可选择指向现有的保存的索引 JSON 文件）。需要注意的是，查询中的元数据过滤器目前尚不支持。有关详细的设置说明，请参阅 /docs/providers/llama/setup.md[81]。
Chroma
Chroma[82] 是一个面向 AI 的开源嵌入数据库，旨在尽可能简化入门过程。Chroma 可以在内存中运行，也可以在客户端-服务器设置中运行。它原生支持元数据和关键词过滤。有关详细说明，请参阅 /docs/providers/chroma/setup.md[83]。
Azure Cognitive Search
Azure Cognitive Search[84] 是一个完整的云检索服务，支持向量搜索、文本搜索以及混合搜索（将向量和文本结合以获得两种方法的最佳结果）。它还提供了一个可选的 L2 重新排序步骤[85]，以进一步提高结果的质量。有关详细设置说明，请参阅/docs/providers/azuresearch/setup.md[86]。
Supabase
Supabase[87] 通过 pgvector[88] 扩展为 Postgres 数据库提供了一种简单高效的存储向量的方式。您可以使用 Supabase CLI[89] 在本地或云端设置完整的 Supabase 堆栈，也可以使用 docker-compose、k8s 和其他可用选项。对于托管/托管解决方案，请尝试 Supabase.com[90]，并解锁内置身份验证、存储、自动 API 和实时功能的完整 Postgres 功能。有关详细设置说明，请参阅/docs/providers/supabase/setup.md[91]。
Postgres
Postgres[92] 通过 pgvector[93] 扩展提供了一种简单高效的存储向量的方式。要使用 pgvector，您需要设置启用了 pgvector 扩展的 PostgreSQL 数据库。例如，您可以使用 docker[94] 在本地运行。对于托管/托管解决方案，您可以使用任何支持 pgvector[95] 的云供应商。有关详细设置说明，请参阅/docs/providers/postgres/setup.md[96]。
AnalyticDB
AnalyticDB[97] 是一个分布式的云原生向量数据库，专为存储文档和向量嵌入而设计。它完全兼容 PostgreSQL 语法，并由阿里巴巴云管理。AnalyticDB 提供了强大的向量计算引擎，处理数十亿个数据向量，并提供索引算法、结构化和非结构化数据功能、实时更新、距离度量、标量过滤和时间旅行搜索等功能。有关详细设置说明，请参阅/docs/providers/analyticdb/setup.md[98]。
在本地运行 API
要在本地运行 API，首先需要使用 export 命令设置必要的环境变量：
export DATASTORE=<your_datastore>
export BEARER_TOKEN=<your_bearer_token>
export OPENAI_API_KEY=<your_openai_api_key>
<Add the environment variables for your chosen vector DB here>在本地运行 API
使用以下命令启动 API：
poetry run start在终端显示的 URL 后面添加 docs，在浏览器中打开该 URL，以访问 API 文档并尝试使用端点（例如 http://0.0.0.0/docs）。确保输入您的身份验证令牌并测试 API 端点。
注意： 如果您在 pyproject.toml 文件中添加了新的依赖项，需要运行 poetry lock 和 poetry install 来更新锁定文件并安装新的依赖项。
在 ChatGPT 中测试本地主机插件
要在 ChatGPT 中测试本地主机插件，请使用提供的 local_server/main.py[99] 文件，该文件专门配置为具有 CORS 设置、无身份验证和用于清单、OpenAPI 架构和标志的路由的本地主机测试。
按照以下步骤测试您的本地主机插件：
1.使用 poetry run dev 命令运行本地主机服务器。这将在默认地址（例如 localhost:3333）启动服务器。2.访问 ChatGPT[100]，从模型选择器中选择 "Plugins"，单击插件选择器，然后在列表底部单击 "Plugin store"。3.选择 "Develop your own plugin"，并在提示时输入您的本地主机 URL（例如 localhost:3333）。4.您的本地主机插件现在已启用于 ChatGPT 会话中。
有关更多信息，请参阅 OpenAI 文档[101]。
个性化
您可以通过以下方式为您自己的用例个性化检索插件：
•替换标志: 将 logo.png[102] 中的图像替换为您自己的标志。•编辑数据模型: 编辑 models.py[103] 中的 DocumentMetadata 和 DocumentMetadataFilter 数据模型，以添加自定义元数据字段。相应地更新 openapi.yaml[104] 中的 OpenAPI 架构。为了更轻松地更新 OpenAPI 架构，您可以在本地运行应用程序，然后导航到 http://0.0.0.0/sub/openapi.json 并复制网页的内容。然后转到 Swagger Editor[105]，将 JSON 粘贴到其中以将其转换为 YAML 格式。您还可以将 .well-known[106] 文件夹中的 openapi.yaml[107] 文件替换为 openapi.json 文件。•更改插件名称、描述和使用说明: 更新模型的插件名称、用户界面描述和使用说明。您可以编辑 main.py[108] 文件中的描述，或更新 openapi.yaml[109] 文件。按照前面步骤中的相同说明来更新 OpenAPI 架构。•使 ChatGPT 能够保存对话中的信息: 参阅 memory example folder[110] 中的说明。
身份验证方法
您可以选择四种选项来对请求进行身份验证：
1.无身份验证: 任何人都可以添加您的插件并使用其 API，而无需任何凭证。如果您只公开不敏感或已公开的文档，则此选项适合您。它不会为您的数据提供安全性。如果使用此方法，请将此 main.py[111] 的内容复制到 actual main.py file[112]。示例清单在此[113]。2.HTTP Bearer: 您可以使用密钥令牌作为标头来授权对插件的请求。此选项有两个变体：•用户级别（此实现的默认设置）：将您的插件添加到 ChatGPT 的每个用户在添加插件时必须提供令牌。您可以使用任何工具或方法生成和分发这些令牌，例如 jwt.io[114]。此方法提供更好的安全性，因为每个用户都必须输入共享访问令牌。如果您需要为每个用户提供唯一访问令牌，您需要在 main.py[115] 文件中自行实现。示例清单在此[116]。•服务级别：任何人都可以添加您的插件并使用其 API，而无需凭证，但您必须在注册插件时添加一个令牌。安装插件时，您需要添加您的令牌，然后将从 ChatGPT 接收的令牌包含在托管的清单文件中。ChatGPT 将使用您的令牌代表添加插件的所有用户授权对插件的请求。这种方法对用户来说更加便利，但安全性可能较低，因为所有用户共享相同的令牌且不需要添加令牌来安装插件。示例清单在此[117]。3.OAuth: 用户必须通过 OAuth 流程添加您的插件。您可以使用 OAuth 提供程序对添加您的插件的用户进行身份验证，并授予他们访问您的 API 的权限。此方法提供了最高级别的安全性和控制性，因为用户通过受信任的第三方提供程序进行身份验证。但是，您需要在 main.py[118] 文件中自行实现 OAuth 流程，并在清单文件中提供必要的参数。示例清单在此[119]。
在选择最适合您的用例和安全需求的身份验证方法之前，请考虑每种身份验证方法的优点和缺点。如果选择与默认设置（用户级别 HTTP）不同的方法，请确保更新清单文件 在此[120]。
部署
根据您的偏好和需求，您可以将应用程序部署到不同的云提供商。但无论您选择的提供商如何，您都需要更新应用程序中的两个文件：openapi.yaml[121] 和 ai-plugin.json[122]。如上所述，这些文件分别定义了应用程序的 API 规范和 AI 插件配置。您需要在这两个文件中的 url 字段中更改为与您部署的应用程序的地址相匹配。
Render 提供了一键部署选项，可以自动更新这两个文件中的 url 字段[123]
在部署应用程序之前，您可能希望从 pyproject.toml[124] 文件中删除未使用的依赖项，以减小应用程序的大小并提高性能。根据您选择的向量数据库提供商，您可以删除对特定提供商不需要的软件包。有关为每个提供商删除未使用依赖项的详细信息，请参阅 /docs/deployment/removing-unused-dependencies.md[125] 文件中的相应文档。
部署说明：
•部署到 Fly.io[126]•部署到 Heroku[127]•部署到 Render[128]•其他部署选项[129]（Azure 容器应用程序，Google Cloud Run，AWS 弹性容器服务等）
一旦您部署了应用程序，请考虑使用其中一个脚本[130]或调用 /upsert 端点上传初始批量文档。
安装开发者插件
要安装开发者插件，请按照以下步骤进行操作：
•首先，通过将开发者插件部署到您首选的托管平台（例如 Fly.io、Heroku 等）并更新插件 URL 在清单文件和 OpenAPI schema 中。•前往 ChatGPT[131] 并从模型选择器中选择 "Plugins"。•从插件选择器中，滚动到底部并点击 "Plugin store"。•进入 "Develop your own plugin" 并按照提供的说明进行操作。您需要输入部署插件的域名。•根据您为插件选择的身份验证类型（例如，如果插件使用 Service Level HTTP，则需要粘贴您的访问令牌，然后将插件流程中收到的新访问令牌粘贴到您的 ai-plugin.json[132] 文件中并重新部署您的应用程序）。•接下来，您需要添加您的插件。再次前往 "Plugin store"，然后点击 "Install an unverified plugin"。•按照提供的说明进行操作，这将要求您输入部署插件的域名。•根据您为插件选择的身份验证类型（例如，如果插件使用 User Level HTTP，则需要粘贴您的 Bearer Token）。
完成这些步骤后，您的开发者插件应该已安装并可以在 ChatGPT 中使用。
Webhooks
为了保持存储在向量数据库中的文档的实时性，您可以考虑使用工具如 Zapier[133] 或 Make[134] 来配置基于事件或计划的入站 Webhooks 到您的插件的 API。例如，这可以允许您在更新笔记或接收电子邮件时同步新信息。您还可以使用 Zapier Transfer[135] 批量处理一组现有文档，并将它们上传到向量数据库中。
如果您需要将这些工具中的自定义字段传递给您的插件，您可能需要创建一个额外的 Retrieval Plugin API 端点来调用数据存储的 upsert 函数，例如 upsert-email。这个自定义端点可以被设计为接受 Webhook 中的特定字段，并相应地处理它们。
要设置入站 Webhook，请按照以下一般步骤进行操作：
•选择像 Zapier 或 Make 这样的 Webhook 工具，并创建一个帐户。•在工具中设置一个新的 Webhook 或 Transfer，并根据事件或计划进行配置。•指定 Webhook 的目标 URL，该 URL 应该是您的检索插件的 API 端点（例如 https://your-plugin-url.com/upsert）。•配置 Webhook payload，以包含所需的数据字段，并根据您的检索插件的 API 要求进行格式化。•测试 Webhook，确保它能正确工作，并将数据按预期发送到您的检索插件。
设置完 Webhook 后，您可能需要运行一个回溯操作，以确保任何之前遗漏的数据都包含在向量数据库中。
请记住，如果您想使用入站 Webhooks 来连续同步数据，您应该在设置完毕后运行一个回溯操作，以避免遗漏任何数据。
除了使用像 Zapier 和 Make 这样的工具之外，您还可以构建自己的定制集成来与您的检索插件同步数据。这样可以让您更好地控制数据流，并根据您的具体需求和要求定制集成。
脚本
scripts 文件夹包含了批量插入或处理来自不同数据源（如 zip 文件、JSON 文件或 JSONL 文件）的文本文档的脚本。这些脚本使用插件的 upsert 实用函数将文档及其元数据上传到向量数据库，首先将它们转换为纯文本并拆分成块。每个脚本文件夹都有一个 README 文件，解释了如何使用它以及它所需的参数。您还可以选择使用语言模型对文档进行个人身份信息（PII）筛查，如果检测到 PII，则跳过这些文档，使用 services.pii_detection[136] 模块。如果您想避免意外将敏感或私人文档上传到向量数据库中，这可能会有所帮助。此外，您还可以选择使用语言模型从文档文本中提取元数据，使用 services.extract_metadata[137] 模块。如果您想丰富文档的元数据，这可能会有用。注意：如果您想使用入站 Webhooks 来连续同步数据，请在设置后运行回溯操作，以避免遗漏任何数据。
这些脚本包括：
•process_json[138]：此脚本处理以 JSON 格式存储的文档文件，并将其与一些元数据一起存储到向量数据库中。JSON 文件的格式应该是一个 JSON 对象列表，其中每个对象代表一个文档。JSON 对象应该有一个 text 字段，以及其他可选字段来填充元数据。您可以提供自定义元数据作为 JSON 字符串，以及用于筛查 PII 和提取元数据的标志。•process_jsonl[139]：此脚本处理以 JSONL 格式存储的文档文件，并将其与一些元数据一起存储到向量数据库中。JSONL 文件的格式应该是一个逐行分隔的 JSON 文件，其中每行是一个有效的 JSON 对象，表示一个文档。JSON 对象应该有一个 text 字段，以及其他可选字段来填充元数据。您可以提供自定义元数据作为 JSON 字符串，以及用于筛查 PII 和提取元数据的标志。•process_zip[140]：此脚本处理存储在 zip 文件中的文档文件，并将其与一些元数据一起存储到向量数据库中。zip 文件的格式应该是一个扁平的 zip 文件夹，包含 docx、pdf、txt、md、pptx 或 csv 文件。您可以提供自定义元数据作为 JSON 字符串，以及用于筛查 PII 和提取元数据的标志。
Pull Request（PR）检查清单
如果您想要贡继续以下是Pull Request（PR）的检查清单，请按照以下步骤提交PR，这将有助于我们更快地审核和合并您的更改！感谢您的贡献！
1.PR类型：在标题开头加上方括号内的标签，指示PR的类型，例如[修复错误]，[功能]，[增强]，[重构]或[文档]。2.简短描述：提供一个简洁明了的PR描述，解释所做的更改。3.关联的问题：使用关键字Fixes或Closes后跟相关问题的编号（例如Fixes #123，Closes #456）提及任何相关的问题。4.分支：确保您为更改创建了一个新的分支，并且该分支基于最新的main分支。5.代码更改：确保代码更改是最小的、集中的，并与正在解决的问题或功能相关。6.提交消息：编写清晰简明的提交消息，解释每个提交的目的。7.测试：对于任何新代码或对现有代码的更改，请包含单元测试和/或集成测试。在提交PR之前确保所有测试都通过。8.文档：更新相关文档（如README、内部注释或外部文档），以反映所做的任何更改。9.请求审核：从至少一个其他贡献者或存储库的维护者那里请求审核。10.视频提交（对于复杂/大型的PR）：如果您的PR引入了重大更改、复杂性或大量代码行，请随PR一起提交一个简短的视频演示。该视频应该解释更改的目的、背后的逻辑以及它们如何解决问题或添加所建议的功能。这将帮助审核者更好地理解您的贡献并加快审核过程。
Pull Request 命名约定
请使用以下命名约定命名您的PR分支：
<type>/<short-description>-<issue-number>•<type>: PR的类型，例如bugfix，feature，enhancement，refactor或docs。多个类型可以使用逗号分隔，并且应该显示为<type>，<type2>。•<short-description>: 对所做更改的简要描述，使用连字符分隔单词。•<issue-number>: 与所做更改相关联的问题编号（如果适用）。
示例：
feature/advanced-chunking-strategy-123限制
尽管 ChatGPT 检索插件旨在提供灵活的语义搜索和检索解决方案，但它确实有一些限制：
•关键词搜索限制：text-embedding-ada-002 模型生成的嵌入向量可能无法有效捕捉精确的关键词匹配。因此，对于依赖于特定关键词的查询，插件可能无法返回最相关的结果。一些向量数据库（如 Pinecone、Weaviate 和 Azure Cognitive Search）使用混合搜索，并且在关键词搜索方面可能表现更好。•敏感数据处理：插件不会自动检测或过滤敏感数据。开发人员有责任确保他们有必要的授权将内容包含在检索插件中，并且内容符合数据隐私要求。•可扩展性：插件的性能可能因所选择的向量数据库提供商和数据集的大小而异。某些提供商可能比其他提供商提供更好的可扩展性和性能。•语言支持：插件当前使用的是 OpenAI 的 text-embedding-ada-002 模型，该模型针对英语进行了优化。但是，它仍然足够强大，可以为各种语言生成良好的结果。•元数据提取：可选的元数据提取功能依赖于语言模型从文档文本中提取信息。该过程可能不总是准确的，并且提取的元数据质量可能取决于文档内容和结构。•PII 检测：可选的个人身份信息（PII）检测功能不是百分之百可靠，可能无法捕捉所有个人身份信息的实例。请谨慎使用此功能，并验证其对于您特定的用例是否有效。
未来发展方向
ChatGPT 检索插件提供了一种灵活的语义搜索和检索解决方案，但始终存在进一步发展的潜力。我们鼓励用户通过提交新功能或增强功能的拉取请求来为项目做出贡献。值得注意的贡献可能会获得 OpenAI 的认可。
一些未来发展方向的想法包括：
•更多的向量数据库提供商：如果您有兴趣将另一个向量数据库提供商集成到 ChatGPT 检索插件中，请随时提交实现。•附加脚本：扩展可用于处理和上传来自各种数据源的文档的脚本范围，将使插件更加多功能。•用户界面：开发一个用户界面，用于管理文档和与插件交互，可以改善用户体验。•混合搜索/TF-IDF 选项：通过增强 数据存储的 upsert 函数[141]，以使用混合搜索或 TF-IDF 索引的选项，可以提高插件对基于关键字的查询的性能。•高级分块策略和嵌入计算：实现更复杂的分块策略和嵌入计算，例如对文档标题和摘要进行嵌入、对文档分块和摘要进行加权平均，或计算文档的平均嵌入，可能会导致更好的搜索结果。•自定义元数据：允许用户将自定义元数据添加到文档分块中，例如标题或其他相关信息，可能会在某些用例中改善检索结果。•附加的可选服务：集成更多的可选服务，例如对文档进行摘要或在嵌入之前对文档进行预处理，可以增强插件的功能和检索结果的质量。这些服务可以使用语言模型实现，并直接集成到插件中，而不仅仅在脚本中提供。
我们欢迎社区的贡献，以帮助改进 ChatGPT 检索插件并扩展其功能。如果您有想法或功能要贡献，请通过拉取请求提交到存储库中。
贡献者
我们要对以下贡献者对 ChatGPT 检索插件的代码/文档贡献以及在集成各种向量数据库提供商方面的支持表示感谢：
•Pinecone[142]•acatav[143]•gkogan[144]•jamescalam[145]•Weaviate[146]•byronvoorbach[147]•hsm207[148]•sebawita[149]•Zilliz[150]•filip-halt[151]•Milvus[152]•filip-halt[153]•Qdrant[154]•kacperlukawski[155]•Redis[156]•spartee[157]•tylerhutcherson[158]•LlamaIndex[159]•jerryjliu[160]•Disiok[161]•Supabase[162]•egor-romanov[163]•Postgres[164]•egor-romanov[165]•mmmaia[166]声明
本文是对openai官方插件示例文档翻译整理而来，供大家技术学习使用，其github地址为：https://github.com/openai/chatgpt-retrieval-plugin，喜欢的同学请点赞、收藏。
References
[1] ChatGPT 插件等待名单: https://openai.com/waitlist/plugins
[2] 此处: https://cdn.openai.com/chat-plugins/retrieval-gh-repo-readme/Retrieval-Final.mp4
[3] datastore: /datastore
[4] docs: /docs
[5] examples: /examples
[6] local_server: /local_server
[7] models: /models
[8] scripts: /scripts
[9] server: /server
[10] services: /services
[11] tests: /tests
[12] .well-known: /.well-known
[13] 快速开始: #快速开始
[14] 关于: #关于
[15] 插件: #插件
[16] 检索插件: #检索插件
[17] 记忆功能: #记忆功能
[18] 安全性: #安全性
[19] API 端点: #API端点
[20] 开发: #开发
[21] 设置: #设置
[22] 通用环境变量: #通用环境变量
[23] 选择向量数据库: #选择向量数据库
[24] Pinecone: #Pinecone
[25] Weaviate: #Weaviate
[26] Zilliz: #Zilliz
[27] Milvus: #Milvus
[28] Qdrant: #Qdrant
[29] Redis: #Redis
[30] Llama Index: #Llama-Index
[31] Chroma: #Chroma
[32] Azure Cognitive Search: #Azure-Cognitive-Search
[33] Supabase: #Supabase
[34] Postgres: #Postgres
[35] AnalyticDB: #AnalyticDB
[36] 在本地运行 API: #在本地运行-API
[37] 在 ChatGPT 中测试本地主机插件: #在-ChatGPT-中测试本地主机插件
[38] 个性化: #个性化
[39] 身份验证方法: #身份验证方法
[40] 部署: #部署
[41] 安装开发者插件: #安装开发者插件
[42] Webhooks: #Webhooks
[43] 脚本: #脚本
[44] 限制: #限制
[45] 贡献者: #贡献者
[46] 未来方向: #未来方向
[47] bearer token: #通用环境变量
[48] 在 ChatGPT 中测试本地主机插件: #在-ChatGPT-中测试本地主机插件
[49] 这里: https://openai.com/blog/chatgpt-plugins
[50] 这里: https://platform.openai.com/docs/plugins/introduction
[51] Zapier: https://zapier.com
[52] Make: https://www.make.com
[53] here: #authentication-methods
[54] 链接: https://fastapi.tiangolo.com/
[55] 链接: /.well-known/openapi.yaml
[56] 此处: /examples/memory
[57] 此处: /models/models.py
[58] 此处: /.well-known/openapi.yaml
[59] Swagger Editor: https://editor.swagger.io/
[60] poetry: https://python-poetry.org/
[61] Python 网站: https://www.python.org/downloads/
[62] jwt.io: https://jwt.io/
[63] OpenAI: https://openai.com/
[64] 此处的文件夹: /docs/providers
[65] Pinecone: https://www.pinecone.io
[66] /docs/providers/pinecone/setup.md: /docs/providers/pinecone/setup.md
[67] Weaviate: https://weaviate.io/
[68] /docs/providers/weaviate/setup.md: /docs/providers/weaviate/setup.md
[69] Zilliz: https://zilliz.com
[70] /docs/providers/zilliz/setup.md: /docs/providers/zilliz/setup.md
[71] Milvus: https://milvus.io/
[72] /docs/providers/milvus/setup.md: /docs/providers/milvus/setup.md
[73] Qdrant: https://qdrant.tech/
[74] Qdrant Cloud: https://cloud.qdrant.io/
[75] /docs/providers/qdrant/setup.md: /docs/providers/qdrant/setup.md
[76] Redis: https://redis.com/solutions/use-cases/vector-database/
[77] Redis Stack docker container: /examples/docker/redis/docker-compose.yml
[78] Redis Cloud: https://app.redislabs.com/#/
[79] /docs/providers/redis/setup.md: /docs/providers/redis/setup.md
[80] LlamaIndex: https://github.com/jerryjliu/llama_index
[81] /docs/providers/llama/setup.md: /docs/providers/llama/setup.md
[82] Chroma: https://trychroma.com
[83] /docs/providers/chroma/setup.md: /docs/providers/chroma/setup.md
[84] Azure Cognitive Search: https://azure.microsoft.com/products/search/
[85] 可选的 L2 重新排序步骤: https://learn.microsoft.com/azure/search/semantic-search-overview
[86] /docs/providers/azuresearch/setup.md: /docs/providers/azuresearch/setup.md
[87] Supabase: https://supabase.com/blog/openai-embeddings-postgres-vector
[88] pgvector: https://github.com/pgvector/pgvector
[89] Supabase CLI: https://github.com/supabase/cli
[90] Supabase.com: https://supabase.com/
[91] /docs/providers/supabase/setup.md: /docs/providers/supabase/setup.md
[92] Postgres: https://www.postgresql.org
[93] pgvector: https://github.com/pgvector/pgvector
[94] 使用 docker: https://www.docker.com/blog/how-to-use-the-postgres-docker-official-image/
[95] pgvector: https://github.com/pgvector/pgvector#hosted-postgres
[96] /docs/providers/postgres/setup.md: /docs/providers/postgres/setup.md
[97] AnalyticDB: https://www.alibabacloud.com/help/en/analyticdb-for-postgresql/latest/product-introduction-overview
[98] /docs/providers/analyticdb/setup.md: /docs/providers/analyticdb/setup.md
[99] local_server/main.py: /local_server/main.py
[100] ChatGPT: https://chat.openai.com/
[101] OpenAI 文档: https://platform.openai.com/docs/plugins/getting-started/openapi-definition
[102] logo.png: /.well-known/logo.png
[103] models.py: /models/models.py
[104] openapi.yaml: /.well-known/openapi.yaml
[105] Swagger Editor: https://editor.swagger.io/
[106] .well-known: /.well-known
[107] openapi.yaml: /.well-known/openapi.yaml
[108] main.py: /server/main.py
[109] openapi.yaml: /.well-known/openapi.yaml
[110] memory example folder: /examples/memory
[111] main.py: /examples/authentication-methods/no-auth/main.py
[112] actual main.py file: /server/main.py
[113] 在此: /examples/authentication-methods/no-auth/ai-plugin.json
[114] jwt.io: https://jwt.io/
[115] main.py: /server/main.py
[116] 在此: /examples/authentication-methods/user-http/ai-plugin.json
[117] 在此: /examples/authentication-methods/service-http/ai-plugin.json
[118] main.py: /server/main.py
[119] 在此: /examples/authentication-methods/oauth/ai-plugin.json
[120] 在此: /.well-known/ai-plugin.json
[121] openapi.yaml: /.well-known/openapi.yaml
[122] ai-plugin.json: /.well-known/ai-plugin.json
[123] : https://render.com/deploy?repo=https://github.com/render-examples/chatgpt-retrieval-plugin/tree/main
[124] pyproject.toml: /pyproject.toml
[125] /docs/deployment/removing-unused-dependencies.md: /docs/deployment/removing-unused-dependencies.md
[126] 部署到 Fly.io: /docs/deployment/flyio.md
[127] 部署到 Heroku: /docs/deployment/heroku.md
[128] 部署到 Render: /docs/deployment/render.md
[129] 其他部署选项: /docs/deployment/other-options.md
[130] 脚本: /scripts
[131] ChatGPT: https://chat.openai.com/
[132] ai-plugin.json: /.well-known/ai-plugin.json
[133] Zapier: https://zapier.com
[134] Make: https://www.make.com
[135] Zapier Transfer: https://zapier.com/blog/zapier-transfer-guide/
[136] services.pii_detection: /services/pii_detection.py
[137] services.extract_metadata: /services/extract_metadata.py
[138] process_json: scripts/process_json/
[139] process_jsonl: scripts/process_jsonl/
[140] process_zip: scripts/process_zip/
[141] 数据存储的 upsert 函数: /datastore/datastore.py#L18
[142] Pinecone: https://www.pinecone.io/
[143] acatav: https://github.com/acatav
[144] gkogan: https://github.com/gkogan
[145] jamescalam: https://github.com/jamescalam
[146] Weaviate: https://www.semi.technology/
[147] byronvoorbach: https://github.com/byronvoorbach
[148] hsm207: https://github.com/hsm207
[149] sebawita: https://github.com/sebawita
[150] Zilliz: https://zilliz.com/
[151] filip-halt: https://github.com/filip-halt
[152] Milvus: https://milvus.io/
[153] filip-halt: https://github.com/filip-halt
[154] Qdrant: https://qdrant.tech/
[155] kacperlukawski: https://github.com/kacperlukawski
[156] Redis: https://redis.io/
[157] spartee: https://github.com/spartee
[158] tylerhutcherson: https://github.com/tylerhutcherson
[159] LlamaIndex: https://github.com/jerryjliu/llama_index
[160] jerryjliu: https://github.com/jerryjliu
[161] Disiok: https://github.com/Disiok
[162] Supabase: https://supabase.com/
[163] egor-romanov: https://github.com/egor-romanov
[164] Postgres: https://www.postgresql.org/
[165] egor-romanov: https://github.com/egor-romanov
[166] mmmaia: https://github.com/mmmaia
