Haystack 集成指南：在 RAG 管道中完整使用 Jina AI（Reader 连接器、Embedder、Ranker）

Haystack 集成指南在 RAG 管道中完整使用 Jina AIReader 连接器、Embedder、Ranker【免费下载链接】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本指南以 Haystack 2.19 版本中jina-haystack集成包为核心系统讲解JinaReaderConnector网页读取/搜索/事实核查、JinaTextEmbedder、JinaDocumentEmbedder、JinaDocumentImageEmbedder文本与多模态向量化以及JinaRanker重排序五个组件的完整 API、参数语义与实战用法。读完本文你将能够独立搭建包含网页抓取 → 向量化 → 存储 → 检索 → 重排序 → 生成全链路的 Jina AI Haystack RAG 管道。前置准备安装与认证jina-haystack是 Haystack 的第三方集成包安装命令如下pip install jina-haystack所有组件统一从haystack_integrations命名空间导入例如from haystack_integrations.components.connectors.jina import JinaReaderConnector from haystack_integrations.components.embedders.jina import JinaTextEmbedder from haystack_integrations.components.rankers.jina import JinaRankerAPI Key 的两种注入方式所有 Jina 组件都默认从环境变量JINA_API_KEY读取密钥官方推荐方式避免密钥硬编码进代码或仓库reader JinaReaderConnector(moderead) # 自动读取 JINA_API_KEY也可以在初始化时通过Secret显式传入参数默认值即Secret.from_env_var(JINA_API_KEY)from haystack.utils import Secret reader JinaReaderConnector(moderead, api_keySecret.from_token(your-api-key))Secret是 Haystack 的密钥管理抽象详见 Secret 相关文档支持环境变量、token 直传等多种来源序列化时不会泄露明文。一、JinaReaderConnectorURL 读取、联网搜索与事实核查JinaReaderConnector对接 Jina AI 的 Reader 服务把查询或 URL 处理成 Haystack 的Document列表。它最常作为管道中的第一个组件把抓取结果传递给下游组件参考 JinaReaderConnector 组件指南。三种运行模式初始化时必须指定mode可选read、search、ground模式行为典型场景read处理一个 URL返回页面的文本内容网页内容提取、文档采集search联网搜索返回最相关页面的文本内容实时信息检索、无自有检索源的问答ground调用 grounding 引擎进行事实核查返回事实性判定与引用来源生成内容的事实校验、防幻觉关键参数JinaReaderConnector的完整初始化签名来源jina.md__init__( mode: JinaReaderMode | str, api_key: Secret Secret.from_env_var(JINA_API_KEY), json_response: bool True, ) - Nonemode操作模式read/search/ground三者必选其一。api_keyJina API 密钥建议走JINA_API_KEY环境变量。json_response控制 Jina Reader API 的响应格式。True默认请求 JSON 响应返回的Document带丰富的结构化元数据如title、description、url、usage等False请求原始raw响应只返回一个Document元数据极简。单独使用三种模式的输出形态read 模式from haystack_integrations.components.connectors.jina import JinaReaderConnector reader JinaReaderConnector(moderead) query https://example.com result reader.run(queryquery) print(result) # {documents: [Document(idfa3e51e4..., # content: This domain is for use in illustrative examples in documents. ..., # meta: {title: Example Domain, description: , url: https://example.com/, usage: {tokens: 42}})]}search 模式reader JinaReaderConnector(modesearch) query UEFA Champions League 2024 result reader.run(queryquery) print(result) # {documents: [Document(id6a71abf9..., # content: 2024/25 UEFA Champions League: Matches, draw, final, key dates | ..., # meta: {title: ..., description: ..., url: https://www.uefa.com/..., usage: {tokens: 5581}}), ...]}ground 模式reader JinaReaderConnector(modeground) query ChatGPT was launched in 2017 result reader.run(queryquery) print(result) # {documents: [Document(idf0c964db..., # content: The statement that ChatGPT was launched in 2017 is incorrect. ..., # meta: {factuality: 0, result: False, references: [ # {url: https://en.wikipedia.org/wiki/ChatGPT, # keyQuote: ChatGPT is ... launched in 2022., # isSupportive: False}, ...], # usage: {tokens: 10188}})]}可以看到ground模式的元数据尤为有价值factuality给出 0/1 事实性评分result给出布尔判定references列出支撑或反驳该陈述的引用来源及关键引文keyQuote可直接用于构建带证据链的事实核查应用。自定义请求头与异步调用run方法支持传入自定义 HTTP 头以定制 Reader 请求run(query: str, headers: dict[str, str] | None None) - dict[str, list[Document]]例如可通过headers透传 Jina Reader 支持的额外参数如目标语言、X-With-Links-Summary 等定制项具体以 Jina Reader 官方接口为准。每个组件都提供了对应的异步版本run_async签名与返回值完全一致可在async/await环境中使用result await reader.run_async(queryhttps://example.com)接入 RAG 管道search 模式驱动问答把JinaReaderConnector作为检索源头接入问答管道实现搜索 → 拼装提示 → LLM 生成from haystack import Pipeline from haystack.utils import Secret from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.components.connectors.jina import JinaReaderConnector reader_connector JinaReaderConnector(modesearch) prompt_template [ ChatMessage.from_system(You are a helpful assistant.), ChatMessage.from_user( Given the information below:\n {% for document in documents %}{{ document.content }}{% endfor %}\n Answer question: {{ query }}.\nAnswer:, ), ] prompt_builder ChatPromptBuilder( templateprompt_template, required_variables{query, documents}, ) llm OpenAIChatGenerator( modelgpt-4o-mini, api_keySecret.from_token(your-api-key), ) pipe Pipeline() pipe.add_component(reader_connector, reader_connector) pipe.add_component(prompt_builder, prompt_builder) pipe.add_component(llm, llm) pipe.connect(reader_connector.documents, prompt_builder.documents) pipe.connect(prompt_builder.prompt, llm.messages) query What is the most famous landmark in Berlin? result pipe.run( data{reader_connector: {query: query}, prompt_builder: {query: query}}, ) print(result) # {llm: {replies: [ChatMessage(_roleChatRole.ASSISTANT: assistant, # _content[TextContent(textThe most famous landmark in Berlin is the **Brandenburg Gate**. ...)], ...)]}}该组件在 search 模式下同样可用于索引管道indexing pipeline把搜索结果批量写入文档库。二、JinaTextEmbedder查询文本向量化JinaTextEmbedder负责把单条字符串典型场景是查询语句编码为语义向量是 embedding 检索向量检索时对查询进行向量化的组件。它通常放在 query/RAG 管道中、embedding Retriever 之前参考 JinaTextEmbedder 组件指南。初始化参数__init__( api_key: Secret Secret.from_env_var(JINA_API_KEY), model: str jina-embeddings-v3, prefix: str , suffix: str , task: str | None None, dimensions: int | None None, late_chunking: bool | None None, *, base_url: str JINA_API_URL ) - None参数默认值说明api_keyJINA_API_KEY环境变量Jina API 密钥modeljina-embeddings-v3使用的 Jina 嵌入模型名称prefix/suffix在文本开头/结尾附加的字符串可用于拼接指令或上下文taskNone下游任务类型如retrieval.query、retrieval.passage等模型会为对应任务返回优化后的嵌入dimensionsNone期望的向量维度。得益于 MRLMatryoshka Representation Learning较小的维度更易存储与检索且性能损失极小late_chunkingNone是否启用 late chunking 技术利用模型长上下文能力生成上下文感知的 chunk 嵌入base_urlJINA_API_URLJina API 的 base URL可用于自定义网关/代理注意task与late_chunking参数仅对jina-embeddings-v3模型生效。单独使用from haystack_integrations.components.embedders.jina import JinaTextEmbedder text_embedder JinaTextEmbedder(taskretrieval.query) text_to_embed I love pizza! print(text_embedder.run(text_to_embed)) # {embedding: [0.017020374536514282, -0.023255806416273117, ...], # meta: {model: jina-embeddings-v3, # usage: {prompt_tokens: 4, total_tokens: 4}}}返回值包含两个键embedding输入文本的向量与meta模型名与 token 用量统计。若传入的不是字符串会抛出TypeError。在查询管道中的位置JinaTextEmbedder输出的embedding直接接入InMemoryEmbeddingRetriever的query_embedding输入示例见下文三、文档向量化与 RAG 实战实现文本 → 向量 → 相似度检索的链路。三、JinaDocumentEmbedder文档批量向量化JinaDocumentEmbedder为一批Document计算嵌入并把结果写入每个Document的embedding字段。它是 embedding 检索的前置条件——索引时用其向量化文档集合检索时再用JinaTextEmbedder向量化查询两者比对找出最相似文档。最典型的管道位置是索引管道中、DocumentWriter之前参考 JinaDocumentEmbedder 组件指南。初始化参数__init__( api_key: Secret Secret.from_env_var(JINA_API_KEY), model: str jina-embeddings-v3, prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, task: str | None None, dimensions: int | None None, late_chunking: bool | None None, *, base_url: str JINA_API_URL ) - None在JinaTextEmbedder参数之外文档嵌入器还独有两个参数batch_size默认32单次 API 请求编码的 Document 数量影响吞吐与请求成本。progress_bar默认True是否显示进度条生产部署中建议关闭以保持日志整洁。meta_fields_to_embed默认None需要随正文一起编码的元数据字段列表。embedding_separator默认\n拼接元数据与正文时使用的分隔符。嵌入元数据提升检索质量的关键技巧文本通常携带语义丰富的元数据把它们与正文一起编码可以显著改善检索效果from haystack import Document from haystack.utils import Secret from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder doc Document(contentsome text, meta{title: relevant title, page number: 18}) embedder JinaDocumentEmbedder( api_keySecret.from_token(your-api-key), meta_fields_to_embed[title], # 只嵌入 title跳过 page number 这类无语义字段 ) docs_w_embeddings embedder.run(documents[doc])[documents]底层实现会把选中的元数据字段值用embedding_separator拼接到正文后再送入模型因此应只选择语义相关的字段避免把数字、ID 等噪声字段混入向量。单独使用from haystack import Document from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder doc Document(contentI love pizza!) document_embedder JinaDocumentEmbedder() # 确保已设置 JINA_API_KEY result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run返回documents带embedding字段的 Document 列表与meta含模型名与用量统计若输入不是 Document 列表则抛出TypeError。RAG 实战索引管道 查询管道下面是一套完整的文档向量化入库 向量检索双管道方案使用InMemoryDocumentStorefrom haystack import Document, Pipeline from haystack.utils import Secret from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder, JinaTextEmbedder from haystack.components.writers import DocumentWriter from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] # 索引管道向量化 - 写入 indexing_pipeline Pipeline() indexing_pipeline.add_component(embedder, JinaDocumentEmbedder()) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run({embedder: {documents: documents}}) # 查询管道查询向量化 - 相似度检索 query_pipeline Pipeline() query_pipeline.add_component(text_embedder, JinaTextEmbedder()) query_pipeline.add_component(retriever, InMemoryEmbeddingRetriever(document_storedocument_store)) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query Who lives in Berlin? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0]) # Document(id..., content: My name is Wolfgang and I live in Berlin, score: ...)注意索引与查询阶段应使用同一模型否则向量空间不一致会导致检索失真。四、JinaDocumentImageEmbedder多模态图像向量化JinaDocumentImageEmbedder基于 Jina 多模态模型计算图像/PDF的向量并把结果写入Document.embedding字段。它支持jina-clip系列与jina-embeddings-v4——这些模型能把图像与文本编码进同一向量空间从而支持文本查图图查图等跨模态检索参考 JinaDocumentImageEmbedder 组件指南。支持的模型模型说明jina-clip-v1多模态嵌入模型jina-clip-v2默认多模态嵌入模型能力更强jina-embeddings-v4仅限非商业研究用途初始化参数__init__( *, api_key: Secret Secret.from_env_var(JINA_API_KEY), model: str jina-clip-v2, base_url: str JINA_API_URL, file_path_meta_field: str file_path, root_path: str | None None, embedding_dimension: int | None None, image_size: tuple[int, int] | None None, batch_size: int 5 ) - None参数默认值说明file_path_meta_fieldfile_pathDocument元数据中存放图像/PDF 文件路径的字段名root_pathNone文件所在根目录提供后元数据中的路径会相对该目录解析None时按绝对路径处理embedding_dimensionNone期望向量维度仅jina-embeddings-v4支持同样受益于 MRLimage_sizeNone若提供(width, height)会在保持宽高比的前提下把图像缩放至该尺寸内降低文件体积、内存与处理耗时batch_size5每次 API 请求发送的图像数量单独使用from haystack import Document from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder embedder JinaDocumentImageEmbedder(modeljina-clip-v2) documents [ Document(contentA photo of a cat, meta{file_path: cat.jpg}), Document(contentA photo of a dog, meta{file_path: dog.jpg}), ] result embedder.run(documentsdocuments) documents_with_embeddings result[documents] print(documents_with_embeddings) # [Document(id..., contentA photo of a cat, # meta{file_path: cat.jpg, # embedding_source: {type: image, file_path_meta_field: file_path}}, # embeddingvector of size 1024), ...]注意输入的Document必须在指定元数据字段默认file_path中给出图像或 PDF 的文件路径组件负责加载文件、计算嵌入并写回embedding字段同时会在meta中写入embedding_source记录嵌入来源类型。多模态 RAG索引管道 文本检索管道完整的多模态检索方案包含两条管道。索引管道由三个组件组成ImageFileToDocument转换器把图像文件转为带meta.file_path引用的空 Document、JinaDocumentImageEmbedder加载图像、计算嵌入这里用image_size缩放以降低 API 用量与DocumentWriter写入文档库检索管道则由同模型的JinaTextEmbedder与InMemoryEmbeddingRetriever组成from haystack import Pipeline from haystack.components.converters.image import ImageFileToDocument from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder, JinaTextEmbedder document_store InMemoryDocumentStore() # 索引管道 indexing_pipeline Pipeline() indexing_pipeline.add_component(image_converter, ImageFileToDocument()) indexing_pipeline.add_component(embedder, JinaDocumentImageEmbedder(modeljina-clip-v2, image_size(200, 200))) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(image_converter, embedder) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run(data{image_converter: {sources: [dog.jpg, cat.jpg]}}) # 多模态检索管道用文本查询检索图像 retrieval_pipeline Pipeline() retrieval_pipeline.add_component(embedder, JinaTextEmbedder(modeljina-clip-v2)) retrieval_pipeline.add_component(retriever, InMemoryEmbeddingRetriever(document_storedocument_store, top_k2)) retrieval_pipeline.connect(embedder.embedding, retriever.query_embedding) result retrieval_pipeline.run(data{text: mans best friend}) print(result) # {retriever: {documents: [Document(id0c96..., meta{file_path: dog.jpg, ...}, score0.246), # Document(id5e76..., meta{file_path: cat.jpg, ...}, score0.199)]}}因为jina-clip把文本与图像编码在同一向量空间mans best friend文本可以正确检索出dog.jpg图像且相似度得分0.246高于cat.jpg0.199直观体现了跨模态语义对齐的效果。五、JinaRanker文档重排序JinaRanker使用 Jina AI 的重排序模型根据文档与查询的相似度对候选文档重新排序默认模型为jina-reranker-v1-base-en。它在查询管道中通常位于返回文档列表的组件如 Retriever之后用于精排参考 JinaRanker 组件指南。初始化参数__init__( model: str jina-reranker-v1-base-en, api_key: Secret Secret.from_env_var(JINA_API_KEY), top_k: int | None None, score_threshold: float | None None, *, base_url: str JINA_API_URL ) - None参数默认值说明modeljina-reranker-v1-base-en使用的重排序模型top_kNone每个查询最多返回的文档数None时返回全部文档score_thresholdNone只保留相似度得分高于该阈值的文档校验规则若top_k不大于 0初始化或运行时会抛出ValueError。单独使用from haystack import Document from haystack_integrations.components.rankers.jina import JinaRanker docs [Document(contentParis), Document(contentBerlin)] ranker JinaRanker() result ranker.run(queryCity in Germany, documentsdocs, top_k1) docs result[documents] print(docs[0].content) # Berlinrun的完整签名如下其中top_k与score_threshold也可以在运行时覆盖初始化时的设置run( query: str, documents: list[Document], top_k: int | None None, score_threshold: float | None None, ) - dict[str, Any]返回值包含documents按相似度降序排列的 Document 列表与meta本次请求使用的模型与用量信息。在管道中BM25 召回 Jina 精排经典的混合检索范式——先用InMemoryBM25Retriever做关键词召回再用JinaRanker做语义精排from haystack import Document, Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack_integrations.components.rankers.jina import JinaRanker docs [ Document(contentParis is in France), Document(contentBerlin is in Germany), Document(contentLyon is in France), ] document_store InMemoryDocumentStore() document_store.write_documents(docs) retriever InMemoryBM25Retriever(document_storedocument_store) ranker JinaRanker() ranker_pipeline Pipeline() ranker_pipeline.add_component(instanceretriever, nameretriever) ranker_pipeline.add_component(instanceranker, nameranker) ranker_pipeline.connect(retriever.documents, ranker.documents) query Cities in France result ranker_pipeline.run( data{ retriever: {query: query, top_k: 3}, ranker: {query: query, top_k: 2}, }, )这里 BM25 先把候选从 3 篇粗筛出来JinaRanker再按语义相似度精排并只返回前 2 篇兼顾召回率与精度。六、序列化与反序列化to_dict / from_dict五个组件都实现了 Haystack 的标准序列化接口便于管道保存、加载与 YAML/JSON 配置化to_dict() - dict[str, Any]把组件序列化为字典包含类名、初始化参数等完整信息。from_dict(data: dict[str, Any]) - JinaXxx从字典反序列化重建组件实例。这意味着你可以把整个含 Jina 组件的管道保存为 YAML/JSON 配置在部署时无损还原。由于 API Key 使用Secret封装序列化结果中密钥不会以明文形式暴露。七、最佳实践小结密钥管理统一通过JINA_API_KEY环境变量注入配合 Haystack 的 Secret 机制 避免明文泄露。向量一致性索引与检索阶段务必使用同一个嵌入模型含task等参数否则向量空间错位会导致检索失效。元数据嵌入JinaDocumentEmbedder只挑选语义相关的meta_fields_to_embed字段用embedding_separator控制拼接格式。检索增强JinaReaderConnector(search)提供实时联网检索能力JinaRanker提供语义精排能力两者可单独或组合接入 RAG 管道提升上下文质量。多模态场景图像索引用JinaDocumentImageEmbedderjina-clip系列查询端用同模型JinaTextEmbedder即可实现文本查图的跨模态检索。异步支持所有组件均提供run_async在高并发服务场景下优先使用异步版本。生产配置关闭progress_bar、按需设置batch_size与dimensionsMRL 降维平衡成本与性能。更多组件细节可查阅本文引用的各组件使用指南docs-website/docs/pipeline-components/目录下jinareaderconnector.mdx、jinatextembedder.mdx、jinadocumentembedder.mdx、jinadocumentimageembedder.mdx、jinaranker.mdx以及本文依据的 API 参考文档 jina.md。【免费下载链接】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），仅供参考