ChatGPT 检索插件

使用检索插件后端构建自定义 GPT，使 ChatGPT 能够访问个人文档。

简介

ChatGPT 检索插件仓库提供了一种灵活的解决方案，用于通过自然语言查询对个人或组织文档进行语义搜索和检索。它是一个独立的检索后端，可以与 ChatGPT 自定义 GPT、使用 聊天补全 或 助手 API 的 函数调用，或者与 ChatGPT 插件模型（已弃用） 一起使用。ChatGPT 和助手 API 都原生支持从上传的文件中进行检索，因此只有在您希望对检索系统有更细粒度的控制时（例如文档文本分块长度、嵌入模型/大小等），才应将检索插件用作后端。

该仓库被组织成多个目录：

目录	描述
datastore	包含使用各种向量数据库提供商存储和查询文档嵌入的核心逻辑。
docs	包括设置和使用每个向量数据库提供商、Webhook 以及移除未使用的依赖项的文档。
examples	提供示例配置、身份验证方法和特定于提供商的示例。
local_server	包含为本地测试配置的检索插件实现。
models	包含插件使用的数据模型，例如文档和元数据模型。
scripts	提供用于处理和上传来自不同数据源的文档的脚本。
server	承载主要的 FastAPI 服务器实现。
services	包含用于分块、元数据提取和 PII 检测等任务的实用服务。
tests	包括针对各种向量数据库提供商的集成测试。
.well-known	存储插件清单文件和 OpenAPI 模式，它们定义了插件配置和 API 规范。

本 README 提供了有关如何设置、开发和部署 ChatGPT 检索插件（独立检索后端）的详细信息。

目录

• 快速入门
• 简介
  • 检索插件
  • 与自定义 GPT 结合的检索插件
  • 与函数调用结合的检索插件
  • 与插件模型结合的检索插件（已弃用）
  • API 端点
  • 记忆功能
  • 安全性
  • 选择嵌入模型
• 开发
  • 设置
    • 通用环境变量
  • 选择向量数据库
    • Pinecone
    • Elasticsearch
    • MongoDB Atlas
    • Weaviate
    • Zilliz
    • Milvus
    • Qdrant
    • Redis
    • Llama Index
    • Chroma
    • Azure 认知搜索
    • Azure CosmosDB Mongo vCore
    • Supabase
    • Postgres
    • AnalyticDB
  • 在本地运行 API
  • 个性化
  • 身份验证方法
• 部署
• Webhooks
• 脚本
• 限制
• 贡献者
• 未来方向

快速入门

按照以下步骤快速设置并运行 ChatGPT 检索插件：

1. 如果尚未安装，请先安装 Python 3.10。

2. 克隆仓库：git clone https://github.com/openai/chatgpt-retrieval-plugin.git

3. 进入克隆后的仓库目录：cd /path/to/chatgpt-retrieval-plugin

4. 安装 Poetry：pip install poetry

5. 使用 Python 3.10 创建一个新的虚拟环境：poetry env use python3.10

6. 激活虚拟环境：poetry shell

7. 安装应用依赖：poetry install

8. 创建一个 Bearer 令牌。

9. 设置所需的环境变量：

   export DATASTORE=<your_datastore>
   export BEARER_TOKEN=<your_bearer_token>
   export OPENAI_API_KEY=<your_openai_api_key>
   export EMBEDDING_DIMENSION=256 # 根据您想要使用的嵌入维度调整此值
   export EMBEDDING_MODEL=text-embedding-3-large # 根据您的模型偏好进行修改，例如 text-embedding-3-small、text-embedding-ada-002
   
   # 在使用 Azure OpenAI 时可选的环境变量
   export OPENAI_API_BASE=https://<AzureOpenAIName>.openai.azure.com/
   export OPENAI_API_TYPE=azure
   export OPENAI_EMBEDDINGMODEL_DEPLOYMENTID=<嵌入模型部署名称>
   export OPENAI_METADATA_EXTRACTIONMODEL_DEPLOYMENTID=<元数据提取模型部署名称>
   export OPENAI_COMPLETIONMODEL_DEPLOYMENTID=<用于完成任务的通用模型部署名称>
   export OPENAI_EMBEDDING_BATCH_SIZE=<嵌入批处理大小，对于 Azure OpenAI，此值需设置为 1>
   
   # 添加您所选择向量数据库的环境变量。
   # 其中一些是可选的；请参阅 /docs/providers 中的提供商设置文档以获取更多信息。
   
   # 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=<保存索引的 JSON 文件路径>
   export LLAMA_QUERY_KWARGS_JSON_PATH=<保存查询参数的 JSON 文件路径>
   export LLAMA_RESPONSE_MODE=<查询响应模式>
   
   # Chroma
   export CHROMA_COLLECTION=<your_chroma_collection>
   export CHROMA_IN_MEMORY=<true_or_false>
   export CHROMA_PERSISTENCE_DIR=<您的 Chroma 持久化目录>
   export CHROMA_HOST=<您的 Chroma 主机>
   export CHROMA_PORT=<您的 Chroma 端口>
   
   # Azure Cognitive Search
   export AZURESEARCH_SERVICE=<您的搜索服务名称>
   export AZURESEARCH_INDEX=<您的搜索索引名称>
   export AZURESEARCH_API_KEY=<您的 API 密钥>（可选，未设置时将使用无密钥托管身份验证）
   
   # Azure CosmosDB Mongo vCore
   export AZCOSMOS_API = <您的 Azure Cosmos DB API，目前仅支持 MongoDB>
   export AZCOSMOS_CONNSTR = <您的 Azure Cosmos DB MongoDB vCore 连接字符串>
   export AZCOSMOS_DATABASE_NAME = <您的 MongoDB 数据库名称>
   export AZCOSMOS_CONTAINER_NAME = <您的 MongoDB 容器名称>
   
   # 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_DB=<postgres_database>
   
   # Elasticsearch
   export ELASTICSEARCH_URL=<elasticsearch_host_and_port>（可以指定主机或 cloud_id）
   export ELASTICSEARCH_CLOUD_ID=<elasticsearch_cloud_id>
   
   export ELASTICSEARCH_USERNAME=<elasticsearch_username>
   export ELASTICSEARCH_PASSWORD=<elasticsearch_password>
   export ELASTICSEARCH_API_KEY=<elasticsearch_api_key>
   
   export ELASTICSEARCH_INDEX=<elasticsearch_index_name>
   export ELASTICSEARCH_REPLICAS=<elasticsearch_replicas>
   export ELASTICSEARCH_SHARDS=<elasticsearch_shards>
   
   # MongoDB Atlas
   export MONGODB_URI=<mongodb_uri>
   export MONGODB_DATABASE=<mongodb_database>
   export MONGODB_COLLECTION=<mongodb_collection>
   export MONGODB_INDEX=<mongodb_index>
   

10. 在本地运行 API：poetry run start

11. 访问 API 文档页面 http://0.0.0.0:8000/docs 并测试 API 端点（请确保添加您的 Bearer 令牌）。

关于

检索插件

这是一个独立的检索后端，可与 ChatGPT 自定义 GPT、使用 聊天补全 或 助手 API 的 函数调用，或与 已弃用的 ChatGPT 插件模型 一起使用。它使模型能够执行语义搜索和检索个人或组织文档，并根据相关检索到的内容撰写答案（有时称为“检索增强生成”或“RAG”）。用户只需用自然语言提问或表达需求，即可从其数据源中获取最相关的文档片段，例如文件、笔记或电子邮件。企业可以利用此插件，通过 ChatGPT 向员工开放内部文档。

该插件使用 OpenAI 的嵌入模型（默认为 text-embedding-3-large 的 256 维嵌入）为文档块生成嵌入向量，并在后端使用向量数据库进行存储和查询。作为一款开源且可自托管的解决方案，开发者可以部署自己的检索插件并将其注册到 ChatGPT 中。检索插件支持多家向量数据库提供商，开发者可从中选择自己偏好的服务。

一个 FastAPI 服务器公开了插件的端点，用于插入/更新、查询和删除文档。用户可以通过来源、日期、作者或其他元数据过滤器来优化搜索结果。该插件可以部署在任何支持 Docker 容器的云平台上，例如 Fly.io、Heroku、Render 或 Azure 容器应用。为了使向量数据库始终包含最新文档，插件可以持续处理并存储来自各种数据源的文档，借助针对插入/更新和删除端点的 Webhook 实现。像 Zapier 或 Make 这样的工具可以帮助基于事件或计划配置这些 Webhook。

检索插件与自定义 GPT

要创建一个能够使用您的检索插件进行语义搜索和文档检索，甚至将新信息保存回数据库的自定义 GPT，您首先需要部署好检索插件。有关详细部署步骤，请参阅部署部分。当您获得应用 URL（例如 https://your-app-url.com）后，按照以下步骤操作：

1. 访问 https://chat.openai.com/gpts/editor 的创建 GPT 页面。
2. 按照标准流程设置您的 GPT。
3. 切换到“配置”选项卡。在此处，您可以手动填写名称、描述和指令等字段，或使用智能创建工具辅助完成。
4. 在“操作”部分，点击“创建新操作”。
5. 选择身份验证方式。检索插件支持无身份验证、API 密钥（Basic 或 Bearer）以及 OAuth。有关这些方法的更多信息，请参阅身份验证方法部分。
6. 导入 OpenAPI 规范。您可以：
   • 直接从应用中托管的 OpenAPI 规范导入，地址为 https://your-app-url.com/.well-known/openapi.yaml。
   • 如果您只想向 GPT 公开查询端点，也可以将此文件的内容复制并粘贴到 Schema 输入区域。请务必修改粘贴的 OpenAPI 规范中 -servers 部分的 URL。
7. 您还可以选择添加一个获取端点。这需要编辑 /server/main.py 文件以添加端点，并针对您选择的向量数据库实现该功能。如果您做出此更改，请考虑通过提交拉取请求将其贡献回项目！将获取端点添加到 OpenAPI 规范中，可以让模型根据 ID 从文档中获取更多内容，从而解决检索结果中文本被截断的问题。此外，您还可以传入检索结果中的文本字符串，并提供返回固定长度上下文的选项。
8. 如果您希望 GPT 能够将信息保存回向量数据库，可以为其授予访问检索插件 /upsert 端点的权限。为此，您可以将此文件的内容复制到 Schema 区域。这样，GPT 就可以在对话过程中存储其生成或学到的新信息。有关此功能的更多详情，请参阅记忆功能以及此处的文档。

请注意：ChatGPT 和自定义 GPT 原生支持从上传的文件中检索内容，因此只有在您希望对检索系统拥有更细粒度的控制时（例如自托管、嵌入块长度、嵌入模型/尺寸等），才应将检索插件用作后端。

带有函数调用的检索插件

检索插件可以与 Chat Completions API 和 Assistants API 中的函数调用功能集成。这使得模型能够根据对话上下文决定何时使用您的函数（查询、获取、插入或更新）。

使用 Chat Completions 进行函数调用

在调用聊天完成 API 时，您可以描述函数，并让模型生成一个包含参数的 JSON 对象，以调用一个或多个函数。最新的模型（gpt-3.5-turbo-0125 和 gpt-4-turbo-preview）经过训练，能够检测何时应调用函数，并返回符合函数签名的 JSON 数据。

您可以为检索插件端点定义函数，并在使用最新模型之一的 Chat Completions API 时将其作为工具传递进去。随后，模型将智能地调用这些函数。您可以通过函数调用来向您的 API 发送查询，在后端调用相应端点，并将响应作为工具消息返回给模型，以便继续对话。函数定义/模式以及示例可以在此处找到：这里。

使用 Assistants API 进行函数调用

您可以将相同的函数定义用于 OpenAI 的 Assistants API，特别是其中的 工具使用中的函数调用。Assistants API 允许您在自己的应用程序中构建 AI 助手，利用模型、工具和知识来响应用户查询。函数定义/模式以及示例可以在此处找到：这里。Assistants API 原生支持从上传的文件中进行检索，因此只有在您希望对检索系统进行更细粒度的控制时（例如嵌入块长度、嵌入模型/大小等），才应结合函数调用使用检索插件。

Chat Completions API 和 Assistants API 都支持并行函数调用。这意味着您可以在同一条消息中执行多项任务，例如查询某些内容并将结果保存回向量数据库。

有关使用检索插件进行函数调用的更多信息，请参阅此处。

ChatGPT 插件模型

（已弃用）我们建议使用 GPTs 的自定义操作，通过 ChatGPT 来使用检索插件。有关如何在已弃用的插件模型中使用检索功能的说明可以在此处找到：这里。

API 终端点

检索插件基于 FastAPI 构建，FastAPI 是一个用于使用 Python 构建 API 的 Web 框架。FastAPI 能够轻松地开发、验证和记录 API 终端点。您可以在 这里 找到 FastAPI 的文档。

使用 FastAPI 的一大优势是能够自动生成带有 Swagger UI 的交互式 API 文档。当 API 在本地运行时，可以通过 <local_host_url，例如 http://0.0.0.0:8000>/docs 访问 Swagger UI，与 API 终端点进行交互、测试其功能，并查看预期的请求和响应模型。

该插件公开了以下终端点，用于向向量数据库中插入或更新文档、查询文档以及删除文档。所有请求和响应均采用 JSON 格式，并且需要在授权头中提供有效的 Bearer 令牌。

• /upsert: 此终端点允许上传一个或多个文档，并将其文本和元数据存储在向量数据库中。文档会被分割成每个约 200 个标记的块，每个块都有唯一的 ID。该终端点在请求体中期望接收一个文档列表，每个文档包含 text 字段，以及可选的 id 和 metadata 字段。metadata 字段可以包含以下可选子字段：source、source_id、url、created_at 和 author。该终端点会返回已插入文档的 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:8000/openapi.json 查看，或者在 OpenAPI 模式的 这里 查阅。请注意，OpenAPI 模式仅包含 /query 终端点，因为这是 ChatGPT 需要访问的唯一功能。这样，ChatGPT 就只能使用该插件根据自然语言查询或需求检索相关文档。然而，如果开发者希望让 ChatGPT 具备稍后记住内容的能力，也可以使用 /upsert 终端点将对话片段保存到向量数据库中。一个赋予 ChatGPT /upsert 终端点访问权限的清单和 OpenAPI 模式示例可以在 这里 找到。

如需添加自定义元数据字段，请编辑 这里 的 DocumentMetadata 和 DocumentMetadataFilter 数据模型，并更新 这里 的 OpenAPI 模式。您可以轻松完成此操作：在本地运行应用程序，复制 http://0.0.0.0:8000/sub/openapi.json 中的 JSON 内容，并使用 Swagger Editor 将其转换为 YAML 格式。或者，您也可以用 openapi.json 文件替换 openapi.yaml 文件。

记忆功能

检索插件的一个显著特性是它能够为 ChatGPT 提供记忆功能。通过使用插件的 upsert 终端点，ChatGPT 可以在用户提示下将对话片段保存到向量数据库中，以便日后参考。此功能有助于实现更具上下文感知的聊天体验，使 ChatGPT 能够记住并检索之前对话中的信息。请参阅 这里 了解如何配置具备记忆功能的检索插件。

安全性

检索插件允许 ChatGPT 搜索内容向量数据库，并将最佳结果添加到 ChatGPT 会话中。这意味着它不会产生任何外部影响，主要的风险考虑因素是数据授权和隐私。开发者应仅将获得授权且愿意出现在用户 ChatGPT 会话中的内容添加到他们的检索插件中。您可以选择多种不同的身份验证方法来保护插件的安全性（更多信息请参阅 [身份验证方法]）。

选择嵌入模型

ChatGPT 检索插件使用 OpenAI 的嵌入模型来生成文档块的嵌入向量。检索插件的默认模型是 text-embedding-3-large，维度为 256。OpenAI 提供了两个最新的嵌入模型 text-embedding-3-small 和 text-embedding-3-large，以及一个较旧的模型 text-embedding-ada-002。

新模型支持在不显著降低检索准确率的情况下缩短嵌入向量的长度，从而帮助您在检索准确率、成本和速度之间取得平衡。

以下是各模型的对比：

模型	嵌入大小	平均 MTEB 分数	每 1k 个 token 的成本
text-embedding-3-large	3072	64.6%	$0.00013
text-embedding-3-large	1024	64.1%	$0.00013
text-embedding-3-large	256	62.0%	$0.00013
text-embedding-3-small	1536	62.3%	$0.00002
text-embedding-3-small	512	61.6%	$0.00002
text-embedding-ada-002	1536	61.0%	$0.0001

在选择模型时，请考虑以下几点：

1. 检索准确率与成本：text-embedding-3-large 提供最高的准确率，但成本也较高。text-embedding-3-small 在保持竞争力的同时更具成本效益。而较旧的 text-embedding-ada-002 模型则具有最低的准确率。

2. 嵌入大小：较大的嵌入向量能提供更好的准确率，但会占用更多存储空间，并且查询速度可能较慢。您可以调整嵌入向量的大小以平衡这些因素。

例如，如果您的向量数据库最多支持 1024 维，则可以使用 text-embedding-3-large 并将 API 参数中的维度设置为 1024。这样可以将嵌入向量从 3072 维缩短至 1024 维，虽然会损失部分准确率，但可以降低存储和查询成本。

要更改您选择的嵌入模型及其维度，请编辑以下环境变量：

EMBEDDING_DIMENSION=256 # 根据您希望使用的嵌入维度修改此值
EMBEDDING_MODEL="text-embedding-3-large" # 根据您希望使用的模型修改此值，例如 text-embedding-3-small、text-embedding-ada-002

开发

设置

本应用使用 Python 3.10，并通过 poetry 进行依赖管理。

如果您的机器上尚未安装 Python 3.10，请先进行安装。您可以从官方 Python 网站 下载，或使用包管理器（如 brew 或 apt）进行安装。

从 GitHub 克隆仓库：

git clone https://github.com/openai/chatgpt-retrieval-plugin.git

进入克隆后的仓库目录：

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	是	指定您希望用于存储和查询嵌入向量的向量数据库提供商。可选值包括 elasticsearch、chroma、pinecone、weaviate、zilliz、milvus、qdrant、redis、azuresearch、supabase、postgres、analyticdb、mongodb-atlas。
BEARER_TOKEN	是	这是一个用于认证 API 请求的密钥令牌。您可以使用任何工具或方法生成，例如 jwt.io。
OPENAI_API_KEY	是	这是您的 OpenAI API 密钥，用于调用 OpenAI 的嵌入模型生成嵌入向量。您可以通过在 OpenAI 上注册账户来获取 API 密钥。

使用 Azure OpenAI 插件

Azure OpenAI 使用特定于您资源的 URL，并且不通过模型名称而是通过部署 ID 来引用模型。因此，在这种情况下，您需要设置额外的环境变量。

除了 OPENAI_API_BASE（您的特定 URL）和 OPENAI_API_TYPE（azure）之外，您还需要设置 OPENAI_EMBEDDINGMODEL_DEPLOYMENTID，用于指定在插入和查询时使用的嵌入模型。我们建议部署 text-embedding-ada-002 模型，并在此处使用其部署名称。

如果您希望使用数据准备脚本，还需要设置用于元数据提取的 OPENAI_METADATA_EXTRACTIONMODEL_DEPLOYMENTID，以及用于 PII 处理的 OPENAI_COMPLETIONMODEL_DEPLOYMENTID。

选择向量数据库

该插件支持多种向量数据库提供商，每种都有不同的功能、性能和定价。根据您选择的数据库，您需要使用不同的 Dockerfile 并设置不同的环境变量。以下部分将简要介绍每种向量数据库提供商。

有关每种向量数据库提供商的详细设置和使用说明，请参阅 /docs/providers/<datastore_name>/setup.md 文件中的相应文档（此处的文件夹）。

Pinecone

Pinecone 是一种托管式向量数据库，专为速度、规模和快速部署到生产环境而设计。它支持混合搜索，也是目前唯一原生支持 SPLADE 稀疏向量的数据存储。有关详细的设置说明，请参阅 /docs/providers/pinecone/setup.md。

Weaviate

Weaviate 是一个开源的向量搜索引擎，能够无缝扩展到数十亿条数据记录。它开箱即用支持混合搜索，非常适合需要高效关键词搜索的用户。Weaviate 可以自托管或由第三方托管，提供了灵活的部署方式。有关详细的设置说明，请参阅 /docs/providers/weaviate/setup.md。

Zilliz

Zilliz 是一款面向十亿级数据的托管云原生向量数据库。它提供了丰富的功能，包括多种索引算法、距离度量方式、标量过滤、时间旅行查询、快照回滚、完整的 RBAC 权限管理、99.9% 的高可用性、存储与计算分离以及多语言 SDK。有关详细的部署指南，请参阅 /docs/providers/zilliz/setup.md。

Milvus

Milvus 是一款开源的云原生向量数据库，可扩展至数十亿条向量。它是 Zilliz 的开源版本，共享许多相同的功能，例如多种索引算法、距离度量方式、标量过滤、时间旅行查询、快照回滚、多语言 SDK、存储与计算分离以及云端可扩展性。有关详细的部署指南，请参阅 /docs/providers/milvus/setup.md。

Qdrant

Qdrant 是一款能够存储文档和向量嵌入的向量数据库。它提供自托管和托管的 Qdrant Cloud 部署选项，为不同需求的用户提供了灵活性。有关详细的部署指南，请参阅 /docs/providers/qdrant/setup.md。

Redis

Redis 是一个适用于多种场景的实时数据平台，既可用于日常应用，也可用于 AI/ML 工作负载。通过使用 Redis Stack Docker 容器 创建 Redis 数据库，它可以作为低延迟的向量引擎使用。对于托管解决方案，可以使用 Redis Cloud。有关详细的部署指南，请参阅 /docs/providers/redis/setup.md。

LlamaIndex

LlamaIndex 是一个用于将您的大模型与外部数据连接起来的中央接口。它为您的非结构化和结构化数据提供了一系列内存中的索引，以便与 ChatGPT 配合使用。与标准的向量数据库不同，LlamaIndex 支持多种索引策略（如树状索引、关键词表、知识图谱），这些策略针对不同的用例进行了优化。它轻量级、易于使用，无需额外部署。您只需设置几个环境变量即可（也可以选择指向已保存的 Index JSON 文件）。需要注意的是，目前查询中尚不支持元数据过滤。有关详细的部署指南，请参阅 /docs/providers/llama/setup.md。

Chroma

Chroma 是一款面向 AI 的开源嵌入数据库，旨在让入门尽可能简单。Chroma 可以在内存中运行，也可以采用客户端-服务器架构。它开箱即用就支持元数据和关键词过滤。有关详细说明，请参阅 /docs/providers/chroma/setup.md。

Azure 认知搜索

Azure 认知搜索 是一项完整的检索云服务，支持向量搜索、文本搜索以及混合搜索（结合向量和文本，以发挥两种方法的最佳效果）。它还提供一个可选的 L2 重新排序步骤，以进一步提升结果质量。有关详细的部署指南，请参阅 /docs/providers/azuresearch/setup.md。

Azure Cosmos DB MongoDB vCore

Azure Cosmos DB MongoDB vCore 支持对嵌入进行向量搜索，可用于将您的基于 AI 的应用程序与存储在 Azure Cosmos DB 中的数据无缝集成。有关详细说明，请参阅 /docs/providers/azurecosmosdb/setup.md。

Supabase

Supabase 提供了一种通过 Postgres 数据库的 pgvector 扩展来高效存储向量的方式。您可以使用 Supabase CLI 在本地或云端搭建完整的 Supabase 堆栈，也可以使用 docker-compose、k8s 等其他选项。对于托管解决方案，可以尝试 Supabase.com——它集成了身份验证、存储、自动 API 和实时功能，充分释放了 Postgres 的强大能力。有关详细的部署指南，请参阅 /docs/providers/supabase/setup.md。

Postgres

Postgres 提供了一种通过 pgvector 扩展高效存储向量的方式。要使用 pgvector，您需要设置一个启用了 pgvector 扩展的 PostgreSQL 数据库。例如，您可以使用 Docker 在本地运行。对于托管解决方案，可以选择任何支持 pgvector 的云服务商。有关详细的部署指南，请参阅 /docs/providers/postgres/setup.md。

AnalyticDB

AnalyticDB 是一款专为存储文档和向量嵌入而设计的分布式云原生向量数据库。它完全兼容 PostgreSQL 语法，并由阿里云托管。AnalyticDB 提供强大的向量计算引擎，能够处理数十亿条数据向量，并具备索引算法、结构化与非结构化数据处理能力、实时更新、距离度量方式、标量过滤以及时间旅行查询等功能。有关详细的部署指南，请参阅 /docs/providers/analyticdb/setup.md。

Elasticsearch

Elasticsearch 目前支持通过 dense_vector 字段类型存储向量，并利用这些向量来计算文档得分。Elasticsearch 8.0 在此基础上进一步支持快速的近似最近邻搜索 (ANN)，这是一种更具可扩展性的方法，能够在大型数据集上高效地执行向量搜索。有关详细的部署指南，请参阅 /docs/providers/elasticsearch/setup.md。

MongoDB Atlas

MongoDB Atlas 目前，该流程涉及为所有包含宽度不超过 2048 维向量嵌入的集合生成 Atlas 向量搜索索引。这适用于与您 Atlas 集群上其他数据共存的各种数据类型，且该过程通过 Atlas UI 和 Atlas 管理 API 执行，请参阅 /docs/providers/mongodb_atlas/setup.md。

在本地运行 API

要在本地运行 API，您首先需要使用 export 命令设置必要的环境变量：

export DATASTORE=<your_datastore>
export BEARER_TOKEN=<your_bearer_token>
export OPENAI_API_KEY=<your_openai_api_key>
<在此处添加您所选向量数据库的环境变量>

然后使用以下命令启动 API：

poetry run start

在终端显示的 URL 后面加上 docs，并在浏览器中打开，即可访问 API 文档并试用各个端点（即 http://0.0.0.0:8000/docs）。请务必输入您的 Bearer 令牌，并测试 API 端点。

注意： 如果您在 pyproject.toml 文件中添加了新的依赖项，需要运行 poetry lock 和 poetry install 来更新锁定文件并安装新依赖项。

个性化设置

您可以按照以下步骤为自己的用例个性化检索插件：

• 替换徽标：将 logo.png 中的图片替换为您自己的徽标。

• 编辑数据模型：编辑 models.py 中的 DocumentMetadata 和 DocumentMetadataFilter 数据模型，以添加自定义元数据字段。相应地更新 .well-known/openapi.yaml 中的 OpenAPI 模式。为了更方便地更新 OpenAPI 模式，您可以在本地运行应用，然后导航到 http://0.0.0.0:8000/sub/openapi.json，复制页面内容。接着前往 Swagger Editor 并粘贴 JSON 内容将其转换为 YAML 格式。您也可以将 .well-known/openapi.yaml 文件替换为位于 .well-known 文件夹中的 openapi.json 文件。

• 更改插件名称、描述和使用说明：更新插件名称、面向用户的描述以及模型的使用说明。您可以在 main.py 文件中直接编辑这些描述，也可以更新 .well-known/openapi.yaml 文件。按照上一步骤中的说明更新 OpenAPI 模式。

• 启用 ChatGPT 保存对话信息功能：请参阅 memory example folder 中的说明。

身份验证方法

您可从四种选项中选择用于对插件请求进行身份验证的方式：

1. 无身份验证：任何人都可以添加您的插件并使用其 API，无需任何凭据。此选项适用于仅公开非敏感或已公开的文档的情况。它无法为您的数据提供任何安全保障。若采用此方法，请将此 main.py 的内容复制到实际的 main.py 文件中。示例清单文件见 此处。

2. HTTP Bearer：您可以使用密钥令牌作为标头来授权对插件的请求。此选项有两种变体：

   • 用户级别（本实现的默认设置）：每位将您的插件添加到 ChatGPT 的用户都必须在添加插件时提供 Bearer 令牌。您可以使用任何工具或方法生成并分发这些令牌，例如 jwt.io。这种方式安全性更高，因为每个用户都需要输入共享的访问令牌。如果您需要为每个用户分配唯一的访问令牌，则需自行在 main.py 文件中实现。示例清单文件见 此处。

   • 服务级别：任何人都可以添加您的插件并使用其 API，无需凭据，但您在注册插件时必须添加 Bearer 令牌。当您安装插件时，需要添加您的 Bearer 令牌，随后会收到 ChatGPT 分配的一个令牌，您必须将其包含在托管的清单文件中。ChatGPT 将使用您的令牌代表所有添加该插件的用户来授权对插件的请求。这种方法对用户更为便捷，但安全性可能较低，因为所有用户共享同一令牌，且无需添加令牌即可安装插件。示例清单文件见 此处。

3. OAuth：用户必须通过 OAuth 流程才能添加您的插件。您可以使用 OAuth 提供商对添加插件的用户进行身份验证，并授予其访问您的 API 的权限。此方法提供了最高级别的安全性和控制，因为用户通过受信任的第三方提供商进行身份验证。然而，您需要自行在 main.py 文件中实现 OAuth 流程，并在清单文件中提供必要的参数。示例清单文件见 此处。

在选择最适合您用例和安全需求的身份验证方法之前，请考虑每种方法的优缺点。如果您选择使用不同于默认设置（用户级别 HTTP）的方法，请务必更新位于 .well-known/ai-plugin.json 的清单文件。

部署

您可以根据自己的偏好和需求，将应用部署到不同的云服务提供商。无论选择哪家提供商，您都需要更新应用中的两个文件：openapi.yaml 和 ai-plugin.json。如上文所述，这两个文件分别定义了应用的 API 规范和 AI 插件配置。您需要将这两个文件中的 url 字段修改为与已部署应用地址一致。

Render 提供了一键部署选项，可自动更新这两个文件中的 url 字段：

在部署应用之前，建议您从 pyproject.toml 文件中移除未使用的依赖项，以减小应用体积并提升性能。根据您选择的向量数据库提供商，可以移除针对该特定提供商不必要的包。有关各提供商如何移除未使用依赖项的信息，请参阅 /docs/deployment/removing-unused-dependencies.md 文件中的相应文档。

部署指南：

• 部署到 Fly.io
• 部署到 Heroku
• 部署到 Render
• 其他部署选项（Azure 容器应用、Google Cloud Run、AWS 弹性容器服务等）

完成应用部署后，您可以使用其中一份脚本或调用 /upsert 端点来上传初始文档批次。

Webhook

为了保持向量数据库中存储的文档始终最新，您可以考虑使用 Zapier 或 Make 等工具，基于事件或计划配置指向插件 API 的入站 webhook。例如，当您更新笔记或收到电子邮件时，这些 webhook 可以帮助您同步新信息。此外，您还可以使用 Zapier Transfer 工具批量处理现有文档集合，并将其上传到向量数据库。

如果您需要将自定义字段从这些工具传递到您的插件，可以创建一个额外的检索插件 API 端点，用于调用数据存储的 upsert 函数，例如 upsert-email。此自定义端点可以设计为接收来自 webhook 的特定字段，并按要求进行处理。

设置入站 webhook 的一般步骤如下：

• 选择 Zapier 或 Make 等 webhook 工具并注册账户。
• 在工具中创建新的 webhook 或传输任务，并配置其基于事件或计划触发。
• 指定 webhook 的目标 URL，即您的检索插件的 API 端点（例如 https://your-plugin-url.com/upsert）。
• 配置 webhook 负载，包含必要的数据字段，并按照您的检索插件 API 要求进行格式化。
• 测试 webhook，确保其正常工作并按预期将数据发送到您的检索插件。

设置完 webhook 后，建议您执行一次回填操作，以确保所有之前遗漏的数据都被纳入向量数据库中。

请记住，如果您希望使用入站 webhook 持续同步数据，在设置完成后应执行一次回填操作，以免遗漏任何数据。

除了使用 Zapier 和 Make 等工具外，您也可以构建自定义集成来与您的检索插件同步数据。这样可以更好地控制数据流，并根据您的具体需求定制集成方案。

脚本

scripts 文件夹包含用于批量 upsert 或处理来自不同数据源的文本文档的脚本，例如 zip 文件、JSON 文件或 JSONL 文件。这些脚本利用插件的 upsert 工具函数，将文档及其元数据转换为纯文本并拆分为块后上传到向量数据库。每个脚本文件夹都配有 README 文件，说明如何使用以及所需的参数。您还可以选择使用语言模型对文档进行个人身份信息 (PII) 屏蔽，若检测到 PII 则跳过该文档，相关功能由 services.pii_detection 模块提供。这有助于避免无意中将敏感或隐私文档上传到向量数据库。此外，您还可以选择使用语言模型从文档文本中提取元数据，相关功能由 services.extract_metadata 模块提供。这在您希望丰富文档元数据时非常有用。注意： 如果使用入站 webhook 持续同步数据，建议在设置完成后执行一次回填操作，以避免遗漏任何数据。

脚本包括：

• process_json：此脚本处理 JSON 格式的文档转储文件，并将文档连同部分元数据存储到向量数据库中。JSON 文件的格式应为 JSON 对象列表，每个对象代表一篇文档。JSON 对象应包含 text 字段，并可选地包含其他字段以填充元数据。您可以提供自定义元数据（以 JSON 字符串形式）以及用于 PII 屏蔽和元数据提取的标志。
• process_jsonl：此脚本处理 JSONL 格式的文档转储文件，并将文档连同部分元数据存储到向量数据库中。JSONL 文件的格式应为每行一个有效 JSON 对象的换行分隔文件，每个对象代表一篇文档。JSON 对象应包含 text 字段，并可选地包含其他字段以填充元数据。您可以提供自定义元数据（以 JSON 字符串形式）以及用于 PII 屏蔽和元数据提取的标志。
• process_zip：此脚本处理 zip 文件中的文档转储，并将文档连同部分元数据存储到向量数据库中。zip 文件的格式应为 docx、pdf、txt、md、pptx 或 csv 文件的扁平文件夹。您可以提供自定义元数据（以 JSON 字符串形式）以及用于 PII 屏蔽和元数据提取的标志。

拉取请求 (PR) 检查清单

如果您希望贡献代码，请在提交 PR 时遵循以下检查清单。这将帮助我们更快地审查和合并您的更改！感谢您的贡献！

1. PR 类型：在标题开头的方括号中添加标签以标明 PR 类型，例如 [Bugfix]、[Feature]、[Enhancement]、[Refactor] 或 [Documentation]。

2. 简短描述：提供一段简明扼要、信息丰富的 PR 描述，说明所做的更改。

3. 关联问题：使用关键字 Fixes 或 Closes 后跟相应的问题编号来提及任何相关问题（例如 Fixes #123、Closes #456）。

4. 分支：确保您为此次更改创建了一个新分支，并且该分支基于最新的 main 分支。

5. 代码更改：请确保代码更改尽可能精简、聚焦，并与所解决的问题或新增功能直接相关。

6. 提交信息：编写清晰简洁的提交信息，解释每次提交的目的。

7. 测试：为任何新代码或对现有代码的更改包含单元测试和/或集成测试。请务必在提交 PR 之前确保所有测试都通过。

8. 文档更新：更新相关文档（如 README、内联注释或外部文档），以反映所做的任何更改。

9. 请求评审：至少请求一位其他贡献者或仓库维护者进行评审。

10. 视频提交（针对复杂或大型 PR）：如果您的 PR 引入了重大更改、复杂逻辑或大量代码行，请随 PR 一起提交一段简短的演示视频。视频应解释更改的目的、背后的逻辑，以及这些更改如何解决问题或实现拟议的功能。这将有助于评审人员更好地理解您的贡献，并加快评审流程。

拉取请求命名规范

请按照以下命名规范为您的 PR 分支命名：

<type>/<short-description>-<issue-number>

• <type>：PR 类型，例如 bugfix、feature、enhancement、refactor 或 docs。可以使用多个类型，用逗号分隔。
• <short-description>：对所做更改的简要描述，单词之间用连字符分隔。
• <issue-number>：与所做更改相关联的问题编号（如果适用）。

示例：

feature/advanced-chunking-strategy-123

限制

尽管 ChatGPT 检索插件旨在为语义搜索和检索提供灵活的解决方案，但它仍存在一些局限性：

• 关键词搜索限制：所选 OpenAI 嵌入模型生成的嵌入可能无法有效捕捉精确的关键词匹配。因此，对于高度依赖特定关键词的查询，插件可能无法返回最相关的结果。某些向量数据库，如 Elasticsearch、Pinecone、Weaviate 和 Azure Cognitive Search，采用混合搜索方式，可能在关键词搜索方面表现更佳。
• 敏感数据处理：插件不会自动检测或过滤敏感数据。开发者有责任确保其拥有将内容纳入检索插件的必要授权，并保证内容符合数据隐私要求。
• 可扩展性：插件的性能可能因所选的向量数据库提供商及数据集大小而异。不同提供商的可扩展性和性能可能存在差异。
• 元数据提取：可选的元数据提取功能依赖于语言模型从文档文本中提取信息。此过程并不总是准确的，提取的元数据质量可能因文档内容和结构而异。
• PII 检测：可选的 PII 检测功能并非万无一失，可能无法捕获所有个人身份信息。请谨慎使用此功能，并根据您的具体用例验证其有效性。

未来发展方向

ChatGPT 检索插件为语义搜索和检索提供了一种灵活的解决方案，但仍有进一步开发的空间。我们鼓励用户通过提交拉取请求来为项目贡献新功能或改进。重要的贡献可能会获得 OpenAI 积分作为认可。

未来的一些发展方向包括：

• 更多向量数据库提供商：如果您有兴趣将其他向量数据库提供商与 ChatGPT 检索插件集成，请随时提交相应的实现。
• 更多脚本：扩展可用于处理和上传来自各种数据源的文档的脚本范围，将使插件更加通用。
• 用户界面：开发用于管理文档和与插件交互的用户界面，可以提升用户体验。
• 混合搜索 / TF-IDF 选项：在 datastore 的 upsert 函数 中增加使用混合搜索或 TF-IDF 索引的选项，可以提高插件在基于关键词查询方面的性能。
• 高级分块策略和嵌入计算：实施更复杂的分块策略和嵌入计算方法，例如对文档标题和摘要进行嵌入、对文档分块和摘要进行加权平均，或计算文档的平均嵌入，都有望带来更好的搜索结果。
• 自定义元数据：允许用户为文档分块添加自定义元数据，例如标题或其他相关信息，在某些场景下可能会改善检索结果。
• 更多可选服务：集成更多可选服务，例如对文档进行摘要生成或在嵌入前对文档进行预处理，可以增强插件的功能和检索结果的质量。这些服务可以使用语言模型实现，并直接集成到插件中，而不只是在脚本中提供。

我们欢迎社区的贡献，以帮助改进 ChatGPT 检索插件并扩展其功能。如果您有任何想法或想要贡献的功能，请向仓库提交拉取请求。

贡献者

我们谨向以下贡献者致以诚挚的感谢，感谢他们为代码和文档所做的贡献，以及在将各类向量数据库提供商与 ChatGPT 检索插件集成过程中给予的支持：

• Pinecone
  • acatav
  • gkogan
  • jamescalam
• Weaviate
  • byronvoorbach
  • hsm207
  • sebawita
• Zilliz
  • filip-halt
• Milvus
  • filip-halt
• Qdrant
  • kacperlukawski
• Redis
  • spartee
  • tylerhutcherson
• LlamaIndex
  • jerryjliu
  • Disiok
• Supabase
  • egor-romanov
• Postgres
  • egor-romanov
  • mmmaia
• Elasticsearch
  • joemcelroy

ChatGPT Retrieval Plugin 快速上手指南

ChatGPT Retrieval Plugin 是一个独立的检索后端，旨在让 ChatGPT（通过 Custom GPTs、Function Calling 或 Assistants API）能够访问和检索您的个人或组织文档。它利用语义搜索技术，使模型能够基于您提供的私有数据生成更准确的回答（即 RAG 架构）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 WSL2)
• Python 版本：必须安装 Python 3.10 (其他版本可能导致依赖冲突)
• 包管理工具：pip
• 依赖管理工具：poetry
• 向量数据库：需预先准备一个向量数据库实例（如 Pinecone, Weaviate, Qdrant, Milvus, Redis, Chroma, Elasticsearch, MongoDB Atlas 等）并获取相应的连接凭证。
• OpenAI API Key：有效的 OpenAI API 密钥。

提示：国内开发者若遇到 pip 或 poetry 下载缓慢，可配置国内镜像源加速：

• Pip: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
• Poetry: poetry config pypi-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

请依次执行以下命令完成项目克隆与环境搭建：

1. 克隆仓库

   git clone https://github.com/openai/chatgpt-retrieval-plugin.git
   cd chatgpt-retrieval-plugin
   

2. 安装 Poetry

   pip install poetry
   

3. 创建并激活虚拟环境 指定使用 Python 3.10 创建环境：

   poetry env use python3.10
   poetry shell
   

4. 安装项目依赖

   poetry install
   

5. 配置环境变量 您需要设置数据存储类型、认证令牌、OpenAI 密钥以及所选向量数据库的连接信息。

   创建一个 .env 文件或直接在终端导出变量（以下为示例，请根据实际情况替换 <...> 内容）：

   # 基础配置
   export DATASTORE=<your_datastore>  # 例如：pinecone, weaviate, qdrant 等
   export BEARER_TOKEN=<your_bearer_token> # 自定义一个用于 API 认证的令牌
   export OPENAI_API_KEY=<your_openai_api_key>
   
   # 嵌入模型配置 (默认使用 text-embedding-3-large)
   export EMBEDDING_DIMENSION=256
   export EMBEDDING_MODEL=text-embedding-3-large
   
   # 向量数据库配置 (以 Pinecone 为例，其他数据库请参考 README 中的对应部分)
   export PINECONE_API_KEY=<your_pinecone_api_key>
   export PINECONE_ENVIRONMENT=<your_pinecone_environment>
   export PINECONE_INDEX=<your_pinecone_index>
   

   注意：如果您使用的是 Azure OpenAI 或其他向量数据库（如 Milvus, Qdrant, Redis 等），请参照原 README 中 Quickstart 部分的完整列表设置对应的 export 变量。

基本使用

完成安装和配置后，您可以启动本地服务并进行测试。

1. 启动 API 服务 在激活的虚拟环境中运行：

   poetry run start
   

   服务默认将在 http://0.0.0.0:8000 启动。

2. 访问文档与测试接口 打开浏览器访问 Swagger UI 界面：

   http://0.0.0.0:8000/docs
   

3. 执行操作

   • 在 Swagger 界面中，找到 /upsert 接口上传文档（支持文本、URL 或文件）。
   • 点击 "Try it out"。
   • 在 Authorization 栏输入您的 Bearer Token（格式：Bearer <your_bearer_token>）。
   • 填入文档内容进行测试。
   • 随后可以使用 /query 接口通过自然语言提问，系统将返回基于您上传文档的检索结果。

此时，您的检索后端已运行成功，接下来可将其部署到云端并配置到 ChatGPT Custom GPTs 或通过 Function Calling 集成到您的应用中。