deepset-ai--haystack/docs-website/reference_versioned_docs/version-2.31/integrations-api/jina.md

---
title: "Jina"
id: integrations-jina
description: "Jina integration for Haystack"
slug: "/integrations-jina"
---


## haystack_integrations.components.connectors.jina.reader

### JinaReaderConnector

A component that interacts with Jina AI's reader service to process queries and return documents.

This component supports different modes of operation: `read`, `search`, and `ground`.

Usage example:

```python
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..."
```

#### __init__

```python
__init__(
    mode: JinaReaderMode | str,
    api_key: Secret = Secret.from_env_var("JINA_API_KEY"),
    json_response: bool = True,
) -> None
```

Initialize a JinaReader instance.

**Parameters:**

- **mode** (<code>JinaReaderMode | str</code>) – The operation mode for the reader (`read`, `search` or `ground`).
- `read`: process a URL and return the textual content of the page.
- `search`: search the web and return textual content of the most relevant pages.
- `ground`: call the grounding engine to perform fact checking.
  For more information on the modes, see the [Jina Reader documentation](https://jina.ai/reader/).
- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
  environment variable JINA_API_KEY (recommended).
- **json_response** (<code>bool</code>) – Controls the response format from the Jina Reader API.
  If `True`, requests a JSON response, resulting in Documents with rich structured metadata.
  If `False`, requests a raw response, resulting in one Document with minimal metadata.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> JinaReaderConnector
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.

**Returns:**

- <code>JinaReaderConnector</code> – Deserialized component.

#### run

```python
run(
    query: str, headers: dict[str, str] | None = None
) -> dict[str, list[Document]]
```

Process the query/URL using the Jina AI reader service.

**Parameters:**

- **query** (<code>str</code>) – The query string or URL to process.
- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
  [Jina Reader documentation](https://jina.ai/reader/) for more information.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
  - `documents`: A list of `Document` objects.

#### run_async

```python
run_async(
    query: str, headers: dict[str, str] | None = None
) -> dict[str, list[Document]]
```

Asynchronously process the query/URL using the Jina AI reader service.

This is the asynchronous version of the `run` method. It has the same parameters and return values
but can be used with `await` in async code.

**Parameters:**

- **query** (<code>str</code>) – The query string or URL to process.
- **headers** (<code>dict\[str, str\] | None</code>) – Optional headers to include in the request for customization. Refer to the
  [Jina Reader documentation](https://jina.ai/reader/) for more information.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
  - `documents`: A list of `Document` objects.

## haystack_integrations.components.embedders.jina.document_embedder

### JinaDocumentEmbedder

A component for computing Document embeddings using Jina AI models.

The embedding of each Document is stored in the `embedding` field of the Document.

Usage example:

```python
from haystack import Document
from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder

# Make sure that the environment variable JINA_API_KEY is set

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, ...]
```

#### __init__

```python
__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
```

Create a JinaDocumentEmbedder component.

**Parameters:**

- **api_key** (<code>Secret</code>) – The Jina API key.
- **model** (<code>str</code>) – The name of the Jina model to use.
  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
- **suffix** (<code>str</code>) – A string to add to the end of each text.
- **batch_size** (<code>int</code>) – Number of Documents to encode at once.
- **progress_bar** (<code>bool</code>) – Whether to show a progress bar or not. Can be helpful to disable in production deployments
  to keep the logs clean.
- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
- **task** (<code>str | None</code>) – The downstream task for which the embeddings will be used.
  The model will return the optimized embeddings for that task.
  Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
- **dimensions** (<code>int | None</code>) – Number of desired dimension.
  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
- **late_chunking** (<code>bool | None</code>) – A boolean to enable or disable late chunking.
  Apply the late chunking technique to leverage the model's long-context capabilities for
  generating contextual chunk embeddings.
- **base_url** (<code>str</code>) – The base URL of the Jina API.

The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> JinaDocumentEmbedder
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.

**Returns:**

- <code>JinaDocumentEmbedder</code> – Deserialized component.

#### run

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

Compute the embeddings for a list of Documents.

**Parameters:**

- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.

**Returns:**

- <code>dict\[str, Any\]</code> – A dictionary with following keys:
- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
- `meta`: A dictionary with metadata including the model name and usage statistics.

**Raises:**

- <code>TypeError</code> – If the input is not a list of Documents.

#### run_async

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

Asynchronously compute the embeddings for a list of Documents.

This is the asynchronous version of the `run` method. It has the same parameters and return values
but can be used with `await` in async code.

**Parameters:**

- **documents** (<code>list\[Document\]</code>) – A list of Documents to embed.

**Returns:**

- <code>dict\[str, Any\]</code> – A dictionary with following keys:
- `documents`: List of Documents, each with an `embedding` field containing the computed embedding.
- `meta`: A dictionary with metadata including the model name and usage statistics.

**Raises:**

- <code>TypeError</code> – If the input is not a list of Documents.

## haystack_integrations.components.embedders.jina.document_image_embedder

### JinaDocumentImageEmbedder

A component for computing Document embeddings based on images using Jina AI multimodal models.

The embedding of each Document is stored in the `embedding` field of the Document.

The JinaDocumentImageEmbedder supports models from the jina-clip series and jina-embeddings-v4
which can encode images into vector representations in the same embedding space as text.

Usage example:

```python
from haystack import Document
from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder

# Make sure that the environment variable JINA_API_KEY is set

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, ...]
```

#### __init__

```python
__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
```

Create a JinaDocumentImageEmbedder component.

**Parameters:**

- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
  environment variable `JINA_API_KEY` (recommended).
- **model** (<code>str</code>) – The name of the Jina multimodal model to use.
  Supported models include:
- "jina-clip-v1"
- "jina-clip-v2" (default)
- "jina-embeddings-v4"
  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
- **base_url** (<code>str</code>) – The base URL of the Jina API.
- **file_path_meta_field** (<code>str</code>) – The metadata field in the Document that contains the file path to the image or PDF.
- **root_path** (<code>str | None</code>) – The root directory path where document files are located. If provided, file paths in
  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
- **embedding_dimension** (<code>int | None</code>) – Number of desired dimensions for the embedding.
  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
  Only supported by jina-embeddings-v4.
- **image_size** (<code>tuple\[int, int\] | None</code>) – If provided, resizes the image to fit within the specified dimensions (width, height) while
  maintaining aspect ratio. This reduces file size, memory usage, and processing time.
- **batch_size** (<code>int</code>) – Number of images to send in each API request. Defaults to 5.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> JinaDocumentImageEmbedder
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.

**Returns:**

- <code>JinaDocumentImageEmbedder</code> – Deserialized component.

#### run

```python
run(documents: list[Document]) -> dict[str, list[Document]]
```

Embed a list of image documents.

**Parameters:**

- **documents** (<code>list\[Document\]</code>) – Documents to embed.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
- `documents`: Documents with embeddings.

#### run_async

```python
run_async(documents: list[Document]) -> dict[str, list[Document]]
```

Asynchronously embed a list of image documents.

This is the asynchronous version of the `run` method. It has the same parameters and return values
but can be used with `await` in async code.

**Parameters:**

- **documents** (<code>list\[Document\]</code>) – Documents to embed.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
- `documents`: Documents with embeddings.

## haystack_integrations.components.embedders.jina.text_embedder

### JinaTextEmbedder

A component for embedding strings using Jina AI models.

Usage example:

```python
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}}}
```

#### __init__

```python
__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
```

Create a JinaTextEmbedder component.

**Parameters:**

- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
  environment variable `JINA_API_KEY` (recommended).
- **model** (<code>str</code>) – The name of the Jina model to use.
  Check the list of available models on [Jina documentation](https://jina.ai/embeddings/).
- **prefix** (<code>str</code>) – A string to add to the beginning of each text.
- **suffix** (<code>str</code>) – A string to add to the end of each text.
- **task** (<code>str | None</code>) – The downstream task for which the embeddings will be used.
  The model will return the optimized embeddings for that task.
  Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/).
- **dimensions** (<code>int | None</code>) – Number of desired dimension.
  Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL.
- **late_chunking** (<code>bool | None</code>) – A boolean to enable or disable late chunking.
  Apply the late chunking technique to leverage the model's long-context capabilities for
  generating contextual chunk embeddings.
- **base_url** (<code>str</code>) – The base URL of the Jina API.

The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> JinaTextEmbedder
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.

**Returns:**

- <code>JinaTextEmbedder</code> – Deserialized component.

#### run

```python
run(text: str) -> dict[str, Any]
```

Embed a string.

**Parameters:**

- **text** (<code>str</code>) – The string to embed.

**Returns:**

- <code>dict\[str, Any\]</code> – A dictionary with following keys:
- `embedding`: The embedding of the input string.
- `meta`: A dictionary with metadata including the model name and usage statistics.

**Raises:**

- <code>TypeError</code> – If the input is not a string.

#### run_async

```python
run_async(text: str) -> dict[str, Any]
```

Asynchronously embed a string.

This is the asynchronous version of the `run` method. It has the same parameters and return values
but can be used with `await` in async code.

**Parameters:**

- **text** (<code>str</code>) – The string to embed.

**Returns:**

- <code>dict\[str, Any\]</code> – A dictionary with following keys:
- `embedding`: The embedding of the input string.
- `meta`: A dictionary with metadata including the model name and usage statistics.

**Raises:**

- <code>TypeError</code> – If the input is not a string.

## haystack_integrations.components.rankers.jina.ranker

### JinaRanker

Ranks Documents based on their similarity to the query using Jina AI models.

Usage example:

```python
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)
```

#### __init__

```python
__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
```

Creates an instance of JinaRanker.

**Parameters:**

- **api_key** (<code>Secret</code>) – The Jina API key. It can be explicitly provided or automatically read from the
  environment variable JINA_API_KEY (recommended).
- **model** (<code>str</code>) – The name of the Jina model to use. Check the list of available models on `https://jina.ai/reranker/`
- **top_k** (<code>int | None</code>) – The maximum number of Documents to return per query. If `None`, all documents are returned
- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.
- **base_url** (<code>str</code>) – The base URL of the Jina API.

**Raises:**

- <code>ValueError</code> – If `top_k` is not > 0.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> JinaRanker
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.

**Returns:**

- <code>JinaRanker</code> – Deserialized component.

#### run

```python
run(
    query: str,
    documents: list[Document],
    top_k: int | None = None,
    score_threshold: float | None = None,
) -> dict[str, list[Document]]
```

Returns a list of Documents ranked by their similarity to the given query.

**Parameters:**

- **query** (<code>str</code>) – Query string.
- **documents** (<code>list\[Document\]</code>) – List of Documents.
- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
- `documents`: List of Documents most similar to the given query in descending order of similarity.

**Raises:**

- <code>ValueError</code> – If `top_k` is not > 0.

#### run_async

```python
run_async(
    query: str,
    documents: list[Document],
    top_k: int | None = None,
    score_threshold: float | None = None,
) -> dict[str, list[Document]]
```

Asynchronously returns a list of Documents ranked by their similarity to the given query.

This is the asynchronous version of the `run` method. It has the same parameters and return values
but can be used with `await` in async code.

**Parameters:**

- **query** (<code>str</code>) – Query string.
- **documents** (<code>list\[Document\]</code>) – List of Documents.
- **top_k** (<code>int | None</code>) – The maximum number of Documents you want the Ranker to return.
- **score_threshold** (<code>float | None</code>) – If provided only returns documents with a score above this threshold.

**Returns:**

- <code>dict\[str, list\[Document\]\]</code> – A dictionary with the following keys:
- `documents`: List of Documents most similar to the given query in descending order of similarity.

**Raises:**

- <code>ValueError</code> – If `top_k` is not > 0.