Haystack 2.21 ArangoDB 集成解析：ArangoDocumentStore 与 ArangoEmbeddingRetriever 的 API 全解

Haystack 2.21 ArangoDB 集成解析ArangoDocumentStore 与 ArangoEmbeddingRetriever 的 API 全解【免费下载链接】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 文档站 2.21 版本的 ArangoDB 集成 API 参考系统讲解ArangoDocumentStore与ArangoEmbeddingRetriever两个核心组件覆盖全部构造参数、方法签名与默认值并结合仓库中的核心DocumentStore协议源码说明重复写入策略、元数据过滤语法和序列化机制在实现层如何被约束。读完你可以独立完成 ArangoDB 向量库的接入配置、文档读写并将其嵌入 Haystack Pipeline 构建 RAG 检索链路。集成定位与能力边界ArangoDB 集成由haystack_integrations生态中的arangodb-haystack包提供包含两类组件参考文档docs-website/reference_versioned_docs/version-2.21/integrations-api/arangodb.mdArangoDocumentStorehaystack_integrations.document_stores.arangodb.document_store一个以 ArangoDB 为后端的 Haystack DocumentStore。文档存放在 ArangoDB 的 collection 中向量相似度检索通过 AQLArangoDB Query Language向量函数实现。ArangoEmbeddingRetrieverhaystack_integrations.components.retrievers.arangodb.embedding_retriever从ArangoDocumentStore中按嵌入向量相似度检索文档的 Pipeline 组件。两条关键约束需要注意ArangoDB 版本要求 3.12 及以上因为 AQL 向量函数是 3.12 引入的能力相似度函数cosine / dot_product / l2配置在 DocumentStore 上而不是 Retriever 上。ArangoEmbeddingRetriever本身不携带相似度语义它只是把查询向量交给 Store 执行检索。从 Haystack 官方文档站对 ArangoDB 的选型说明docs-website/docs/document-stores/arangodocumentstore.mdx可以看到ArangoDB 是文档、图、键值多模数据库文档与其关系存放在同一引擎内因此该集成同时适合 GraphRAG 一类语义检索 图遍历的工作负载。环境准备与安装向量检索需要开启向量索引的 ArangoDB 3.12 实例官方文档给出的 Docker 启动方式为docker run -d -p 8529:8529 \ -e ARANGO_ROOT_PASSWORDtest-password \ arangodb:3.12 arangod --vector-index其中--vector-index启动参数是启用 AQL 向量函数的前提。随后安装集成包pip install arangodb-haystack如果要在 Pipeline 中使用 Sentence Transformers 嵌入器还需安装配套的嵌入组件包pip install sentence-transformers-haystack凭据默认从环境变量读取ARANGO_USERNAME未设置时回退为root与ARANGO_PASSWORDexport ARANGO_PASSWORDtest-passwordArangoDocumentStore 构造参数详解init签名与参数2.21 版本 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全部参数为关键字参数keyword-only。逐项说明参数类型默认值说明hoststrhttp://localhost:8529ArangoDB 服务地址如http://localhost:8529databasestrhaystack要使用的数据库名不存在时会自动创建usernameSecretSecret.from_env_var(ARANGO_USERNAME, strictFalse)用户名strictFalse意味着环境变量缺失时回退为rootpasswordSecretSecret.from_env_var(ARANGO_PASSWORD)密码默认从ARANGO_PASSWORD环境变量读取collection_namestrhaystack_documents存放文档的 collection 名称embedding_dimensionint768文档嵌入向量的维度必须与所用 Embedder 的输出维度一致recreate_collectionboolFalse为True时启动阶段会 drop 并重建 collection清空存量数据similarity_functionLiteral[cosine, dot_product, l2]cosine向量相似度函数决定嵌入检索的打分方式官方示例来自 API 参考文档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, )认证方式凭据以 Haystack 的Secret对象传入from haystack.utils import Secret。默认行为是从环境变量读取strictFalse是username特有的宽松模式——ARANGO_USERNAME缺失时不报错而回退为root这正对应了 Docker 示例中未显式指定用户名的用法。生产环境中建议显式传入Secret对象而不是依赖环境变量默认值。相似度函数similarity_function决定 AQL 向量函数的比较方式三种取值各有适用场景cosine默认余弦相似度最适合已归一化的嵌入dot_product点积当向量幅值本身携带语义如未归一化嵌入时更合适l2欧氏距离。document_store ArangoDocumentStore( hosthttp://localhost:8529, embedding_dimension768, similarity_functiondot_product, )文档 CRUD APIwrite_documents写入与重复策略write_documents( documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE ) - intdocumentslist[Document]待写入的文档列表policyDuplicatePolicy处理同 ID 重复的策略API 参考列出OVERWRITE、SKIP、FAIL三种行为文档正文标注FAIL为语义默认返回值int实际写入的文档数量异常若documents中混入非Document对象抛出ValueError策略为FAIL且发现重复时抛出DuplicateDocumentError。DuplicatePolicy是 Haystack 核心的统一定义位于 haystack/document_stores/types/policy.py由核心DocumentStore协议在 haystack/document_stores/types/protocol.py 中约定为所有集成 Store 的公共行为契约。从核心协议的 docstring 看完整枚举包含四种策略DuplicatePolicy.NONE签名默认值行为交由具体 Document Store 自行决定DuplicatePolicy.SKIP同 ID 已存在则跳过不写DuplicatePolicy.OVERWRITE同 ID 已存在则覆盖DuplicatePolicy.FAIL同 ID 已存在则抛出错误。也就是说Arango 集成的签名层面取核心协议的NONE默认值而实际重复行为如直接覆盖或报错由 ArangoDB 后端实现决定这正是NONE策略行为依赖 Store语义的体现。幂等重建索引这类场景通常显式传DuplicatePolicy.OVERWRITE。count_documentscount_documents() - int返回 store 中文档总数常用于写入后自检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())filter_documentsHaystack 元数据过滤filter_documents(filters: dict[str, Any] | None None) - list[Document]filters为None时返回全部文档否则按 Haystack 统一的嵌套字典过滤语法返回匹配文档。这套语法由核心协议统一定义见 haystack/document_stores/types/protocol.py所有集成 Store 必须遵守Arango 集成也不例外。比较Comparison字典必须包含field、operator、value三个键operator 取值为、!、、、、、in、not in逻辑Logic字典必须包含operatorNOT/OR/AND与conditions条件字典列表支持任意嵌套。简单过滤示例filters {field: meta.type, operator: , value: article}组合逻辑示例filters { operator: AND, conditions: [ {field: meta.type, operator: , value: article}, { operator: OR, conditions: [ {field: meta.genre, operator: in, value: [economy, politics]}, {field: meta.publisher, operator: , value: nytimes}, ], }, ], }过滤字段作用于文档的meta字典field形如meta.typeDocument数据类本身定义在 haystack/dataclasses/document.py。delete_documentsdelete_documents(document_ids: list[str]) - None按 ID 列表批量删除文档无返回值。序列化与资源释放to_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - ArangoDocumentStore close() - Noneto_dict/from_dict将 store 序列化为字典及反序列化还原。这两个方法同样是核心DocumentStore协议的必备成员haystack/document_stores/types/protocol.py使得整个 Pipeline 连同 DocumentStore 可以被Pipeline.to_dict()一并导出为可部署的 YAML/JSON 定义close释放底层的同步连接资源适用于应用退出或 store 实例不再需要时的显式清理。ArangoEmbeddingRetriever 组件详解构造参数__init__( *, document_store: ArangoDocumentStore, top_k: int 10, filters: dict[str, Any] | None None ) - None参数类型默认值说明document_storeArangoDocumentStore必填检索所用的 DocumentStore 实例必填top_kint10单次检索最多返回的文档数filtersdict[str, Any] \| NoneNone检索时应用的 Haystack 元数据过滤条件语法同filter_documents注意嵌入维度与相似度函数均不在 Retriever 上配置——它们继承自ArangoDocumentStore的embedding_dimension与similarity_function这是文档明确强调的配置归属。run执行向量检索run( query_embedding: list[float], top_k: int | None None, filters: dict[str, Any] | None None, ) - dict[str, list[Document]]query_embeddinglist[float]查询向量必填维度必须等于 store 的embedding_dimensiontop_kint | None本次调用的临时上限覆盖实例级top_kfiltersdict[str, Any] | None本次调用的临时过滤条件覆盖实例级filters返回dict[str, list[Document]]键为documents值为按相似度得分排序的Document列表。top_k与filters的实例默认值 run 级覆盖双通道设计让同一个 Retriever 实例既能承载静态配置又允许上游组件或调用方按请求动态收窄检索空间。独立使用示例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, ...])官方文档给出的可独立运行示例使用 3 维手工向量便于本地验证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)序列化与资源释放to_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - ArangoEmbeddingRetriever close() - None与 DocumentStore 一致to_dict输出序列化字典、from_dict还原实例close用于释放底层 Document Store 的同步资源。作为 Haystackcomponent这套序列化能力使 Retriever 可以随 Pipeline 一起持久化。在 Pipeline 中的完整 RAG 用法官方文档docs-website/docs/pipeline-components/retrievers/arangoembeddingretriever.mdx将ArangoEmbeddingRetriever的典型位置描述为RAG 管线中文本嵌入器之后、PromptBuilder 之前或语义检索管线的最后一个组件。完整可运行示例如下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, ) # 1. 初始化 store维度必须与嵌入模型输出一致all-MiniLM-L6-v2 为 384 维 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.), ] # 2. 文档嵌入并写入 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, ) # 3. 组装查询管线text_embedder - retriever 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)调用链对应关系text_embedder.embedding输出的查询向量按 socket 名称匹配retriever.query_embedding输入这正是run()的必填参数retriever的documents输出可继续连接PromptBuilder等下游组件。两个注意点值得强调embedding_dimension384与all-MiniLM-L6-v2的输出维度严格对应维度不匹配会在 ArangoDB 向量写入或查询时出错write_documents显式传入DuplicatePolicy.OVERWRITE保证重复构建索引时同 ID 文档被覆盖而非报错。核心协议约束集成组件为何长这样Arango 集成虽然源码不在本仓库它发布在独立的haystack-core-integrations仓库中但其 API 形态完全受 Haystack 核心协议约束这一点可以在本仓库源码中得到印证公共方法面haystack/document_stores/types/protocol.py 定义的DocumentStore协议要求实现to_dict、from_dict、count_documents、filter_documents、write_documents——API 参考中ArangoDocumentStore的方法面与之逐一对应delete_documents是 Arango 集成的额外补充过滤语法的统一性比较/逻辑嵌套字典与、in、AND/OR/NOT等操作符由核心协议 docstring 统一定义因此ArangoEmbeddingRetriever.filters与filter_documents(filters)接受同一套语法用户在不同 Store 间迁移时无需重学过滤 DSL重复策略的枚举来源DuplicatePolicy枚举定义于 haystack/document_stores/types/policy.py是全部集成 Store 共享的重复处理契约可序列化性是硬要求to_dict/from_dict在协议中是一等成员使得ArangoDocumentStore和ArangoEmbeddingRetriever都能随 Pipeline 一同序列化部署close()则为显式生命周期管理提供入口。从源码结构看这一核心定义协议与枚举、集成实现后端细节的分层设计是 Haystack 能让 ArangoDB 等外部数据库以统一姿势接入 Pipeline 编排的基础。版本适用说明本文参数与签名以 Haystack 文档站 2.21 版本快照 docs-website/reference_versioned_docs/version-2.21/integrations-api/arangodb.md 为准当前未版本化的参考文档 docs-website/reference/integrations-api/arangodb.md 内容与之一致。适用前提ArangoDB ≥ 3.12 且启动时启用--vector-indexpip install arangodb-haystack安装集成包。若在更高版本中升级建议以新版本参考文档核对签名变化。相关仓库路径API 参考2.21 快照docs-website/reference_versioned_docs/version-2.21/integrations-api/arangodb.md使用指南docs-website/docs/document-stores/arangodocumentstore.mdx、docs-website/docs/pipeline-components/retrievers/arangoembeddingretriever.mdx核心协议与策略haystack/document_stores/types/protocol.py、haystack/document_stores/types/policy.py数据类haystack/dataclasses/document.py【免费下载链接】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），仅供参考