在 Haystack 中集成 VespaVespaDocumentStore 与双检索器完整指南【免费下载链接】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/haystackVespa 是开源的大数据服务引擎支持结构化文本、文本检索与向量检索的海量扩展。本文基于当前仓库中 Vespa 集成的 API 参考文档与使用指南完整讲解VespaDocumentStore的初始化、鉴权、写入与删除 API以及VespaEmbeddingRetriever稠密向量检索与VespaKeywordRetrieverBM25 词法检索两大检索器的全部参数、运行签名与 Pipeline 集成示例帮助你基于已有的 Vespa 应用构建生产级 RAG 与混合检索系统。集成定位与设计哲学VespaDocumentStore是一个背靠已有 Vespa 应用的 Document Store它通过 pyvespa 与 vespadocumentstore.mdx。与 Haystack 中多数 Document Store 不同VespaDocumentStore不会替你创建或部署 Vespa 应用与 schema。你需要自己配置好字段与 rank profile部署 Vespa自托管或 Vespa Cloud再把 Document Store 指向运行中的端点。这意味着 Vespa 的 schema 是集成行为的契约——store 和 retriever 的所有字段名、profile 名参数都必须与已部署的 schema 严格对齐。安装与部署前提安装集成包pip install vespa-haystack本地运行 Vespa 可参考 Vespa 官方快速开始托管部署可选用 Vespa Cloud。文章中的检索示例若使用 Sentence Transformers 嵌入器还需安装pip install sentence-transformers-haystackVespaDocumentStore完整初始化参数构造函数签名如下来自 vespa.md__init__( *, url: str | None None, port: int 8080, cert: Secret | None None, key: Secret | None None, vespa_cloud_secret_token: Secret | None None, additional_headers: dict[str, str] | None None, content_cluster_name: str content, schema: str doc, namespace: str | None None, groupname: str | None None, content_field: str content, embedding_field: str embedding, id_field: str id, metadata_fields: list[str] | None None, query_limit: int DEFAULT_QUERY_LIMIT ) - None参数类型默认值说明urlstr \| NoneNoneVespa 端点基础 URL省略时使用VESPA_URL环境变量portint8080Vespa HTTP 端口cert/keySecret \| NoneNonemTLS 数据面证书/密钥文件路径以 Secret 形式传入vespa_cloud_secret_tokenSecret \| NoneNoneVespa Cloud 数据面 token省略时若设置了VESPA_CLOUD_SECRET_TOKEN环境变量则使用之与 pyvespa 行为一致additional_headersdict[str, str] \| NoneNone发送给 Vespa 应用的额外请求头content_cluster_namestrcontentVespa content cluster 名称schemastrdoc读写所针对的 Vespa schema 名称namespacestr \| NoneNoneVespa namespace省略时默认取 schema 名groupnamestr \| NoneNone可选的 Vespa group 名称content_fieldstrcontent存放文档文本的 Vespa 字段embedding_fieldstrembedding存放稠密向量的 Vespa 字段id_fieldstrid查询响应中携带文档 id 的字段Vespa 文档 id 总是通过data_id写入。若 schema 或 summary 中没有该字段集成会回退到解析 Vespa 文档路径metadata_fieldslist[str] \| NoneNone允许写入并读回的元数据字段白名单query_limitint400批量查询返回文档数的上限默认 400 以保持在 Vespa 常见查询命中上限之内可按需覆盖一个典型初始化示例端点、schema、字段全部对齐from haystack import Document from haystack_integrations.document_stores.vespa import VespaDocumentStore document_store VespaDocumentStore( urlhttp://localhost, schemadoc, namespacedoc, content_fieldcontent, embedding_fieldembedding, metadata_fields[category], ) document_store.write_documents( [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), ], ) print(document_store.count_documents())HTTP 客户端采用懒加载在首次使用时才构建app属性会基于构造时的url、port与鉴权设置cert、key、vespa_cloud_secret_token、additional_headers构建出底层 pyvespaVespa客户端因此 mTLS、bearer token 与自定义请求头会自动生效。Schema 前提字段与 Rank Profile默认情况下集成期望已部署的 Vespa 应用包含字段与 profile 名称均可通过构造参数自定义详见 vespadocumentstore.mdx名为content的文本字段承载 Document 正文VespaKeywordRetriever要求该字段在 schema 中按文本匹配建立索引名为embedding的张量tensor字段承载稠密向量使用 embedding 检索时必需名为bm25的 rank profile供VespaKeywordRetriever使用典型实现为bm25(content)名为semantic的 rank profile以closeness(field, embedding)计分供VespaEmbeddingRetriever使用。鉴权方式VespaDocumentStore支持 pyvespa 提供的全部鉴权方式详见 vespadocumentstore.mdx 鉴权小节无鉴权本地开发时指向未加固的 Vespa 端点mTLS通过cert与key参数传入数据面证书与密钥以 Secret 形式Bearer Token通过vespa_cloud_secret_token参数或VESPA_CLOUD_SECRET_TOKEN环境变量用于 Vespa Cloud token 端点。端点 URL 可通过url参数或VESPA_URL环境变量指定export VESPA_URLhttp://localhostVespa Cloud token 鉴权示例export VESPA_URLhttps://my-app.my-tenant.aws-us-east-1c.z.vespa-app.cloud export VESPA_CLOUD_SECRET_TOKENmy-secret-token元数据字段白名单与元数据过滤Vespa 是严格 schema 绑定的任何要写入或读回的元数据字段都必须在已部署 schema 中存在。metadata_fields参数就是这份白名单——白名单外的元数据键只保留在内存中的 Document 上不会持久化到 Vespa。在过滤方面VespaDocumentStore支持比较运算符、!、、、、、in、not in以及逻辑运算符AND、OR、NOT。过滤器会尽可能被翻译为 Vespa 的 YQL。Document Store 完整 APIVespaDocumentStore提供的核心方法签名与语义见 vespa.md方法签名要点行为to_dict()() - dict[str, Any]使用与__init__一致的参数名基于default_to_dict序列化保证与 Haystack 默认组件序列化兼容count_documents()() - int返回 Vespa 中文档总数count_documents_by_filter(filters)(dict[str, Any]) - int返回匹配过滤条件的文档数write_documents(documents, policy)(list[Document], DuplicatePolicy)写入文档支持重复策略如DuplicatePolicy.OVERWRITE、DuplicatePolicy.NONE返回写入数量delete_documents(document_ids)(list[str]) - None按 id 删除文档delete_all_documents()() - None删除该 store 的 schema、namespace 与 content cluster 下所有文档底层使用 pyvespaVespa.delete_all_docsDocument V1 批量删除delete_by_filter(filters)(dict[str, Any]) - int删除所有匹配过滤条件的文档返回删除数量update_by_filter(filters, meta)(dict[str, Any], dict[str, Any]) - int将meta中的元数据值合并进匹配文档返回更新数量get_documents_by_id(document_ids)(list[str]) - list[Document]按 id 批量取回文档filter_documents(filtersNone)(dict[str, Any] \| None) - list[Document]取回匹配过滤条件的文档get_metadata_fields_info()() - dict[str, dict[str, str]]基于已配置字段返回尽力而为best-effort的元数据字段信息VespaEmbeddingRetriever稠密向量检索VespaEmbeddingRetriever使用 Vespa 的 nearest-neighbor 搜索找到与查询向量最接近的文档并用可配置的 rank profile 计分详见 vespaembeddingretriever.mdx。初始化参数__init__( *, document_store: VespaDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, ranking: str | None DEFAULT_SEMANTIC_RANKING, query_tensor_name: str query_embedding, target_hits: int | None None ) - None参数说明document_store配置好的VespaDocumentStore例如VespaDocumentStore(urlhttp://localhost, schemadoc, namespacedoc)需与 Vespa schema 对齐filters可选的静态 Haystack 元数据过滤器除非在run中被覆盖例如{field: meta.category, operator: , value: news}top_k每次查询默认返回的最大文档数例如10rankingnearest-neighbor 检索后使用的 Vespa rank profile例如semantic用closeness(field, embedding)计分。默认semantic传None使用 schema 默认 profilequery_tensor_nameYQL 与 rank profile 中input.query(...)里的查询张量名例如query_embedding匹配默认semanticprofiletarget_hits可选的 nearest-neighbortargetHits值如10或100在 first-phase ranking 之前每个 content node 考虑多少邻居若document_store不是VespaDocumentStore实例构造会抛出ValueError。运行签名run( query_embedding: list[float], filters: dict[str, Any] | None None, top_k: int | None None, ) - dict[str, list[Document]]query_embedding稠密查询向量float 列表filters抓取文档时应用的过滤器top_k返回的最大文档数返回{documents: [...]}。单独使用from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaEmbeddingRetriever, ) document_store VespaDocumentStore(schemadoc, namespacedoc) retriever VespaEmbeddingRetriever(document_storedocument_store) # 用假向量保持示例简单 retriever.run(query_embedding[0.1] * 768)在 Pipeline 中组合索引阶段用SentenceTransformersDocumentEmbedder生成文档向量查询阶段用SentenceTransformersTextEmbedder生成查询向量并喂给 retrieverfrom haystack import Document, Pipeline from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.writers import DocumentWriter from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaEmbeddingRetriever, ) document_store VespaDocumentStore( schemadoc, namespacedoc, content_fieldcontent, embedding_fieldembedding, metadata_fields[category], ) documents [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), Document(contentCats sleep most of the day., meta{category: animals}), ] indexing Pipeline() indexing.add_component(embedder, SentenceTransformersDocumentEmbedder()) indexing.add_component(writer, DocumentWriter(document_storedocument_store)) indexing.connect(embedder, writer) indexing.run({embedder: {documents: documents}}) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, SentenceTransformersTextEmbedder()) query_pipeline.add_component( retriever, VespaEmbeddingRetriever( document_storedocument_store, top_k2, query_tensor_namequery_embedding, ), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query semantic vector search result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])VespaKeywordRetrieverBM25 词法检索VespaKeywordRetriever对 Vespa 应用执行 YQLuserQuery()并用可配置的 rank profile默认bm25通常使用 Vespa 的 BM25 ranking feature对结果排序详见 vespakeywordretriever.mdx。初始化参数__init__( *, document_store: VespaDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, ranking: str | None DEFAULT_BM25_RANKING ) - None参数说明document_store配置好的VespaDocumentStore需匹配已部署 schema 与端点filters可选的静态 Haystack 元数据过滤器在每次检索时应用除非在run中覆盖top_k每次查询默认返回的最大文档数例如10ranking词法匹配使用的 Vespa rank profile例如bm25用bm25(content)计分。默认bm25传None使用 schema 默认 profile同样地document_store类型不符会抛出ValueError。运行签名run( query: str, filters: dict[str, Any] | None None, top_k: int | None None ) - dict[str, list[Document]]单独使用from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaKeywordRetriever, ) document_store VespaDocumentStore(schemadoc, namespacedoc) retriever VespaKeywordRetriever(document_storedocument_store) retriever.run(querymy nice query)在 RAG Pipeline 中使用运行该示例的前提设置OPENAI_API_KEY、设置VESPA_URL或向 Document Store 传url...、已部署含content文本字段、category元数据字段与bm25rank profile 的 Vespa schemafrom haystack import Document, Pipeline from haystack.components.builders.answer_builder import AnswerBuilder from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaKeywordRetriever, ) # 创建 RAG 查询 Pipeline prompt_template [ ChatMessage.from_system(You are a helpful assistant.), ChatMessage.from_user( Given these documents, answer the question.\nDocuments:\n {% for doc in documents %}{{ doc.content }}{% endfor %}\n Question: {{question}}\nAnswer:, ), ] document_store VespaDocumentStore( schemadoc, namespacedoc, content_fieldcontent, metadata_fields[category], ) documents [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), Document( contentThis note is about something else entirely., meta{category: misc}, ), ] document_store.write_documents(documentsdocuments, policyDuplicatePolicy.OVERWRITE) retriever VespaKeywordRetriever( document_storedocument_store, filters{field: meta.category, operator: , value: docs}, ) rag_pipeline Pipeline() rag_pipeline.add_component(nameretriever, instanceretriever) rag_pipeline.add_component( instanceChatPromptBuilder( templateprompt_template, required_variables{question, documents}, ), nameprompt_builder, ) rag_pipeline.add_component(instanceOpenAIChatGenerator(), namellm) rag_pipeline.add_component(instanceAnswerBuilder(), nameanswer_builder) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder.prompt, llm.messages) rag_pipeline.connect(llm.replies, answer_builder.replies) rag_pipeline.connect(retriever, answer_builder.documents) question How does Haystack work with Vespa? result rag_pipeline.run( { retriever: {query: question}, prompt_builder: {question: question}, answer_builder: {query: question}, }, ) print(result[answer_builder])常见配置要点小结字段对齐是硬约束content_field、embedding_field、id_field、metadata_fields必须与已部署 Vespa schema 完全一致否则写入或读回会失败双检索模式可互补VespaKeywordRetrieverBM25适合精确词法匹配VespaEmbeddingRetrievernearest-neighbor semanticprofile适合语义检索二者共用同一个 Document Store可分别接入不同 Pipeline 或组合为混合检索批量查询上限query_limit默认 400控制批量查询返回的文档数上限超大返回集需求可显式调高鉴权配置本地无鉴权、云端 mTLScert/key与 bearer tokenvespa_cloud_secret_token或VESPA_CLOUD_SECRET_TOKEN三条路径均受支持URL 统一走url参数或VESPA_URL环境变量懒加载客户端pyvespaVespaHTTP 客户端在首次使用时才构建构造 store 本身不会触发网络请求。延伸阅读Vespa 集成 API 参考本文全部方法签名与参数语义的权威出处VespaDocumentStore 使用指南VespaEmbeddingRetriever 使用指南VespaKeywordRetriever 使用指南元数据过滤概念Secret 管理概念选择 Document Store 指南【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Haystack 中集成 Vespa：VespaDocumentStore 与双检索器完整指南
在 Haystack 中集成 VespaVespaDocumentStore 与双检索器完整指南【免费下载链接】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/haystackVespa 是开源的大数据服务引擎支持结构化文本、文本检索与向量检索的海量扩展。本文基于当前仓库中 Vespa 集成的 API 参考文档与使用指南完整讲解VespaDocumentStore的初始化、鉴权、写入与删除 API以及VespaEmbeddingRetriever稠密向量检索与VespaKeywordRetrieverBM25 词法检索两大检索器的全部参数、运行签名与 Pipeline 集成示例帮助你基于已有的 Vespa 应用构建生产级 RAG 与混合检索系统。集成定位与设计哲学VespaDocumentStore是一个背靠已有 Vespa 应用的 Document Store它通过 pyvespa 与 vespadocumentstore.mdx。与 Haystack 中多数 Document Store 不同VespaDocumentStore不会替你创建或部署 Vespa 应用与 schema。你需要自己配置好字段与 rank profile部署 Vespa自托管或 Vespa Cloud再把 Document Store 指向运行中的端点。这意味着 Vespa 的 schema 是集成行为的契约——store 和 retriever 的所有字段名、profile 名参数都必须与已部署的 schema 严格对齐。安装与部署前提安装集成包pip install vespa-haystack本地运行 Vespa 可参考 Vespa 官方快速开始托管部署可选用 Vespa Cloud。文章中的检索示例若使用 Sentence Transformers 嵌入器还需安装pip install sentence-transformers-haystackVespaDocumentStore完整初始化参数构造函数签名如下来自 vespa.md__init__( *, url: str | None None, port: int 8080, cert: Secret | None None, key: Secret | None None, vespa_cloud_secret_token: Secret | None None, additional_headers: dict[str, str] | None None, content_cluster_name: str content, schema: str doc, namespace: str | None None, groupname: str | None None, content_field: str content, embedding_field: str embedding, id_field: str id, metadata_fields: list[str] | None None, query_limit: int DEFAULT_QUERY_LIMIT ) - None参数类型默认值说明urlstr \| NoneNoneVespa 端点基础 URL省略时使用VESPA_URL环境变量portint8080Vespa HTTP 端口cert/keySecret \| NoneNonemTLS 数据面证书/密钥文件路径以 Secret 形式传入vespa_cloud_secret_tokenSecret \| NoneNoneVespa Cloud 数据面 token省略时若设置了VESPA_CLOUD_SECRET_TOKEN环境变量则使用之与 pyvespa 行为一致additional_headersdict[str, str] \| NoneNone发送给 Vespa 应用的额外请求头content_cluster_namestrcontentVespa content cluster 名称schemastrdoc读写所针对的 Vespa schema 名称namespacestr \| NoneNoneVespa namespace省略时默认取 schema 名groupnamestr \| NoneNone可选的 Vespa group 名称content_fieldstrcontent存放文档文本的 Vespa 字段embedding_fieldstrembedding存放稠密向量的 Vespa 字段id_fieldstrid查询响应中携带文档 id 的字段Vespa 文档 id 总是通过data_id写入。若 schema 或 summary 中没有该字段集成会回退到解析 Vespa 文档路径metadata_fieldslist[str] \| NoneNone允许写入并读回的元数据字段白名单query_limitint400批量查询返回文档数的上限默认 400 以保持在 Vespa 常见查询命中上限之内可按需覆盖一个典型初始化示例端点、schema、字段全部对齐from haystack import Document from haystack_integrations.document_stores.vespa import VespaDocumentStore document_store VespaDocumentStore( urlhttp://localhost, schemadoc, namespacedoc, content_fieldcontent, embedding_fieldembedding, metadata_fields[category], ) document_store.write_documents( [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), ], ) print(document_store.count_documents())HTTP 客户端采用懒加载在首次使用时才构建app属性会基于构造时的url、port与鉴权设置cert、key、vespa_cloud_secret_token、additional_headers构建出底层 pyvespaVespa客户端因此 mTLS、bearer token 与自定义请求头会自动生效。Schema 前提字段与 Rank Profile默认情况下集成期望已部署的 Vespa 应用包含字段与 profile 名称均可通过构造参数自定义详见 vespadocumentstore.mdx名为content的文本字段承载 Document 正文VespaKeywordRetriever要求该字段在 schema 中按文本匹配建立索引名为embedding的张量tensor字段承载稠密向量使用 embedding 检索时必需名为bm25的 rank profile供VespaKeywordRetriever使用典型实现为bm25(content)名为semantic的 rank profile以closeness(field, embedding)计分供VespaEmbeddingRetriever使用。鉴权方式VespaDocumentStore支持 pyvespa 提供的全部鉴权方式详见 vespadocumentstore.mdx 鉴权小节无鉴权本地开发时指向未加固的 Vespa 端点mTLS通过cert与key参数传入数据面证书与密钥以 Secret 形式Bearer Token通过vespa_cloud_secret_token参数或VESPA_CLOUD_SECRET_TOKEN环境变量用于 Vespa Cloud token 端点。端点 URL 可通过url参数或VESPA_URL环境变量指定export VESPA_URLhttp://localhostVespa Cloud token 鉴权示例export VESPA_URLhttps://my-app.my-tenant.aws-us-east-1c.z.vespa-app.cloud export VESPA_CLOUD_SECRET_TOKENmy-secret-token元数据字段白名单与元数据过滤Vespa 是严格 schema 绑定的任何要写入或读回的元数据字段都必须在已部署 schema 中存在。metadata_fields参数就是这份白名单——白名单外的元数据键只保留在内存中的 Document 上不会持久化到 Vespa。在过滤方面VespaDocumentStore支持比较运算符、!、、、、、in、not in以及逻辑运算符AND、OR、NOT。过滤器会尽可能被翻译为 Vespa 的 YQL。Document Store 完整 APIVespaDocumentStore提供的核心方法签名与语义见 vespa.md方法签名要点行为to_dict()() - dict[str, Any]使用与__init__一致的参数名基于default_to_dict序列化保证与 Haystack 默认组件序列化兼容count_documents()() - int返回 Vespa 中文档总数count_documents_by_filter(filters)(dict[str, Any]) - int返回匹配过滤条件的文档数write_documents(documents, policy)(list[Document], DuplicatePolicy)写入文档支持重复策略如DuplicatePolicy.OVERWRITE、DuplicatePolicy.NONE返回写入数量delete_documents(document_ids)(list[str]) - None按 id 删除文档delete_all_documents()() - None删除该 store 的 schema、namespace 与 content cluster 下所有文档底层使用 pyvespaVespa.delete_all_docsDocument V1 批量删除delete_by_filter(filters)(dict[str, Any]) - int删除所有匹配过滤条件的文档返回删除数量update_by_filter(filters, meta)(dict[str, Any], dict[str, Any]) - int将meta中的元数据值合并进匹配文档返回更新数量get_documents_by_id(document_ids)(list[str]) - list[Document]按 id 批量取回文档filter_documents(filtersNone)(dict[str, Any] \| None) - list[Document]取回匹配过滤条件的文档get_metadata_fields_info()() - dict[str, dict[str, str]]基于已配置字段返回尽力而为best-effort的元数据字段信息VespaEmbeddingRetriever稠密向量检索VespaEmbeddingRetriever使用 Vespa 的 nearest-neighbor 搜索找到与查询向量最接近的文档并用可配置的 rank profile 计分详见 vespaembeddingretriever.mdx。初始化参数__init__( *, document_store: VespaDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, ranking: str | None DEFAULT_SEMANTIC_RANKING, query_tensor_name: str query_embedding, target_hits: int | None None ) - None参数说明document_store配置好的VespaDocumentStore例如VespaDocumentStore(urlhttp://localhost, schemadoc, namespacedoc)需与 Vespa schema 对齐filters可选的静态 Haystack 元数据过滤器除非在run中被覆盖例如{field: meta.category, operator: , value: news}top_k每次查询默认返回的最大文档数例如10rankingnearest-neighbor 检索后使用的 Vespa rank profile例如semantic用closeness(field, embedding)计分。默认semantic传None使用 schema 默认 profilequery_tensor_nameYQL 与 rank profile 中input.query(...)里的查询张量名例如query_embedding匹配默认semanticprofiletarget_hits可选的 nearest-neighbortargetHits值如10或100在 first-phase ranking 之前每个 content node 考虑多少邻居若document_store不是VespaDocumentStore实例构造会抛出ValueError。运行签名run( query_embedding: list[float], filters: dict[str, Any] | None None, top_k: int | None None, ) - dict[str, list[Document]]query_embedding稠密查询向量float 列表filters抓取文档时应用的过滤器top_k返回的最大文档数返回{documents: [...]}。单独使用from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaEmbeddingRetriever, ) document_store VespaDocumentStore(schemadoc, namespacedoc) retriever VespaEmbeddingRetriever(document_storedocument_store) # 用假向量保持示例简单 retriever.run(query_embedding[0.1] * 768)在 Pipeline 中组合索引阶段用SentenceTransformersDocumentEmbedder生成文档向量查询阶段用SentenceTransformersTextEmbedder生成查询向量并喂给 retrieverfrom haystack import Document, Pipeline from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.writers import DocumentWriter from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaEmbeddingRetriever, ) document_store VespaDocumentStore( schemadoc, namespacedoc, content_fieldcontent, embedding_fieldembedding, metadata_fields[category], ) documents [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), Document(contentCats sleep most of the day., meta{category: animals}), ] indexing Pipeline() indexing.add_component(embedder, SentenceTransformersDocumentEmbedder()) indexing.add_component(writer, DocumentWriter(document_storedocument_store)) indexing.connect(embedder, writer) indexing.run({embedder: {documents: documents}}) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, SentenceTransformersTextEmbedder()) query_pipeline.add_component( retriever, VespaEmbeddingRetriever( document_storedocument_store, top_k2, query_tensor_namequery_embedding, ), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query semantic vector search result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])VespaKeywordRetrieverBM25 词法检索VespaKeywordRetriever对 Vespa 应用执行 YQLuserQuery()并用可配置的 rank profile默认bm25通常使用 Vespa 的 BM25 ranking feature对结果排序详见 vespakeywordretriever.mdx。初始化参数__init__( *, document_store: VespaDocumentStore, filters: dict[str, Any] | None None, top_k: int 10, ranking: str | None DEFAULT_BM25_RANKING ) - None参数说明document_store配置好的VespaDocumentStore需匹配已部署 schema 与端点filters可选的静态 Haystack 元数据过滤器在每次检索时应用除非在run中覆盖top_k每次查询默认返回的最大文档数例如10ranking词法匹配使用的 Vespa rank profile例如bm25用bm25(content)计分。默认bm25传None使用 schema 默认 profile同样地document_store类型不符会抛出ValueError。运行签名run( query: str, filters: dict[str, Any] | None None, top_k: int | None None ) - dict[str, list[Document]]单独使用from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaKeywordRetriever, ) document_store VespaDocumentStore(schemadoc, namespacedoc) retriever VespaKeywordRetriever(document_storedocument_store) retriever.run(querymy nice query)在 RAG Pipeline 中使用运行该示例的前提设置OPENAI_API_KEY、设置VESPA_URL或向 Document Store 传url...、已部署含content文本字段、category元数据字段与bm25rank profile 的 Vespa schemafrom haystack import Document, Pipeline from haystack.components.builders.answer_builder import AnswerBuilder from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.document_stores.vespa import VespaDocumentStore from haystack_integrations.components.retrievers.vespa import ( VespaKeywordRetriever, ) # 创建 RAG 查询 Pipeline prompt_template [ ChatMessage.from_system(You are a helpful assistant.), ChatMessage.from_user( Given these documents, answer the question.\nDocuments:\n {% for doc in documents %}{{ doc.content }}{% endfor %}\n Question: {{question}}\nAnswer:, ), ] document_store VespaDocumentStore( schemadoc, namespacedoc, content_fieldcontent, metadata_fields[category], ) documents [ Document( contentHaystack integrates with Vespa for search., meta{category: docs}, ), Document( contentVespa supports lexical and vector retrieval., meta{category: docs}, ), Document( contentThis note is about something else entirely., meta{category: misc}, ), ] document_store.write_documents(documentsdocuments, policyDuplicatePolicy.OVERWRITE) retriever VespaKeywordRetriever( document_storedocument_store, filters{field: meta.category, operator: , value: docs}, ) rag_pipeline Pipeline() rag_pipeline.add_component(nameretriever, instanceretriever) rag_pipeline.add_component( instanceChatPromptBuilder( templateprompt_template, required_variables{question, documents}, ), nameprompt_builder, ) rag_pipeline.add_component(instanceOpenAIChatGenerator(), namellm) rag_pipeline.add_component(instanceAnswerBuilder(), nameanswer_builder) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder.prompt, llm.messages) rag_pipeline.connect(llm.replies, answer_builder.replies) rag_pipeline.connect(retriever, answer_builder.documents) question How does Haystack work with Vespa? result rag_pipeline.run( { retriever: {query: question}, prompt_builder: {question: question}, answer_builder: {query: question}, }, ) print(result[answer_builder])常见配置要点小结字段对齐是硬约束content_field、embedding_field、id_field、metadata_fields必须与已部署 Vespa schema 完全一致否则写入或读回会失败双检索模式可互补VespaKeywordRetrieverBM25适合精确词法匹配VespaEmbeddingRetrievernearest-neighbor semanticprofile适合语义检索二者共用同一个 Document Store可分别接入不同 Pipeline 或组合为混合检索批量查询上限query_limit默认 400控制批量查询返回的文档数上限超大返回集需求可显式调高鉴权配置本地无鉴权、云端 mTLScert/key与 bearer tokenvespa_cloud_secret_token或VESPA_CLOUD_SECRET_TOKEN三条路径均受支持URL 统一走url参数或VESPA_URL环境变量懒加载客户端pyvespaVespaHTTP 客户端在首次使用时才构建构造 store 本身不会触发网络请求。延伸阅读Vespa 集成 API 参考本文全部方法签名与参数语义的权威出处VespaDocumentStore 使用指南VespaEmbeddingRetriever 使用指南VespaKeywordRetriever 使用指南元数据过滤概念Secret 管理概念选择 Document Store 指南【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考