Haystack 集成指南用 ArangoDocumentStore 与 ArangoEmbeddingRetriever 构建 ArangoDB 向量检索【免费下载链接】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/haystackArangoDB 是一款将文档、图、键值三种数据模型统一在单一引擎中的多模型数据库。Haystack 通过arangodb-haystack集成包提供了ArangoDocumentStore文档存储与ArangoEmbeddingRetriever嵌入检索器两个组件让开发者可以直接在 ArangoDB 上完成文档写入、向量相似度检索与 GraphRAG 流水线搭建。读完本文你将掌握两个组件的完整初始化参数、认证与相似度函数配置、序列化机制以及如何在 Haystack Pipeline 中组合使用它们。集成概览为什么用 ArangoDB 承载 Haystack 检索在 Haystack 的文档存储选型体系中ArangoDB 被归类为多模型数据库见 选择文档存储。它的核心定位是单一引擎同时支持图graph、文档document、键值key-value和向量vector多种数据模型免去为不同数据形态维护多套数据库的负担适合知识图谱或实体关系复杂的应用——实体既可以通过关系相连又需要向量相似度检索向量检索基于 AQLArangoDB Query Language向量函数完成要求 ArangoDB 3.12 及以上版本且需要启用--vector-index启动标志。因为文档与它们之间的关系存放在同一数据库中ArangoDB 尤其适合把语义搜索与图遍历结合在一起的 GraphRAG 流水线见 ArangoDocumentStore 指南。集成包共提供两个组件定义于haystack_integrations命名空间下组件模块路径职责ArangoDocumentStorehaystack_integrations.document_stores.arangodb将Document写入 ArangoDB collection并执行基于 AQL 向量函数的相似度检索ArangoEmbeddingRetrieverhaystack_integrations.components.retrievers.arangodb接收查询向量从ArangoDocumentStore中取回最相似的文档环境准备与安装启动 ArangoDBDocker向量检索需要 ArangoDB 3.12且必须显式开启向量索引功能。官方推荐用 Docker 一条命令启动同时设置 root 密码docker run -d -p 8529:8529 \ -e ARANGO_ROOT_PASSWORDtest-password \ arangodb:3.12 arangod --vector-index命令说明-p 8529:8529映射 ArangoDB 默认 HTTP 端口-e ARANGO_ROOT_PASSWORDtest-password设置 root 用户密码后续认证需要用到arangod --vector-index以启用向量索引的模式启动服务这是 AQL 向量函数可用的前提。安装 Haystack 集成包pip install arangodb-haystack若要在 Pipeline 示例中使用 Sentence Transformers 生成真实嵌入还需要安装对应的 embedder 集成pip install sentence-transformers-haystackArangoDocumentStore参数、认证与文档操作初始化参数ArangoDocumentStore的构造函数签名如下参考 API 文档__init__( *, host: str http://localhost:8529, database: str haystack, username: Secret Secret.from_env_var(ARANGO_USERNAME, strictFalse), password: Secret Secret.from_env_var(ARANGO_PASSWORD), collection_name: str haystack_documents, embedding_dimension: int 768, recreate_collection: bool False, similarity_function: Literal[cosine, dot_product, l2] cosine ) - None各参数含义与默认值参数类型默认值说明hoststrhttp://localhost:8529ArangoDB 服务器 URLdatabasestrhaystack使用的数据库名不存在时自动创建usernameSecret读取ARANGO_USERNAME环境变量用户名环境变量未设置时回退为rootpasswordSecret读取ARANGO_PASSWORD环境变量密码必须提供collection_namestrhaystack_documents存放文档的 collection 名称embedding_dimensionint768文档嵌入向量的维度必须与嵌入模型输出维度一致recreate_collectionboolFalse为True时启动即删除并重建 collection清空数据similarity_functionLiteralcosine向量相似度函数cosine/dot_product/l2认证Secret 与环境变量凭证以 Haystack 的Secret对象定义于 haystack/utils形式传入。默认从环境变量读取其中ARANGO_USERNAME未设置时回退为root因此通常只需导出密码export ARANGO_PASSWORDtest-password也可以显式构造Secret传入与 ArangoDocumentStore 指南 中的认证章节一致from haystack.utils import Secret from haystack_integrations.document_stores.arangodb import ArangoDocumentStore document_store ArangoDocumentStore( hosthttp://localhost:8529, databasehaystack, usernameSecret.from_env_var(ARANGO_USERNAME, strictFalse), passwordSecret.from_env_var(ARANGO_PASSWORD), )相似度函数ArangoDocumentStore在初始化时通过similarity_function参数固定检索所用的相似度计算方式支持三种取值cosine默认余弦相似度最适合归一化后的嵌入向量dot_product点积适合向量模长携带语义信息的场景l2欧氏距离L2 距离。document_store ArangoDocumentStore( hosthttp://localhost:8529, embedding_dimension768, similarity_functiondot_product, )写入、计数、过滤与删除文档写入文档时如果文档没有嵌入向量仅写入文本内容write_documents返回实际写入数量from haystack import Document from haystack_integrations.document_stores.arangodb import ArangoDocumentStore document_store ArangoDocumentStore( hosthttp://localhost:8529, databasehaystack, collection_namedocuments, embedding_dimension768, recreate_collectionTrue, ) document_store.write_documents( [ Document(contentThere are over 7,000 languages spoken around the world today.), Document(contentElephants have been observed to recognize themselves in mirrors.), ], ) print(document_store.count_documents())存储层公开的文档操作方法如下签名见 API 文档方法签名行为count_documents() - int返回 store 中文档总数filter_documents(filters: dict[str, Any] \| None None) - list[Document]按 Haystack 元数据过滤器返回匹配文档None时返回全部write_documents(documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE) - int写入文档并返回写入数delete_documents(document_ids: list[str]) - None按文档 ID 列表删除重复文档策略DuplicatePolicywrite_documents通过policy参数控制重复文档的处理取值来自 Haystack 的DuplicatePolicy枚举定义于 haystack/document_stores/typesOVERWRITE覆盖已存在的重复文档SKIP跳过重复文档FAIL默认遇到重复时抛出DuplicateDocumentError。此外当documents列表中混入非Document对象时会抛出ValueError在FAIL策略下发现重复文档会抛出DuplicateDocumentError。ArangoEmbeddingRetriever向量检索组件ArangoEmbeddingRetriever基于向量相似度从ArangoDocumentStore检索文档。相似度函数本身并不在本组件上配置而是由ArangoDocumentStore在初始化时决定cosine/dot_product/l2检索器直接复用这一配置。初始化参数__init__( *, document_store: ArangoDocumentStore, top_k: int 10, filters: dict[str, Any] | None None ) - Nonedocument_storeArangoDocumentStore必填要检索的文档存储实例top_kint默认10最多返回的文档数量filtersdict[str, Any] | None可选的 Haystack 元数据过滤器在检索时生效。run 方法run( query_embedding: list[float], top_k: int | None None, filters: dict[str, Any] | None None, ) - dict[str, list[Document]]参数说明query_embeddinglist[float]必填查询向量top_k可选覆盖实例级top_k仅对本次调用生效filters可选覆盖实例级filters仅对本次调用生效。返回值{documents: [...]}即按相似度分数降序排列的Document列表。初始化时设置的top_k与filters均可被run()调用级参数覆盖见 ArangoEmbeddingRetriever 指南。独立使用from haystack import Document from haystack_integrations.document_stores.arangodb import ArangoDocumentStore from haystack_integrations.components.retrievers.arangodb import ( ArangoEmbeddingRetriever, ) document_store ArangoDocumentStore( hosthttp://localhost:8529, embedding_dimension3, recreate_collectionTrue, ) document_store.write_documents( [ Document( contentThere are over 7,000 languages spoken around the world today., embedding[0.1, 0.2, 0.3], ), Document( contentElephants have been observed to recognize themselves in mirrors., embedding[0.8, 0.1, 0.5], ), ], ) retriever ArangoEmbeddingRetriever(document_storedocument_store, top_k1) result retriever.run(query_embedding[0.1, 0.2, 0.3]) print(result[documents][0].content)这段示例中embedding_dimension3与手工编写的三维嵌入向量对应。实际生产场景中嵌入应通过 Document Embedder 生成其输出维度必须与 store 的embedding_dimension严格一致。在 Pipeline 中使用ArangoEmbeddingRetriever最常见的流水线位置是在 RAG 流水线中位于 Text Embedder 之后、PromptBuilder之前或在语义搜索流水线中作为最后一个组件见 ArangoEmbeddingRetriever 指南。完整示例先用SentenceTransformersDocumentEmbedder生成文档嵌入并写入 store再构建文本嵌入 → 检索两段式查询流水线from haystack import Document, Pipeline from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack_integrations.document_stores.arangodb import ArangoDocumentStore from haystack_integrations.components.retrievers.arangodb import ( ArangoEmbeddingRetriever, ) document_store ArangoDocumentStore( hosthttp://localhost:8529, embedding_dimension384, recreate_collectionTrue, ) 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( modelsentence-transformers/all-MiniLM-L6-v2, ) documents_with_embeddings document_embedder.run(documents) document_store.write_documents( documents_with_embeddings[documents], policyDuplicatePolicy.OVERWRITE, ) query_pipeline Pipeline() query_pipeline.add_component( text_embedder, SentenceTransformersTextEmbedder(modelsentence-transformers/all-MiniLM-L6-v2), ) query_pipeline.add_component( retriever, ArangoEmbeddingRetriever(document_storedocument_store, top_k3), ) 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].content)几点实战要点sentence-transformers/all-MiniLM-L6-v2输出 384 维嵌入因此 store 的embedding_dimension必须同步设为384索引与查询阶段应使用同一个嵌入模型否则向量空间不一致会导致检索失真写入时显式传入DuplicatePolicy.OVERWRITE可安全地重复执行索引脚本而不产生重复文档。序列化与资源管理两个组件都实现了 Haystack 的标准序列化协议便于将组件状态保存到 YAML/JSON 并在流水线中重建方法签名说明to_dict() - dict[str, Any]将组件序列化为字典from_dict(data: dict[str, Any]) - ArangoDocumentStore / ArangoEmbeddingRetriever从字典反序列化出组件实例close() - None释放底层 Document Store 持有的同步资源其中close()用于在组件生命周期结束时释放资源——ArangoEmbeddingRetriever.close()会释放底层ArangoDocumentStore的同步资源而ArangoDocumentStore.close()释放其自身关联的同步资源见 API 文档。从源码结构看close()的引入与 Haystack 组件资源生命周期管理机制一致用于在流水线或应用退出时干净地回收数据库连接等资源。小结安装与启动pip install arangodb-haystackArangoDB 需 3.12 并以arangod --vector-index启动存储配置ArangoDocumentStore负责数据库/collection 管理、文档写入删除、元数据过滤以及cosine/dot_product/l2三种相似度函数的选定检索使用ArangoEmbeddingRetriever接收query_embedding支持实例级与调用级双层top_k/filters覆盖返回按分数排序的Document列表组合方式可独立运行也可与 Text Embedder、PromptBuilder 组合成 RAG 流水线配合 DuplicatePolicy 与序列化协议适合工程化落地。更多细节可继续阅读仓库内的 ArangoDocumentStore 指南、ArangoEmbeddingRetriever 指南 以及 选择文档存储 中的选型对比。【免费下载链接】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），仅供参考