Haystack 集成 ArangoDB：ArangoDocumentStore 与 ArangoEmbeddingRetriever 实战指南

Haystack 集成 ArangoDBArangoDocumentStore 与 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/haystackArangoDB 是一款多模型数据库将文档、图与键值数据统一在一个引擎中。本文基于 Haystack 官方集成文档与仓库中的用户指南ArangoDocumentStore 文档、ArangoEmbeddingRetriever 文档以及版本化 API 参考version-2.20 integrations-api/arangodb系统讲解ArangoDocumentStore与ArangoEmbeddingRetriever的安装、配置、初始化参数、相似度函数、CRUD 操作与序列化机制。读完本文你将能够在 Haystack 管道中完整落地一套基于 ArangoDB 的向量检索与 GraphRAG 工作流。ArangoDB 集成概览在 Haystack 生态中ArangoDB 集成通过arangodb-haystack包提供核心包含两个组件ArangoDocumentStore基于 ArangoDB 的文档存储文档存放在 ArangoDB 集合中利用 AQLArangoDB Query Language向量函数执行向量相似度检索ArangoEmbeddingRetriever基于嵌入向量的检索器从ArangoDocumentStore中检索与查询向量最相似的文档。由于文档及其关联关系保存在同一个数据库中ArangoDB 特别适合将语义搜索与图遍历结合的GraphRAG 管道见 choosing-a-document-store 中对其的收录以及 platform-components 中对其可用性的标注。版本前提向量检索功能要求ArangoDB 3.12 或更高版本且需在启动时开启向量索引特性--vector-index启动参数。环境安装与 ArangoDB 启动使用 Docker 启动 ArangoDB 并开启向量索引在本地开发环境中推荐用 Docker 一键启动 ArangoDB同时设置 root 密码并开启--vector-index标志docker run -d -p 8529:8529 \ -e ARANGO_ROOT_PASSWORDtest-password \ arangodb:3.12 arangod --vector-index提示--vector-index是向量相似度检索的前提缺失该标志时 AQL 向量函数将不可用。安装 Haystack 集成包pip install arangodb-haystack若需要跟随本文的示例运行还需安装 Sentence Transformers 嵌入器集成包pip install sentence-transformers-haystackArangoDocumentStore 深度解析ArangoDocumentStore将文档持久化到 ArangoDB 集合中并对外提供写入、计数、过滤、删除与序列化等完整能力。其 API 参考见 version-2.20 integrations-api/arangodb。构造参数详解__init__的全部参数如下均以关键字形式传入参数类型默认值说明hoststrhttp://localhost:8529ArangoDB 服务器地址databasestrhaystack使用的数据库名不存在时自动创建usernameSecretSecret.from_env_var(ARANGO_USERNAME, strictFalse)ArangoDB 用户名默认读取环境变量未设置时回退为rootpasswordSecretSecret.from_env_var(ARANGO_PASSWORD)ArangoDB 密码默认从ARANGO_PASSWORD环境变量读取collection_namestrhaystack_documents存放文档的集合名embedding_dimensionint768文档嵌入向量的维度recreate_collectionboolFalse为True时启动时删除并重建集合similarity_functionLiteral[cosine, dot_product, l2]cosine向量检索使用的相似度函数基础初始化示例from haystack_integrations.document_stores.arangodb import ArangoDocumentStore from haystack.utils import Secret store ArangoDocumentStore( hosthttp://localhost:8529, databasehaystack, usernameSecret.from_env_var(ARANGO_USERNAME, strictFalse), passwordSecret.from_env_var(ARANGO_PASSWORD), collection_namedocuments, embedding_dimension768, )几个关键设计点凭据默认来自环境变量ARANGO_USERNAME未设置时回退到root因此通常只需导出密码即可连接export ARANGO_PASSWORDtest-passwordrecreate_collectionTrue适合索引重建场景它会清空集合并重新创建避免残留旧数据干扰实验但注意这会丢失已有文档生产环境慎用。embedding_dimension必须与嵌入模型输出维度严格一致例如sentence-transformers/all-MiniLM-L6-v2输出 384 维则embedding_dimension应设为384。三种相似度函数similarity_function参数决定向量检索的度量方式需在初始化时一次性配置cosine默认余弦相似度适合归一化嵌入向量是大多数语义检索场景的首选dot_product点积当嵌入向量的模长携带语义信息时更有用l2欧几里得L2距离度量向量在空间中的实际距离。document_store ArangoDocumentStore( hosthttp://localhost:8529, embedding_dimension768, similarity_functiondot_product, )写入文档write_documents是核心写入入口签名如下write_documents( documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE ) - intdocuments待写入的Document对象列表policy重复文档处理策略支持OVERWRITE覆盖、SKIP跳过与FAIL失败默认返回实际写入的文档数量当列表中混入非Document对象时抛出ValueError当policy为FAIL且发现重复文档时抛出DuplicateDocumentError。写入示例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())若要写入真实嵌入应先用 Document Embedder如SentenceTransformersDocumentEmbedder计算嵌入并确保嵌入维度与embedding_dimension配置一致。DuplicatePolicy枚举定义于 haystack/document_stores/types。查询、计数与删除方法签名说明count_documentscount_documents() - int返回存储中的文档总数filter_documentsfilter_documents(filters: dict[str, Any] \| None None) - list[Document]按 Haystack 元数据过滤器返回匹配文档filters为None时返回全部delete_documentsdelete_documents(document_ids: list[str]) - None按文档 ID 列表删除文档# 按元数据过滤 docs document_store.filter_documents({field: meta.language, operator: , value: en}) # 按 ID 删除 document_store.delete_documents(document_ids[doc-id-1, doc-id-2])ArangoEmbeddingRetriever 深度解析ArangoEmbeddingRetriever通过 ArangoDB 的 AQL 向量函数比较查询向量与文档向量的相似度返回最相似的文档。其最典型的管道位置是在 RAG 管道中位于 Text Embedder 之后、PromptBuilder 之前或作为语义搜索管道的最后一个组件。构造参数__init__( *, document_store: ArangoDocumentStore, top_k: int 10, filters: dict[str, Any] | None None ) - Nonedocument_store必填关联的ArangoDocumentStore实例top_k单次检索返回的最大文档数默认10filters可选的 Haystack 元数据过滤器在检索时生效。run 方法run( query_embedding: list[float], top_k: int | None None, filters: dict[str, Any] | None None, ) - dict[str, list[Document]]query_embedding必填查询向量浮点数列表top_k/filters均为可选用于覆盖实例级配置实现按调用动态调整返回{documents: [...]}其中Document列表按相似度分数排序。检索示例from haystack_integrations.document_stores.arangodb import ArangoDocumentStore from haystack_integrations.components.retrievers.arangodb import ArangoEmbeddingRetriever store ArangoDocumentStore(hosthttp://localhost:8529, databasehaystack, usernameroot, collection_namedocs, embedding_dimension768) retriever ArangoEmbeddingRetriever(document_storestore, top_k5) result retriever.run(query_embedding[0.1, 0.2, ...])端到端实践单独使用检索器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)在 Haystack 管道中使用将文本嵌入器与检索器连接成一条查询管道实现文本 → 向量 → 检索的完整链路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)该示例说明了两条关键实践索引侧SentenceTransformersDocumentEmbedder负责把纯文本文档转化为带嵌入的Document再以DuplicatePolicy.OVERWRITE策略写入避免重复执行时产生重复文档查询侧SentenceTransformersTextEmbedder将用户查询转为向量通过connect(text_embedder.embedding, retriever.query_embedding)把嵌入送入检索器top_k3限制返回条数。序列化与资源管理两个组件均实现了 Haystack 标准的序列化协议便于管道持久化与重建to_dict() - dict[str, Any]将组件序列化为字典。对ArangoEmbeddingRetriever而言序列化数据包含document_store、top_k与filters对ArangoDocumentStore而言则包含全部初始化参数凭据以Secret形式安全序列化。from_dict(data: dict[str, Any])从字典反序列化返回新的组件实例。close() - None释放底层 Document Store 关联的同步资源如 HTTP 连接池在不再使用存储时调用避免资源泄漏。结合 Haystack 的 YAML 管道编排能力参见 marshal/yaml.pyto_dict/from_dict让包含 ArangoDB 组件的管道可以声明式保存与恢复。小结与适用场景综合来看ArangoDB 集成在 Haystack 中的价值集中在两点多模型统一文档、向量与图关系存于同一数据库省去多系统同步成本GraphRAG 友好语义检索与图遍历可在同一引擎内完成适合构建结合知识图谱的检索增强生成管道。配置上只需记住三件事ArangoDB 需3.12 并开启--vector-indexembedding_dimension要与嵌入模型输出维度一致相似度函数在cosine、dot_product、l2三者中按场景选择。相关完整 API 说明可继续查阅仓库内的 ArangoDB 集成 API 参考、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），仅供参考