企业官网建设流程全解析

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），该集成覆盖四类能力：

所有组件共享统一的鉴权方式：默认从环境变量JINA_API_KEY读取密钥（Secret.from_env_var("JINA_API_KEY")），也支持初始化时显式传入，官方文档推荐使用环境变量方式：

from haystack.utils import Secret reader = JinaReaderConnector(mode="read", api_key=Secret.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)：要处理的查询串或 URL；
• headers(dict[str, str] | None)：可选请求头，用于按 Jina Reader 服务约定定制行为；
• 返回值字典含一个键：documents，值为Document对象列表。

独立使用示例

API 参考中给出的最小示例（read模式处理 URL）：

from haystack_integrations.components.connectors.jina import JinaReaderConnector reader = JinaReaderConnector(mode="read") query = "https://example.com" result = reader.run(query=query) 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.tokens：

reader = JinaReaderConnector(mode="read") result = reader.run(query="https://example.com") # {'documents': [Document(id=fa3e51e4..., # content: 'This domain is for use in illustrative examples ...', # meta: {'title': 'Example Domain', 'description': '', 'url': 'https://example.com/', # 'usage': {'tokens': 42}})]}

search 模式：返回多个文档，每个对应一个相关页面，meta 含页面标题、描述与 URL：

reader = JinaReaderConnector(mode="search") result = reader.run(query="UEFA Champions League 2024") # {'documents': [Document(id=6a71abf9..., # 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(mode="ground") result = reader.run(query="ChatGPT was launched in 2017") # {'documents': [Document(id=f0c964db..., # 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.mdx）：

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_integrations.components.connectors.jina import JinaReaderConnector from haystack.dataclasses import ChatMessage reader_connector = JinaReaderConnector(mode="search") 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( template=prompt_template, required_variables={"query", "documents"}, ) llm = OpenAIChatGenerator( model="gpt-4o-mini", api_key=Secret.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 参考明确指出task与late_chunking参数仅对jina-embeddings-v3模型有效。

运行方法与返回结构

run(documents: list[Document]) -> dict[str, Any] run_async(documents: list[Document]) -> dict[str, Any]

• 输入：documents，Document列表，否则抛出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(task="retrieval.query") doc = Document(content="I 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(content="some text", meta={"title": "relevant title", "page number": 18}) embedder = JinaDocumentEmbedder( api_key=Secret.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_function="cosine") documents = [ Document(content="My name is Wolfgang and I live in Berlin"), Document(content="I saw a black horse running"), Document(content="Germany has many big cities"), ] indexing_pipeline = Pipeline() indexing_pipeline.add_component( "embedder", JinaDocumentEmbedder(api_key=Secret.from_token("<your-api-key>")), ) indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store)) indexing_pipeline.connect("embedder", "writer") indexing_pipeline.run({"embedder": {"documents": documents}}) query_pipeline = Pipeline() query_pipeline.add_component( "text_embedder", JinaTextEmbedder(api_key=Secret.from_token("<your-api-key>")), ) query_pipeline.add_component( "retriever", InMemoryEmbeddingRetriever(document_store=document_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

注意该构造函数所有参数均为关键字参数（*之后）。

运行方法与返回

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_KEY）：

from haystack import Document from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder embedder = JinaDocumentImageEmbedder(model="jina-clip-v2") documents = [ Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}), Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}), ] result = embedder.run(documents=documents) 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.mdx）：

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 indexing_pipeline = Pipeline() indexing_pipeline.add_component("image_converter", ImageFileToDocument()) indexing_pipeline.add_component( "embedder", JinaDocumentImageEmbedder(model="jina-clip-v2", image_size=(200, 200)), ) indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_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(model="jina-clip-v2")) retrieval_pipeline.add_component( "retriever", InMemoryEmbeddingRetriever(document_store=document_store, top_k=2), ) retrieval_pipeline.connect("embedder.embedding", "retriever.query_embedding") result = retrieval_pipeline.run(data={"text": "man's best friend"})

运行结果中，查询 "man's best friend" 排第一的文档是dog.jpg（score=0.246），cat.jpg（score=0.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(task="retrieval.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.mdx），JinaRanker与 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

组件使用文档（见 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(content="Paris"), Document(content="Berlin")] query = "City in Germany" result = ranker.run(query=query, documents=docs) docs = result["documents"] print(docs[0].content)

在流水线中：BM25 检索 + Jina 重排序

下面示例演示典型的两级检索架构：InMemoryBM25Retriever先做关键词检索召回，JinaRanker再做语义精排（完整代码见 jinaranker.mdx）：

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(content="Paris is in France"), Document(content="Berlin is in Germany"), Document(content="Lyon is in France"), ] document_store = InMemoryDocumentStore() document_store.write_documents(docs) retriever = InMemoryBM25Retriever(document_store=document_store) ranker = JinaRanker() ranker_pipeline = Pipeline() ranker_pipeline.add_component(instance=retriever, name="retriever") ranker_pipeline.add_component(instance=ranker, name="ranker") 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环境变量注入密钥而非硬编码）。

选型与使用要点小结

1. 鉴权：所有组件默认读取JINA_API_KEY环境变量；显式传入时统一使用Secret.from_token("<your-api-key>")；
2. 模型配套：文档嵌入与查询嵌入必须使用同一模型（多模态场景下JinaDocumentImageEmbedder与JinaTextEmbedder同理），否则向量不在同一空间，相似度检索无意义；
3. 任务优化：task参数（如"retrieval.query"）与late_chunking仅jina-embeddings-v3支持；dimensions借助 MRL 可在几乎不损失性能的前提下压缩存储；
4. 成本控制：JinaDocumentEmbedder可用batch_size与progress_bar调节吞吐与日志；JinaDocumentImageEmbedder可用image_size缩放图像、embedding_dimension压缩维度；各组件返回的meta.usage提供 token 级用量统计；
5. 同步/异步：每个组件均提供参数与返回值完全一致的run_async，异步流水线可直接await调用；
6. 进一步阅读：本仓库中 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