Contextual retrieval de Anthropic: qué es y cómo implementarlo

El problema clásico del chunking en RAG es la pérdida de contexto: un fragmento de documento que dice "el acuerdo entró en vigor el día siguiente" pierde todo su significado cuando se separa del resto del documento. El sistema de recuperación no puede saber a qué acuerdo se refiere, ni qué significa "el día siguiente".

Contextual retrieval es la técnica que Anthropic publicó para resolver esto. El resultado publicado: una reducción del 67% en recuperaciones fallidas sobre las técnicas estándar.

El problema: chunks sin contexto

Cuando haces chunking de un documento largo, cada fragmento pierde información sobre:

De dónde viene: qué sección, capítulo o documento
Qué pasó antes: el contexto previo que da sentido al fragmento
La estructura general: si es una conclusión, una premisa o un ejemplo

El retrieval estándar busca chunks semánticamente similares a la query, pero si el chunk carece de contexto, la similitud semántica es imprecisa.

La solución: añadir contexto antes de indexar

La idea central de contextual retrieval es sencilla: antes de indexar cada chunk, uses el LLM para generar una descripción corta que sitúe el chunk en el contexto del documento completo. Luego concatenas esa descripción al chunk antes de crear el embedding.

[Contexto generado]: Este fragmento pertenece al contrato de arrendamiento 
entre Inmobiliaria García S.L. y el arrendatario Pedro Martínez, 
específicamente a la cláusula 7 sobre duración y renovación.

[Chunk original]: El acuerdo entró en vigor el día siguiente a la firma 
y tendrá una duración inicial de 12 meses, renovable por períodos anuales 
salvo notificación con 30 días de antelación.

Ahora el embedding captura que este fragmento trata sobre "duración del contrato de arrendamiento García-Martínez", no solo sobre "acuerdo vigente doce meses".

Implementación paso a paso

Paso 1: El prompt para generar contexto

El prompt oficial que Anthropic recomienda:

CONTEXT_PROMPT = """
<document>
{document_content}
</document>

Este es el fragmento del documento que necesita ser situado en contexto:
<chunk>
{chunk_content}
</chunk>

Proporciona un contexto breve y específico para este fragmento dentro del documento completo.
Responde solo con el contexto, sin explicaciones adicionales. Máximo 2-3 oraciones.
"""

Paso 2: Generar contexto para cada chunk

import anthropic

client = anthropic.Anthropic()

def generar_contexto(documento_completo: str, chunk: str) -> str:
    response = client.messages.create(
        model="claude-haiku-3-5",  # Haiku es suficiente y mucho más barato
        max_tokens=150,
        messages=[{
            "role": "user",
            "content": CONTEXT_PROMPT.format(
                document_content=documento_completo,
                chunk_content=chunk
            )
        }]
    )
    return response.content[0].text

def preparar_chunk_con_contexto(documento: str, chunk: str) -> str:
    contexto = generar_contexto(documento, chunk)
    return f"{contexto}\n\n{chunk}"

Paso 3: Prompt caching para reducir costes

El documento completo se envía con cada chunk — esto puede ser muy caro sin optimización. El prompt caching de Anthropic soluciona esto: el documento se cachea y solo se procesa una vez por sesión.

def generar_contexto_con_cache(documento_completo: str, chunk: str) -> str:
    response = client.messages.create(
        model="claude-haiku-3-5",
        max_tokens=150,
        messages=[{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"<document>\n{documento_completo}\n</document>\n\n",
                    "cache_control": {"type": "ephemeral"}  # Cachea el documento
                },
                {
                    "type": "text",
                    "text": f"Sitúa este fragmento en contexto:\n<chunk>\n{chunk}\n</chunk>\n\nRespuesta breve, máximo 2 oraciones."
                }
            ]
        }]
    )
    return response.content[0].text

Con caching activado, el coste de procesar todos los chunks de un documento baja aproximadamente un 90%.

Paso 4: Pipeline completo

from typing import List
import time

def procesar_documento_rag(
    documento: str,
    chunks: List[str],
    embedding_fn,
    vector_store
) -> None:
    """Procesa un documento aplicando contextual retrieval a cada chunk."""
    
    chunks_con_contexto = []
    
    for i, chunk in enumerate(chunks):
        try:
            chunk_contextualizado = preparar_chunk_con_contexto(documento, chunk)
            chunks_con_contexto.append({
                "texto_original": chunk,
                "texto_indexado": chunk_contextualizado,
                "indice": i
            })
            # Rate limiting básico
            time.sleep(0.1)
        except Exception as e:
            print(f"Error en chunk {i}: {e}")
            chunks_con_contexto.append({
                "texto_original": chunk,
                "texto_indexado": chunk,  # Fallback al chunk sin contexto
                "indice": i
            })
    
    # Crear embeddings del texto contextualizado
    embeddings = embedding_fn([c["texto_indexado"] for c in chunks_con_contexto])
    
    # Indexar en el vector store
    for chunk_data, embedding in zip(chunks_con_contexto, embeddings):
        vector_store.upsert(
            id=f"chunk_{chunk_data['indice']}",
            embedding=embedding,
            metadata={
                "texto": chunk_data["texto_original"],  # Guardamos el original para el output
                "texto_indexado": chunk_data["texto_indexado"]
            }
        )

Nota importante: el embedding se crea sobre el texto contextualizado (para mejor retrieval), pero en los resultados se devuelve el texto original del chunk (para que el LLM no reciba el contexto generado dos veces).

Combinación con BM25

Anthropic encontró que combinar contextual retrieval con retrieval híbrido (dense + sparse) reduce los fallos un 67% frente al RAG estándar. La implementación básica:

from rank_bm25 import BM25Okapi

class HybridRetriever:
    def __init__(self, chunks_originales: List[str], chunks_indexados: List[str]):
        # BM25 sobre los textos contextualizados
        tokenized = [t.lower().split() for t in chunks_indexados]
        self.bm25 = BM25Okapi(tokenized)
        self.chunks = chunks_originales
    
    def buscar(self, query: str, vector_results: List[dict], top_k: int = 5) -> List[dict]:
        # Scores BM25
        bm25_scores = self.bm25.get_scores(query.lower().split())
        
        # Combinar con scores del vector store (Reciprocal Rank Fusion)
        resultado_final = []
        for i, chunk in enumerate(self.chunks):
            vector_rank = next(
                (r["rank"] for r in vector_results if r["indice"] == i), len(self.chunks)
            )
            bm25_rank = len(self.chunks) - int(bm25_scores[i] * len(self.chunks))
            
            rrf_score = 1/(60 + vector_rank) + 1/(60 + bm25_rank)
            resultado_final.append({"chunk": chunk, "score": rrf_score, "indice": i})
        
        return sorted(resultado_final, key=lambda x: x["score"], reverse=True)[:top_k]

Cuándo aplicar contextual retrieval

Alta prioridad:

Documentos largos donde los chunks pierden referencia al sujeto (contratos, manuales, informes)
Documentos con estructura jerárquica (capítulos, secciones, subsecciones)
Bases de conocimiento con múltiples documentos sobre el mismo tema

Menor prioridad:

Chunks que ya son autosuficientes por su naturaleza (FAQs, artículos cortos independientes)
Volúmenes muy grandes donde el coste adicional no se justifica
Cuando la latencia de indexación es un factor crítico

Coste real

Con Haiku y prompt caching activado, el coste de contextualizar 1000 chunks de documentos medianos es aproximadamente 0.10-0.30 USD. Para la mayoría de bases de conocimiento empresariales, es una inversión que se amortiza rápidamente con la mejora en calidad del retrieval.

El coste de no aplicarlo es respuestas incorrectas o incompletas del sistema RAG — que tiene un coste mucho mayor en términos de confianza del usuario y correcciones manuales.