Haystack 集成 Azure AI Search 完全指南AzureAISearchDocumentStore 与 EmbeddingRetriever 实战详解【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackAzure AI Search原 Azure Cognitive Search是微软 Azure 云上企业级的搜索与检索服务专为构建基于 RAG 的应用而设计内置了与 LLM 生态的深度集成能力。Haystack 通过azure-ai-search-haystack集成包将 Azure AI Search 的能力封装为标准的 Haystack 组件——AzureAISearchDocumentStore文档存储与AzureAISearchEmbeddingRetriever向量检索器使其可以无缝嵌入 Haystack 的 Pipeline 编排体系。本文基于 Haystack 仓库中 version-2.18 的官方 API 参考文档docs-website/reference_versioned_docs/version-2.18/integrations-api/azure_ai_search.md逐项拆解这两大组件的全部构造函数参数、方法签名与使用限制并结合仓库内配套的使用指南与源码证据给出可直接复制运行的索引与检索实战方案。读完本文你将掌握在 Haystack 中配置 Azure AI Search 索引、写入与删除文档、执行向量/BM25/混合检索、以及通过元数据过滤精确缩小检索范围的完整能力。集成概览Document Store 与三种 RetrieverAzure AI Search 集成以AzureAISearchDocumentStore为数据底座围绕它提供了三种 Retriever 组件每种组件都基于 Azure AI Search API 实现可依据检索场景灵活选用详见配套文档 docs-website/versioned_docs/version-2.18/document-stores/azureaisearchdocumentstore.mdxAzureAISearchEmbeddingRetriever接受单条查询的 embedding 向量作为输入返回与之最相似的文档列表。查询必须先经 Embedder 组件如文本嵌入器向量化后才能传入。AzureAISearchBM25Retriever基于关键词的检索器使用 BM25 算法计算查询与文档的词项加权重合度直接以文本查询字符串为输入。AzureAISearchHybridRetriever在同一请求中并行执行向量检索与 BM25 全文检索再通过 Reciprocal Rank FusionRRF对两个结果集进行合并重排得到更相关的统一结果。其中AzureAISearchEmbeddingRetriever与AzureAISearchDocumentStore的完整 API 说明位于本文档 azure_ai_search.md 中下文将以其为核心逐一深入。环境准备与安装使用该集成需要满足两个前置条件一个有效的 Azure 订阅并且已部署 Azure AI Search 服务实例配套文档 azureaisearchdocumentstore.mdx 明确要求。安装集成包pip install azure-ai-search-haystack认证方式与环境变量AzureAISearchDocumentStore初始化时通过两个环境变量完成认证环境变量是否必填作用AZURE_AI_SEARCH_ENDPOINT必填strictTrueAzure AI Search 服务的 URL 端点AZURE_AI_SEARCH_API_KEY可选strictFalse用于认证的 API 密钥若未提供AZURE_AI_SEARCH_API_KEY文档存储会回退到DefaultAzureCredential尝试通过浏览器完成交互式认证。此外构造参数中的azure_token_credential允许直接传入一个 AzureTokenCredential实例且当它存在时优先级高于api_key。AzureAISearchDocumentStore以 Azure AI Search 为后端的文档存储AzureAISearchDocumentStore是 Haystack 与 Azure AI Search 之间的桥梁。它使用 Azure AI Search 索引作为文档的持久化载体在初始化时若给定index_name对应的索引不存在会自动创建若已存在则直接复用。构造函数与全部参数解析__init__( *, api_key: Secret Secret.from_env_var( AZURE_AI_SEARCH_API_KEY, strictFalse ), azure_endpoint: Secret Secret.from_env_var( AZURE_AI_SEARCH_ENDPOINT, strictTrue ), index_name: str default, embedding_dimension: int 768, metadata_fields: dict[str, SearchField | type] | None None, vector_search_configuration: VectorSearch | None None, include_search_metadata: bool False, azure_token_credential: TokenCredential | None None, **index_creation_kwargs: Any ) - None各参数的含义与使用要点azure_endpointSecretAzure AI Search 服务的 URL 端点默认从AZURE_AI_SEARCH_ENDPOINT环境变量读取。api_keySecret认证 API 密钥默认从AZURE_AI_SEARCH_API_KEY环境变量读取非严格模式。index_namestr默认defaultAzure AI Search 中的索引名。若索引不存在会在初始化时自动创建。embedding_dimensionint默认768嵌入向量的维度创建索引时用于声明向量字段的维数必须与所选嵌入模型的实际输出维度一致如sentence-transformers/all-mpnet-base-v2输出 768 维而部分模型为 384 维。metadata_fieldsdict 或 None元数据字段名到字段定义的映射用于在索引中声明可搜索、可过滤的元数据字段。每个字段有两种定义方式传入一个SearchField对象精确控制字段的类型、是否可搜索searchable、是否可过滤filterable等配置直接传入一个 Python 类型str、bool、int、float、datetime自动创建一个简单的可过滤字段。官方示例metadata_fields{ Title: SearchField( nameTitle, typeEdm.String, searchableTrue, filterableTrue ), Pages: int }重要限制Azure AI Search 索引的字段在创建后无法通过 API 修改。因此除默认字段外的任何附加字段必须在文档存储初始化时就通过metadata_fields声明。若确实需要调整可以借助 Azure AI 门户在不删除索引的前提下修改字段。vector_search_configurationVectorSearch 或 None向量搜索相关配置。默认配置使用 HNSW 算法配合余弦相似度cosine similarity处理向量检索可通过该参数自定义。include_search_metadatabool默认False是否将 Azure AI Search 返回的搜索元数据写入结果文档的meta字段。设为True后返回文档的meta中会包含search.score、search.reranker_score、search.highlights、search.captions等 Azure AI Search 返回的字段。azure_token_credentialTokenCredential 或 NoneAzureTokenCredential实例用于请求认证提供时优先于api_key。index_creation_kwargsAny创建索引时透传给SearchIndex类的可选关键字参数常用两项semantic_search定义索引的语义配置SemanticSearch这是启用索引语义检索能力的前提similarity匹配文档时的相似度评分算法类型。只能在索引创建时定义已创建的索引无法修改。属性与生命周期管理client返回 AzureSearchClient实例。这是一个惰性属性——首次访问时若索引不存在会自动创建之后所有读写操作都经由该客户端完成。to_dict()将组件序列化为字典便于 Pipeline 的 YAML 持久化与反序列化。from_dict(data)从字典反序列化出组件实例类方法。close()释放底层文档存储持有的同步资源。Haystack 中实现了资源生命周期管理协议的组件可在 Pipeline 运行结束后被统一回收可对照仓库中 haystack/core/component 的组件协议与生命周期机制理解。文档计数与元数据统计文档存储提供了一组用于了解索引内容与元数据分布的统计方法count_documents() - int返回索引中的文档总数。需要注意受 Azure 搜索索引同步延迟影响刚写入后立即计数可能返回 0应给予索引一定的刷新时间。count_documents_by_filter(filters) - int返回匹配指定过滤条件的文档数量。过滤语法遵循 Haystack 的元数据过滤规范。count_unique_metadata_by_filter(filters, metadata_fields) - dict[str, int]对匹配过滤条件的文档统计每个指定元数据字段的唯一值个数返回字段名到计数int的映射。get_metadata_fields_info() - dict[str, dict[str, str]]返回索引中各元数据字段的类型信息字段名映射到类型描述。get_metadata_field_min_max(metadata_field) - dict[str, Any]返回指定元数据字段的最小值与最大值结果为包含min与max两个键的字典。get_metadata_field_unique_values(metadata_field, search_termNone, from_0, size10, filtersNone) - tuple[list[Any], int]分页获取某个元数据字段的唯一值列表支持search_term可选搜索词对唯一值做过滤from_分页起始偏移量size返回值的数量filters可选过滤条件限制纳入统计的文档范围。返回(唯一值列表, 匹配总数)二元组。若该字段未在索引 schema 中定义则返回([], 0)。这些统计方法可支撑知识库分析、数据探查data exploration等场景例如生成目录式文档检索或内容分类统计。文档写入、删除与更新写入文档write_documents( documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE ) - intdocuments要写入索引的Document列表Haystack 的Document数据类定义见 haystack/dataclasses/document.py。policy处理重复文档的策略。DuplicatePolicy枚举定义在 haystack/document_stores/types/policy.py常见取值包括NONE默认、OVERWRITE、SKIP与FAIL。BM25 检索器的配套示例azureaisearchbm25retriever.mdx中提到AzureAISearchDocumentStore的默认策略为DuplicatePolicy.OVERWRITE。返回实际写入索引的文档数量。异常情况文档不是Document类型时抛出ValueError文档 id 不是字符串时抛出TypeError。删除文档delete_documents(document_ids: list[str]) - None按 id 列表删除索引中的文档。delete_all_documents(recreate_index: bool False) - None清空全部文档。recreate_indexTrue时删除索引并按原 schema 重建False时保留索引结构、仅清空文档。delete_by_filter(filters) - int删除匹配过滤条件的全部文档返回删除数量。Azure AI Search不支持服务端按查询删除因此该方法实现为先搜索出匹配文档再通过批量删除操作完成。update_by_filter(filters, meta) - int更新匹配过滤条件文档的字段返回更新数量。同样由于Azure AI Search 不支持服务端按查询更新实现为先搜索匹配文档、再以 merge 操作更新。meta中的字段必须已存在于索引 schema 中。文档查询get_documents_by_id(document_ids) - list[Document]按 id 批量获取文档。search_documents(search_text*, top_k10) - list[Document]按文本搜索匹配的文档search_text缺省为*时返回全部文档。filter_documents(filtersNone) - list[Document]按过滤条件字典形式遵循 Haystack 元数据过滤规范返回文档。query_sql(query) - Any执行 SQL 查询。Azure AI Search 后端不支持 SQL 查询调用此方法不会得到有效结果——这是该后端与关系型/图数据库后端的显著差异。AzureAISearchEmbeddingRetriever向量相似度检索器AzureAISearchEmbeddingRetriever使用向量相似度指标从AzureAISearchDocumentStore中检索文档。它必须连接到AzureAISearchDocumentStore才能运行且输入是查询的向量表示而非原始文本。构造函数与参数解析__init__( *, document_store: AzureAISearchDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, filter_policy: str | FilterPolicy FilterPolicy.REPLACE, **kwargs: Any ) - Nonedocument_store必填一个AzureAISearchDocumentStore实例检索目标。filtersdict 或 None从文档存储获取文档时应用的过滤条件。top_kint默认10最多返回的文档数量。filter_policystr 或FilterPolicy默认FilterPolicy.REPLACE过滤器合并策略决定运行时传入的 filters 如何与初始化时的 filters 组合。FilterPolicy定义见 haystack/document_stores/types/filter_policy.py典型取值包括REPLACE运行时过滤条件替换初始化过滤条件与MERGE两者合并等是 Haystack 各文档存储检索器的统一约定。**kwargs透传给 Azure AI Search 搜索端点的附加参数官方文档明确支持的关键参数query_type查询类型字符串可选simple、full和semanticsemantic_configuration_name处理语义查询时使用的语义配置名称需在索引中预先配置语义配置。核心方法run(query_embedding, filtersNone, top_kNone) - dict[str, list[Document]]query_embeddinglist[float]必填查询的向量表示来自 Text Embedder 的输出。filtersdict 或 None运行时过滤条件。其应用方式取决于初始化时选择的filter_policy。top_kint 或 None运行时覆盖的最大返回数量。返回值包含documents键的字典值为检索到的Document列表。to_dict()/from_dict(data)与文档存储一致支持组件的序列化与反序列化可配合 Haystack 的 YAML 编排haystack/marshal 提供了 YAML 编解码支持。close()释放底层文档存储的同步资源。独立使用示例from haystack_integrations.document_stores.azure_ai_search import ( AzureAISearchDocumentStore, ) from haystack_integrations.components.retrievers.azure_ai_search import ( AzureAISearchEmbeddingRetriever, ) document_store AzureAISearchDocumentStore() retriever AzureAISearchEmbeddingRetriever(document_storedocument_store) # 示例查询384 维的占位向量 retriever.run(query_embedding[0.1] * 384)在 Pipeline 中使用索引管线 查询管线完整使用向量检索需要两条 Pipeline 协作示例源自配套文档 azureaisearchembeddingretriever.mdx索引管线文档经SentenceTransformersDocumentEmbedder向量化后由DocumentWriter写入AzureAISearchDocumentStore查询管线查询文本经SentenceTransformersTextEmbedder得到向量连接到AzureAISearchEmbeddingRetriever完成检索。from haystack import Document, Pipeline from haystack.components.embedders import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.writers import DocumentWriter from haystack_integrations.components.retrievers.azure_ai_search import ( AzureAISearchEmbeddingRetriever, ) from haystack_integrations.document_stores.azure_ai_search import ( AzureAISearchDocumentStore, ) document_store AzureAISearchDocumentStore(index_nameretrieval-example) model sentence-transformers/all-mpnet-base-v2 documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document( contentElephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors., ), Document( contentIn certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves., ), ] document_embedder SentenceTransformersDocumentEmbedder(modelmodel) document_embedder.warm_up() ## Indexing Pipeline indexing_pipeline Pipeline() indexing_pipeline.add_component(instancedocument_embedder, namedoc_embedder) indexing_pipeline.add_component( instanceDocumentWriter(document_storedocument_store), namedoc_writer, ) indexing_pipeline.connect(doc_embedder, doc_writer) indexing_pipeline.run({doc_embedder: {documents: documents}}) ## Query Pipeline query_pipeline Pipeline() query_pipeline.add_component( text_embedder, SentenceTransformersTextEmbedder(modelmodel), ) query_pipeline.add_component( retriever, AzureAISearchEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query How many languages are there? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])上述代码中SentenceTransformersDocumentEmbedder、SentenceTransformersTextEmbedder等嵌入器组件位于 haystack/components/embeddersDocumentWriter位于 haystack/components/writers都是 Haystack 核心库自带的组件。三种 Retriever 的选型对比维度AzureAISearchEmbeddingRetrieverAzureAISearchBM25RetrieverAzureAISearchHybridRetriever输入query_embedding向量列表query文本字符串queryquery_embedding检索机制向量相似度默认 HNSW 余弦相似度BM25 词项加权重合度向量 BM25 并行执行RRF 融合重排语义排序semantic reranking不支持支持若索引含语义配置支持若索引含语义配置适用场景语义相似检索、embedding 检索管线关键词检索、布尔表达式查询需要兼顾语义与关键词的相关性场景补充要点语义排序与向量检索互斥Azure AI Search 的语义排序semantic ranking能力不适用于纯向量检索。要在检索流程中加入语义排序应改用AzureAISearchBM25Retriever或AzureAISearchHybridRetriever并在索引初始化时通过index_creation_kwargs传入SemanticSearch语义配置详见配套文档 azureaisearchdocumentstore.mdx 与 azureaisearchhybridretriever.mdx。BM25 的查询语法AzureAISearchBM25Retriever接受文本查询也支持布尔运算符组合词项例如pool、pool spa、pool spa airport都是合法查询。混合检索的融合机制AzureAISearchHybridRetriever在单次请求中并行执行全部子查询结果通过 Reciprocal Rank FusionRRF合并重排形成统一结果集。元数据过滤与 FilterPolicy文档存储与检索器都支持基于元数据的过滤用于将检索范围精确收窄到满足条件的文档子集过滤条件以字典形式传入如{Title: {$eq: Haystack Guide}}语法遵循 Haystack 的元数据过滤规范支持等值、范围、逻辑组合等算子。过滤依赖索引中的字段 schema——在AzureAISearchDocumentStore初始化时通过metadata_fields声明为filterable的字段才能参与过滤。这也再次印证了“索引字段创建后不可变附加字段必须在初始化时声明”的设计约束。AzureAISearchEmbeddingRetriever的filter_policy参数控制初始化时 filters 与run()运行时 filters 的合并方式默认FilterPolicy.REPLACE表示运行时过滤条件整体替换初始化条件如需叠加可切换为合并策略。FilterPolicy的具体实现见 haystack/document_stores/types/filter_policy.py。delete_by_filter、update_by_filter、count_documents_by_filter等方法均复用同一套过滤语法但由于 Azure AI Search 不支持服务端按查询删除/更新这两类操作内部会先执行搜索命中匹配文档再进行批量删除或 merge 更新。实践注意事项与已知限制基于 API 参考文档与配套文档以下是使用本集成时务必留意的关键点索引字段不可变性Azure AI Search 索引字段创建后无法通过 API 修改。任何附加字段元数据字段、语义配置、相似度算法都必须在AzureAISearchDocumentStore初始化时通过metadata_fields与index_creation_kwargs声明。如需事后调整只能通过 Azure AI 门户操作或删除索引重建。索引同步延迟受 Azure 搜索索引延迟影响文档写入后立即执行count_documents()可能返回 0检索结果也可能短暂滞后。对实时性要求高的场景需在写入后预留刷新时间。认证优先级azure_token_credentialapi_key环境变量AZURE_AI_SEARCH_API_KEYDefaultAzureCredential浏览器交互式认证。生产环境推荐使用服务主体或托管身份避免硬编码密钥。向量维度一致性embedding_dimension必须与嵌入模型实际输出维度一致否则索引创建或检索会失败。修改模型时需要同步调整文档存储配置因字段不可变通常需重建索引。语义排序的适用范围纯向量检索EmbeddingRetriever无法使用 Azure 的语义排序能力需要语义排序时应选择 BM25 或 Hybrid 检索器并在索引上预先配置SemanticSearch。不支持的能力query_sql在本后端不可用Azure AI Search 不支持 SQL按查询删除与按查询更新需由客户端分两步完成。总结AzureAISearchDocumentStore与AzureAISearchEmbeddingRetriever构成了 Haystack 在 Azure 云上搭建 RAG 与语义检索应用的核心组件对文档存储负责索引的自动创建、文档的写入/删除/更新以及丰富的元数据统计查询检索器负责将查询向量映射为 Top-K 相关文档二者通过 Haystack Pipeline 与 Text Embedder、PromptBuilder、OpenAIGenerator 等标准组件自由编排。理解索引字段不可变性、向量维度一致性、认证优先级与三种 Retriever 的能力边界是构建稳定可上线的 Azure AI Search 检索系统的关键。相关组件的详细 API 可随时查阅 version-2.18 API 参考并对照配套的 Document Store 指南 与 Embedding Retriever 指南 实践。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Haystack 集成 Azure AI Search 完全指南：AzureAISearchDocumentStore 与 EmbeddingRetriever 实战详解
Haystack 集成 Azure AI Search 完全指南AzureAISearchDocumentStore 与 EmbeddingRetriever 实战详解【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackAzure AI Search原 Azure Cognitive Search是微软 Azure 云上企业级的搜索与检索服务专为构建基于 RAG 的应用而设计内置了与 LLM 生态的深度集成能力。Haystack 通过azure-ai-search-haystack集成包将 Azure AI Search 的能力封装为标准的 Haystack 组件——AzureAISearchDocumentStore文档存储与AzureAISearchEmbeddingRetriever向量检索器使其可以无缝嵌入 Haystack 的 Pipeline 编排体系。本文基于 Haystack 仓库中 version-2.18 的官方 API 参考文档docs-website/reference_versioned_docs/version-2.18/integrations-api/azure_ai_search.md逐项拆解这两大组件的全部构造函数参数、方法签名与使用限制并结合仓库内配套的使用指南与源码证据给出可直接复制运行的索引与检索实战方案。读完本文你将掌握在 Haystack 中配置 Azure AI Search 索引、写入与删除文档、执行向量/BM25/混合检索、以及通过元数据过滤精确缩小检索范围的完整能力。集成概览Document Store 与三种 RetrieverAzure AI Search 集成以AzureAISearchDocumentStore为数据底座围绕它提供了三种 Retriever 组件每种组件都基于 Azure AI Search API 实现可依据检索场景灵活选用详见配套文档 docs-website/versioned_docs/version-2.18/document-stores/azureaisearchdocumentstore.mdxAzureAISearchEmbeddingRetriever接受单条查询的 embedding 向量作为输入返回与之最相似的文档列表。查询必须先经 Embedder 组件如文本嵌入器向量化后才能传入。AzureAISearchBM25Retriever基于关键词的检索器使用 BM25 算法计算查询与文档的词项加权重合度直接以文本查询字符串为输入。AzureAISearchHybridRetriever在同一请求中并行执行向量检索与 BM25 全文检索再通过 Reciprocal Rank FusionRRF对两个结果集进行合并重排得到更相关的统一结果。其中AzureAISearchEmbeddingRetriever与AzureAISearchDocumentStore的完整 API 说明位于本文档 azure_ai_search.md 中下文将以其为核心逐一深入。环境准备与安装使用该集成需要满足两个前置条件一个有效的 Azure 订阅并且已部署 Azure AI Search 服务实例配套文档 azureaisearchdocumentstore.mdx 明确要求。安装集成包pip install azure-ai-search-haystack认证方式与环境变量AzureAISearchDocumentStore初始化时通过两个环境变量完成认证环境变量是否必填作用AZURE_AI_SEARCH_ENDPOINT必填strictTrueAzure AI Search 服务的 URL 端点AZURE_AI_SEARCH_API_KEY可选strictFalse用于认证的 API 密钥若未提供AZURE_AI_SEARCH_API_KEY文档存储会回退到DefaultAzureCredential尝试通过浏览器完成交互式认证。此外构造参数中的azure_token_credential允许直接传入一个 AzureTokenCredential实例且当它存在时优先级高于api_key。AzureAISearchDocumentStore以 Azure AI Search 为后端的文档存储AzureAISearchDocumentStore是 Haystack 与 Azure AI Search 之间的桥梁。它使用 Azure AI Search 索引作为文档的持久化载体在初始化时若给定index_name对应的索引不存在会自动创建若已存在则直接复用。构造函数与全部参数解析__init__( *, api_key: Secret Secret.from_env_var( AZURE_AI_SEARCH_API_KEY, strictFalse ), azure_endpoint: Secret Secret.from_env_var( AZURE_AI_SEARCH_ENDPOINT, strictTrue ), index_name: str default, embedding_dimension: int 768, metadata_fields: dict[str, SearchField | type] | None None, vector_search_configuration: VectorSearch | None None, include_search_metadata: bool False, azure_token_credential: TokenCredential | None None, **index_creation_kwargs: Any ) - None各参数的含义与使用要点azure_endpointSecretAzure AI Search 服务的 URL 端点默认从AZURE_AI_SEARCH_ENDPOINT环境变量读取。api_keySecret认证 API 密钥默认从AZURE_AI_SEARCH_API_KEY环境变量读取非严格模式。index_namestr默认defaultAzure AI Search 中的索引名。若索引不存在会在初始化时自动创建。embedding_dimensionint默认768嵌入向量的维度创建索引时用于声明向量字段的维数必须与所选嵌入模型的实际输出维度一致如sentence-transformers/all-mpnet-base-v2输出 768 维而部分模型为 384 维。metadata_fieldsdict 或 None元数据字段名到字段定义的映射用于在索引中声明可搜索、可过滤的元数据字段。每个字段有两种定义方式传入一个SearchField对象精确控制字段的类型、是否可搜索searchable、是否可过滤filterable等配置直接传入一个 Python 类型str、bool、int、float、datetime自动创建一个简单的可过滤字段。官方示例metadata_fields{ Title: SearchField( nameTitle, typeEdm.String, searchableTrue, filterableTrue ), Pages: int }重要限制Azure AI Search 索引的字段在创建后无法通过 API 修改。因此除默认字段外的任何附加字段必须在文档存储初始化时就通过metadata_fields声明。若确实需要调整可以借助 Azure AI 门户在不删除索引的前提下修改字段。vector_search_configurationVectorSearch 或 None向量搜索相关配置。默认配置使用 HNSW 算法配合余弦相似度cosine similarity处理向量检索可通过该参数自定义。include_search_metadatabool默认False是否将 Azure AI Search 返回的搜索元数据写入结果文档的meta字段。设为True后返回文档的meta中会包含search.score、search.reranker_score、search.highlights、search.captions等 Azure AI Search 返回的字段。azure_token_credentialTokenCredential 或 NoneAzureTokenCredential实例用于请求认证提供时优先于api_key。index_creation_kwargsAny创建索引时透传给SearchIndex类的可选关键字参数常用两项semantic_search定义索引的语义配置SemanticSearch这是启用索引语义检索能力的前提similarity匹配文档时的相似度评分算法类型。只能在索引创建时定义已创建的索引无法修改。属性与生命周期管理client返回 AzureSearchClient实例。这是一个惰性属性——首次访问时若索引不存在会自动创建之后所有读写操作都经由该客户端完成。to_dict()将组件序列化为字典便于 Pipeline 的 YAML 持久化与反序列化。from_dict(data)从字典反序列化出组件实例类方法。close()释放底层文档存储持有的同步资源。Haystack 中实现了资源生命周期管理协议的组件可在 Pipeline 运行结束后被统一回收可对照仓库中 haystack/core/component 的组件协议与生命周期机制理解。文档计数与元数据统计文档存储提供了一组用于了解索引内容与元数据分布的统计方法count_documents() - int返回索引中的文档总数。需要注意受 Azure 搜索索引同步延迟影响刚写入后立即计数可能返回 0应给予索引一定的刷新时间。count_documents_by_filter(filters) - int返回匹配指定过滤条件的文档数量。过滤语法遵循 Haystack 的元数据过滤规范。count_unique_metadata_by_filter(filters, metadata_fields) - dict[str, int]对匹配过滤条件的文档统计每个指定元数据字段的唯一值个数返回字段名到计数int的映射。get_metadata_fields_info() - dict[str, dict[str, str]]返回索引中各元数据字段的类型信息字段名映射到类型描述。get_metadata_field_min_max(metadata_field) - dict[str, Any]返回指定元数据字段的最小值与最大值结果为包含min与max两个键的字典。get_metadata_field_unique_values(metadata_field, search_termNone, from_0, size10, filtersNone) - tuple[list[Any], int]分页获取某个元数据字段的唯一值列表支持search_term可选搜索词对唯一值做过滤from_分页起始偏移量size返回值的数量filters可选过滤条件限制纳入统计的文档范围。返回(唯一值列表, 匹配总数)二元组。若该字段未在索引 schema 中定义则返回([], 0)。这些统计方法可支撑知识库分析、数据探查data exploration等场景例如生成目录式文档检索或内容分类统计。文档写入、删除与更新写入文档write_documents( documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE ) - intdocuments要写入索引的Document列表Haystack 的Document数据类定义见 haystack/dataclasses/document.py。policy处理重复文档的策略。DuplicatePolicy枚举定义在 haystack/document_stores/types/policy.py常见取值包括NONE默认、OVERWRITE、SKIP与FAIL。BM25 检索器的配套示例azureaisearchbm25retriever.mdx中提到AzureAISearchDocumentStore的默认策略为DuplicatePolicy.OVERWRITE。返回实际写入索引的文档数量。异常情况文档不是Document类型时抛出ValueError文档 id 不是字符串时抛出TypeError。删除文档delete_documents(document_ids: list[str]) - None按 id 列表删除索引中的文档。delete_all_documents(recreate_index: bool False) - None清空全部文档。recreate_indexTrue时删除索引并按原 schema 重建False时保留索引结构、仅清空文档。delete_by_filter(filters) - int删除匹配过滤条件的全部文档返回删除数量。Azure AI Search不支持服务端按查询删除因此该方法实现为先搜索出匹配文档再通过批量删除操作完成。update_by_filter(filters, meta) - int更新匹配过滤条件文档的字段返回更新数量。同样由于Azure AI Search 不支持服务端按查询更新实现为先搜索匹配文档、再以 merge 操作更新。meta中的字段必须已存在于索引 schema 中。文档查询get_documents_by_id(document_ids) - list[Document]按 id 批量获取文档。search_documents(search_text*, top_k10) - list[Document]按文本搜索匹配的文档search_text缺省为*时返回全部文档。filter_documents(filtersNone) - list[Document]按过滤条件字典形式遵循 Haystack 元数据过滤规范返回文档。query_sql(query) - Any执行 SQL 查询。Azure AI Search 后端不支持 SQL 查询调用此方法不会得到有效结果——这是该后端与关系型/图数据库后端的显著差异。AzureAISearchEmbeddingRetriever向量相似度检索器AzureAISearchEmbeddingRetriever使用向量相似度指标从AzureAISearchDocumentStore中检索文档。它必须连接到AzureAISearchDocumentStore才能运行且输入是查询的向量表示而非原始文本。构造函数与参数解析__init__( *, document_store: AzureAISearchDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, filter_policy: str | FilterPolicy FilterPolicy.REPLACE, **kwargs: Any ) - Nonedocument_store必填一个AzureAISearchDocumentStore实例检索目标。filtersdict 或 None从文档存储获取文档时应用的过滤条件。top_kint默认10最多返回的文档数量。filter_policystr 或FilterPolicy默认FilterPolicy.REPLACE过滤器合并策略决定运行时传入的 filters 如何与初始化时的 filters 组合。FilterPolicy定义见 haystack/document_stores/types/filter_policy.py典型取值包括REPLACE运行时过滤条件替换初始化过滤条件与MERGE两者合并等是 Haystack 各文档存储检索器的统一约定。**kwargs透传给 Azure AI Search 搜索端点的附加参数官方文档明确支持的关键参数query_type查询类型字符串可选simple、full和semanticsemantic_configuration_name处理语义查询时使用的语义配置名称需在索引中预先配置语义配置。核心方法run(query_embedding, filtersNone, top_kNone) - dict[str, list[Document]]query_embeddinglist[float]必填查询的向量表示来自 Text Embedder 的输出。filtersdict 或 None运行时过滤条件。其应用方式取决于初始化时选择的filter_policy。top_kint 或 None运行时覆盖的最大返回数量。返回值包含documents键的字典值为检索到的Document列表。to_dict()/from_dict(data)与文档存储一致支持组件的序列化与反序列化可配合 Haystack 的 YAML 编排haystack/marshal 提供了 YAML 编解码支持。close()释放底层文档存储的同步资源。独立使用示例from haystack_integrations.document_stores.azure_ai_search import ( AzureAISearchDocumentStore, ) from haystack_integrations.components.retrievers.azure_ai_search import ( AzureAISearchEmbeddingRetriever, ) document_store AzureAISearchDocumentStore() retriever AzureAISearchEmbeddingRetriever(document_storedocument_store) # 示例查询384 维的占位向量 retriever.run(query_embedding[0.1] * 384)在 Pipeline 中使用索引管线 查询管线完整使用向量检索需要两条 Pipeline 协作示例源自配套文档 azureaisearchembeddingretriever.mdx索引管线文档经SentenceTransformersDocumentEmbedder向量化后由DocumentWriter写入AzureAISearchDocumentStore查询管线查询文本经SentenceTransformersTextEmbedder得到向量连接到AzureAISearchEmbeddingRetriever完成检索。from haystack import Document, Pipeline from haystack.components.embedders import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.writers import DocumentWriter from haystack_integrations.components.retrievers.azure_ai_search import ( AzureAISearchEmbeddingRetriever, ) from haystack_integrations.document_stores.azure_ai_search import ( AzureAISearchDocumentStore, ) document_store AzureAISearchDocumentStore(index_nameretrieval-example) model sentence-transformers/all-mpnet-base-v2 documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document( contentElephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors., ), Document( contentIn certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves., ), ] document_embedder SentenceTransformersDocumentEmbedder(modelmodel) document_embedder.warm_up() ## Indexing Pipeline indexing_pipeline Pipeline() indexing_pipeline.add_component(instancedocument_embedder, namedoc_embedder) indexing_pipeline.add_component( instanceDocumentWriter(document_storedocument_store), namedoc_writer, ) indexing_pipeline.connect(doc_embedder, doc_writer) indexing_pipeline.run({doc_embedder: {documents: documents}}) ## Query Pipeline query_pipeline Pipeline() query_pipeline.add_component( text_embedder, SentenceTransformersTextEmbedder(modelmodel), ) query_pipeline.add_component( retriever, AzureAISearchEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query How many languages are there? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])上述代码中SentenceTransformersDocumentEmbedder、SentenceTransformersTextEmbedder等嵌入器组件位于 haystack/components/embeddersDocumentWriter位于 haystack/components/writers都是 Haystack 核心库自带的组件。三种 Retriever 的选型对比维度AzureAISearchEmbeddingRetrieverAzureAISearchBM25RetrieverAzureAISearchHybridRetriever输入query_embedding向量列表query文本字符串queryquery_embedding检索机制向量相似度默认 HNSW 余弦相似度BM25 词项加权重合度向量 BM25 并行执行RRF 融合重排语义排序semantic reranking不支持支持若索引含语义配置支持若索引含语义配置适用场景语义相似检索、embedding 检索管线关键词检索、布尔表达式查询需要兼顾语义与关键词的相关性场景补充要点语义排序与向量检索互斥Azure AI Search 的语义排序semantic ranking能力不适用于纯向量检索。要在检索流程中加入语义排序应改用AzureAISearchBM25Retriever或AzureAISearchHybridRetriever并在索引初始化时通过index_creation_kwargs传入SemanticSearch语义配置详见配套文档 azureaisearchdocumentstore.mdx 与 azureaisearchhybridretriever.mdx。BM25 的查询语法AzureAISearchBM25Retriever接受文本查询也支持布尔运算符组合词项例如pool、pool spa、pool spa airport都是合法查询。混合检索的融合机制AzureAISearchHybridRetriever在单次请求中并行执行全部子查询结果通过 Reciprocal Rank FusionRRF合并重排形成统一结果集。元数据过滤与 FilterPolicy文档存储与检索器都支持基于元数据的过滤用于将检索范围精确收窄到满足条件的文档子集过滤条件以字典形式传入如{Title: {$eq: Haystack Guide}}语法遵循 Haystack 的元数据过滤规范支持等值、范围、逻辑组合等算子。过滤依赖索引中的字段 schema——在AzureAISearchDocumentStore初始化时通过metadata_fields声明为filterable的字段才能参与过滤。这也再次印证了“索引字段创建后不可变附加字段必须在初始化时声明”的设计约束。AzureAISearchEmbeddingRetriever的filter_policy参数控制初始化时 filters 与run()运行时 filters 的合并方式默认FilterPolicy.REPLACE表示运行时过滤条件整体替换初始化条件如需叠加可切换为合并策略。FilterPolicy的具体实现见 haystack/document_stores/types/filter_policy.py。delete_by_filter、update_by_filter、count_documents_by_filter等方法均复用同一套过滤语法但由于 Azure AI Search 不支持服务端按查询删除/更新这两类操作内部会先执行搜索命中匹配文档再进行批量删除或 merge 更新。实践注意事项与已知限制基于 API 参考文档与配套文档以下是使用本集成时务必留意的关键点索引字段不可变性Azure AI Search 索引字段创建后无法通过 API 修改。任何附加字段元数据字段、语义配置、相似度算法都必须在AzureAISearchDocumentStore初始化时通过metadata_fields与index_creation_kwargs声明。如需事后调整只能通过 Azure AI 门户操作或删除索引重建。索引同步延迟受 Azure 搜索索引延迟影响文档写入后立即执行count_documents()可能返回 0检索结果也可能短暂滞后。对实时性要求高的场景需在写入后预留刷新时间。认证优先级azure_token_credentialapi_key环境变量AZURE_AI_SEARCH_API_KEYDefaultAzureCredential浏览器交互式认证。生产环境推荐使用服务主体或托管身份避免硬编码密钥。向量维度一致性embedding_dimension必须与嵌入模型实际输出维度一致否则索引创建或检索会失败。修改模型时需要同步调整文档存储配置因字段不可变通常需重建索引。语义排序的适用范围纯向量检索EmbeddingRetriever无法使用 Azure 的语义排序能力需要语义排序时应选择 BM25 或 Hybrid 检索器并在索引上预先配置SemanticSearch。不支持的能力query_sql在本后端不可用Azure AI Search 不支持 SQL按查询删除与按查询更新需由客户端分两步完成。总结AzureAISearchDocumentStore与AzureAISearchEmbeddingRetriever构成了 Haystack 在 Azure 云上搭建 RAG 与语义检索应用的核心组件对文档存储负责索引的自动创建、文档的写入/删除/更新以及丰富的元数据统计查询检索器负责将查询向量映射为 Top-K 相关文档二者通过 Haystack Pipeline 与 Text Embedder、PromptBuilder、OpenAIGenerator 等标准组件自由编排。理解索引字段不可变性、向量维度一致性、认证优先级与三种 Retriever 的能力边界是构建稳定可上线的 Azure AI Search 检索系统的关键。相关组件的详细 API 可随时查阅 version-2.18 API 参考并对照配套的 Document Store 指南 与 Embedding Retriever 指南 实践。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考