Haystack 与 ArcadeDB 集成深度指南:基于 LSM_VECTOR/HNSW 索引的向量检索与文档存储实战

原创2026-09-12 19:48:421,632 阅读
文章标签:人工智能大模型RAGAI AgentAgent 框架Agent 编排AI 应用提示工程

Haystack 与 ArcadeDB 集成深度指南:基于 LSM_VECTOR/HNSW 索引的向量检索与文档存储实战

Haystack 的 ArcadeDB 集成通过 ArcadeDBDocumentStore 与 ArcadeDBEmbeddingRetriever 两个组件,让开发者可以借助 ArcadeDB 多模型数据库的 LSM_VECTOR(HNSW)向量索引,构建"索引—写入—向量检索"全链路语义搜索与 RAG 应用。本文以 version-2.18 的 ArcadeDB API 参考文档 为主体,结合 文档存储使用指南 与 检索器组件文档,完整讲解安装配置、全部构造参数、文档增删改查 API、向量检索调用方式以及序列化与资源管理,读完即可在本地跑通一套可复制的语义检索管线。

ArcadeDB 集成概览:为什么选择多模型数据库做向量检索

ArcadeDB 是一个支持图(graph)、文档(document)、键值(key-value)的多模型数据库,其内置的 LSM_VECTOR(基于 HNSW 算法)索引提供了高性能的稠密向量近似最近邻检索能力。Haystack 的 ArcadeDB 集成在设计上有两个显著特点:

  • 纯 HTTP/JSON API 通信:文档存储的所有操作都通过 ArcadeDB 的 HTTP/JSON 接口完成,不需要安装任何专用数据库驱动,降低了部署与依赖复杂度;
  • SQL 元数据过滤:在向量相似度检索之外,还支持基于 SQL 的元数据条件过滤,可以将向量检索与结构化筛选(如类型、日期、标签等字段)组合使用。

从当前仓库中的选型对比文档可以看到,ArcadeDB 的定位是"多模型数据库",支持向量检索但属于纯 Embedding 检索类别(不支持稀疏检索),适合以稠密向量相似度为核心的语义搜索与 RAG 场景。集成对外提供的完整组件面为:

组件 类型 职责
ArcadeDBDocumentStore Document Store 文档写入、删除、过滤、计数、元数据统计与向量索引管理
ArcadeDBEmbeddingRetriever Retriever 基于向量相似度(HNSW)从 Document Store 中检索文档

环境准备:启动 ArcadeDB 与安装集成包

用 Docker 启动 ArcadeDB

ArcadeDB 官方提供了 Docker 镜像,一条命令即可在本地启动服务。注意通过 JAVA_OPTS 中的 -Darcadedb.server.rootPassword 设置 root 用户密码(示例密码为 arcadedb,请按实际环境修改):

docker run -d -p 2480:2480 \
  -e JAVA_OPTS="-Darcadedb.server.rootPassword=arcadedb" \
  arcadedata/arcadedb:latest

启动后,ArcadeDB 的 HTTP 端点默认监听在 2480 端口,即文档存储默认的 url="http://localhost:2480" 所指向的地址。

安装 Haystack 集成包

pip install arcadedb-haystack

如果在示例中还需要使用 Sentence Transformers 嵌入器(将文本转成向量),需额外安装:

pip install sentence-transformers-haystack

配置凭据(推荐环境变量方式)

ArcadeDBDocumentStore 默认从环境变量读取用户名与密码,比硬编码在代码中更安全,也便于切换环境:

export ARCADEDB_USERNAME=root
export ARCADEDB_PASSWORD=arcadedb

当然,也可以显式地在构造函数中传入 username 与 password 参数。

ArcadeDBDocumentStore:向量文档存储的完整 API 解析

ArcadeDBDocumentStore 是面向 Haystack 2.x 的 ArcadeDB 文档存储实现,负责把 Haystack 的 Document 对象持久化到 ArcadeDB 中,并通过 LSM_VECTOR(HNSW)索引提供向量检索能力,同时支持 SQL 元数据过滤。

构造参数详解

__init__ 的完整签名如下(所有参数均为关键字参数):

__init__(
    *,
    url: str = "http://localhost:2480",
    database: str = "haystack",
    username: Secret = Secret.from_env_var("ARCADEDB_USERNAME", strict=False),
    password: Secret = Secret.from_env_var("ARCADEDB_PASSWORD", strict=False),
    type_name: str = "Document",
    embedding_dimension: int = 768,
    similarity_function: str = "cosine",
    recreate_type: bool = False,
    create_database: bool = True
) -> None

各参数的含义与注意事项如下:

参数 类型 默认值 说明
url str "http://localhost:2480" ArcadeDB 的 HTTP 端点地址
database str "haystack" 数据库名称,写入的文档会落到该数据库中
username Secret ARCADEDB_USERNAME 环境变量 HTTP Basic Auth 用户名
password Secret ARCADEDB_PASSWORD 环境变量 HTTP Basic Auth 密码
type_name str "Document" 文档对应的顶点类型(vertex type)名称
embedding_dimension int 768 HNSW 向量索引的维度,必须与实际使用的嵌入模型输出维度一致
similarity_function str "cosine" 距离度量,可选 "cosine"、"euclidean"、"dot"
recreate_type bool False 若为 True,初始化时删除并重建顶点类型(常用于开发环境重置索引结构)
create_database bool True 若为 True,数据库不存在时自动创建

其中两个参数对索引行为影响最大:

  • embedding_dimension:该值决定 HNSW 索引的向量维度。它必须与文档写入时的向量维度一致,否则会触发填充逻辑(见下文"零填充"说明),从而影响检索精度。文档存储指南中也明确提示:维度不匹配或缺失向量的文档会被写入零填充向量,以保证可以写入与过滤,但要获得真正的语义检索能力,必须使用嵌入器生成真实向量。
  • similarity_function:决定向量相似度的度量方式。cosine(余弦相似度)适合大多数语义检索场景;dot(点积)适合已经做过归一化的向量;euclidean(欧氏距离)则适合强调绝对距离差异的场景。选择时应与嵌入模型的训练与使用习惯保持一致。

基础写入与计数示例

下面的示例展示了初始化文档存储并向其中写入两条文档:

from haystack.dataclasses.document import Document
from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore

document_store = ArcadeDBDocumentStore(
    url="http://localhost:2480",
    database="haystack",
    embedding_dimension=768,
)
document_store.write_documents([
    Document(content="This is first", embedding=[0.0]*5),
    Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
])
print(document_store.count_documents())

该示例中写入的向量维度(5)与 embedding_dimension=768 不一致,这正好演示了零填充行为:写入的向量会被补齐/规整到索引要求的维度。在实际生产流程中,应让 embedding_dimension 与 SentenceTransformersDocumentEmbedder 等嵌入器输出的维度严格一致,以 recreate_type=True 在开发期反复重建类型也很方便。

文档写入策略:DuplicatePolicy

write_documents 支持通过 policy 参数控制重复文档 ID 的处理方式:

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

返回值是被写入的文档数量。DuplicatePolicy 枚举定义在 haystack/document_stores/types/policy.py,共有四种取值:

取值 行为
NONE 不检查重复,直接写入(默认)
SKIP 跳过 ID 已存在的文档
OVERWRITE 用新文档覆盖 ID 已存在的旧文档
FAIL 遇到重复 ID 直接抛出异常

例如在更新场景中,使用 policy=DuplicatePolicy.OVERWRITE 可以让同一批文档反复写入而不会堆积重复数据。

文档查询与过滤 API

文档存储提供了丰富的查询与过滤方法:

  • count_documents() -> int:返回文档存储中的文档总数。
  • filter_documents(filters: dict[str, Any] | None = None) -> list[Document]:按 Haystack 过滤语法返回匹配的文档列表。
  • delete_documents(document_ids: list[str]) -> None:按文档 ID 列表删除文档。
  • delete_all_documents() -> None:清空文档存储中的所有文档。
  • delete_by_filter(filters: dict[str, Any]) -> int:删除所有匹配过滤条件的文档,返回删除数量。过滤语法遵循 Haystack 的元数据过滤规范。
  • update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int:更新所有匹配过滤条件文档的元数据,返回更新数量。
  • count_documents_by_filter(filters: dict[str, Any]) -> int:统计匹配过滤条件的文档数量。

元数据统计 API

对于构建数据质量看板、筛选器 UI 或调试检索效果,文档存储还提供了一组元数据统计方法:

  • count_unique_metadata_by_filter(filters, metadata_fields) -> dict[str, int]:对匹配过滤条件的文档,统计每个指定元数据字段的去重值个数,返回 {字段名: 唯一值数量} 字典。
  • get_metadata_fields_info() -> dict[str, dict[str, str]]:基于抽样文档返回元数据字段及其类型,返回形如 {字段名: {"type": "..."}} 的字典。
  • get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]:返回指定元数据字段的最小值与最大值,键为 min 和 max。
  • get_metadata_field_unique_values(metadata_field, search_term=None, from_=0, size=10, filters=None) -> tuple[list[Any], int]:检索某字段的唯一值列表,支持大小写不敏感的子串搜索与分页,返回 (分页后的值列表, 总数量)。

需要注意的是:get_metadata_field_unique_values 中不同类型的值即使在 Python 比较中相等也会被区分对待——整数 1、浮点数 1.0、布尔值 True 与字符串 "1" 会被作为四个独立的值返回。在设计筛选器 UI 或做去重统计时,务必考虑这一行为。

ArcadeDBEmbeddingRetriever:向量相似度检索

ArcadeDBEmbeddingRetriever 通过比较查询向量与文档向量之间的相似度,借助文档存储的 LSM_VECTOR(HNSW)索引完成检索,并可选地叠加元数据过滤与 top_k 数量限制。

构造参数详解

__init__(
    *,
    document_store: ArcadeDBDocumentStore,
    filters: dict[str, Any] | None = None,
    top_k: int = 10,
    filter_policy: FilterPolicy = FilterPolicy.REPLACE
) -> None
参数 类型 默认值 说明
document_store ArcadeDBDocumentStore 必填 一个已初始化的 ArcadeDBDocumentStore 实例,检索器所有查询都会落到该存储上
filters dict[str, Any] | None None 默认过滤条件,会在每次检索调用时生效
top_k int 10 返回的最大文档数量
filter_policy FilterPolicy FilterPolicy.REPLACE 运行时传入的过滤条件与初始化默认过滤条件的组合策略

run 方法与返回结构

run(
    query_embedding: list[float],
    filters: dict[str, Any] | None = None,
    top_k: int | None = None,
) -> dict[str, list[Document]]
参数 类型 说明
query_embedding list[float] 用于检索的查询向量(必填,通常由 Text Embedder 生成)
filters dict[str, Any] | None 可选的元数据过滤条件,用于缩小结果范围
top_k int | None 可选的最大返回数量,覆盖初始化时的默认值

返回值是一个字典,包含键 documents,其值为与查询向量最相似的 Document 列表。

FilterPolicy:初始化过滤与运行时过滤如何协作

filter_policy 决定了初始化时设置的默认过滤条件与每次 run 调用传入的过滤条件如何组合。FilterPolicy 枚举定义于 haystack/document_stores/types/filter_policy.py,有两种取值:

  • FilterPolicy.REPLACE(默认):运行时传入的过滤条件直接替换初始化时设置的过滤条件。这是最直观的策略:run 里给了 filters 就用 run 的,没给就用初始化时的默认过滤条件。
  • FilterPolicy.MERGE:运行时过滤条件与初始化过滤条件合并。二者为比较型过滤条件时按 AND 组合;为逻辑型过滤条件(含 operator 与 conditions)时,若逻辑运算符一致则合并 conditions 列表,不一致则忽略初始化过滤条件并以运行时过滤条件为准。若初始化与运行时过滤条件针对同一字段,则运行时条件覆盖初始化条件。

底层合并逻辑由 apply_filter_policy 函数实现(filter_policy.py),它区分比较过滤({"field", "operator", "value"})与逻辑过滤({"operator", "conditions"})两类结构,再按 MERGE/REPLACE 语义组合。这意味着:

  • 当需要"默认限定某个租户/类别,查询时再叠加个性化条件"时,应使用 FilterPolicy.MERGE;
  • 当需要"每次查询完全独立控制过滤条件"时,使用默认的 FilterPolicy.REPLACE 即可。

独立使用示例

以下示例展示了检索器脱离 Pipeline 直接调用的方式(查询向量由 SentenceTransformersTextEmbedder 生成):

from haystack import Document
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
)
from haystack_integrations.components.retrievers.arcadedb import (
    ArcadeDBEmbeddingRetriever,
)
from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore

store = ArcadeDBDocumentStore(database="mydb")
retriever = ArcadeDBEmbeddingRetriever(document_store=store, top_k=5)

# 写入文档
documents = [
    Document(text="My name is Carla and I live in Berlin"),
    Document(text="My name is Paul and I live in New York"),
    Document(text="My name is Silvano and I live in Matera"),
    Document(text="My name is Usagi Tsukino and I live in Tokyo"),
]
store.write_documents(documents)

# 生成查询向量并检索
embedder = SentenceTransformersTextEmbedder()
query_embeddings = embedder.run("Who lives in Berlin?")["embedding"]

result = retriever.run(query_embedding=query_embeddings)
for doc in result["documents"]:
    print(doc.content)

说明:API 参考文档中该示例的调用写法为 retriever.run(query=query_embeddings),而 run 方法的正式签名参数名为 query_embedding(参考 version-2.18 API 文档),实际调用时应使用 query_embedding= 关键字以保证正确传参。

实战:在 Pipeline 中构建完整语义检索 / RAG 链路

检索器在 Pipeline 中通常有两个典型位置(见 ArcadeDBEmbeddingRetriever 组件文档):

  1. 在 RAG 管线中位于 Text Embedder 之后、ChatPromptBuilder 之前;
  2. 在纯语义搜索管线中作为最后一个组件输出结果。

下面是一个完整的"索引 + 查询"双管线示例。索引侧使用 SentenceTransformersDocumentEmbedder 为文档生成向量并写入存储;查询侧将 Text Embedder 与 Retriever 连接成 Pipeline,实现"文本进、文档出"的语义检索:

from haystack import Document, Pipeline
from haystack.document_stores.types import DuplicatePolicy
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
    SentenceTransformersDocumentEmbedder,
)
from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore
from haystack_integrations.components.retrievers.arcadedb import (
    ArcadeDBEmbeddingRetriever,
)

# 初始化文档存储(开发期重建类型便于反复试验)
document_store = ArcadeDBDocumentStore(
    url="http://localhost:2480",
    database="haystack",
    embedding_dimension=768,
    recreate_type=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()
documents_with_embeddings = document_embedder.run(documents)
document_store.write_documents(
    documents_with_embeddings["documents"],
    policy=DuplicatePolicy.OVERWRITE,
)

# ---- 查询侧:Text Embedder -> Retriever ----
query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
query_pipeline.add_component(
    "retriever",
    ArcadeDBEmbeddingRetriever(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])

要点拆解:

  • 索引侧:SentenceTransformersDocumentEmbedder 为每条 Document 生成 768 维向量,write_documents 配合 DuplicatePolicy.OVERWRITE 确保重复写入时覆盖旧数据;
  • 查询侧:connect("text_embedder.embedding", "retriever.query_embedding") 将文本嵌入结果直接喂给检索器的 query_embedding 输入,省去手动拼装向量的步骤;
  • 结果获取:Pipeline 输出按组件名组织,result["retriever"]["documents"] 即检索到的文档列表。

若要进一步叠加元数据过滤,只需在初始化时传入 filters(例如 {"field": "meta.type", "operator": "==", "value": "article"}),并按需调整 filter_policy。

序列化与资源管理:to_dict / from_dict / close

作为 Haystack 组件,ArcadeDBDocumentStore 与 ArcadeDBEmbeddingRetriever 都实现了标准的序列化协议,便于将组件配置保存为 YAML/JSON 并在不同环境中还原。

ArcadeDBEmbeddingRetriever

  • to_dict() -> dict[str, Any]:将组件序列化为字典(包含组件类型与全部初始化参数),可无缝用于 Pipeline.dumps() 等场景;
  • from_dict(data: dict[str, Any]) -> ArcadeDBEmbeddingRetriever:从字典反序列化还原组件实例;
  • close() -> None:释放底层 Document Store 的同步资源,适合在应用退出或组件生命周期结束时调用。

ArcadeDBDocumentStore

  • to_dict() -> dict[str, Any]:序列化文档存储配置为字典;
  • from_dict(data: dict[str, Any]) -> ArcadeDBDocumentStore:从字典还原文档存储实例;
  • close() -> None:释放关联的同步资源。

借助这套协议,你可以把 ArcadeDB 相关组件纳入 Haystack 的声明式 YAML 配置体系中,实现"配置文件描述管线、代码只负责运行"的部署模式。

最佳实践与注意事项总结

结合上述 API 与源码细节,在实际项目中使用 ArcadeDB 集成时建议关注以下几点:

  1. 向量维度严格一致:embedding_dimension 必须与嵌入模型输出维度一致。文档中提示,缺失向量或维度不匹配的文档会被写入零填充向量,虽然可写入、可过滤,但会污染检索质量——生产环境务必先 Embedder 后写入。
  2. 凭据安全:优先通过 ARCADEDB_USERNAME / ARCADEDB_PASSWORD 环境变量注入凭据,避免在代码或配置文件中出现明文密码;Secret 类型也支持从环境变量惰性读取(strict=False 表示未设置时不报错)。
  3. 开发期善用 recreate_type:当文档结构或索引定义变化时,设 recreate_type=True 可在初始化时自动删除并重建顶点类型,避免手工清理脏数据;生产环境建议保持 False 以防误删。
  4. 过滤策略按场景选择:固定业务范围的过滤条件(如租户隔离)放初始化 filters 并用 MERGE,完全动态的过滤需求用默认 REPLACE,避免出现"预期叠加却互相覆盖"的坑。
  5. 检索质量依赖索引与查询两侧嵌入器:索引侧用 Document Embedder、查询侧用 Text Embedder,二者应使用同一模型族,才能保证向量空间可比,从而让 HNSW 相似度检索有意义。

至此,从 Docker 启动 ArcadeDB、安装 arcadedb-haystack、初始化文档存储、写入文档,到独立调用检索器、组装完整 Pipeline 并掌握序列化与过滤策略,你已经具备在 Haystack 项目中落地 ArcadeDB 向量检索的全部必要知识。更多细节可继续查阅 ArcadeDBDocumentStore 文档、ArcadeDBEmbeddingRetriever 文档 以及 FilterPolicy 源码 与 DuplicatePolicy 源码。

登录后查看全文
haystack