Jina AI Tutorial: Embeddings, Reranker, and Reader API for RAG Pipelines

# Tutorial Lengkap Jina AI: Embeddings, Reranker, dan Reader API untuk RAG Pipeline Jina AI telah menjadi salah satu penyedia layanan embedding dan reranking terpopuler di ekosistem AI modern. Dengan...

By Ruby Abdullah · · tutorial
Jina AIEmbeddingsRAGRerankerSemantic Search

Complete Jina AI Tutorial: Embeddings, Reranker, and Reader API for RAG Pipelines

Jina AI has become one of the most popular embedding and reranking providers in the modern AI ecosystem. With jina-embeddings-v3 supporting 89 languages and Jina Reranker v2 capable of processing documents up to 1 million tokens, Jina AI offers an end-to-end solution for building high-quality Retrieval-Augmented Generation (RAG) pipelines. In this tutorial, we will explore in depth how to use Jina AI Embeddings, Reranker, and Reader API to build an accurate and efficient semantic search system.

Why Jina AI?

Before diving into implementation, let's understand why Jina AI is worth considering:

  • Multilingual Support: jina-embeddings-v3 supports 89 languages, making it ideal for multilingual applications.
  • Late Chunking: A proprietary technology that preserves context across chunks, producing more accurate embeddings.
  • Task-Specific LoRA Adapters: A single model can be optimized for various tasks (retrieval, classification, text matching) without deploying separate models.
  • Matryoshka Representation Learning: Embedding dimensions can be reduced without significant performance loss, saving storage and speeding up search.
  • Reader API: Extracts clean content from any URL, extremely useful for web scraping in RAG pipelines.
  • Installation and Setup

    Getting an API Key

    First, register at Jina AI and obtain your API key. Jina provides a generous free tier sufficient for development and testing.

    Installing Dependencies

    pip install requests numpy python-dotenv
    

    For integration with popular frameworks:

    pip install langchain-community llama-index jina
    

    Environment Configuration

    Create a .env file in your project root:

    JINAAPIKEY=jinaxxxxxxxxxxxxxxxxxxxx
    

    Basic configuration setup:

    import os
    

    import requests

    import numpy as np

    from dotenv import loaddotenv

    loaddotenv()

    JINAAPIKEY = os.getenv("JINAAPIKEY")

    HEADERS = {

    "Authorization": f"Bearer {JINAAPIKEY}",

    "Content-Type": "application/json",

    "Accept": "application/json"

    }

    Jina Embeddings API

    Basic Embedding Generation

    The Jina Embeddings API allows you to convert text into numerical vectors representing semantic meaning. Here's the basic usage:

    def getembeddings(texts, model="jina-embeddings-v3", task="retrieval.passage"):
    

    """Generate embeddings using Jina AI API."""

    url = "https://api.jina.ai/v1/embeddings"

    payload = {

    "model": model,

    "input": texts,

    "task": task,

    "dimensions": 1024

    }

    response = requests.post(url, json=payload, headers=HEADERS)

    response.raiseforstatus()

    data = response.json()

    embeddings = [item["embedding"] for item in data["data"]]

    return embeddings

    Example usage

    documents = [

    "Machine learning is a branch of artificial intelligence that focuses on learning from data.",

    "Deep learning uses neural networks with many layers to process complex data.",

    "Natural language processing enables computers to understand and generate human language.",

    "Computer vision is a field of AI that enables computers to interpret images and video."

    ]

    embeddings = getembeddings(documents)

    print(f"Number of embeddings: {len(embeddings)}")

    print(f"Dimensions per embedding: {len(embeddings[0])}")

    Task-Specific Embeddings

    One of jina-embeddings-v3's standout features is the ability to use different LoRA adapters for different tasks. This is important because optimal embeddings for retrieval differ from those for classification:

    # For documents to be stored in a vector database
    

    passageembeddings = getembeddings(

    texts=documents,

    task="retrieval.passage"

    )

    For user search queries

    query = "How can computers understand human language?"

    queryembedding = getembeddings(

    texts=[query],

    task="retrieval.query"

    )

    For text classification

    classificationembeddings = getembeddings(

    texts=documents,

    task="classification"

    )

    For text matching / similarity

    matchingembeddings = getembeddings(

    texts=documents,

    task="text-matching"

    )

    For separation / clustering

    separationembeddings = getembeddings(

    texts=documents,

    task="separation"

    )

    After obtaining embeddings, we can perform semantic search using cosine similarity:

    def cosinesimilarity(vec1, vec2):
    

    """Calculate cosine similarity between two vectors."""

    vec1 = np.array(vec1)

    vec2 = np.array(vec2)

    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) np.linalg.norm(vec2))

    def semanticsearch(query, documents, docembeddings, topk=3):

    """Perform semantic search on a collection of documents."""

    # Generate query embedding with retrieval.query task

    queryemb = getembeddings([query], task="retrieval.query")[0]

    # Calculate similarity with each document

    scores = []

    for i, docemb in enumerate(docembeddings):

    score = cosinesimilarity(queryemb, docemb)

    scores.append((i, score, documents[i]))

    # Sort by highest score

    scores.sort(key=lambda x: x[1], reverse=True)

    return scores[:topk]

    Search example

    query = "How can AI see and recognize objects?"

    results = semanticsearch(query, documents, embeddings)

    print(f"Query: {query}\n")

    for rank, (idx, score, doc) in enumerate(results, 1):

    print(f"{rank}. [Score: {score:.4f}] {doc}")

    Matryoshka Dimensions

    Jina embeddings support Matryoshka Representation Learning, which allows you to reduce embedding dimensions without retraining:

    def getembeddings(texts, model="jina-embeddings-v3", task="retrieval.passage", dimensions=1024):
    

    """Generate embeddings with dimension control."""

    url = "https://api.jina.ai/v1/embeddings"

    payload = {

    "model": model,

    "input": texts,

    "task": task,

    "dimensions": dimensions

    }

    response = requests.post(url, json=payload, headers=HEADERS)

    response.raiseforstatus()

    data = response.json()

    return [item["embedding"] for item in data["data"]]

    Full dimension embedding (1024)

    fullembeddings = getembeddings(documents, dimensions=1024)

    Reduced dimension embedding (512) - faster, saves storage

    reducedembeddings = getembeddings(documents, dimensions=512)

    Minimal dimension embedding (256) - most storage efficient

    minimalembeddings = getembeddings(documents, dimensions=256)

    Jina Reranker API

    Reranking is a critical step in RAG pipelines. After initial retrieval using embedding similarity, the reranker re-evaluates the relevance of each document against the query using a more accurate cross-encoder:

    Basic Reranking

    def rerankdocuments(query, documents, model="jina-reranker-v2-base-multilingual", topn=5):
    

    """Rerank documents based on relevance to query."""

    url = "https://api.jina.ai/v1/rerank"

    payload = {

    "model": model,

    "query": query,

    "documents": documents,

    "topn": topn,

    "returndocuments": True

    }

    response = requests.post(url, json=payload, headers=HEADERS)

    response.raiseforstatus()

    return response.json()["results"]

    Reranking example

    query = "How to deploy machine learning models to production?"

    candidatedocs = [

    "Docker containers make it easy to package applications with all their dependencies.",

    "MLflow provides a platform for managing the ML model lifecycle including deployment.",

    "Python is a popular programming language for data science.",

    "Kubernetes can be used for orchestrating ML model containers in production.",

    "TensorFlow Serving enables serving ML models via REST or gRPC APIs.",

    "Git is a version control system used for tracking code changes.",

    "BentoML simplifies the process of packaging and deploying ML models.",

    "Pandas is a Python library for data manipulation and analysis."

    ]

    results = rerankdocuments(query, candidatedocs)

    print(f"Query: {query}\n")

    print("Reranking Results:")

    for result in results:

    score = result["relevancescore"]

    text = result["document"]["text"]

    idx = result["index"]

    print(f" [{score:.4f}] (idx:{idx}) {text}")

    Reranking with Metadata

    You can also include metadata or document titles to improve reranking accuracy:

    def rerankwithmetadata(query, documentswithtitles, topn=5):
    

    """Rerank documents that have titles/metadata."""

    url = "https://api.jina.ai/v1/rerank"

    # Format documents with titles

    formatteddocs = []

    for doc in documentswithtitles:

    formatteddocs.append(f"{doc['title']}: {doc['content']}")

    payload = {

    "model": "jina-reranker-v2-base-multilingual",

    "query": query,

    "documents": formatteddocs,

    "topn": topn,

    "returndocuments": True

    }

    response = requests.post(url, json=payload, headers=HEADERS)

    response.raiseforstatus()

    return response.json()["results"]

    Example with metadata

    docswithtitles = [

    {"title": "MLOps Best Practices", "content": "Continuous integration and delivery for ML models ensures quality and reliability."},

    {"title": "Data Preprocessing", "content": "Cleaning and transforming raw data into a format ready for training."},

    {"title": "Model Serving", "content": "Deploying models to production using TensorFlow Serving or Triton Inference Server."},

    {"title": "Feature Engineering", "content": "Creating new features from raw data to improve model performance."}

    ]

    results = rerankwithmetadata("how to deploy ML models", docswithtitles)

    for r in results:

    print(f"[{r['relevancescore']:.4f}] {r['document']['text']}")

    Jina Reader API

    The Jina Reader API allows you to extract clean content from any web page, which is extremely useful for building knowledge bases in RAG pipelines:

    Basic URL Reading

    def readurl(url):
    

    """Extract clean content from a URL using Jina Reader API."""

    readerurl = f"https://r.jina.ai/{url}"

    headers = {

    "Authorization": f"Bearer {JINAAPIKEY}",

    "Accept": "application/json",

    "X-Return-Format": "markdown"

    }

    response = requests.get(readerurl, headers=headers)

    response.raiseforstatus()

    return response.json()

    Example reading a web page

    result = readurl("https://en.wikipedia.org/wiki/Machinelearning")

    print(f"Title: {result.get('title', 'N/A')}")

    print(f"Content length: {len(result.get('content', ''))}")

    print(f"Content preview: {result.get('content', '')[:500]}")

    Batch URL Reading

    def readmultipleurls(urls):
    

    """Read content from multiple URLs."""

    results = []

    for url in urls:

    try:

    content = readurl(url)

    results.append({

    "url": url,

    "title": content.get("title", ""),

    "content": content.get("content", ""),

    "status": "success"

    })

    except Exception as e:

    results.append({

    "url": url,

    "title": "",

    "content": "",

    "status": f"error: {str(e)}"

    })

    return results

    Batch reading example

    urls = [

    "https://pytorch.org/tutorials/beginner/basics/intro.html",

    "https://scikit-learn.org/stable/gettingstarted.html"

    ]

    contents = readmultipleurls(urls)

    for c in contents:

    print(f"[{c['status']}] {c['url']} - {c['title']}")

    Search API

    Jina also provides a Search API that combines web search with content extraction:

    def jinasearch(query, numresults=5):
    

    """Search and extract content from the web using Jina Search API."""

    url = f"https://s.jina.ai/{query}"

    headers = {

    "Authorization": f"Bearer {JINAAPIKEY}",

    "Accept": "application/json",

    "X-Retain-Images": "none"

    }

    response = requests.get(url, headers=headers)

    response.raiseforstatus()

    return response.json()

    Search example

    results = jinasearch("tutorial deploy machine learning model production 2026")

    for item in results.get("data", []):

    print(f"Title: {item.get('title', 'N/A')}")

    print(f"URL: {item.get('url', 'N/A')}")

    print(f"Content: {item.get('content', '')[:200]}...")

    print()

    Building a Complete RAG Pipeline with Jina AI

    Now let's combine all Jina AI components to build a complete RAG pipeline:

    import json
    

    from typing import List, Dict

    class JinaRAGPipeline:

    """RAG Pipeline using Jina AI for embedding, reranking, and reading."""

    def init(self, apikey: str):

    self.apikey = apikey

    self.headers = {

    "Authorization": f"Bearer {apikey}",

    "Content-Type": "application/json",

    "Accept": "application/json"

    }

    self.knowledgebase = []

    self.kbembeddings = []

    def ingesturls(self, urls: List[str]) -> int:

    """Ingest content from URLs into the knowledge base."""

    for url in urls:

    try:

    readerurl = f"https://r.jina.ai/{url}"

    headers = {self.headers, "X-Return-Format": "markdown"}

    response = requests.get(readerurl, headers=headers)

    response.raiseforstatus()

    data = response.json()

    content = data.get("content", "")

    chunks = self.chunktext(content, chunksize=500, overlap=50)

    for chunk in chunks:

    self.knowledgebase.append({

    "source": url,

    "title": data.get("title", ""),

    "content": chunk

    })

    except Exception as e:

    print(f"Error ingesting {url}: {e}")

    # Generate embeddings for all chunks

    texts = [doc["content"] for doc in self.knowledgebase]

    if texts:

    self.kbembeddings = self.getembeddings(texts, task="retrieval.passage")

    return len(self.knowledgebase)

    def ingesttexts(self, texts: List[Dict[str, str]]) -> int:

    """Ingest texts directly into the knowledge base.

    Args:

    texts: List of dicts with 'title' and 'content' keys

    """

    for text in texts:

    chunks = self.chunktext(text["content"], chunksize=500, overlap=50)

    for chunk in chunks:

    self.knowledgebase.append({

    "source": "directinput",

    "title": text.get("title", ""),

    "content": chunk

    })

    alltexts = [doc["content"] for doc in self.knowledgebase]

    if alltexts:

    self.kbembeddings = self.getembeddings(alltexts, task="retrieval.passage")

    return len(self.knowledgebase)

    def query(self, question: str, topk: int = 10, topn: int = 3) -> List[Dict]:

    """Query RAG pipeline: embed -> retrieve -> rerank."""

    # Step 1: Generate query embedding

    queryemb = self.getembeddings([question], task="retrieval.query")[0]

    # Step 2: Retrieve top-k candidates via cosine similarity

    scores = []

    for i, docemb in enumerate(self.kbembeddings):

    score = self.cosinesimilarity(queryemb, docemb)

    scores.append((i, score))

    scores.sort(key=lambda x: x[1], reverse=True)

    candidates = scores[:topk]

    # Step 3: Rerank candidates

    candidatetexts = [self.knowledgebase[idx]["content"] for idx, in candidates]

    reranked = self.rerank(question, candidatetexts, topn=topn)

    # Step 4: Return results with metadata

    results = []

    for r in reranked:

    originalidx = candidates[r["index"]][0]

    doc = self.knowledgebase[originalidx]

    results.append({

    "content": doc["content"],

    "title": doc["title"],

    "source": doc["source"],

    "embeddingscore": candidates[r["index"]][1],

    "rerankscore": r["relevancescore"]

    })

    return results

    def getembeddings(self, texts, task="retrieval.passage", dimensions=1024):

    url = "https://api.jina.ai/v1/embeddings"

    payload = {

    "model": "jina-embeddings-v3",

    "input": texts,

    "task": task,

    "dimensions": dimensions

    }

    response = requests.post(url, json=payload, headers=self.headers)

    response.raiseforstatus()

    return [item["embedding"] for item in response.json()["data"]]

    def rerank(self, query, documents, topn=5):

    url = "https://api.jina.ai/v1/rerank"

    payload = {

    "model": "jina-reranker-v2-base-multilingual",

    "query": query,

    "documents": documents,

    "topn": topn,

    "returndocuments": True

    }

    response = requests.post(url, json=payload, headers=self.headers)

    response.raiseforstatus()

    return response.json()["results"]

    def chunktext(self, text, chunksize=500, overlap=50):

    words = text.split()

    chunks = []

    for i in range(0, len(words), chunksize - overlap):

    chunk = " ".join(words[i:i + chunksize])

    if chunk.strip():

    chunks.append(chunk)

    return chunks

    @staticmethod

    def cosinesimilarity(vec1, vec2):

    v1, v2 = np.array(vec1), np.array(vec2)

    return float(np.dot(v1, v2) / (np.linalg.norm(v1) np.linalg.norm(v2)))

    Using the RAG Pipeline

    rag = JinaRAGPipeline(apikey=JINAAPIKEY)

    Ingest documents

    documents = [

    {"title": "MLOps Fundamentals", "content": "MLOps is a practice that combines Machine Learning, DevOps, and Data Engineering to automate and standardize the ML model lifecycle. Key MLOps components include version control for models and data, CI/CD pipelines for training and deployment, model monitoring in production, and feature stores for feature management."},

    {"title": "Model Deployment Strategies", "content": "There are several ML model deployment strategies: Blue-Green deployment allows switching between two model versions. Canary deployment releases the new model to a small portion of traffic first. Shadow deployment runs the new model in parallel without affecting user responses. A/B testing compares the performance of two models directly."},

    {"title": "Feature Store", "content": "A feature store is a centralized storage system for ML features that ensures consistency between training and serving. Popular feature stores include Feast, Tecton, and Hopsworks. Key benefits include avoiding training-serving skew, enabling feature reuse, and accelerating new model development."}

    ]

    count = rag.ingesttexts(documents)

    print(f"Ingested {count} chunks")

    Query

    results = rag.query("How to safely deploy ML models?")

    for i, r in enumerate(results, 1):

    print(f"\n--- Result {i} ---")

    print(f"Title: {r['title']}")

    print(f"Rerank Score: {r['rerankscore']:.4f}")

    print(f"Content: {r['content'][:200]}...")

    Integration with LangChain

    Jina AI integrates well with the LangChain framework:

    from langchaincommunity.embeddings import JinaEmbeddings
    

    from langchaincommunity.documentloaders import WebBaseLoader

    from langchain.textsplitter import RecursiveCharacterTextSplitter

    from langchaincommunity.vectorstores import FAISS

    Setup Jina Embeddings

    embeddings = JinaEmbeddings(

    jinaapikey=JINAAPIKEY,

    modelname="jina-embeddings-v3"

    )

    Load and chunk documents

    textsplitter = RecursiveCharacterTextSplitter(

    chunksize=500,

    chunkoverlap=50

    )

    texts = [

    "A machine learning pipeline consists of data collection, preprocessing, feature engineering, model training, evaluation, and deployment.",

    "Monitoring models in production is important for detecting data drift, concept drift, and model performance degradation over time."

    ]

    Create vector store

    vectorstore = FAISS.fromtexts(texts, embeddings)

    Semantic search

    results = vectorstore.similaritysearchwithscore(

    "How to detect model issues in production?",

    k=3

    )

    for doc, score in results:

    print(f"[Score: {score:.4f}] {doc.pagecontent}")

    Integration with LlamaIndex

    from llamaindex.core import VectorStoreIndex, Document, Settings
    

    from llamaindex.embeddings.jinaai import JinaEmbedding

    Setup Jina Embedding

    Settings.embedmodel = JinaEmbedding(

    apikey=JINAAPIKEY,

    model="jina-embeddings-v3"

    )

    Create documents

    documents = [

    Document(text="Feature engineering is the process of creating new variables from raw data to improve predictive model performance."),

    Document(text="Hyperparameter tuning uses techniques like Grid Search, Random Search, or Bayesian Optimization to find the optimal configuration."),

    Document(text="Cross-validation helps evaluate model generalization by splitting data into multiple folds for training and testing.")

    ]

    Build index

    index = VectorStoreIndex.fromdocuments(documents)

    Query

    queryengine = index.asqueryengine()

    response = queryengine.query("How to improve model performance?")

    print(response)

    Best Practices

    1. Choose the Right Task for Embeddings

    Using the right task significantly affects result quality:

    | Task | When to Use |

    |------|------------|

    | retrieval.query | For user queries/questions |

    | retrieval.passage | For documents to be searched |

    | text-matching | For matching two similar texts |

    | classification | For text classification |

    | separation | For clustering/grouping |

    2. Optimize Embedding Dimensions

    # Production with high accuracy requirements
    

    highaccuracy = getembeddings(texts, dimensions=1024)

    Balance between accuracy and speed

    balanced = getembeddings(texts, dimensions=512)

    Prototype or very large datasets

    fastprototype = getembeddings(texts, dimensions=256)

    3. Use Reranker After Initial Retrieval

    Always use two-stage retrieval:

  • Stage 1: Retrieve 20-50 candidates using embedding similarity (fast)
  • Stage 2: Rerank top candidates using cross-encoder (more accurate)
  • # GOOD: Two-stage retrieval
    

    initialcandidates = vectorsearch(query, topk=30) # Fast

    finalresults = rerank(query, initialcandidates, topn=5) # Accurate

    SUBOPTIMAL: Embedding search only

    results = vectorsearch(query, topk=5) # May miss relevant documents

    4. Batching for Efficiency

    # GOOD: Batch processing
    

    allembeddings = getembeddings(alldocuments) # Single API call

    SUBOPTIMAL: One by one

    for doc in alldocuments:

    emb = getembeddings([doc]) # Many API calls

    5. Caching Embeddings

    import hashlib
    

    import json

    class EmbeddingCache:

    def init(self, cachefile="embeddingcache.json"):

    self.cachefile = cachefile

    try:

    with open(cachefile, "r") as f:

    self.cache = json.load(f)

    except FileNotFoundError:

    self.cache = {}

    def getorcompute(self, text, computefn):

    key = hashlib.md5(text.encode()).hexdigest()

    if key not in self.cache:

    self.cache[key] = computefn(text)

    self.save()

    return self.cache[key]

    def save(self):

    with open(self.cachefile, "w") as f:

    json.dump(self.cache, f)

    cache = EmbeddingCache()

    embedding = cache.getorcompute(

    "text to embed",

    lambda t: getembeddings([t])[0]

    )

    6. Error Handling and Rate Limiting

    import time
    
    

    def getembeddingswithretry(texts, maxretries=3, backoff=2):

    """Get embeddings with retry logic."""

    for attempt in range(maxretries):

    try:

    return getembeddings(texts)

    except requests.exceptions.HTTPError as e:

    if e.response.statuscode == 429: # Rate limited

    waittime = backoff attempt

    print(f"Rate limited. Waiting {waittime}s...")

    time.sleep(waittime)

    elif e.response.statuscode >= 500: # Server error

    waittime = backoff attempt

    print(f"Server error. Retrying in {waittime}s...")

    time.sleep(waittime)

    else:

    raise

    raise Exception(f"Failed after {max_retries} retries")

    Jina Model Comparison

    | Model | Dimensions | Languages | Context Length | Use Case |

    |-------|-----------|-----------|---------------|----------|

    | jina-embeddings-v3 | 1024 (adjustable) | 89 languages | 8192 tokens | General purpose, multilingual |

    | jina-embeddings-v2-base-en | 768 | English | 8192 tokens | English-only, cost-effective |

    | jina-reranker-v2-base-multilingual | N/A | Multilingual | 1M tokens | Long document reranking |

    | jina-colbert-v2 | 128 per token | Multilingual | 8192 tokens | Late interaction retrieval |

    Conclusion

    Jina AI provides a comprehensive toolkit for building high-quality RAG pipelines. By combining embeddings, reranker, and reader API, you can build an accurate and efficient semantic search system. Key takeaways to remember:

  • Use task-specific embeddings for optimal results on each use case.
  • Apply two-stage retrieval (embedding + reranker) for maximum accuracy.
  • Leverage Matryoshka dimensions to optimize the trade-off between accuracy and performance.
  • Use the Reader API to extract clean content from the web as a knowledge base source.
  • Integrate with frameworks like LangChain or LlamaIndex to accelerate development.
  • With a solid foundation from Jina AI, you can build production-ready RAG applications capable of handling semantic search needs across multiple languages.

    Related Articles

    Complete txtai Tutorial: All-in-One Embeddings Database for Semantic Search and LLM Workflows

    Tutorial Lengkap txtai: Database Embeddings All-in-One untuk Semantic Search dan LLM Workflows txtai adalah framework Py...

    Complete Cohere API Tutorial: Embeddings, Reranking, and RAG with Python

    Tutorial Lengkap Cohere API: Embeddings, Reranking, dan RAG dengan Python Cohere adalah platform AI yang menyediakan mod...

    FastEmbed: Fast and Lightweight Embeddings Without Torch, by Qdrant

    FastEmbed: Bikin Embedding Cepat dan Ringan Tanpa Torch dari Qdrant Halo temen-temen, balik lagi sama aku Ruby Abdullah....

    Complete Pinecone Tutorial: Vector Database for AI and Semantic Search

    Tutorial Lengkap Pinecone: Vector Database untuk AI dan Semantic Search Pinecone adalah managed vector database yang dir...