Instructions to use Kervyn-AI/Kervyn-Rerank-100M-Preview with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- sentence-transformers
How to use Kervyn-AI/Kervyn-Rerank-100M-Preview with sentence-transformers:
from sentence_transformers import CrossEncoder model = CrossEncoder("Kervyn-AI/Kervyn-Rerank-100M-Preview") query = "Which planet is known as the Red Planet?" passages = [ "Venus is often called Earth's twin because of its similar size and proximity.", "Mars, known for its reddish appearance, is often referred to as the Red Planet.", "Jupiter, the largest planet in our solar system, has a prominent red spot.", "Saturn, famous for its rings, is sometimes mistaken for the Red Planet." ] scores = model.predict([(query, passage) for passage in passages]) print(scores) - Notebooks
- Google Colab
- Kaggle
Kervyn Rerank 100M · Preview
Español
🔬 Preview. Es la primera versión pública del reranker de Kervyn y todavía está en desarrollo.
- Funciona y está medido: las cifras de abajo son reales y reproducibles.
- Los pesos pueden cambiar en próximas versiones. Para fijar esta, usa
revision="v1".- Tu opinión nos ayuda a mejorarlo.
Kervyn Rerank es un cross-encoder: lee la pregunta y el pasaje juntos y les da una puntuación de relevancia.
- Para qué sirve: reordenar los primeros resultados de cualquier buscador (denso, BM25 o híbrido) para que el pasaje correcto quede primero.
- Idiomas: funciona en español, inglés y entre los dos.
- Modelo propio, de cero: arquitectura, tokenizer y pesos de Kervyn, entrenados desde cero.
- Licencia Apache-2.0.
- Pareja: hace equipo con Kervyn Embeddings 100M · Preview.
Ventajas frente a otros modelos del mercado
- ⚡ 5 veces más pequeño y 2,8 veces más rápido en CPU que bge-reranker-v2-m3.
- Son 104M parámetros frente a 568M.
- Reordena un top-20 en 2,5 s con 8 vCPU, frente a 7,1 s.
- 🥇 Mejor media de búsqueda que bge-reranker-v2-m3, sobre el top-20 de los dos
buscadores probados:
- 94,45 frente a 94,23 sobre Kervyn Embeddings;
- 94,67 frente a 94,18 sobre bge-m3.
- 💻 No rompe la búsqueda de código.
- bge-reranker-v2-m3 baja CodeSearchNet de 90,1 a 82,8, peor que no reordenar.
- Kervyn Rerank lo sube a 91,7.
- 📈 Gran mejora sobre cualquier buscador: de +2,9 a +3,7 puntos de nDCG@10 de media.
- 🔓 100 % propio y Apache-2.0, sin licencias heredadas.
- 🛠️ Ideal para ajustarlo con los datos de tu empresa. Ver Ajuste fino.
Uso
from sentence_transformers import SentenceTransformer, CrossEncoder
embedder = SentenceTransformer("Kervyn-AI/Kervyn-Embeddings-100M-Preview")
reranker = CrossEncoder("Kervyn-AI/Kervyn-Rerank-100M-Preview", max_length=512)
pasajes = [...] # tus documentos, en trozos de ~200 palabras
query = "¿Qué plazo de preaviso tiene el contrato?"
# 1) Recuperación densa: los 20 mejores
scores = embedder.similarity(embedder.encode(query), embedder.encode(pasajes))[0]
top = scores.argsort(descending=True)[:20].tolist()
# 2) Reordenación con Kervyn Rerank
relevancia = reranker.predict([(query, pasajes[i]) for i in top])
orden = [top[i] for i in relevancia.argsort()[::-1]]
- Salida: una puntuación por par. Más alta es más relevante.
- Límites de entrada: hasta 512 tokens entre pregunta y pasaje. La pregunta se recorta a 400 caracteres.
Ajuste fino con los datos de tu empresa
Un reranker ajustado a tu dominio suele ser la mejora más rentable de un buscador:
- Pequeño: 104M parámetros, así que el ajuste completo cabe en una GPU de consumo.
- Estándar: el ajuste usa el entrenamiento normal de sentence-transformers.
- Privado: tus datos no salen de tu infraestructura.
- Apache-2.0: el modelo ajustado es tuyo.
Con los mismos pares (pregunta, pasaje correcto) que uses para Kervyn Embeddings, el propio buscador mina los negativos difíciles: pasajes parecidos que no responden a la pregunta.
from datasets import Dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.cross_encoder import (CrossEncoder, CrossEncoderTrainer,
CrossEncoderTrainingArguments)
from sentence_transformers.cross_encoder.losses import BinaryCrossEntropyLoss
from sentence_transformers.util import mine_hard_negatives
embedder = SentenceTransformer("Kervyn-AI/Kervyn-Embeddings-100M-Preview")
model = CrossEncoder("Kervyn-AI/Kervyn-Rerank-100M-Preview", max_length=512)
pairs = Dataset.from_dict({
"query": ["¿Cuál es el plazo de devolución?", "¿Cómo descargo una factura?"],
"answer": ["Las devoluciones se aceptan durante 30 días desde la entrega.",
"Las facturas se descargan desde Mi cuenta > Pedidos > Factura."],
})
# 3 negativos por pregunta entre los puestos 5 y 30 del buscador (los primeros pueden ser
# respuestas válidas)
train = mine_hard_negatives(pairs, embedder, num_negatives=3, range_min=5, range_max=30,
output_format="labeled-pair")
args = CrossEncoderTrainingArguments(
output_dir="kervyn-rerank-mi-empresa",
num_train_epochs=1,
per_device_train_batch_size=32,
learning_rate=1e-5,
warmup_ratio=0.1,
)
trainer = CrossEncoderTrainer(model=model, args=args, train_dataset=train,
loss=BinaryCrossEntropyLoss(model))
trainer.train()
model.save_pretrained("kervyn-rerank-mi-empresa/final")
Benchmarks
Las métricas son estas:
- nDCG@10 reordenando el top-20 de un buscador denso.
- Tareas: Belebele y XQuAD en español, en inglés y entre idiomas (ES→EN: pregunta en español, pasaje en inglés), documentación técnica en español (kervyn-docs) y CodeSearchNet Python.
Sobre el top-20 de Kervyn Embeddings 100M:
| Tarea | Sin reranker | + Kervyn Rerank (104M) | + bge-reranker-v2-m3 (568M) |
|---|---|---|---|
| Belebele ES | 92,19 | 95,63 | 96,09 |
| Belebele EN | 93,91 | 97,11 | 97,56 |
| Belebele ES→EN | 90,13 | 93,56 | 95,37 |
| XQuAD ES | 95,32 | 98,78 | 99,11 |
| XQuAD EN | 96,25 | 98,77 | 99,23 |
| XQuAD ES→EN | 94,53 | 98,09 | 98,98 |
| kervyn-docs (ES) | 75,78 | 81,89 | 84,67 |
| CodeSearchNet Python | 90,08 | 91,74 | 82,81 |
| Media (8) | 91,02 | 94,45 | 94,23 |
| Media sin código (7) | 91,16 | 94,83 | 95,86 |
Sobre el top-20 de bge-m3:
| Sistema | Media (8) | Media sin código (7) |
|---|---|---|
| bge-m3 sin reranker | 91,41 | 92,28 |
| bge-m3 + Kervyn Rerank | 94,67 | 95,16 |
| bge-m3 + bge-reranker-v2-m3 | 94,18 | 95,86 |
- Media total: Kervyn Rerank tiene la mejor media en los dos buscadores.
- Solo texto: bge-reranker-v2-m3, 5 veces mayor, queda entre 0,7 y 1 punto por delante.
Velocidad en CPU
Medido en una CPU x86 de servidor con 8 vCPU, PyTorch en fp32. Cada pregunta puntúa 20 pares (pregunta, pasaje de ~140 tokens).
| Reranker | Pares/s | Reordenar un top-20 (p50) |
|---|---|---|
| Kervyn Rerank 100M | 8,1 | 2,5 s |
| bge-reranker-v2-m3 | 2,9 | 7,1 s |
- En CPU el reranker es la parte cara de la búsqueda. Para respuestas interactivas, reordena el top-5 o el top-10 (~0,6–1,3 s) o usa GPU.
- Cuantización int8 dinámica: no la recomendamos en esta Preview, porque cambia el orden de los resultados. Usa fp32.
Detalles del modelo
| Campo | Valor |
|---|---|
| Arquitectura | Encoder bidireccional: 12 capas × 768, atención completa y RoPE, más una cabeza de relevancia (un logit) |
| Parámetros | 104M |
| Entrada | `< |
| Tokenizer | Propio, ~24.600 tokens (el mismo que Kervyn Embeddings) |
| Formato | ModernBertForSequenceClassification (safetensors), compatible con CrossEncoder |
Cómo se entrenó:
- Base: el mismo preentrenamiento propio que Kervyn Embeddings, con 48.000 millones de tokens en español, inglés y código.
- Ordenación por listas: ~680.000 preguntas, cada una con su pasaje correcto y 7
negativos difíciles minados por Kervyn Embeddings. La pérdida es una entropía cruzada
sobre el grupo de 8.
- Pares públicos: MS MARCO en inglés y en español, Natural Questions, GooAQ, SQuAD, SQAC, ELI5, Stack Exchange, charlas TED ES↔EN y CodeSearchNet.
- Queries sintéticas, escritas a partir de pasajes públicos con modelos abiertos de licencia MIT.
- Se descartan los falsos negativos.
- No se destila ningún reranker de terceros.
Limitaciones
- Preview: los pesos pueden cambiar. Fija
revision="v1"si necesitas reproducibilidad. - Texto: queda algo por detrás de bge-reranker-v2-m3, sobre todo en documentación (−2,8) y en Belebele ES→EN (−1,8).
- Velocidad en CPU: 2,5 s por pregunta para un top-20. Reordena menos pasajes o usa GPU.
- Idiomas: solo español e inglés.
- Datos de entrenamiento: los datasets públicos listados en
datasets.
English
🔬 Preview. This is the first public release of Kervyn's reranker, and it is still under development.
- It works and it is measured: the numbers below are real and reproducible.
- Weights may change in future versions. To pin this one, use
revision="v1".- Your feedback helps us improve it.
Kervyn Rerank is a cross-encoder: it reads the question and the passage together and gives them a relevance score.
- What it is for: reranking the top results of any retriever (dense, BM25 or hybrid) so the right passage comes first.
- Languages: it works in Spanish, English and across the two.
- Own model, from scratch: Kervyn's own architecture, tokenizer and weights, trained from scratch.
- Apache-2.0 license.
- Pair: it teams up with Kervyn Embeddings 100M · Preview.
Advantages over other models
- ⚡ 5× smaller and 2.8× faster on CPU than bge-reranker-v2-m3.
- It has 104M parameters vs 568M.
- It reranks a top-20 in 2.5 s on 8 vCPU, vs 7.1 s.
- 🥇 A higher average than bge-reranker-v2-m3, over the top-20 of both retrievers
tested:
- 94.45 vs 94.23 over Kervyn Embeddings;
- 94.67 vs 94.18 over bge-m3.
- 💻 It does not break code search.
- bge-reranker-v2-m3 drops CodeSearchNet from 90.1 to 82.8, worse than not reranking.
- Kervyn Rerank lifts it to 91.7.
- 📈 A big gain over any retriever: +2.9 to +3.7 nDCG@10 points on average.
- 🔓 100% own and Apache-2.0, with no inherited licenses.
- 🛠️ Ideal for fine-tuning on your company data. See Fine-tuning.
Usage
from sentence_transformers import SentenceTransformer, CrossEncoder
embedder = SentenceTransformer("Kervyn-AI/Kervyn-Embeddings-100M-Preview")
reranker = CrossEncoder("Kervyn-AI/Kervyn-Rerank-100M-Preview", max_length=512)
passages = [...] # your documents, in chunks of ~200 words
query = "What notice period does the contract have?"
# 1) Dense retrieval: the top 20
scores = embedder.similarity(embedder.encode(query), embedder.encode(passages))[0]
top = scores.argsort(descending=True)[:20].tolist()
# 2) Reranking with Kervyn Rerank
relevance = reranker.predict([(query, passages[i]) for i in top])
order = [top[i] for i in relevance.argsort()[::-1]]
- Output: one score per pair. Higher means more relevant.
- Input limits: up to 512 tokens for question and passage together. The question is cut to 400 characters.
Fine-tuning on your company data
A reranker tuned to your domain is often the most cost-effective upgrade to a search engine:
- Small: 104M parameters, so full fine-tuning fits on a consumer GPU.
- Standard: fine-tuning uses regular sentence-transformers training.
- Private: your data never leaves your infrastructure.
- Apache-2.0: the fine-tuned model is yours.
With the same (question, correct passage) pairs you use for Kervyn Embeddings, the retriever itself mines the hard negatives: similar passages that do not answer the question.
from datasets import Dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.cross_encoder import (CrossEncoder, CrossEncoderTrainer,
CrossEncoderTrainingArguments)
from sentence_transformers.cross_encoder.losses import BinaryCrossEntropyLoss
from sentence_transformers.util import mine_hard_negatives
embedder = SentenceTransformer("Kervyn-AI/Kervyn-Embeddings-100M-Preview")
model = CrossEncoder("Kervyn-AI/Kervyn-Rerank-100M-Preview", max_length=512)
pairs = Dataset.from_dict({
"query": ["What is the return period?", "How do I download an invoice?"],
"answer": ["Returns are accepted for 30 days after delivery.",
"Invoices can be downloaded from My account > Orders > Invoice."],
})
# 3 negatives per question from ranks 5 to 30 of the retriever (the very top ones may be
# valid answers)
train = mine_hard_negatives(pairs, embedder, num_negatives=3, range_min=5, range_max=30,
output_format="labeled-pair")
args = CrossEncoderTrainingArguments(
output_dir="kervyn-rerank-my-company",
num_train_epochs=1,
per_device_train_batch_size=32,
learning_rate=1e-5,
warmup_ratio=0.1,
)
trainer = CrossEncoderTrainer(model=model, args=args, train_dataset=train,
loss=BinaryCrossEntropyLoss(model))
trainer.train()
model.save_pretrained("kervyn-rerank-my-company/final")
Benchmark results
These are the metrics:
- nDCG@10 when reranking the top-20 of a dense retriever.
- Tasks: Belebele and XQuAD in Spanish, in English and across languages (ES→EN: Spanish question, English passage), technical documentation in Spanish (kervyn-docs) and CodeSearchNet Python.
Over the top-20 of Kervyn Embeddings 100M:
| Task | No reranker | + Kervyn Rerank (104M) | + bge-reranker-v2-m3 (568M) |
|---|---|---|---|
| Belebele ES | 92.19 | 95.63 | 96.09 |
| Belebele EN | 93.91 | 97.11 | 97.56 |
| Belebele ES→EN | 90.13 | 93.56 | 95.37 |
| XQuAD ES | 95.32 | 98.78 | 99.11 |
| XQuAD EN | 96.25 | 98.77 | 99.23 |
| XQuAD ES→EN | 94.53 | 98.09 | 98.98 |
| kervyn-docs (ES) | 75.78 | 81.89 | 84.67 |
| CodeSearchNet Python | 90.08 | 91.74 | 82.81 |
| Average (8) | 91.02 | 94.45 | 94.23 |
| Average without code (7) | 91.16 | 94.83 | 95.86 |
Over the top-20 of bge-m3:
| System | Average (8) | Average without code (7) |
|---|---|---|
| bge-m3, no reranker | 91.41 | 92.28 |
| bge-m3 + Kervyn Rerank | 94.67 | 95.16 |
| bge-m3 + bge-reranker-v2-m3 | 94.18 | 95.86 |
- Overall average: Kervyn Rerank has the best average over both retrievers.
- Text only: bge-reranker-v2-m3, 5× larger, is 0.7 to 1 point ahead.
CPU speed
Measured on an x86 server CPU with 8 vCPU, PyTorch in fp32. Each question scores 20 pairs (question, passage of ~140 tokens).
| Reranker | Pairs/s | Rerank a top-20 (p50) |
|---|---|---|
| Kervyn Rerank 100M | 8.1 | 2.5 s |
| bge-reranker-v2-m3 | 2.9 | 7.1 s |
- On CPU the reranker is the expensive part of search. For interactive answers, rerank the top-5 or top-10 (~0.6–1.3 s) or use a GPU.
- Dynamic int8 quantization: we do not recommend it in this Preview, because it changes the order of the results. Use fp32.
Model details
| Field | Value |
|---|---|
| Architecture | Bidirectional encoder: 12 layers × 768, full attention and RoPE, plus a relevance head (one logit) |
| Parameters | 104M |
| Input | `< |
| Tokenizer | Own, ~24,600 tokens (the same as Kervyn Embeddings) |
| Format | ModernBertForSequenceClassification (safetensors), compatible with CrossEncoder |
How it was trained:
- Base: the same own pre-training as Kervyn Embeddings, with 48 billion tokens in Spanish, English and code.
- Listwise ranking: ~680,000 questions, each with its correct passage and 7 hard
negatives mined by Kervyn Embeddings. The loss is a cross-entropy over the group of 8.
- Public pairs: MS MARCO in English and Spanish, Natural Questions, GooAQ, SQuAD, SQAC, ELI5, Stack Exchange, ES↔EN TED talks and CodeSearchNet.
- Synthetic queries, written from public passages with open MIT-licensed models.
- False negatives are discarded.
- No third-party reranker is distilled.
Limitations
- Preview: weights may change. Pin
revision="v1"if you need reproducibility. - Text: slightly behind bge-reranker-v2-m3, mostly on documentation (−2.8) and Belebele ES→EN (−1.8).
- CPU speed: 2.5 s per question for a top-20. Rerank fewer passages or use a GPU.
- Languages: Spanish and English only.
- Training data: the public datasets listed in
datasets.
- Downloads last month
- -