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:
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"
)
Cosine Similarity Search
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.raise
forstatus()
data = response.json()
return [item["embedding"] for item in data["data"]]
Full dimension embedding (1024)
full
embeddings = getembeddings(documents, dimensions=1024)
Reduced dimension embedding (512) - faster, saves storage
reduced
embeddings = getembeddings(documents, dimensions=512)
Minimal dimension embedding (256) - most storage efficient
minimal
embeddings = 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,
"top
n": topn,
"return
documents": 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
formatted
docs = []
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."""
reader
url = 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 = read
url(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 {JINA
APIKEY}",
"Accept": "application/json",
"X-Retain-Images": "none"
}
response = requests.get(url, headers=headers)
response.raise
forstatus()
return response.json()
Search example
results = jina
search("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 langchain
community.documentloaders import WebBaseLoader
from langchain.text
splitter 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 llama
index.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:
# 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:
With a solid foundation from Jina AI, you can build production-ready RAG applications capable of handling semantic search needs across multiple languages.