Haystack Jina 集成 API 详解：JinaReaderConnector、Embedders 与 JinaRanker 的完整参考与实战指南

Haystack Jina 集成 API 详解JinaReaderConnector、Embedders 与 JinaRanker 的完整参考与实战指南【免费下载链接】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.21 版本文档站中的 Jina 集成 API 参考docs-website/reference_versioned_docs/version-2.21/integrations-api/jina.md系统讲解jina-haystack集成包提供的 5 个核心组件JinaReaderConnector、JinaDocumentEmbedder、JinaDocumentImageEmbedder、JinaTextEmbedder与JinaRanker。读完后你将掌握每个组件的初始化签名、全部配置参数含义、同步/异步运行方法以及如何在索引与查询流水线中落地网页读取、文本/图像向量化与重排序能力。总览一个集成包五类组件jina-haystack是 Haystack 官方核心集成之一通过pip install jina-haystack安装所有组件均从haystack_integrations.components命名空间导入。按照 API 参考见 jina.md该集成覆盖四类能力组件模块路径定位常见流水线位置JinaReaderConnectorhaystack_integrations.components.connectors.jina.reader网页读取/搜索/事实核查查询流水线首组件JinaDocumentEmbedderhaystack_integrations.components.embedders.jina.document_embedder文档批量向量化索引流水线中DocumentWriter之前JinaDocumentImageEmbedderhaystack_integrations.components.embedders.jina.document_image_embedder图像/PDF 多模态向量化索引流水线中DocumentWriter之前JinaTextEmbedderhaystack_integrations.components.embedders.jina.text_embedder查询文本向量化查询流水线中 Embedding Retriever 之前JinaRankerhaystack_integrations.components.rankers.jina.ranker文档重排序查询流水线中 Retriever 之后所有组件共享统一的鉴权方式默认从环境变量JINA_API_KEY读取密钥Secret.from_env_var(JINA_API_KEY)也支持初始化时显式传入官方文档推荐使用环境变量方式from haystack.utils import Secret reader JinaReaderConnector(moderead, api_keySecret.from_token(your-api-key))所有组件同样实现to_dict()/from_dict()序列化接口可随Pipeline一起序列化为 YAML 部署均提供run同步与run_async异步可在异步代码中await两种运行方式。JinaReaderConnector网页读取、搜索与事实核查连接器JinaReaderConnector与 Jina AI 的 Reader 服务交互处理查询并返回Document列表。初始化时必须指定运行模式mode支持三种模式read处理一个 URL返回页面的文本内容search搜索网络返回最相关页面的文本内容ground调用 grounding 引擎执行事实核查fact checking。初始化签名__init__( mode: JinaReaderMode | str, api_key: Secret Secret.from_env_var(JINA_API_KEY), json_response: bool True, ) - None参数说明mode(JinaReaderMode | str)操作模式即上文三选一api_key(Secret)Jina API 密钥可显式提供或自动从JINA_API_KEY环境变量读取推荐json_response(bool)控制响应格式。True默认请求 JSON 响应产出的Document带有丰富的结构化 metadata如标题、URL、token 用量False请求原始响应产出单个 metadata 极简的Document。运行方法run( query: str, headers: dict[str, str] | None None ) - dict[str, list[Document]] run_async( query: str, headers: dict[str, str] | None None ) - dict[str, list[Document]]query(str)要处理的查询串或 URLheaders(dict[str, str] | None)可选请求头用于按 Jina Reader 服务约定定制行为返回值字典含一个键documents值为Document对象列表。独立使用示例API 参考中给出的最小示例read模式处理 URLfrom haystack_integrations.components.connectors.jina import JinaReaderConnector reader JinaReaderConnector(moderead) query https://example.com result reader.run(queryquery) document result[documents][0] print(document.content) This domain is for use in illustrative examples...仓库的组件使用文档见 jinareaderconnector.mdx进一步给出了三种模式的真实返回样例可帮助理解每种模式Document.meta的结构read 模式返回单文档meta含title、description、url、usage.tokensreader JinaReaderConnector(moderead) result reader.run(queryhttps://example.com) # {documents: [Document(idfa3e51e4..., # content: This domain is for use in illustrative examples ..., # meta: {title: Example Domain, description: , url: https://example.com/, # usage: {tokens: 42}})]}search 模式返回多个文档每个对应一个相关页面meta 含页面标题、描述与 URLreader JinaReaderConnector(modesearch) result reader.run(queryUEFA Champions League 2024) # {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 模式meta中额外包含factuality事实性分数、result布尔判定与references含支持性引用reader JinaReaderConnector(modeground) result reader.run(queryChatGPT was launched in 2017) # {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 a generative artificial intelligence ..., # isSupportive: False}, ...], # usage: {tokens: 10188}})]}在流水线中search 模式驱动的查询 RAG 流水线下面示例展示JinaReaderConnector作为流水线首组件先搜索相关文档再与用户查询一起交给ChatPromptBuilder渲染模板最后由 LLM 生成回答完整代码见 jinareaderconnector.mdxfrom 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_integrations.components.connectors.jina import JinaReaderConnector from haystack.dataclasses import ChatMessage 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}}, )运行后 LLM 输出的回复示例为 The most famous landmark in Berlin is theBrandenburg Gate...其meta.usage中可见 prompt tokens 约 4500说明 search 模式检索到的多页面内容确实被注入了上下文。同一组件在 search 模式下同样可用于索引流水线。JinaDocumentEmbedder文档批量向量化JinaDocumentEmbedder使用 Jina AI 模型为一批Document计算向量结果写入每个Document的embedding字段——这是后续执行向量检索embedding retrieval的前提。默认模型为jina-embeddings-v3。初始化签名与全部参数__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参数类型/默认值说明api_keySecret默认Secret.from_env_var(JINA_API_KEY)Jina API 密钥modelstr默认jina-embeddings-v3使用的 Jina 模型名prefixstr默认拼接到每条文本开头的字符串suffixstr默认拼接到每条文本末尾的字符串batch_sizeint默认32一次编码的 Document 数量progress_barbool默认True是否显示进度条生产环境建议关闭以保持日志干净meta_fields_to_embedlist[str] \| None默认None需要与正文一起参与嵌入的 meta 字段名列表embedding_separatorstr默认\n拼接 meta 字段与正文时使用的分隔符taskstr \| None默认None下游任务标识如retrieval.query模型将返回针对该任务优化的向量dimensionsint \| None默认None期望的向量维度借助 MRL 技术更小的维度更易存储与检索且性能损失很小late_chunkingbool \| None默认None启用/禁用 late chunking利用模型长上下文能力生成带上下文的分块嵌入base_urlstr默认JINA_API_URL仅关键字参数Jina API 的基础 URL注意API 参考明确指出task与late_chunking参数仅对jina-embeddings-v3模型有效。运行方法与返回结构run(documents: list[Document]) - dict[str, Any] run_async(documents: list[Document]) - dict[str, Any]输入documentsDocument列表否则抛出TypeError返回字典含两个键documents向量已写入embedding字段的文档列表meta包含模型名与用量统计usage statistics的元数据。独立使用与 meta 嵌入API 参考中的最小示例需预先设置JINA_API_KEY环境变量from haystack import Document from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder document_embedder JinaDocumentEmbedder(taskretrieval.query) doc Document(contentI love pizza!) result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]组件使用文档见 jinadocumentembedder.mdx补充了嵌入元数据这一实战技巧如果文档带有语义上有区分度的 metadata如标题可将其与正文一并嵌入以提升检索质量from haystack import Document 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], ) docs_w_embeddings embedder.run(documents[doc])[documents]在流水线中完整的索引 查询 RAG 流水线下面的双流水线示例同样见 jinadocumentembedder.mdx演示了该组件在 Haystack 中的典型协作方式索引流水线中JinaDocumentEmbedder位于DocumentWriter之前查询流水线中JinaTextEmbedder位于InMemoryEmbeddingRetriever之前from 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 from haystack_integrations.components.embedders.jina import 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(api_keySecret.from_token(your-api-key)), ) 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(api_keySecret.from_token(your-api-key)), ) 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图像与 PDF 的多模态向量化JinaDocumentImageEmbedder基于 Jina AI 多模态模型将图像或 PDF编码为向量并与文本共享同一嵌入空间因此检索时可以用JinaTextEmbedder加载相同模型嵌入文本查询。API 参考声明其支持jina-clip系列与jina-embeddings-v4模型组件使用文档见 jinadocumentimageembedder.mdx列出的兼容模型为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参数类型/默认值说明api_keySecret默认Secret.from_env_var(JINA_API_KEY)Jina API 密钥建议用环境变量modelstr默认jina-clip-v2Jina 多模态模型名base_urlstr默认JINA_API_URLJina API 基础 URLfile_path_meta_fieldstr默认file_pathDocument meta 中存放图像/PDF 文件路径的字段名root_pathstr \| None默认None文档文件的根目录提供时 meta 中的路径相对该目录解析否则视为绝对路径embedding_dimensionint \| None默认None期望向量维度MRL小维度更易存储检索仅jina-embeddings-v4支持image_sizetuple[int, int] \| None默认None提供时按(width, height)在保持纵横比的前提下缩放图像可降低文件体积、内存占用与处理时间batch_sizeint默认5每个 API 请求发送的图像数量注意该构造函数所有参数均为关键字参数*之后。运行方法与返回run(documents: list[Document]) - dict[str, list[Document]] run_async(documents: list[Document]) - dict[str, list[Document]]输入为待嵌入的Document列表返回字典含documents键带embedding的文档列表。独立使用示例API 参考中的示例构造两个带meta.file_path的文档调用run后读取第一个文档的向量需设置JINA_API_KEYfrom 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[0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]从使用文档的完整运行输出可推断组件还会在meta中写入embedding_source信息{type: image, file_path_meta_field: file_path}示例中jina-clip-v2产出 1024 维向量。在流水线中多模态索引 文本查询检索下面示例演示完整的 Vision RAG 模式索引流水线由ImageFileToDocument在meta.file_path中记录图像路径的空文档转换器、JinaDocumentImageEmbedder此处用image_size(200, 200)缩放图像以降低 API 用量与DocumentWriter组成检索流水线则由同一模型的JinaTextEmbedder与InMemoryEmbeddingRetriever组成完整代码见 jinadocumentimageembedder.mdxfrom 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 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]}}) # Multimodal retrieval pipeline 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})运行结果中查询 mans best friend 排第一的文档是dog.jpgscore0.246cat.jpgscore0.199次之验证了文本查询确实能在图像向量空间中找到语义最相关的图片。JinaTextEmbedder查询文本向量化JinaTextEmbedder将单个字符串通常是用户查询转为语义向量与JinaDocumentEmbedder配对使用文档侧批量嵌入入库查询侧单条嵌入再由 Embedding Retriever 完成相似度匹配。默认模型同样是jina-embeddings-v3。初始化签名与全部参数__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参数与JinaDocumentEmbedder大体一致api_key、model、prefix、suffix、task、dimensions、late_chunking、base_url只是没有batch_size/progress_bar/meta_fields_to_embed等批量处理参数。同样地task与late_chunking仅对jina-embeddings-v3有效。使用文档见 jinatextembedder.mdx强调要嵌入文档列表应改用JinaDocumentEmbedder。运行方法与返回run(text: str) - dict[str, Any] run_async(text: str) - dict[str, Any]text(str)待嵌入字符串非字符串输入会抛出TypeError返回字典含embedding输入字符串的向量meta含模型名与用量统计的元数据。独立使用示例from haystack_integrations.components.embedders.jina import JinaTextEmbedder # Make sure that the environment variable JINA_API_KEY is set 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}}}从meta输出可以看出用量统计精确到 token 级别prompt_tokens与total_tokens便于成本核算。在流水线中的用法与前述完整索引 查询 RAG 流水线一致连接text_embedder.embedding到retriever.query_embedding即可。JinaRanker基于 Jina 模型的重排序JinaRanker基于 Jina AI 的排序模型按文档与查询的相似度对文档排序。默认模型为jina-reranker-v1-base-en。从仓库文档结构看见 choosing-the-right-ranker.mdxJinaRanker与 AmazonBedrockRanker、CohereRanker 同属基于 cross-encoder 的 API 类 Ranker这类组件把查询与文档一起送评产出更精确的相关性分数。初始化签名与全部参数__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参数类型/默认值说明modelstr默认jina-reranker-v1-base-enJina 排序模型名api_keySecret默认Secret.from_env_var(JINA_API_KEY)Jina API 密钥top_kint \| None默认None每次查询最多返回的文档数None表示全部返回。初始化传入非正数会抛ValueErrorscore_thresholdfloat \| None默认None提供时仅返回分数高于该阈值的文档base_urlstr默认JINA_API_URL仅关键字参数Jina API 基础 URL组件使用文档见 jinaranker.mdx补充了top_k的流水线语义它决定 Ranker 返回若为流水线末端或传递给下一组件的文档数量。运行方法与返回run( query: str, documents: list[Document], top_k: int | None None, score_threshold: float | None None, ) - dict[str, Any] run_async( query: str, documents: list[Document], top_k: int | None None, score_threshold: float | None None, ) - dict[str, Any]query(str)查询串documents(list[Document])待排序文档列表top_k/score_threshold运行时可覆盖初始化设置top_k非正数抛ValueError返回字典含documents按相似度降序排列的文档列表meta请求元数据含所用模型与用量信息。独立使用示例from haystack import Document from haystack_integrations.components.rankers.jina import JinaRanker ranker JinaRanker() docs [Document(contentParis), Document(contentBerlin)] query City in Germany result ranker.run(queryquery, documentsdocs) docs result[documents] print(docs[0].content)在流水线中BM25 检索 Jina 重排序下面示例演示典型的两级检索架构InMemoryBM25Retriever先做关键词检索召回JinaRanker再做语义精排完整代码见 jinaranker.mdxfrom 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 ranker_pipeline.run( data{ retriever: {query: query, top_k: 3}, ranker: {query: query, top_k: 2}, }, )注意这里retriever与ranker各自独立配置了top_k检索阶段召回 3 篇重排阶段输出前 2 篇。序列化与部署to_dict / from_dict五个组件全部实现相同的序列化契约这是它们能被Pipeline.to_dict()/Pipeline.save_json()等机制随流水线一起持久化的前提to_dict() - dict[str, Any] # 序列化为字典 from_dict(data: dict[str, Any]) - Component # 从字典反序列化以JinaRanker为例to_dict()返回带序列化数据的字典JinaRanker.from_dict(data)接收该字典并还原组件实例。对Secret类型的api_key参数Haystack 的序列化机制会避免把明文密钥写入磁盘从 API 参考的Secret.from_env_var默认值设计可推断部署时推荐依赖JINA_API_KEY环境变量注入密钥而非硬编码。选型与使用要点小结鉴权所有组件默认读取JINA_API_KEY环境变量显式传入时统一使用Secret.from_token(your-api-key)模型配套文档嵌入与查询嵌入必须使用同一模型多模态场景下JinaDocumentImageEmbedder与JinaTextEmbedder同理否则向量不在同一空间相似度检索无意义任务优化task参数如retrieval.query与late_chunking仅jina-embeddings-v3支持dimensions借助 MRL 可在几乎不损失性能的前提下压缩存储成本控制JinaDocumentEmbedder可用batch_size与progress_bar调节吞吐与日志JinaDocumentImageEmbedder可用image_size缩放图像、embedding_dimension压缩维度各组件返回的meta.usage提供 token 级用量统计同步/异步每个组件均提供参数与返回值完全一致的run_async异步流水线可直接await调用进一步阅读本仓库中 2.21 版 API 参考的完整原文见 jina.md五个组件各自的独立使用文档分别位于 jinareaderconnector.mdx、jinadocumentembedder.mdx、jinatextembedder.mdx、jinadocumentimageembedder.mdx 与 jinaranker.mdx。需要说明的是本文所有签名、参数默认值与返回结构均以jina-haystack组件在 2.21 版 API 参考中记录的版本为准实际可用的模型清单、任务类型等以 Jina 官方文档为准。【免费下载链接】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），仅供参考