Vespa는 완전한 기능을 갖춘 검색 엔진이자 vector database입니다. vector search(ANN), lexical search, 그리고 구조화된 데이터 검색을 모두 동일한 쿼리에서 지원합니다.
이 노트북은 Vespa.ai를 LangChain vector store로 사용하는 방법을 보여줍니다. 이 integration을 사용하려면 pip install -qU langchain-community로 langchain-community를 설치해야 합니다 vector store를 생성하기 위해 pyvespa를 사용하여 Vespa 서비스에 대한 연결을 생성합니다. 
pip install -qU  pyvespa
pyvespa 패키지를 사용하여 Vespa Cloud instance 또는 로컬 Docker instance에 연결할 수 있습니다. 여기서는 새로운 Vespa application을 생성하고 Docker를 사용하여 배포합니다.

​
Vespa application 생성하기

먼저 application package를 생성해야 합니다: 
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])")],
    )
)
이것은 두 개의 field를 포함하는 각 document에 대한 schema를 가진 Vespa application을 설정합니다: document text를 보관하는 text와 embedding vector를 보관하는 embedding입니다. text field는 효율적인 텍스트 검색을 위해 BM25 index를 사용하도록 설정되며, 나중에 이것과 hybrid search를 사용하는 방법을 살펴보겠습니다. embedding field는 텍스트의 embedding 표현을 보관하기 위해 길이 384의 vector로 설정됩니다. Vespa의 tensor에 대한 자세한 내용은 Vespa’s Tensor Guide를 참조하세요. 마지막으로 rank profile을 추가하여 Vespa에게 document를 정렬하는 방법을 지시합니다. 여기서는 nearest neighbor search로 설정합니다. 이제 이 application을 로컬에 배포할 수 있습니다: 
from vespa.deployment import VespaDocker

vespa_docker = VespaDocker()
vespa_app = vespa_docker.deploy(application_package=app_package)
이것은 Vespa 서비스에 대한 연결을 배포하고 생성합니다. 이미 실행 중인 Vespa application이 있는 경우(예: 클라우드에서), 연결 방법에 대해서는 PyVespa application을 참조하세요.

​
Vespa vector store 생성하기

이제 일부 document를 로드해 보겠습니다: 
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")
여기서는 텍스트를 embedding vector로 변환하기 위해 로컬 sentence embedder도 설정합니다. OpenAI embedding을 사용할 수도 있지만, 해당 embedding의 더 큰 크기를 반영하기 위해 vector 길이를 1536으로 업데이트해야 합니다. 이것들을 Vespa에 공급하려면 vector store가 Vespa application의 field에 어떻게 매핑되어야 하는지 구성해야 합니다. 그런 다음 이 document 세트에서 직접 vector store를 생성합니다: 
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)
이것은 Vespa vector store를 생성하고 해당 document 세트를 Vespa에 공급합니다. vector store는 각 document에 대해 embedding function을 호출하고 데이터베이스에 삽입하는 작업을 처리합니다. 이제 vector store를 쿼리할 수 있습니다: 
query = "What did the president say about Ketanji Brown Jackson"
results = db.similarity_search(query)

print(results[0].page_content)
이것은 위에서 제공한 embedding function을 사용하여 쿼리에 대한 표현을 생성하고 이를 사용하여 Vespa를 검색합니다. 이것은 위의 application package에서 설정한 default ranking function을 사용합니다. similarity_search의 ranking 인수를 사용하여 사용할 ranking function을 지정할 수 있습니다. 자세한 내용은 pyvespa documentation을 참조하세요. 이것은 LangChain에서 Vespa store의 기본 사용법을 다룹니다. 이제 결과를 반환하고 LangChain에서 계속 사용할 수 있습니다.

​
Document 업데이트하기

from_documents를 호출하는 대신 vector store를 직접 생성하고 여기서 add_texts를 호출할 수 있습니다. 이것은 document를 업데이트하는 데에도 사용할 수 있습니다: 
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의 콘텐츠를 조작하는 메서드가 포함되어 있으며 이를 직접 사용할 수 있습니다.

​
Document 삭제하기

delete function을 사용하여 document를 삭제할 수 있습니다: 
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 연결에는 document를 삭제하는 메서드도 포함되어 있습니다.

​
점수와 함께 반환하기

similarity_search 메서드는 관련성 순서로 document만 반환합니다. 실제 점수를 검색하려면: 
results = db.similarity_search_with_score(query)
result = results[0]
# result[1] ~= 0.463
이것은 cosine distance function을 사용하는 "all-MiniLM-L6-v2" embedding model을 사용한 결과입니다(application function의 angular 인수로 제공됨). 다른 embedding function에는 다른 distance function이 필요하며, Vespa는 document를 정렬할 때 사용할 distance function을 알아야 합니다. 자세한 내용은 documentation on distance functions를 참조하세요.

​
Retriever로 사용하기

이 vector store를 LangChain retriever로 사용하려면 표준 vector store 메서드인 as_retriever function을 호출하기만 하면 됩니다: 
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"
이것은 vector store에서 보다 일반적이고 비구조화된 검색을 가능하게 합니다.

​
Metadata

지금까지의 예제에서는 텍스트와 해당 텍스트의 embedding만 사용했습니다. Document에는 일반적으로 추가 정보가 포함되어 있으며, LangChain에서는 이를 metadata라고 합니다. Vespa는 application package에 추가하여 다양한 타입의 많은 field를 포함할 수 있습니다: 
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)
document에 일부 metadata field를 추가할 수 있습니다: 
# 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 vector store에 이러한 field에 대해 알려줍니다: 
vespa_config.update(dict(metadata_fields=["date", "rating", "author"]))
이제 이러한 document를 검색할 때 이러한 field가 반환됩니다. 또한 이러한 field를 필터링할 수 있습니다: 
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"

​
Custom query

similarity search의 기본 동작이 요구 사항에 맞지 않는 경우 항상 자체 쿼리를 제공할 수 있습니다. 따라서 vector store에 모든 구성을 제공할 필요 없이 직접 작성할 수 있습니다. 먼저 application에 BM25 ranking function을 추가해 보겠습니다: 
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
custom query를 사용하여 Vespa의 모든 강력한 검색 및 쿼리 기능을 사용할 수 있습니다. 자세한 내용은 Vespa documentation의 Query API를 참조하세요. Hybrid search는 BM25와 같은 기존 term 기반 검색과 vector search를 모두 사용하고 결과를 결합하는 것을 의미합니다. Vespa에서 hybrid search를 위한 새로운 rank profile을 생성해야 합니다: 
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)
여기서는 각 document를 BM25 점수와 distance 점수의 조합으로 점수를 매깁니다. custom query를 사용하여 쿼리할 수 있습니다: 
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의 Native embedder

지금까지 텍스트에 대한 embedding을 제공하기 위해 Python의 embedding function을 사용했습니다. Vespa는 embedding function을 기본적으로 지원하므로 이 계산을 Vespa로 연기할 수 있습니다. 한 가지 이점은 대규모 컬렉션이 있는 경우 document를 embedding할 때 GPU를 사용할 수 있다는 것입니다. 자세한 내용은 Vespa embeddings를 참조하세요. 먼저 application package를 수정해야 합니다: 
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])")],
    )
)
embedder model과 tokenizer를 application에 추가하는 방법은 embeddings documentation을 참조하세요. hfembedding field에는 hf-embedder를 사용한 embedding 지침이 포함되어 있습니다. 이제 custom query로 쿼리할 수 있습니다: 
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
여기서 쿼리에는 document와 동일한 model을 사용하여 쿼리를 embedding하는 embed 지침이 포함되어 있습니다.

​
Approximate nearest neighbor

위의 모든 예제에서는 결과를 찾기 위해 exact nearest neighbor를 사용했습니다. 그러나 대규모 document 컬렉션의 경우 최상의 일치 항목을 찾기 위해 모든 document를 스캔해야 하므로 실행 가능하지 않습니다. 이를 방지하기 위해 approximate nearest neighbors를 사용할 수 있습니다. 먼저 embedding field를 변경하여 HNSW index를 생성할 수 있습니다: 
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,
        ),
    )
)
이것은 효율적인 검색을 가능하게 하는 embedding data에 HNSW index를 생성합니다. 이것이 설정되면 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 vector store에 있는 대부분의 기능을 다룹니다.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I