Haystack 与 MariaDB 集成实战：基于 MariaDB 11.7 原生 VECTOR 的文档存储与向量、关键词双路检索
发布时间：2026/9/13 19:01:03 作者：尧图编辑部 阅读量：1,286
Haystack 与 MariaDB 集成实战基于 MariaDB 11.7 原生 VECTOR 的文档存储与向量、关键词双路检索【免费下载链接】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本篇指南围绕 Haystack 生态中的 MariaDB 集成展开系统讲解如何以 MariaDB 11.7 的原生VECTOR数据类型和 MHNSW 索引作为检索后端构建支持向量相似度检索、全文关键词检索与元数据过滤的MariaDBDocumentStore并搭配MariaDBEmbeddingRetriever与MariaDBKeywordRetriever完成语义搜索、RAG 与抽取式问答流水线。读完本文你将掌握 MariaDB 集成的安装配置、三类核心组件的全部参数语义、两种检索器的调用方式以及它们在 Haystack Pipeline 中的完整接线方案。文章主体依据 version-2.18 MariaDB API 参考并辅以当前仓库中对应的用户指南与核心源码进行佐证。一、集成概览为什么在 MariaDB 中直接做向量检索MariaDB 从 11.7 版本开始引入原生VECTOR数据类型并配套提供 MHNSWMulti-HNSW索引与VEC_DISTANCE_COSINE、VEC_DISTANCE_EUCLIDEAN等向量距离函数使数据库可以在不依赖任何外部扩展的前提下直接完成高效的近似最近邻ANN检索。Haystack 的 MariaDB 集成正是建立在这一能力之上它包含三个核心组件见 集成 API 参考组件所属模块底层机制MariaDBDocumentStorehaystack_integrations.document_stores.mariadbVECTOR数据类型 MHNSW 索引 MATCH ... AGAINST全文检索MariaDBEmbeddingRetrieverhaystack_integrations.components.retrievers.mariadbVEC_DISTANCE_COSINE/VEC_DISTANCE_EUCLIDEAN向量相似度排序MariaDBKeywordRetrieverhaystack_integrations.components.retrievers.mariadbMATCH ... AGAINST自然语言模式全文检索依赖content列的 FULLTEXT 索引该集成在同一数据库实例中同时支持三种检索能力嵌入向量检索、关键词检索与元数据过滤。由于检索逻辑下沉到 SQL 层数据集较大时仍可利用数据库索引与查询优化能力适合希望复用既有 MariaDB 运维体系、同时为 LLM 应用增加向量检索能力的场景。关于集成的定位与能力矩阵可参考用户指南 mariadbdocumentstore.mdx。二、环境准备启动 MariaDB 11.7 并安装集成2.1 使用 Docker 快速启动实例集成要求 MariaDB 11.7 及以上版本。官方用户指南mariadbdocumentstore.mdx给出了一键启动命令docker run -d -p 3306:3306 \ -e MARIADB_ROOT_PASSWORDsecret \ -e MARIADB_DATABASEhaystack \ -e MARIADB_USERhaystack \ -e MARIADB_PASSWORDsecret \ mariadb:11.7该命令会创建名为haystack的数据库并预置haystack用户及其密码。2.2 安装系统依赖与 Python 集成包mariadb连接器是基于 C 扩展从源码编译的因此需要 MariaDB Connector/C 系统库提供mariadb_config# Ubuntu / Debian sudo apt-get install -y libmariadb-dev # macOS brew install mariadb-connector-c随后安装集成包pip install mariadb-haystack如需在示例中同时使用 Sentence Transformers 嵌入器还需额外安装pip install sentence-transformers-haystack2.3 配置数据库凭据用户与密码在初始化时通过Secret.from_env_var从环境变量读取见 API 参考 中__init__的user与password参数说明因此使用前需先导出export MARIADB_USERhaystack export MARIADB_PASSWORDsecret三、MariaDBDocumentStore核心参数与方法详解MariaDBDocumentStore是基于 MariaDB 11.7 原生 VECTOR 支持的文档存储实现负责建表、写入、过滤、删除与统计。它的完整初始化签名如下__init__( *, host: str 127.0.0.1, port: int 3306, database: str haystack, user: Secret Secret.from_env_var(MARIADB_USER), password: Secret Secret.from_env_var(MARIADB_PASSWORD), table_name: str haystack_documents, recreate_table: bool False, embedding_dimension: int 768, distance: str cosine, create_vector_index: bool False ) - None3.1 初始化参数对照表参数类型/默认值说明hoststr 127.0.0.1MariaDB 主机地址portint 3306MariaDB 端口databasestr haystack数据库名称userSecret数据库用户默认从MARIADB_USER环境变量读取passwordSecret数据库密码默认从MARIADB_PASSWORD环境变量读取table_namestr haystack_documents存储文档的表名仅允许字母、数字与下划线recreate_tablebool False初始化时删除并重建表会删除全部数据embedding_dimensionint 768向量维度仅在建表时生效已存在的表上该参数被忽略distancestr cosine向量距离函数取cosine或euclidean仅在建表时生效create_vector_indexbool False为True时创建 MHNSW 向量索引以加速 ANN 检索要求每篇文档都有非空 embedding仅在建表时生效表创建参数注意embedding_dimension、distance、create_vector_index三个参数只在表首次创建或recreate_tableTrue时生效事后修改不会影响已存在的表。这是文档存储与检索器示例中反复强调的关键约束见 mariadbdocumentstore.mdx 与 mariadbembeddingretriever.mdx 中的 note 说明。此外开启create_vector_indexTrue后任何无 embedding 的文档在写入时都会报错。3.2 初始化与写入示例import os from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore from haystack import Document os.environ[MARIADB_USER] haystack os.environ[MARIADB_PASSWORD] secret document_store MariaDBDocumentStore( port3306, databasehaystack, embedding_dimension768, distancecosine, ) document_store.write_documents( [ Document(contentThis is first, embedding[0.1] * 768), Document(contentThis is second, embedding[0.3] * 768), ], ) print(document_store.count_documents())3.3 实例方法一览根据 API 参考MariaDBDocumentStore除to_dict/from_dict序列化方法外还提供以下方法write_documents(documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE) - int向存储写入文档返回实际写入数量。policy支持 Haystack 标准的重复文档策略如DuplicatePolicy.OVERWRITE、DuplicatePolicy.SKIP、DuplicatePolicy.FAIL枚举定义见 policy.py。当文档 id 已存在且策略为FAIL或未指定时抛出DuplicateDocumentError写入失败时抛出DocumentStoreError。filter_documents(filters: dict[str, Any] | None None) - list[Document]按 Haystack 元数据过滤语法返回匹配的文档filters非字典时抛TypeError语法非法时抛ValueError。delete_documents(document_ids: list[str]) - None按文档 id 批量删除。count_documents() - int返回存储中的文档总数。delete_table() - None删除DROP文档表。close() - None释放关联的同步资源。四、MariaDBEmbeddingRetriever基于查询向量的相似度检索4.1 类定位与底层机制MariaDBEmbeddingRetriever从MariaDBDocumentStore中基于向量相似度检索文档内部调用 MariaDB 原生VEC_DISTANCE_COSINE或VEC_DISTANCE_EUCLIDEAN距离函数并结合 MHNSW 索引实现高效的近似最近邻搜索。初始化签名如下__init__( *, document_store: MariaDBDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, score_threshold: float | None None, filter_policy: str | FilterPolicy FilterPolicy.REPLACE ) - None参数类型/默认值说明document_storeMariaDBDocumentStore一个MariaDBDocumentStore实例必填filtersdict[str, Any] \| None None默认的 Haystack 元数据过滤器应用于每次查询top_kint 10返回文档的最大数量score_thresholdfloat \| None None包含文档的最低分数阈值低于该分数的文档被排除filter_policystr \| FilterPolicy FilterPolicy.REPLACE运行时过滤器与初始化时过滤器的交互策略若传入的document_store不是MariaDBDocumentStore实例初始化会抛出ValueError。4.2 run 方法run( query_embedding: list[float], filters: dict[str, Any] | None None, top_k: int | None None, score_threshold: float | None None, ) - dict[str, list[Document]]query_embedding必填查询向量filters运行时过滤器按filter_policy与初始化时过滤器合并top_k运行时覆盖检索器的top_kscore_threshold运行时覆盖检索器的score_threshold返回值包含documents键的字典值为按相关度排序的文档列表。4.3 独立使用示例from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore from haystack_integrations.components.retrievers.mariadb import MariaDBEmbeddingRetriever store MariaDBDocumentStore(host127.0.0.1, databasehaystack, embedding_dimension768) retriever MariaDBEmbeddingRetriever(document_storestore, top_k5) result retriever.run(query_embedding[0.1] * 768) documents result[documents]前提条件在 Pipeline 中使用该检索器时必须确保文档与查询都具备 embedding——在索引 Pipeline 中接入 Document Embedder在查询 Pipeline 中接入 Text Embeddermariadbembeddingretriever.mdx。五、MariaDBKeywordRetriever基于全文索引的关键词检索5.1 类定位与底层机制MariaDBKeywordRetriever使用 MariaDB 内建的MATCH ... AGAINST全文检索自然语言模式底层依赖content列上的 FULLTEXT 索引无需任何外部搜索引擎。初始化签名如下__init__( *, document_store: MariaDBDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, filter_policy: str | FilterPolicy FilterPolicy.REPLACE ) - None与向量检索器相比MariaDBKeywordRetriever没有score_threshold参数。其run签名如下run( query: str, filters: dict[str, Any] | None None, top_k: int | None None ) - dict[str, list[Document]]query必填关键词查询字符串filters运行时过滤器按filter_policy与初始化过滤器合并top_k运行时覆盖检索器的top_k返回值documents键对应的按相关度排序的文档列表。5.2 独立使用示例from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore from haystack_integrations.components.retrievers.mariadb import MariaDBKeywordRetriever store MariaDBDocumentStore(host127.0.0.1, databasehaystack, embedding_dimension768) retriever MariaDBKeywordRetriever(document_storestore, top_k5) result retriever.run(queryclimate change) documents result[documents]六、在 Pipeline 中实战语义搜索与 RAG 完整接线6.1 索引 Pipeline 语义查询 Pipeline以下示例来自 mariadbembeddingretriever.mdx完整演示了“写入带 embedding 的文档 → 用 Text Embedder 编码查询 → 检索相似文档”的闭环import os from haystack import Document, Pipeline from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder, ) from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore from haystack_integrations.components.retrievers.mariadb import ( MariaDBEmbeddingRetriever, ) os.environ[MARIADB_USER] haystack os.environ[MARIADB_PASSWORD] secret document_store MariaDBDocumentStore( embedding_dimension768, distancecosine, ) documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document(contentElephants have been observed to recognize themselves in mirrors.), Document(contentBioluminescent waves can be seen in the Maldives and Puerto Rico.), ] document_embedder SentenceTransformersDocumentEmbedder() documents_with_embeddings document_embedder.run(documents) document_store.write_documents( documents_with_embeddings.get(documents), policyDuplicatePolicy.OVERWRITE, ) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, SentenceTransformersTextEmbedder()) query_pipeline.add_component( retriever, MariaDBEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) result query_pipeline.run( {text_embedder: {text: How many languages are there?}} ) print(result[retriever][documents][0])6.2 关键词检索驱动的 RAG PipelineMariaDBKeywordRetriever在 RAG 流水线中的典型位置是 PromptBuilder 之前。下面的完整示例来自 mariadbkeywordretriever.mdx展示了从文档写入到生成答案的完整链路import os from haystack import Document, Pipeline from haystack.components.builders import AnswerBuilder, ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore from haystack_integrations.components.retrievers.mariadb import MariaDBKeywordRetriever os.environ[MARIADB_USER] haystack os.environ[MARIADB_PASSWORD] secret os.environ[OPENAI_API_KEY] your-openai-api-key prompt_template [ ChatMessage.from_user( Given these documents, answer the question. Documents: {% for doc in documents %} {{ doc.content }} {% endfor %} Question: {{question}} Answer: ), ] document_store MariaDBDocumentStore() documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document(contentElephants have been observed to recognize themselves in mirrors.), Document(contentBioluminescent waves can be seen in the Maldives and Puerto Rico.), ] document_store.write_documents(documentsdocuments, policyDuplicatePolicy.SKIP) retriever MariaDBKeywordRetriever(document_storedocument_store) rag_pipeline Pipeline() rag_pipeline.add_component(nameretriever, instanceretriever) rag_pipeline.add_component( instanceChatPromptBuilder(templateprompt_template, required_variables*), nameprompt_builder, ) rag_pipeline.add_component(instanceOpenAIChatGenerator(), namellm) rag_pipeline.add_component(instanceAnswerBuilder(), nameanswer_builder) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder.prompt, llm.messages) rag_pipeline.connect(llm.replies, answer_builder.replies) rag_pipeline.connect(retriever, answer_builder.documents) question languages spoken around the world today result rag_pipeline.run( { retriever: {query: question}, prompt_builder: {question: question}, answer_builder: {query: question}, } ) print(result[answer_builder])从组件编排方式可以看出检索结果同时流向prompt_builder.documents构造提示词与answer_builder.documents支撑答案溯源生成器输出经answer_builder.replies汇入最终答案。七、元数据过滤与 FilterPolicy 语义两个检索器与filter_documents都支持 Haystack 元数据过滤语法。filter_policy决定了初始化过滤器init filters与每次 run 时传入的运行时过滤器runtime filters的交互方式其枚举定义与合并逻辑位于 filter_policy.pyFilterPolicy.REPLACE默认运行时过滤器直接替换初始化过滤器——即apply_filter_policy中runtime_filters or init_filters的分支只要 run 时提供了过滤器就完全覆盖初始化时设置的条件。FilterPolicy.MERGE运行时过滤器与初始化过滤器合并。从源码filter_policy.py可以看到合并遵循一组组合规则两个比较过滤器含field/operator/value若字段相同运行时过滤条件覆盖初始化条件否则以AND逻辑运算符组合成{operator: AND, conditions: [...]}初始化逻辑过滤器含operator/conditions与运行时比较过滤器若逻辑运算符匹配则将运行时条件并入初始化条件列表同名字段先移除再追加实现运行时覆盖两个逻辑过滤器仅当逻辑运算符一致时才合并条件否则运行时过滤器生效并给出警告日志。因此在实际使用中若希望每次查询动态切换过滤条件使用默认REPLACE若希望“初始化时设定全局约束如仅检索某分类运行时叠加额外条件”则选择MERGE并留意逻辑运算符一致性。八、序列化to_dict / from_dict三个组件均实现了标准的 Haystack 序列化协议to_dict() - dict[str, Any]将组件序列化为字典便于通过 YAML/JSON 保存流水线定义或随配置分发from_dict(data: dict[str, Any])从字典反序列化出对应的MariaDBDocumentStore、MariaDBEmbeddingRetriever或MariaDBKeywordRetriever实例。这使整个 MariaDB 集成可以无缝嵌入 Haystack 的 Pipeline 序列化体系haystack.marshal实现“配置即代码”的部署方式。九、注意事项与最佳实践版本硬性要求集成依赖 MariaDB 11.7 的原生 VECTOR 能力低于该版本无法使用mariadbdocumentstore.mdx。建表参数不可后改embedding_dimension、distance、create_vector_index仅在建表时生效如需变更必须显式设置recreate_tableTrue代价是清空全部数据。向量索引与空 embedding 的冲突开启create_vector_indexTrue后每篇写入的文档都必须携带非空 embedding否则写入报错若数据集中存在无法嵌入的文档应权衡是否开启该索引。距离函数与检索一致性MariaDBDocumentStore的distance参数决定了底层使用VEC_DISTANCE_COSINE还是VEC_DISTANCE_EUCLIDEAN需与 Embedder 产出的向量分布特性相匹配余弦距离对向量模长不敏感适合绝大多数语义向量。凭据走环境变量用户与密码通过Secret.from_env_var(MARIADB_USER)/MARIADB_PASSWORD读取避免在代码或配置中明文硬编码。双路检索按需选择语义检索EmbeddingRetriever适合模糊语义匹配关键词检索KeywordRetriever适合精确术语命中如专有名词、代码标识符。两者可分别驱动 RAG 或组合为混合检索方案。十、进一步阅读MariaDBDocumentStore 用户指南安装步骤、建表参数与受支持的检索器总览MariaDBEmbeddingRetriever 用户指南语义检索 Pipeline 完整示例MariaDBKeywordRetriever 用户指南关键词 RAG Pipeline 完整示例MariaDB 集成 API 参考version-2.18本文所述全部签名、参数与异常的原生出处FilterPolicy 实现源码过滤器 REPLACE/MERGE 的合并规则DuplicatePolicy 枚举定义写入文档时的重复策略选项【免费下载链接】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），仅供参考
尧图网站开发 