Vespa

Vespa 是一个功能齐全的搜索引擎和向量数据库。它支持向量搜索（ANN）、词法搜索以及结构化数据查询，所有这些都可以在同一查询中实现。

该笔记本展示了如何将Vespa.ai用作LangChain向量存储。

您需要使用 langchain-community 安装 pip install -qU langchain-community 才能使用此集成

为了创建向量存储，我们使用 pyvespa 来建立与 Vespa 服务的连接。

%pip install --upgrade --quiet  pyvespa

使用 pyvespa 包，你可以连接到 Vespa Cloud 实例或本地的 Docker 实例。这里，我们将创建一个新的 Vespa 应用程序，并使用 Docker 部署它。

创建一个Vespa应用

首先，我们需要创建一个应用程序包：

from vespa.package import ApplicationPackage, Field, RankProfile

app_package = ApplicationPackage(name="testapp")
app_package.schema.add_fields(
    Field(
        name="text", type="string", indexing=["index", "summary"], index="enable-bm25"
    ),
    Field(
        name="embedding",
        type="tensor<float>(x[384])",
        indexing=["attribute", "summary"],
        attribute=["distance-metric: angular"],
    ),
)
app_package.schema.add_rank_profile(
    RankProfile(
        name="default",
        first_phase="closeness(field, embedding)",
        inputs=[("query(query_embedding)", "tensor<float>(x[384])")],
    )
)

这将为每个文档设置一个带有模式的 Vespa 应用程序，该模式包含两个字段：text 用于存储文档文本，embedding 用于存储嵌入向量。text 字段配置为使用 BM25 索引以实现高效的文本检索，稍后我们将了解如何使用该索引以及混合搜索。

embedding 字段被设置为一个长度为 384 的向量，用于存储文本的嵌入表示。有关 Vespa 中张量的更多内容，请参见 Vespa 张量指南。

最后，我们添加一个排序配置文件，以指示Vespa如何对文档进行排序。在这里，我们通过最近邻搜索来设置此功能。

现在我们可以将此应用程序本地部署：

from vespa.deployment import VespaDocker

vespa_docker = VespaDocker()
vespa_app = vespa_docker.deploy(application_package=app_package)

此操作将部署并创建与 Vespa 服务的连接。如果您已经运行了 Vespa 应用程序，例如在云端，请参考 PyVespa 应用程序以了解如何进行连接。

创建一个Vespa向量存储

现在，让我们加载一些文档：

from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import CharacterTextSplitter

loader = TextLoader("../../how_to/state_of_the_union.txt")
documents = loader.load()
text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
docs = text_splitter.split_documents(documents)

from langchain_community.embeddings.sentence_transformer import (
    SentenceTransformerEmbeddings,
)

embedding_function = SentenceTransformerEmbeddings(model_name="all-MiniLM-L6-v2")

API 参考:文本加载器 |CharacterTextSplitter |SentenceTransformer嵌入

这里，我们还设置了本地句子嵌入器，用于将文本转换为嵌入向量。也可以使用 OpenAI 嵌入，但需要将向量长度更新为 1536，以反映该嵌入的更大尺寸。

要将这些数据提供给 Vespa，我们需要配置向量存储应如何映射到 Vespa 应用程序中的字段。然后，我们直接从这组文档创建向量存储：

vespa_config = dict(
    page_content_field="text",
    embedding_field="embedding",
    input_field="query_embedding",
)

from langchain_community.vectorstores import VespaStore

db = VespaStore.from_documents(docs, embedding_function, app=vespa_app, **vespa_config)

API 参考:VespaStore

这将创建一个Vespa向量存储，并将该组文档导入Vespa。向量存储会负责为每个文档调用嵌入函数，并将它们插入到数据库中。

我们现在可以查询向量存储了：

query = "What did the president say about Ketanji Brown Jackson"
results = db.similarity_search(query)

print(results[0].page_content)

这将使用上面给出的嵌入函数为查询创建一个表示，并利用该表示来搜索Vespa。请注意，这将使用我们在上述应用包中设置的default排序函数。你可以通过向similarity_search传递ranking参数来指定要使用的排序函数。

请参阅pyvespa 文档以获取更多信息。

这涵盖了 LangChain 中 Vespa 存储的基本用法。现在你可以返回结果并继续在 LangChain 中使用这些结果。

更新文档

调用 from_documents 的另一种方式是直接创建向量存储，然后从中调用 add_texts。这也可以用于更新文档：

query = "What did the president say about Ketanji Brown Jackson"
results = db.similarity_search(query)
result = results[0]

result.page_content = "UPDATED: " + result.page_content
db.add_texts([result.page_content], [result.metadata], result.metadata["id"])

results = db.similarity_search(query)
print(results[0].page_content)

然而，pyvespa 库包含可直接用于操作 Vespa 上内容的方法。

删除文档

您可以使用 delete 函数删除文档：

result = db.similarity_search(query)
# docs[0].metadata["id"] == "id:testapp:testapp::32"

db.delete(["32"])
result = db.similarity_search(query)
# docs[0].metadata["id"] != "id:testapp:testapp::32"

同样，pyvespa 连接也包含用于删除文档的方法。

返回并附带分数

similarity_search 方法仅按相关性顺序返回文档。要获取实际的分数：

results = db.similarity_search_with_score(query)
result = results[0]
# result[1] ~= 0.463

这是使用 "all-MiniLM-L6-v2" 嵌入模型并结合余弦距离函数（由应用函数中的参数 angular 指定）所得的结果。

不同的嵌入函数需要不同的距离函数，而Vespa 需要知道在对文档进行排序时使用哪种距离函数。更多信息请参考关于距离函数的文档。

作为检索器

要将此向量存储用作 LangChain 检索器，只需调用 as_retriever 函数即可，这是一个标准的向量存储方法：

db = VespaStore.from_documents(docs, embedding_function, app=vespa_app, **vespa_config)
retriever = db.as_retriever()
query = "What did the president say about Ketanji Brown Jackson"
results = retriever.invoke(query)

# results[0].metadata["id"] == "id:testapp:testapp::32"

这使得可以从向量存储中进行更通用、非结构化的检索。

元数据

到目前为止，在示例中我们仅使用了文本及其对应的嵌入表示。通常文档还包含其他信息，在 LangChain 中这些信息被称为元数据。

Vespa 可以通过将不同类型的字段添加到应用程序包中来包含许多字段：

app_package.schema.add_fields(
    # ...
    Field(name="date", type="string", indexing=["attribute", "summary"]),
    Field(name="rating", type="int", indexing=["attribute", "summary"]),
    Field(name="author", type="string", indexing=["attribute", "summary"]),
    # ...
)
vespa_app = vespa_docker.deploy(application_package=app_package)

我们可以在文档中添加一些元数据字段：

# Add metadata
for i, doc in enumerate(docs):
    doc.metadata["date"] = f"2023-{(i % 12)+1}-{(i % 28)+1}"
    doc.metadata["rating"] = range(1, 6)[i % 5]
    doc.metadata["author"] = ["Joe Biden", "Unknown"][min(i, 1)]

并让 Vespa 向量存储了解这些字段：

vespa_config.update(dict(metadata_fields=["date", "rating", "author"]))

现在，当搜索这些文档时，将返回这些字段。此外，还可以对这些字段进行过滤：

db = VespaStore.from_documents(docs, embedding_function, app=vespa_app, **vespa_config)
query = "What did the president say about Ketanji Brown Jackson"
results = db.similarity_search(query, filter="rating > 3")
# results[0].metadata["id"] == "id:testapp:testapp::34"
# results[0].metadata["author"] == "Unknown"

自定义查询

如果相似性搜索的默认行为不符合您的需求，您可以始终提供自己的查询。因此，您不必将所有配置提供给向量存储，而只需自行编写即可。

首先，让我们向我们的应用程序添加一个BM25排序函数：

from vespa.package import FieldSet

app_package.schema.add_field_set(FieldSet(name="default", fields=["text"]))
app_package.schema.add_rank_profile(RankProfile(name="bm25", first_phase="bm25(text)"))
vespa_app = vespa_docker.deploy(application_package=app_package)
db = VespaStore.from_documents(docs, embedding_function, app=vespa_app, **vespa_config)

然后，基于BM25执行常规文本搜索：

query = "What did the president say about Ketanji Brown Jackson"
custom_query = {
    "yql": "select * from sources * where userQuery()",
    "query": query,
    "type": "weakAnd",
    "ranking": "bm25",
    "hits": 4,
}
results = db.similarity_search_with_score(query, custom_query=custom_query)
# results[0][0].metadata["id"] == "id:testapp:testapp::32"
# results[0][1] ~= 14.384

通过使用自定义查询，可以利用 Vespa 所有强大的搜索和查询功能。更多详细信息，请参考 Vespa 关于其查询API 的文档。

混合搜索

混合搜索是指同时使用基于经典术语的搜索（如 BM25）和向量搜索，并将两者的结果进行结合。我们需要在 Vespa 上为混合搜索创建一个新的排序配置文件：

app_package.schema.add_rank_profile(
    RankProfile(
        name="hybrid",
        first_phase="log(bm25(text)) + 0.5 * closeness(field, embedding)",
        inputs=[("query(query_embedding)", "tensor<float>(x[384])")],
    )
)
vespa_app = vespa_docker.deploy(application_package=app_package)
db = VespaStore.from_documents(docs, embedding_function, app=vespa_app, **vespa_config)

在这里，我们将每个文档的得分作为其BM25得分和距离得分的组合。我们可以使用自定义查询进行查询：

query = "What did the president say about Ketanji Brown Jackson"
query_embedding = embedding_function.embed_query(query)
nearest_neighbor_expression = (
    "{targetHits: 4}nearestNeighbor(embedding, query_embedding)"
)
custom_query = {
    "yql": f"select * from sources * where {nearest_neighbor_expression} and userQuery()",
    "query": query,
    "type": "weakAnd",
    "input.query(query_embedding)": query_embedding,
    "ranking": "hybrid",
    "hits": 4,
}
results = db.similarity_search_with_score(query, custom_query=custom_query)
# results[0][0].metadata["id"], "id:testapp:testapp::32")
# results[0][1] ~= 2.897

Vespa中的原生嵌入器

到目前为止，我们一直在 Python 中使用嵌入函数为文本提供嵌入。Vespa 原生支持嵌入函数，因此您可以将此计算推迟到 Vespa 中进行。其中一个好处是，当您拥有大量文档集合时，可以在嵌入文档时使用 GPU。

请参考 Vespa 嵌入以获取更多信息。

首先，我们需要修改我们的应用程序包：

from vespa.package import Component, Parameter

app_package.components = [
    Component(
        id="hf-embedder",
        type="hugging-face-embedder",
        parameters=[
            Parameter("transformer-model", {"path": "..."}),
            Parameter("tokenizer-model", {"url": "..."}),
        ],
    )
]
Field(
    name="hfembedding",
    type="tensor<float>(x[384])",
    is_document_field=False,
    indexing=["input text", "embed hf-embedder", "attribute", "summary"],
    attribute=["distance-metric: angular"],
)
app_package.schema.add_rank_profile(
    RankProfile(
        name="hf_similarity",
        first_phase="closeness(field, hfembedding)",
        inputs=[("query(query_embedding)", "tensor<float>(x[384])")],
    )
)

请参考嵌入式文档，了解如何向应用程序添加嵌入模型和分词器。请注意，hfembedding 字段包含使用 hf-embedder 进行嵌入的说明。

现在我们可以使用自定义查询进行查询：

query = "What did the president say about Ketanji Brown Jackson"
nearest_neighbor_expression = (
    "{targetHits: 4}nearestNeighbor(internalembedding, query_embedding)"
)
custom_query = {
    "yql": f"select * from sources * where {nearest_neighbor_expression}",
    "input.query(query_embedding)": f'embed(hf-embedder, "{query}")',
    "ranking": "internal_similarity",
    "hits": 4,
}
results = db.similarity_search_with_score(query, custom_query=custom_query)
# results[0][0].metadata["id"], "id:testapp:testapp::32")
# results[0][1] ~= 0.630

请注意，此处的查询包含一个 embed 指令，用于使用与文档相同的模型嵌入查询。

近似最近邻

在以上所有示例中，我们均使用了精确最近邻来查找结果。然而，对于大量文档集合而言，这并不可行，因为必须扫描所有文档才能找到最匹配的结果。为避免此问题，我们可以使用近似最近邻。

首先，我们可以更改嵌入字段以创建一个HNSW索引：

from vespa.package import HNSW

app_package.schema.add_fields(
    Field(
        name="embedding",
        type="tensor<float>(x[384])",
        indexing=["attribute", "summary", "index"],
        ann=HNSW(
            distance_metric="angular",
            max_links_per_node=16,
            neighbors_to_explore_at_insert=200,
        ),
    )
)

这会在嵌入数据上创建一个HNSW索引，从而实现高效的搜索。通过此设置，我们可以通过将 approximate 参数设置为 True 来轻松地使用ANN进行搜索：

query = "What did the president say about Ketanji Brown Jackson"
results = db.similarity_search(query, approximate=True)
# results[0][0].metadata["id"], "id:testapp:testapp::32")

这涵盖了 LangChain 中 Vespa 向量存储的大部分功能。

向量存储概念指南
向量存储使用指南

创建一个Vespa应用​

创建一个Vespa向量存储​

更新文档​

删除文档​

返回并附带分数​

作为检索器​

元数据​

自定义查询​

混合搜索​

Vespa中的原生嵌入器​

近似最近邻​

相关​