Haystack 与 ArcadeDB 集成深度指南:基于 LSM_VECTOR/HNSW 索引的向量检索与文档存储实战
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 组件文档):
- 在 RAG 管线中位于 Text Embedder 之后、ChatPromptBuilder 之前;
- 在纯语义搜索管线中作为最后一个组件输出结果。
下面是一个完整的"索引 + 查询"双管线示例。索引侧使用 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 集成时建议关注以下几点:
- 向量维度严格一致:
embedding_dimension必须与嵌入模型输出维度一致。文档中提示,缺失向量或维度不匹配的文档会被写入零填充向量,虽然可写入、可过滤,但会污染检索质量——生产环境务必先 Embedder 后写入。 - 凭据安全:优先通过
ARCADEDB_USERNAME/ARCADEDB_PASSWORD环境变量注入凭据,避免在代码或配置文件中出现明文密码;Secret类型也支持从环境变量惰性读取(strict=False表示未设置时不报错)。 - 开发期善用
recreate_type:当文档结构或索引定义变化时,设recreate_type=True可在初始化时自动删除并重建顶点类型,避免手工清理脏数据;生产环境建议保持False以防误删。 - 过滤策略按场景选择:固定业务范围的过滤条件(如租户隔离)放初始化
filters并用MERGE,完全动态的过滤需求用默认REPLACE,避免出现"预期叠加却互相覆盖"的坑。 - 检索质量依赖索引与查询两侧嵌入器:索引侧用 Document Embedder、查询侧用 Text Embedder,二者应使用同一模型族,才能保证向量空间可比,从而让 HNSW 相似度检索有意义。
至此,从 Docker 启动 ArcadeDB、安装 arcadedb-haystack、初始化文档存储、写入文档,到独立调用检索器、组装完整 Pipeline 并掌握序列化与过滤策略,你已经具备在 Haystack 项目中落地 ArcadeDB 向量检索的全部必要知识。更多细节可继续查阅 ArcadeDBDocumentStore 文档、ArcadeDBEmbeddingRetriever 文档 以及 FilterPolicy 源码 与 DuplicatePolicy 源码。