企业官网建设流程全解析

Haystack 与 ArangoDB 集成指南：ArangoDocumentStore 与 ArangoEmbeddingRetriever 实现向量检索与 GraphRAG

【免费下载链接】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 官方集成 API 文档（docs-website/reference/integrations-api/arangodb.md）与配套使用指南，系统讲解如何在 Haystack 中使用 ArangoDB 作为 Document Store：你将掌握ArangoDocumentStore的完整初始化参数与增删查方法、ArangoEmbeddingRetriever的检索与过滤用法，以及如何将二者接入 RAG Pipeline，为基于图与向量混合检索的 GraphRAG 应用打下基础。

ArangoDB 集成概览：多模型数据库中的向量检索

ArangoDB 是一款多模型数据库，在单一引擎内同时支持文档（Document）、图（Graph）与键值（Key-Value）三种数据模型。在 Haystack 生态中，ArangoDocumentStore将文档存入 ArangoDB 集合，并使用 AQL（ArangoDB Query Language）向量函数执行向量相似度检索。由于文档与文档之间的关系可以存放在同一数据库中，ArangoDB 非常适合用于将语义搜索与图遍历结合的GraphRAG工作负载。

在 docs-website/docs/concepts/document-store/choosing-a-document-store.mdx 的分类体系中，ArangoDB 被归入Multi-model Databases（多模型数据库）类别，其引擎类型描述为“多模型数据库（图、文档、键值），通过 AQL 向量搜索（需 v3.12+）”，开源状态为 Yes（BUSL 许可），当前不提供异步支持，配套检索器为 Embedding 类型。这一分类意味着：如果你需要在一个引擎里同时承载知识图谱的实体关系与向量的相似度计算，而不想分别维护图数据库和向量数据库，ArangoDB 是值得考虑的选择。

版本前提

向量检索能力依赖 ArangoDB 的向量索引特性，因此要求ArangoDB 3.12 或更高版本，并在启动服务时通过--vector-index启动参数启用该特性。

环境准备：Docker 启动 ArangoDB 与安装集成包

使用 Docker 启动 ArangoDB

启用向量索引并设置 root 密码，将 8529 端口映射到本机：

docker run -d -p 8529:8529 \ -e ARANGO_ROOT_PASSWORD=test-password \ arangodb:3.12 arangod --vector-index

其中-p 8529:8529将 ArangoDB 默认的 HTTP 端口映射到宿主机，ARANGO_ROOT_PASSWORD指定 root 用户的初始密码，arangod --vector-index则是在服务端进程中显式开启向量索引能力——这是后续所有向量检索操作能够运行的前提。

安装 Haystack 集成包

pip install arangodb-haystack

如果希望运行本文中的 Pipeline 示例，还需要安装示例所用的 Sentence Transformers 嵌入器集成包：

pip install sentence-transformers-haystack

安装完成后即可在代码中通过haystack_integrations.document_stores.arangodb与haystack_integrations.components.retrievers.arangodb两个命名空间导入相关类。

ArangoDocumentStore：参数详解与文档管理

ArangoDocumentStore是本次集成的核心存储组件，位于模块haystack_integrations.document_stores.arangodb.document_store。它把 Haystack 的Document对象持久化到 ArangoDB 集合中，并通过 AQL 向量函数提供向量相似度搜索。

初始化签名与参数说明

__init__( *, host: str = "http://localhost:8529", database: str = "haystack", username: Secret = Secret.from_env_var("ARANGO_USERNAME", strict=False), 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

各参数含义如下：

注意__init__的*表示所有参数均为关键字参数（keyword-only），调用时不能使用位置传参。

三种相似度函数的选择

similarity_function决定了检索时向量相似度的计算方式，在初始化阶段配置：

• "cosine"（默认）：余弦相似度，适合归一化后的嵌入向量，是多数语义检索场景的首选；
• "dot_product"：点积，当向量模长（magnitude）本身携带语义信息时更有意义；
• "l2"：欧几里得（L2）距离，度量向量在空间中的实际距离。

例如要切换到点积检索：

from haystack_integrations.document_stores.arangodb import ArangoDocumentStore document_store = ArangoDocumentStore( host="http://localhost:8529", embedding_dimension=768, similarity_function="dot_product", )

认证方式：基于 Secret 的凭据管理

ArangoDB 的凭据以 Haystack 的Secret对象传递。默认情况下从环境变量读取：ARANGO_USERNAME未设置时回退为root，因此通常只需提供密码即可：

export ARANGO_PASSWORD=test-password

也可以显式构造Secret传入，将凭据管理与代码解耦：

from haystack.utils import Secret from haystack_integrations.document_stores.arangodb import ArangoDocumentStore document_store = ArangoDocumentStore( host="http://localhost:8529", database="haystack", username=Secret.from_env_var("ARANGO_USERNAME", strict=False), password=Secret.from_env_var("ARANGO_PASSWORD"), )

关于 HaystackSecret的完整机制（环境变量注入、本地文件、明文值等），可进一步阅读 docs-website/docs/concepts/secret-management.mdx。

写入与统计：write_documents 与 count_documents

将文档写入存储并统计数量：

from haystack import Document from haystack_integrations.document_stores.arangodb import ArangoDocumentStore document_store = ArangoDocumentStore( host="http://localhost:8529", database="haystack", collection_name="documents", embedding_dimension=768, recreate_collection=True, ) document_store.write_documents( [ Document( content="There are over 7,000 languages spoken around the world today.", ), Document( content="Elephants have been observed to recognize themselves in mirrors.", ), ], ) print(document_store.count_documents())

write_documents的完整签名为：

write_documents( documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE ) -> int

• documents：待写入的Document列表；若列表中混入非Document对象，将抛出ValueError。
• policy：重复文档的处理策略，取值为DuplicatePolicy枚举，包括OVERWRITE（覆盖）、SKIP（跳过）与FAIL（失败，默认）。当策略为FAIL且发现重复文档时，抛出DuplicateDocumentError。
• 返回值：实际写入的文档数量（int）。

提示：上方示例中写入的文档未携带embedding字段。若要在检索时进行向量相似度匹配，文档必须包含与embedding_dimension匹配的嵌入向量。要生成真实嵌入，可使用SentenceTransformersDocumentEmbedder等 Document Embedder 组件（见后文 Pipeline 示例），嵌入器的输出维度必须与 store 配置的embedding_dimension一致。

查询与删除：filter_documents 与 delete_documents

filter_documents(filters: dict[str, Any] | None = None) -> list[Document]

返回与给定过滤器匹配的文档列表；若filters为None，则返回全部文档。过滤器使用 Haystack 统一的元数据过滤语法，支持$eq、$in、$gt、$and、$or等操作符，详细语法可参考 docs-website/docs/concepts/metadata-filtering.mdx。

delete_documents(document_ids: list[str]) -> None

根据文档 ID 列表删除文档。

序列化：to_dict 与 from_dict

与其他 Haystack 组件一致，ArangoDocumentStore支持通过字典进行序列化与反序列化，用于 Pipeline 的 YAML/JSON 保存与加载：

• to_dict() -> dict[str, Any]：将组件序列化为字典；
• from_dict(data: dict[str, Any]) -> ArangoDocumentStore：从字典还原组件实例。

资源释放：close

close() -> None用于释放底层 Document Store 关联的同步资源。在完成索引、批量写入或需要显式回收连接时调用，避免资源泄漏。

ArangoEmbeddingRetriever：基于嵌入的向量检索组件

ArangoEmbeddingRetriever位于模块haystack_integrations.components.retrievers.arangodb.embedding_retriever，负责基于嵌入向量的相似度从ArangoDocumentStore中检索文档。相似度函数（cosine / dot_product / l2）在ArangoDocumentStore初始化时统一配置，检索器无需重复指定。

在 Pipeline 中的典型位置（参见 docs-website/docs/pipeline-components/retrievers/arangoembeddingretriever.mdx）：

1. RAG Pipeline 中，位于 Text Embedder 之后、PromptBuilder之前；
2. 语义搜索 Pipeline 中，作为最后一个组件输出候选文档。

初始化签名与参数

__init__( *, document_store: ArangoDocumentStore, top_k: int = 10, filters: dict[str, Any] | None = None ) -> None

run 方法与参数覆盖机制

run( query_embedding: list[float], top_k: int | None = None, filters: dict[str, Any] | None = None, ) -> dict[str, list[Document]]

• query_embedding：查询向量，list[float]类型，维度需与 store 的embedding_dimension一致；
• top_k：本次调用的覆盖值，若传入则优先于初始化时的top_k；
• filters：本次调用的覆盖过滤器，若传入则优先于初始化时的filters；
• 返回值：形如{"documents": [...]}的字典，其中documents为按相似度得分排序的Document列表。

这种“初始化设置默认值、运行时按需覆盖”的设计，让同一个检索器实例可以服务于不同查询规模与过滤范围，无需重复实例化。

独立使用示例

from haystack import Document from haystack_integrations.document_stores.arangodb import ArangoDocumentStore from haystack_integrations.components.retrievers.arangodb import ( ArangoEmbeddingRetriever, ) document_store = ArangoDocumentStore( host="http://localhost:8529", embedding_dimension=3, recreate_collection=True, ) document_store.write_documents( [ Document( content="There are over 7,000 languages spoken around the world today.", embedding=[0.1, 0.2, 0.3], ), Document( content="Elephants have been observed to recognize themselves in mirrors.", embedding=[0.8, 0.1, 0.5], ), ], ) retriever = ArangoEmbeddingRetriever(document_store=document_store, top_k=1) result = retriever.run(query_embedding=[0.1, 0.2, 0.3]) print(result["documents"][0].content)

这个最小示例展示了完整的“建库 → 写文档（带嵌入）→ 检索”闭环：两条文档分别携带 3 维嵌入向量，store 的embedding_dimension=3与之匹配；查询向量[0.1, 0.2, 0.3]与第一条文档完全一致，在top_k=1时返回该文档。

序列化与资源释放

与 Document Store 一致，检索器同样提供：

• to_dict() -> dict[str, Any]：序列化组件为字典；
• from_dict(data: dict[str, Any]) -> ArangoEmbeddingRetriever：从字典还原实例；
• close() -> None：释放底层 Document Store 的同步资源。

实战：将 ArangoDB 接入完整 RAG Pipeline

将ArangoEmbeddingRetriever与嵌入器、Pipeline组合，即可构建一个完整的语义检索与 RAG 查询链路。以下示例使用sentence-transformers/all-MiniLM-L6-v2（输出 384 维嵌入，因此 store 的embedding_dimension=384）：

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( host="http://localhost:8529", embedding_dimension=384, recreate_collection=True, ) documents = [ Document(content="There are over 7,000 languages spoken around the world today."), Document( content="Elephants have been observed to recognize themselves in mirrors.", ), Document( content="Bioluminescent waves can be seen in the Maldives and Puerto Rico.", ), ] document_embedder = SentenceTransformersDocumentEmbedder( model="sentence-transformers/all-MiniLM-L6-v2", ) documents_with_embeddings = document_embedder.run(documents) document_store.write_documents( documents_with_embeddings["documents"], policy=DuplicatePolicy.OVERWRITE, ) query_pipeline = Pipeline() query_pipeline.add_component( "text_embedder", SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"), ) query_pipeline.add_component( "retriever", ArangoEmbeddingRetriever(document_store=document_store, top_k=3), ) 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)

该示例的关键链路：

1. 索引阶段：SentenceTransformersDocumentEmbedder为原始文档生成 384 维嵌入，随后通过write_documents(..., policy=DuplicatePolicy.OVERWRITE)写入 ArangoDB——使用OVERWRITE策略可在重复运行时安全地覆盖旧数据；
2. 查询阶段：Pipeline依次执行text_embedder（将用户文本转为查询向量）与retriever（在 ArangoDB 中执行向量相似度检索）；
3. 连接关系：query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")将文本嵌入器输出的embedding直接接到检索器的query_embedding输入。

运行后，result["retriever"]["documents"]即为按相似度排序的文档列表，[0]为最相关文档。在此基础上，可以在检索器之后继续连接PromptBuilder与生成器，构成完整的 RAG 问答管线；也可以利用 ArangoDB 的图能力，对检索结果做图遍历，实现 GraphRAG 风格的混合推理。

小结与延伸阅读

本文完整覆盖了 ArangoDB 集成在 Haystack 中的两个核心组件：

• ArangoDocumentStore：负责文档持久化、向量索引与相似度检索，核心配置项包括host、database、凭据（username/password的Secret管理）、collection_name、embedding_dimension、recreate_collection与similarity_function；对外提供write_documents、count_documents、filter_documents、delete_documents、to_dict/from_dict、close等方法。
• ArangoEmbeddingRetriever：基于查询向量在 store 上执行 Top-K 相似度检索，top_k与filters既可在初始化时设定，也可在每次run()调用时覆盖；支持标准的to_dict/from_dict序列化与close资源释放。

使用前提是ArangoDB 3.12+ 且以--vector-index参数启用向量索引。若需进一步深入，可继续阅读本仓库内的相关文档：

• API 参考全文：docs-website/reference/integrations-api/arangodb.md
• Document Store 使用指南：docs-website/docs/document-stores/arangodocumentstore.mdx
• Retriever 使用指南：docs-website/docs/pipeline-components/retrievers/arangoembeddingretriever.mdx
• 检索器总览：docs-website/docs/pipeline-components/retrievers.mdx
• 多模型数据库选型对比：docs-website/docs/concepts/document-store/choosing-a-document-store.mdx
• 元数据过滤语法：docs-website/docs/concepts/metadata-filtering.mdx
• Secret 凭据管理：docs-website/docs/concepts/secret-management.mdx

【免费下载链接】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