RAGAI Agent后端向量数据库【免费下载链接】chatgpt-retrieval-pluginThe ChatGPT Retrieval Plugin lets you easily find personal or work documents by asking questions in natural language.项目地址https://gitcode.com/gh_mirrors/ch/chatgpt-retrieval-plugin点击查看免费下载Azure Cognitive Search 是 ChatGPT Retrieval Plugin 官方支持的检索后端之一它同时提供纯向量检索、纯文本检索以及二者结合的混合检索并可选启用 L2 语义重排semantic re-ranking进一步提升结果质量。本文以 docs/providers/azuresearch/setup.md 为主线结合仓库中 datastore/providers/azuresearch_datastore.py 的实现与 测试用例完整讲解环境变量配置、认证方式、索引自动创建、混合检索与重排的底层逻辑以及如何复用既有索引并完成字段映射读完即可在生产环境中将 Azure Cognitive Search 作为检索插件的数据存储。Azure Cognitive Search 与检索插件的定位在 ChatGPT Retrieval Plugin 的架构中DATASTORE环境变量决定了语义检索使用哪个向量数据库后端。仓库通过 datastore/factory.py 中的get_datastore()工厂函数按名称实例化对应实现其中case azuresearch分支会创建AzureSearchDataStore实例见 datastore/factory.py。该实现继承自 datastore/datastore.py 中的抽象基类DataStore实现_upsert、_query、delete三个核心抽象方法从而与上层 API、文档切块chunking和 OpenAI 嵌入生成流程无缝衔接。Azure Cognitive Search 的独特之处在于它是一站式检索云服务向量搜索vector search基于 HNSW 索引对嵌入向量做相似度检索文本搜索text search基于 Lucene 分析器的全文检索混合检索hybrid search向量 文本结果融合取两者之长可选的 L2 重排semantic re-ranking在初检结果之上再做一轮语义排序进一步提升质量。在 README 的 Limitations 一节中也有说明由于嵌入模型对精确关键词匹配可能不敏感像 Azure Cognitive Search 这类支持混合检索的后端在关键词查询上通常表现更好见 README.md。前置准备开通向量搜索能力Azure Cognitive Search 原生支持三种检索模式纯向量、纯文本、混合。其中向量相关能力需要先申请vector search private preview。文档给出的方式是填写官方注册表单aka.ms/VectorSearchSignUp完成报名等待服务启用向量搜索后再进行下面的配置。如果你还没有 Azure 账号需要先注册 Azure 并创建一个 Cognitive Search 服务资源在 Azure 门户或通过 Azure CLI 均可完成创建。环境变量完整说明接入 Azure Cognitive Search 需要设置以下环境变量。下表完整保留了原文档中的配置清单并结合源码补充了默认值细节源码中的默认值定义见 datastore/providers/azuresearch_datastore.py名称必填说明默认值DATASTORE是数据存储类型固定设为azuresearchBEARER_TOKEN是访问 API 的密钥令牌OPENAI_API_KEY是OpenAI API 密钥用于生成嵌入向量AZURESEARCH_SERVICE是搜索服务名称resource nameAZURESEARCH_INDEX是搜索索引名称AZURESEARCH_API_KEY否使用密钥认证时的 API Key不设置则改用 Azure 托管标识managed identity认证托管标识AZURESEARCH_DISABLE_HYBRID否设为任意非空值如1可禁用混合检索仅使用向量相似度启用混合检索AZURESEARCH_SEMANTIC_CONFIG否指定语义配置名称以启用 L2 重排见下文重排一节不启用 L2AZURESEARCH_LANGUAGE否使用 L2 重排时查询/文档的语言代码合法值见 Azure 官方文档queryLanguage参数en-usAZURESEARCH_DIMENSIONS否嵌入向量的维度必须与所用嵌入模型输出维度一致256一个最小可运行的配置示例export DATASTOREazuresearch export BEARER_TOKENyour_bearer_token export OPENAI_API_KEYyour_openai_api_key export AZURESEARCH_SERVICEyour_search_service_name export AZURESEARCH_INDEXyour_search_index_name # 可选使用 API Key 认证不设置则走托管标识 export AZURESEARCH_API_KEYyour_api_key # 可选仅向量检索禁用混合检索 # export AZURESEARCH_DISABLE_HYBRID1 # 可选启用 L2 语义重排 # export AZURESEARCH_SEMANTIC_CONFIGyour_semantic_config_name # export AZURESEARCH_LANGUAGEen-us # 可选调整嵌入维度需与嵌入模型匹配 # export AZURESEARCH_DIMENSIONS256需要注意的是源码在模块加载时会对AZURESEARCH_SERVICE与AZURESEARCH_INDEX执行断言assert ... is not None见 datastore/providers/azuresearch_datastore.py缺少这两个变量会导致插件启动直接失败而AZURESEARCH_API_KEY、AZURESEARCH_SEMANTIC_CONFIG、AZURESEARCH_DISABLE_HYBRID等均是可选项。另外README 的通用环境变量说明中还强调若使用 Azure OpenAI 而不是 OpenAI 官方 API还需额外设置OPENAI_API_BASE、OPENAI_API_TYPEazure以及嵌入模型部署 ID 等变量见 README.md这部分与数据存储无关但直接影响嵌入生成配置时需一并注意。认证方式API Key 与托管标识Azure Cognitive Search 支持两种认证方式插件实现均覆盖1. API Key默认启用在 Azure 门户或通过 Azure CLI 获取搜索服务的 admin/query key设置为AZURESEARCH_API_KEY。源码中当该变量存在时使用AzureKeyCredential构造凭证见 datastore/providers/azuresearch_datastore.py。2. 托管标识Managed identity如果插件运行在 Azure 内部如 Azure App Service、Azure Functions 等可以不为宿主配置任何密钥而是启用宿主资源的托管标识并授予该标识对搜索服务的访问权限RBAC从而免去密钥存储与轮换的管理负担。源码中当AZURESEARCH_API_KEY未设置时会回退到DefaultAzureCredential同步/异步两个版本该凭证链会自动尝试环境变量、托管标识、Azure CLI 登录等多种来源if AZURESEARCH_API_KEY is None: credential DefaultAzureCredential() if use_async else DefaultAzureCredentialSync() else: credential AzureKeyCredential(AZURESEARCH_API_KEY)值得注意的是客户端与索引管理客户端会分别调用_create_credentials并在构造SearchClient时通过user_agentretrievalplugin标记请求来源见 datastore/providers/azuresearch_datastore.py。索引自动创建与字段设计插件启动时AzureSearchDataStore.__init__会先列出服务中已有的索引如果AZURESEARCH_INDEX尚不存在则调用_create_index自动创建如果已存在则直接复用并打印日志见 datastore/providers/azuresearch_datastore.py。自动创建的索引结构源码见 datastore/providers/azuresearch_datastore.py包含以下字段字段类型关键属性idString索引主键keytextString可搜索字段分析器为standard.luceneembeddingCollection(Single)向量字段维度取AZURESEARCH_DIMENSIONS绑定名为default的向量配置document_idString可过滤、可排序sourceString可过滤、可排序source_idString可过滤、可排序urlString普通字段created_atDateTimeOffset可过滤、可排序authorString可过滤、可排序向量索引配置采用HNSW 算法、余弦距离cosine源码注释还提示由于 OpenAI 的嵌入向量已归一化为单位长度也可以改用点积dot product度量vector_searchVectorSearch( algorithm_configurations[ HnswVectorSearchAlgorithmConfiguration( namedefault, kindhnsw, hnsw_parametersHnswParameters(metriccosine), ) ] )关于AZURESEARCH_DIMENSIONS需要特别注意它的默认值是256但必须与你实际使用的嵌入模型输出维度一致。例如 OpenAI 的text-embedding-ada-002输出 1536 维、text-embedding-3-small默认 1536 维可降维、text-embedding-3-large默认 3072 维可降维。如果索引已创建后想更换嵌入模型需要重建索引因为向量维度在索引定义中不可变。混合检索与 L2 语义重排的底层逻辑这是 Azure Cognitive Search 相对其他后端的核心亮点文档与源码都给出了明确的行为描述。混合检索Hybrid Search默认情况下AZURESEARCH_DISABLE_HYBRID未设置_single_query会同时提交文本查询和向量查询文本部分q query.query参与全文检索向量部分构造Vector(valuequery.embedding, kvector_top_k, fieldsFIELDS_EMBEDDING)当存在元数据过滤器时vector_top_k翻倍query.top_k * 2启用混合检索时再翻倍* 2以给融合阶段留出更多候选见 datastore/providers/azuresearch_datastore.py。如果设置AZURESEARCH_DISABLE_HYBRID1则q传None仅执行纯向量相似度检索。L2 语义重排Semantic Re-ranking设置AZURESEARCH_SEMANTIC_CONFIG后即启用 L2 重排但前提是你的 Cognitive Search 服务已显式启用 semantic search能力已为索引创建语义配置semantic configuration并把配置名称填入该环境变量。启用后检索请求会使用QueryType.SEMANTIC与query_languageAZURESEARCH_LANGUAGE同时为了让 L2 重排器有足够的候选输入源码会把vector_top_k至少提升到 50if AZURESEARCH_SEMANTIC_CONFIG ! None and not AZURESEARCH_DISABLE_HYBRID: vector_top_k max(50, vector_top_k) r await self.client.search( q, filterfilter, topquery.top_k, vectors[vector_q], query_typeQueryType.SEMANTIC, query_languageAZURESEARCH_LANGUAGE, semantic_configuration_nameAZURESEARCH_SEMANTIC_CONFIG, )从这段代码可以推断出两个要点其一L2 重排仅在混合或文本检索模式下生效纯向量模式下即便设置了AZURESEARCH_SEMANTIC_CONFIG也不会走语义查询分支其二重排会增加延迟与成本因此文档也提示这是一项需要显式开启的选项。插件在自动创建索引时如果指定了AZURESEARCH_SEMANTIC_CONFIG还会同步把text字段配置为优先内容字段prioritized_content_fields生成对应的SemanticSettings见 datastore/providers/azuresearch_datastore.py。复用既有索引字段名映射如果企业已有现成的 Azure Cognitive Search 索引字段与插件所需语义一致但命名不同无需重建索引只需通过AZURESEARCH_FIELDS_*系列环境变量把既有字段映射到插件字段。原文档给出的映射表如下右侧环境变量的默认值即为插件期望的字段名源码见 datastore/providers/azuresearch_datastore.py插件字段名可覆盖它的环境变量源码默认值idAZURESEARCH_FIELDS_IDidtextAZURESEARCH_FIELDS_TEXTtextembeddingAZURESEARCH_FIELDS_EMBEDDINGembeddingdocument_idAZURESEARCH_FIELDS_DOCUMENT_IDdocument_idsourceAZURESEARCH_FIELDS_SOURCEsourcesource_idAZURESEARCH_FIELDS_SOURCE_IDsource_idurlAZURESEARCH_FIELDS_URLurlcreated_atAZURESEARCH_FIELDS_CREATED_ATcreated_atauthorAZURESEARCH_FIELDS_AUTHORauthor例如若你的既有索引主键字段叫doc_key、正文字段叫content可设置export AZURESEARCH_FIELDS_IDdoc_key export AZURESEARCH_FIELDS_TEXTcontent这些映射变量在写入_upsert、查询_single_query与删除delete全链路中统一生效字段名被当作常量使用因此整个插件对索引字段的读写都遵循你的映射。元数据过滤OData 过滤表达式与日期格式插件支持按document_id、source、source_id、author以及created_at时间范围进行过滤这些条件最终由_translate_filter翻译成 Azure Search 的 OData 过滤表达式源码见 datastore/providers/azuresearch_datastore.py字符串字段使用eq比较且会先转义单引号转义为防止注入日期字段使用ge/le比较且必须符合 OData 时间格式\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z如2023-01-01T00:00:00Z否则抛出ValueError多个条件用and连接。对应的行为在 tests/datastore/providers/azuresearch/test_azuresearch_datastore.py 中有完整验证例如非法日期2023-01-01会触发ValueError单引号会被正确转义多条件组合会生成符合预期的 OData 字符串。写入、删除与查询的实现细节写入upsert插件会先把文档切块并生成嵌入向量再通过upload_documents批量写入。两个值得注意的细节ID 编码id会被base64.urlsafe_b64encode编码后写入索引这是为了规避 Azure Search 对文档主键字符集的限制源码注释明确说明了这一点见 datastore/providers/azuresearch_datastore.py批处理写入与删除均按每批 1000 条MAX_UPLOAD_BATCH_SIZE/MAX_DELETE_BATCH_SIZE分批执行部分失败会抛出异常提示上传失败的条数。删除delete支持三种方式——按文档 ID 列表、按元数据过滤器、或delete_all全量清空。使用过滤或全量删除时会先搜索符合条件的文档、分批删除并通过include_total_count判断是否还有剩余若因索引近实时刷新导致重复读到已删文档会短暂休眠 0.25 秒后重试见 datastore/providers/azuresearch_datastore.py。查询query_query通过asyncio.gather并发处理多个查询每个查询返回QueryResult其中命中结果DocumentChunkWithScore的score直接取自 Azure Search 的search.score字段见 datastore/providers/azuresearch_datastore.py。用测试用例验证三种检索模式仓库为 Azure Cognitive Search 提供了完整的集成测试tests/datastore/providers/azuresearch/test_azuresearch_datastore.py覆盖了插件的三种运行模式是验证配置正确性的最佳参考test_lifecycle_hybrid默认混合检索模式test_lifecycle_vectors_only设置AZURESEARCH_DISABLE_HYBRID1的纯向量模式test_lifecycle_semantic设置AZURESEARCH_SEMANTIC_CONFIG的语义重排模式。测试会真实执行索引创建、文档 upsert、带过滤/不带过滤的查询、时间范围过滤以及删除的完整生命周期见 tests/datastore/providers/azuresearch/test_azuresearch_datastore.py其中还特意使用了包含字符的文档 IDtest_id_2来验证 base64 编码对特殊字符的处理。运行测试前需要设置真实的AZURESEARCH_SERVICE环境变量测试中默认写入testindex作为索引名。启动与验证完成以上配置后按仓库 README 的通用步骤安装依赖Python 3.10 Poetry并确保DATASTOREazuresearch随后启动 FastAPI 服务即可。插件启动时会自动完成服务可用性检查与索引创建/复用日志中会打印Using existing index ...或Creating index ...信息可据此判断后端连接是否成功。之后便可通过标准 upsert/query API 上传文档并执行自然语言语义检索。小结将 ChatGPT Retrieval Plugin 接入 Azure Cognitive Search 的关键在于三件事一是正确设置AZURESEARCH_*系列环境变量并保证AZURESEARCH_DIMENSIONS与嵌入模型一致二是根据实际场景选择 API Key 或托管标识认证三是按需启用混合检索与 L2 语义重排并善用AZURESEARCH_FIELDS_*映射复用企业既有索引。结合仓库源码可以看到从索引自动创建、字段过滤到批处理与 ID 编码AzureSearchDataStore的实现都针对 Azure Search 的服务特性做了细致适配配合 测试用例 可以在上线前充分验证各模式行为。赞分享RAGAI Agent后端向量数据库【免费下载链接】chatgpt-retrieval-pluginThe ChatGPT Retrieval Plugin lets you easily find personal or work documents by asking questions in natural language.项目地址https://gitcode.com/gh_mirrors/ch/chatgpt-retrieval-plugin点击查看免费下载相关推荐LangChain4j 集成 Azure AI Search从向量检索到混合检索与重排的完整实践指南LangChain4j 集成 Azure AI Search从向量检索到混合检索与重排的完整实践指南 Azure AI Search前身为 Azure Co人工智能AI 应用RAGAI Agent工具调用如何快速部署Azure搜索服务完整的Azure Cognitive Search入门指南如何快速部署Azure搜索服务完整的Azure Cognitive Search入门指南 想要在Azure上快速搭建企业级搜索服务吗Azure Cognit示例工程ChatGPT Retrieval Plugin构建智能文档检索系统的完整指南ChatGPT Retrieval Plugin构建智能文档检索系统的完整指南 ChatGPT Retrieval Plugin 是一个革命性的开源项目由RAGAI Agent后端向量数据库上一篇5分钟部署MiniCPM-V本地多模态推理全攻略从0到1跑通图片问答下一篇如何通过游戏化编程彻底改变你的学习体验CodeCombat终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ChatGPT Retrieval Plugin 接入 Azure Cognitive Search 完整指南：混合检索、L2 语义重排与字段映射
RAGAI Agent后端向量数据库【免费下载链接】chatgpt-retrieval-pluginThe ChatGPT Retrieval Plugin lets you easily find personal or work documents by asking questions in natural language.项目地址https://gitcode.com/gh_mirrors/ch/chatgpt-retrieval-plugin点击查看免费下载Azure Cognitive Search 是 ChatGPT Retrieval Plugin 官方支持的检索后端之一它同时提供纯向量检索、纯文本检索以及二者结合的混合检索并可选启用 L2 语义重排semantic re-ranking进一步提升结果质量。本文以 docs/providers/azuresearch/setup.md 为主线结合仓库中 datastore/providers/azuresearch_datastore.py 的实现与 测试用例完整讲解环境变量配置、认证方式、索引自动创建、混合检索与重排的底层逻辑以及如何复用既有索引并完成字段映射读完即可在生产环境中将 Azure Cognitive Search 作为检索插件的数据存储。Azure Cognitive Search 与检索插件的定位在 ChatGPT Retrieval Plugin 的架构中DATASTORE环境变量决定了语义检索使用哪个向量数据库后端。仓库通过 datastore/factory.py 中的get_datastore()工厂函数按名称实例化对应实现其中case azuresearch分支会创建AzureSearchDataStore实例见 datastore/factory.py。该实现继承自 datastore/datastore.py 中的抽象基类DataStore实现_upsert、_query、delete三个核心抽象方法从而与上层 API、文档切块chunking和 OpenAI 嵌入生成流程无缝衔接。Azure Cognitive Search 的独特之处在于它是一站式检索云服务向量搜索vector search基于 HNSW 索引对嵌入向量做相似度检索文本搜索text search基于 Lucene 分析器的全文检索混合检索hybrid search向量 文本结果融合取两者之长可选的 L2 重排semantic re-ranking在初检结果之上再做一轮语义排序进一步提升质量。在 README 的 Limitations 一节中也有说明由于嵌入模型对精确关键词匹配可能不敏感像 Azure Cognitive Search 这类支持混合检索的后端在关键词查询上通常表现更好见 README.md。前置准备开通向量搜索能力Azure Cognitive Search 原生支持三种检索模式纯向量、纯文本、混合。其中向量相关能力需要先申请vector search private preview。文档给出的方式是填写官方注册表单aka.ms/VectorSearchSignUp完成报名等待服务启用向量搜索后再进行下面的配置。如果你还没有 Azure 账号需要先注册 Azure 并创建一个 Cognitive Search 服务资源在 Azure 门户或通过 Azure CLI 均可完成创建。环境变量完整说明接入 Azure Cognitive Search 需要设置以下环境变量。下表完整保留了原文档中的配置清单并结合源码补充了默认值细节源码中的默认值定义见 datastore/providers/azuresearch_datastore.py名称必填说明默认值DATASTORE是数据存储类型固定设为azuresearchBEARER_TOKEN是访问 API 的密钥令牌OPENAI_API_KEY是OpenAI API 密钥用于生成嵌入向量AZURESEARCH_SERVICE是搜索服务名称resource nameAZURESEARCH_INDEX是搜索索引名称AZURESEARCH_API_KEY否使用密钥认证时的 API Key不设置则改用 Azure 托管标识managed identity认证托管标识AZURESEARCH_DISABLE_HYBRID否设为任意非空值如1可禁用混合检索仅使用向量相似度启用混合检索AZURESEARCH_SEMANTIC_CONFIG否指定语义配置名称以启用 L2 重排见下文重排一节不启用 L2AZURESEARCH_LANGUAGE否使用 L2 重排时查询/文档的语言代码合法值见 Azure 官方文档queryLanguage参数en-usAZURESEARCH_DIMENSIONS否嵌入向量的维度必须与所用嵌入模型输出维度一致256一个最小可运行的配置示例export DATASTOREazuresearch export BEARER_TOKENyour_bearer_token export OPENAI_API_KEYyour_openai_api_key export AZURESEARCH_SERVICEyour_search_service_name export AZURESEARCH_INDEXyour_search_index_name # 可选使用 API Key 认证不设置则走托管标识 export AZURESEARCH_API_KEYyour_api_key # 可选仅向量检索禁用混合检索 # export AZURESEARCH_DISABLE_HYBRID1 # 可选启用 L2 语义重排 # export AZURESEARCH_SEMANTIC_CONFIGyour_semantic_config_name # export AZURESEARCH_LANGUAGEen-us # 可选调整嵌入维度需与嵌入模型匹配 # export AZURESEARCH_DIMENSIONS256需要注意的是源码在模块加载时会对AZURESEARCH_SERVICE与AZURESEARCH_INDEX执行断言assert ... is not None见 datastore/providers/azuresearch_datastore.py缺少这两个变量会导致插件启动直接失败而AZURESEARCH_API_KEY、AZURESEARCH_SEMANTIC_CONFIG、AZURESEARCH_DISABLE_HYBRID等均是可选项。另外README 的通用环境变量说明中还强调若使用 Azure OpenAI 而不是 OpenAI 官方 API还需额外设置OPENAI_API_BASE、OPENAI_API_TYPEazure以及嵌入模型部署 ID 等变量见 README.md这部分与数据存储无关但直接影响嵌入生成配置时需一并注意。认证方式API Key 与托管标识Azure Cognitive Search 支持两种认证方式插件实现均覆盖1. API Key默认启用在 Azure 门户或通过 Azure CLI 获取搜索服务的 admin/query key设置为AZURESEARCH_API_KEY。源码中当该变量存在时使用AzureKeyCredential构造凭证见 datastore/providers/azuresearch_datastore.py。2. 托管标识Managed identity如果插件运行在 Azure 内部如 Azure App Service、Azure Functions 等可以不为宿主配置任何密钥而是启用宿主资源的托管标识并授予该标识对搜索服务的访问权限RBAC从而免去密钥存储与轮换的管理负担。源码中当AZURESEARCH_API_KEY未设置时会回退到DefaultAzureCredential同步/异步两个版本该凭证链会自动尝试环境变量、托管标识、Azure CLI 登录等多种来源if AZURESEARCH_API_KEY is None: credential DefaultAzureCredential() if use_async else DefaultAzureCredentialSync() else: credential AzureKeyCredential(AZURESEARCH_API_KEY)值得注意的是客户端与索引管理客户端会分别调用_create_credentials并在构造SearchClient时通过user_agentretrievalplugin标记请求来源见 datastore/providers/azuresearch_datastore.py。索引自动创建与字段设计插件启动时AzureSearchDataStore.__init__会先列出服务中已有的索引如果AZURESEARCH_INDEX尚不存在则调用_create_index自动创建如果已存在则直接复用并打印日志见 datastore/providers/azuresearch_datastore.py。自动创建的索引结构源码见 datastore/providers/azuresearch_datastore.py包含以下字段字段类型关键属性idString索引主键keytextString可搜索字段分析器为standard.luceneembeddingCollection(Single)向量字段维度取AZURESEARCH_DIMENSIONS绑定名为default的向量配置document_idString可过滤、可排序sourceString可过滤、可排序source_idString可过滤、可排序urlString普通字段created_atDateTimeOffset可过滤、可排序authorString可过滤、可排序向量索引配置采用HNSW 算法、余弦距离cosine源码注释还提示由于 OpenAI 的嵌入向量已归一化为单位长度也可以改用点积dot product度量vector_searchVectorSearch( algorithm_configurations[ HnswVectorSearchAlgorithmConfiguration( namedefault, kindhnsw, hnsw_parametersHnswParameters(metriccosine), ) ] )关于AZURESEARCH_DIMENSIONS需要特别注意它的默认值是256但必须与你实际使用的嵌入模型输出维度一致。例如 OpenAI 的text-embedding-ada-002输出 1536 维、text-embedding-3-small默认 1536 维可降维、text-embedding-3-large默认 3072 维可降维。如果索引已创建后想更换嵌入模型需要重建索引因为向量维度在索引定义中不可变。混合检索与 L2 语义重排的底层逻辑这是 Azure Cognitive Search 相对其他后端的核心亮点文档与源码都给出了明确的行为描述。混合检索Hybrid Search默认情况下AZURESEARCH_DISABLE_HYBRID未设置_single_query会同时提交文本查询和向量查询文本部分q query.query参与全文检索向量部分构造Vector(valuequery.embedding, kvector_top_k, fieldsFIELDS_EMBEDDING)当存在元数据过滤器时vector_top_k翻倍query.top_k * 2启用混合检索时再翻倍* 2以给融合阶段留出更多候选见 datastore/providers/azuresearch_datastore.py。如果设置AZURESEARCH_DISABLE_HYBRID1则q传None仅执行纯向量相似度检索。L2 语义重排Semantic Re-ranking设置AZURESEARCH_SEMANTIC_CONFIG后即启用 L2 重排但前提是你的 Cognitive Search 服务已显式启用 semantic search能力已为索引创建语义配置semantic configuration并把配置名称填入该环境变量。启用后检索请求会使用QueryType.SEMANTIC与query_languageAZURESEARCH_LANGUAGE同时为了让 L2 重排器有足够的候选输入源码会把vector_top_k至少提升到 50if AZURESEARCH_SEMANTIC_CONFIG ! None and not AZURESEARCH_DISABLE_HYBRID: vector_top_k max(50, vector_top_k) r await self.client.search( q, filterfilter, topquery.top_k, vectors[vector_q], query_typeQueryType.SEMANTIC, query_languageAZURESEARCH_LANGUAGE, semantic_configuration_nameAZURESEARCH_SEMANTIC_CONFIG, )从这段代码可以推断出两个要点其一L2 重排仅在混合或文本检索模式下生效纯向量模式下即便设置了AZURESEARCH_SEMANTIC_CONFIG也不会走语义查询分支其二重排会增加延迟与成本因此文档也提示这是一项需要显式开启的选项。插件在自动创建索引时如果指定了AZURESEARCH_SEMANTIC_CONFIG还会同步把text字段配置为优先内容字段prioritized_content_fields生成对应的SemanticSettings见 datastore/providers/azuresearch_datastore.py。复用既有索引字段名映射如果企业已有现成的 Azure Cognitive Search 索引字段与插件所需语义一致但命名不同无需重建索引只需通过AZURESEARCH_FIELDS_*系列环境变量把既有字段映射到插件字段。原文档给出的映射表如下右侧环境变量的默认值即为插件期望的字段名源码见 datastore/providers/azuresearch_datastore.py插件字段名可覆盖它的环境变量源码默认值idAZURESEARCH_FIELDS_IDidtextAZURESEARCH_FIELDS_TEXTtextembeddingAZURESEARCH_FIELDS_EMBEDDINGembeddingdocument_idAZURESEARCH_FIELDS_DOCUMENT_IDdocument_idsourceAZURESEARCH_FIELDS_SOURCEsourcesource_idAZURESEARCH_FIELDS_SOURCE_IDsource_idurlAZURESEARCH_FIELDS_URLurlcreated_atAZURESEARCH_FIELDS_CREATED_ATcreated_atauthorAZURESEARCH_FIELDS_AUTHORauthor例如若你的既有索引主键字段叫doc_key、正文字段叫content可设置export AZURESEARCH_FIELDS_IDdoc_key export AZURESEARCH_FIELDS_TEXTcontent这些映射变量在写入_upsert、查询_single_query与删除delete全链路中统一生效字段名被当作常量使用因此整个插件对索引字段的读写都遵循你的映射。元数据过滤OData 过滤表达式与日期格式插件支持按document_id、source、source_id、author以及created_at时间范围进行过滤这些条件最终由_translate_filter翻译成 Azure Search 的 OData 过滤表达式源码见 datastore/providers/azuresearch_datastore.py字符串字段使用eq比较且会先转义单引号转义为防止注入日期字段使用ge/le比较且必须符合 OData 时间格式\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z如2023-01-01T00:00:00Z否则抛出ValueError多个条件用and连接。对应的行为在 tests/datastore/providers/azuresearch/test_azuresearch_datastore.py 中有完整验证例如非法日期2023-01-01会触发ValueError单引号会被正确转义多条件组合会生成符合预期的 OData 字符串。写入、删除与查询的实现细节写入upsert插件会先把文档切块并生成嵌入向量再通过upload_documents批量写入。两个值得注意的细节ID 编码id会被base64.urlsafe_b64encode编码后写入索引这是为了规避 Azure Search 对文档主键字符集的限制源码注释明确说明了这一点见 datastore/providers/azuresearch_datastore.py批处理写入与删除均按每批 1000 条MAX_UPLOAD_BATCH_SIZE/MAX_DELETE_BATCH_SIZE分批执行部分失败会抛出异常提示上传失败的条数。删除delete支持三种方式——按文档 ID 列表、按元数据过滤器、或delete_all全量清空。使用过滤或全量删除时会先搜索符合条件的文档、分批删除并通过include_total_count判断是否还有剩余若因索引近实时刷新导致重复读到已删文档会短暂休眠 0.25 秒后重试见 datastore/providers/azuresearch_datastore.py。查询query_query通过asyncio.gather并发处理多个查询每个查询返回QueryResult其中命中结果DocumentChunkWithScore的score直接取自 Azure Search 的search.score字段见 datastore/providers/azuresearch_datastore.py。用测试用例验证三种检索模式仓库为 Azure Cognitive Search 提供了完整的集成测试tests/datastore/providers/azuresearch/test_azuresearch_datastore.py覆盖了插件的三种运行模式是验证配置正确性的最佳参考test_lifecycle_hybrid默认混合检索模式test_lifecycle_vectors_only设置AZURESEARCH_DISABLE_HYBRID1的纯向量模式test_lifecycle_semantic设置AZURESEARCH_SEMANTIC_CONFIG的语义重排模式。测试会真实执行索引创建、文档 upsert、带过滤/不带过滤的查询、时间范围过滤以及删除的完整生命周期见 tests/datastore/providers/azuresearch/test_azuresearch_datastore.py其中还特意使用了包含字符的文档 IDtest_id_2来验证 base64 编码对特殊字符的处理。运行测试前需要设置真实的AZURESEARCH_SERVICE环境变量测试中默认写入testindex作为索引名。启动与验证完成以上配置后按仓库 README 的通用步骤安装依赖Python 3.10 Poetry并确保DATASTOREazuresearch随后启动 FastAPI 服务即可。插件启动时会自动完成服务可用性检查与索引创建/复用日志中会打印Using existing index ...或Creating index ...信息可据此判断后端连接是否成功。之后便可通过标准 upsert/query API 上传文档并执行自然语言语义检索。小结将 ChatGPT Retrieval Plugin 接入 Azure Cognitive Search 的关键在于三件事一是正确设置AZURESEARCH_*系列环境变量并保证AZURESEARCH_DIMENSIONS与嵌入模型一致二是根据实际场景选择 API Key 或托管标识认证三是按需启用混合检索与 L2 语义重排并善用AZURESEARCH_FIELDS_*映射复用企业既有索引。结合仓库源码可以看到从索引自动创建、字段过滤到批处理与 ID 编码AzureSearchDataStore的实现都针对 Azure Search 的服务特性做了细致适配配合 测试用例 可以在上线前充分验证各模式行为。赞分享RAGAI Agent后端向量数据库【免费下载链接】chatgpt-retrieval-pluginThe ChatGPT Retrieval Plugin lets you easily find personal or work documents by asking questions in natural language.项目地址https://gitcode.com/gh_mirrors/ch/chatgpt-retrieval-plugin点击查看免费下载相关推荐LangChain4j 集成 Azure AI Search从向量检索到混合检索与重排的完整实践指南LangChain4j 集成 Azure AI Search从向量检索到混合检索与重排的完整实践指南 Azure AI Search前身为 Azure Co人工智能AI 应用RAGAI Agent工具调用如何快速部署Azure搜索服务完整的Azure Cognitive Search入门指南如何快速部署Azure搜索服务完整的Azure Cognitive Search入门指南 想要在Azure上快速搭建企业级搜索服务吗Azure Cognit示例工程ChatGPT Retrieval Plugin构建智能文档检索系统的完整指南ChatGPT Retrieval Plugin构建智能文档检索系统的完整指南 ChatGPT Retrieval Plugin 是一个革命性的开源项目由RAGAI Agent后端向量数据库上一篇5分钟部署MiniCPM-V本地多模态推理全攻略从0到1跑通图片问答下一篇如何通过游戏化编程彻底改变你的学习体验CodeCombat终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
