El RAG completo

Todo lo anterior era material. Esto es la aplicación, y cabe en una línea:

texto → embedding → recuperar de Supabase → montar el prompt → Claude → salida

Las dos mitades ya existen y ya están medidas: el corpus de la etapa 11 y la recuperación de la etapa 12. Lo que falta son unas sesenta líneas que las unan. Y en esas sesenta líneas hay una idea que no es obvia.

Dos fuentes de estilo, y no hacen lo mismo

Al prompt van dos cosas distintas, y confundirlas es el error natural aquí:

La pregunta es por qué hace falta el núcleo si ya hay recuperación. La respuesta salió medida del experimento de ejes: la recuperación no siempre puede ayudar. El corpus va de ciclismo y de su vida; una petición como «la cena estaba buenísima» no tiene vecinos temáticos ahí dentro, así que la búsqueda devuelve lo menos irrelevante que encuentra, que no es lo mismo que devolver algo útil.

Sin núcleo, esas peticiones llegan a un modelo sin un solo ejemplo delante. Y lo que sale entonces es un español genérico correcto que no reconocería nadie: el registro por defecto de cualquier modelo, no el suyo.

Cómo se elige el núcleo, incluido el primer intento fallido

Cincuenta frases de tres mil quinientas. La primera versión las puntuaba por número de recursos estilísticos: cuantos más lleve una frase, mejor.

Salió mal, y de tres maneras a la vez:

• Frases de treinta palabras de media. Un relato largo roza cuatro recursos de pasada y gana a una línea corta que es un ejemplo limpio de uno solo.
• Casi duplicados: la misma frase con distinto arranque, porque las ventanas solapadas de la etapa 11 dejan una versión corta y otra más larga que la contiene.
• Solo 9 refranes, que son justo el recurso más raro y más reconocible.

Cincuenta frases de treinta palabras son mil quinientas palabras de narración. El modelo no imita el estilo: imita el divagar.

El arreglo es puntuar estilo por palabra en vez de por frase:

# Proverbs are the rarest device and the most characteristic — the thing a fan
# recognises. Weight them so the core does not fill up with tics, which are
# both commoner and easier for a model to pick up unaided.
DEVICE_WEIGHT = {"proverb": 4, "blunder": 3, "metaphor": 2, "digression": 2, "tic": 1}


def score(row):
    """Style per word, not style per phrase.

    Counting devices alone rewards a long ramble that brushes several of them
    in passing over a short line that is a clean example of one. What the core
    needs is density: the most style in the fewest tokens.
    """
    weight = sum(DEVICE_WEIGHT.get(d, 1) for d in row.get("devices", []))
    confidence = {"high": 2, "medium": 1, "low": 0}.get(row.get("confidence"), 0)
    words = max(len(row["text"].split()), 1)
    return (weight + confidence) / (words ** 0.5)

Dividir por la raíz del número de palabras es lo que convierte «cuántos recursos tiene» en «cuánta densidad tiene». Y hay un suelo por recurso al elegir, para que el núcleo no acabe siendo cincuenta muletillas: los tics son los más abundantes y los más fáciles de imitar sin ayuda, así que si mandan ellos el núcleo enseña un truco cincuenta veces.

Con eso, el núcleo pasó de treinta palabras de media a ocho, de 9 refranes a 23, y sin duplicados. Algunas de las que entraron:

Dónde va cada cosa, y por qué importa

El prompt se parte en dos bloques, y el sitio de cada cosa no es cuestión de orden sino de dinero.

def build_system(core):
    """System block: identical every call, so it is what gets cached."""
    examples = "\n".join(f"- {phrase}" for phrase in core)
    return [{
        "type": "text",
        "text": f"{STYLE}\n\nAsí hablas tú:\n\n{examples}",
        "cache_control": {"type": "ephemeral"},
    }]


def build_user(text, retrieved):
    """User block: changes every call, so it comes after the cache breakpoint."""
    if not retrieved:
        return f"Texto:\n\n{text}"
    lines = "\n".join(f"- {phrase}" for phrase, _ in retrieved)
    return (f"Cosas que has dicho sobre asuntos parecidos:\n\n{lines}\n\n"
            f"Texto:\n\n{text}")

La caché de prompt guarda un prefijo del prompt y cobra por leerlo una fracción de lo que cuesta mandarlo entero. La condición es que sea idéntico byte a byte: en cuanto una sola palabra cambia antes del punto de corte, la caché no sirve y se paga todo otra vez.

La descripción del estilo y las cincuenta frases del núcleo no cambian nunca. Van en system, que es donde está el punto de corte. Las doce frases recuperadas y el texto del usuario cambian en cada petición, así que tienen que ir después.

Una salida de verdad

Entrada:

python -m perico.generate.translate "Hoy hace un frío que pela y no me apetece nada salir de casa."

Salida:

Merece la pena mirar qué ha hecho ahí, porque no es una sola cosa:

• Un refrán deformado que se ha inventado él: «no hay maillot que valga», sobre el molde de «no hay tu tía que valga». Ese es el recurso más característico y el más difícil de pedir.
• Un refrán real usado bien: «el que avisa no es traidor», colocado donde encaja.
• La metáfora ciclista llegando sola: «para sufrir frío ya sufrí yo bastante en los puertos». El texto de entrada no mencionaba bicicletas.

Y ninguna de las frases del núcleo aparece copiada. Eso es lo que se pedía: que sirvan de ejemplo, no de catálogo.

Epílogo: el núcleo fijo hacía que la app se repitiera

Esta etapa fijó dos cosas que parecían inofensivas: un núcleo de 50 frases, el mismo en todas las llamadas, y las 12 frases más parecidas, que para un texto dado son siempre las mismas. Semanas después, usando la app de verdad, el dueño del proyecto dio con la consecuencia:

Se midió sobre las 288 traducciones que ya estaban guardadas del barrido de la etapa 15, así que no costó nada:

Y la prueba de que la culpa era del núcleo y no de la recuperación: en la configuración sin núcleo del barrido, «tela marinera» aparece en el 0 %.

El arreglo: sortear en vez de fijar

El corpus tenía 1.103 frases que pasan todos los filtros de calidad (entre 4 y 18 palabras, sin restos de transcripción, con recurso identificado y confianza alta o media). Se estaban usando 50.

Dos cambios, uno en cada mitad del prompt:

1. Los ejemplos se sortean en cada petición. 25 frases de las 1.103, con el reparto equilibrado entre los cinco recursos: si se sortease a lo bruto, saldrían casi solo metáforas y muletillas, que son las más numerosas, y los refranes deformados —el recurso más raro y el que un aficionado reconoce— desaparecerían.
2. La recuperación deja de ser «las 12 más parecidas». Ahora busca las 30 más parecidas y sortea 12 de ellas, con probabilidad proporcional a la similitud elevada a ocho. Entre una frase de 0,70 y una de 0,45, la primera tiene unas 35 veces más opciones de salir: se conserva la relevancia y cambian las caras. Esto no cuesta un céntimo más, porque al prompt siguen yendo 12.

Comprobado en vivo con el mismo texto tres veces: 0 ejemplos repetidos de 25 y 3 frases recuperadas repetidas de 12.

Lo que consiguió el sorteo, medido

Se escribió una prueba nueva, perico.evals.variety, porque ninguna de las que había miraba esto: cuarenta traducciones, cuánto se repite la expresión más frecuente, cuánto se parecen dos respuestas entre sí y cuántas veces asoman las coletillas que el dueño tenía atragantadas.

Y lo que importa tanto como eso: la recuperación sigue llegando a la salida. Los dos pases de solapamiento dieron +16,3 y +15,9 puntos sobre el azar, ganando en 16 y 15 de 24 consultas. Sortear no rompió lo que costó semanas construir.

Dos preguntas del dueño, contestadas con números

Con el sorteo funcionando aparecieron dos preguntas razonables: si 12 de las 30 más parecidas se queda corto, y por qué 25 ejemplos y no 50.

Las tres son la misma cifra. Ampliar la banda de candidatas de 30 a 100 no da más variedad (y tampoco quita relevancia: +15,3 puntos de solapamiento, igual que con 30). Doblar los ejemplos de 25 a 50 tampoco, y en cambio dobla lo que se paga por ellos, porque desde que se sortean van fuera de la caché.

Así que se quedan los valores que ya había, pero ahora por una razón medida y no por costumbre: 12 de 30, y 25 ejemplos. Es la misma lección de la etapa 15 con el RETRIEVE_N, aprendida antes de tropezar: cuando dos opciones son indistinguibles, gana la barata.

Recuperar la caché: el bloque fijo se quedaba 178 tokens corto

Sortear los ejemplos había roto la caché, y la factura subió de 0,18 a 0,50 céntimos por traducción. Antes de rediseñar nada, dos comprobaciones.

La primera, contar. El contador de tokens de la API es gratis, y dio una sorpresa:

La segunda, verificar el umbral en la documentación en vez de fiarse de la memoria: Sonnet 5 no cachea nada por debajo de 1.024 tokens, y —esto es lo importante— cuando el bloque se queda corto no cachea y no devuelve ningún error. Llevábamos semanas mandando un cache_control que no hacía absolutamente nada.

O sea que el bloque fijo se quedaba 178 tokens corto. No hacía falta rediseñar el sorteo: hacía falta que el bloque fijo tuviera algo más que decir.

Y había algo que decir, precisamente por el cambio anterior. Los ejemplos ahora llegan agrupados por recurso, pero el prompt nunca explicaba qué es cada recurso. Añadir esa definición —qué es un refrán deformado, qué es un despiste, cuál usa más y cuál menos— es contenido útil que además es idéntico en cada llamada. El bloque pasó a 1.141 tokens y la caché arrancó:

Las coletillas del prompt estaban inventadas

Con la variedad arreglada, el dueño del proyecto hizo una pregunta incómoda: si hay 3.144 frases suyas en la base de datos, ¿por qué las coletillas del prompt las escribió alguien a mano?

Porque nadie las comprobó. Esta línea llevaba en el prompt desde el primer día:

- Sueltas exclamaciones y coletillas: «¿eh?», «ostras», «madre mía», «fíjate».

Contarlas en sus propias frases cuesta un minuto y no vale un céntimo. Una muletilla vive al principio de la frase o tras una coma, así que se cuentan ahí y no sueltas por el medio:

Tres de las cuatro coletillas que pedía el prompt son de las que menos usa, y faltaban las tres que más. Y hay una consecuencia medida: en las pruebas de variedad, «madre mía» aparecía en el 22-28 % de las traducciones. Él la dice en el 0,9 % de sus frases. La estábamos multiplicando por veinticinco, y solo porque alguien la escribió en una lista.

Las etiquetas que la base de datos tenía y el prompt tiraba

La segunda parte de la misma pregunta. Cada frase del corpus lleva desde la etapa 7 su recurso etiquetado —refrán, metáfora, despiste, muletilla, digresión— y esas etiquetas solo se usaban para equilibrar el sorteo. Al modelo le llegaban los 25 ejemplos en una lista plana, sin decirle qué ilustraba cada uno.

Ahora llegan agrupados bajo su etiqueta:

Así hablas tú:

Refranes y dichos, deformados o aplicados donde no tocan:
- Hay alguien siempre que guarda una bala.
- Todo lo que supere el 20% es mejor bajarse de la bici.

Muletillas:
- Yo me admiro, ¿eh?

Cuesta cero tokens de más y aprovecha un trabajo que ya estaba hecho y guardado. Una frase etiquetada con dos recursos se muestra bajo el más raro: si algo es refrán y metáfora a la vez, se enseña como refrán, que es lo que un aficionado reconoce y lo que menos abunda en el corpus (330 refranes frente a 1.591 metáforas).

Las dos cosas juntas, medidas con las cuatro pruebas:

La variedad es la mejor cifra de todo el proyecto. Dos traducciones cualesquiera comparten ya solo el 1,1 % de su vocabulario, y las coletillas que el dueño tenía atragantadas han desaparecido. La que más se repite ahora es «pues nada, oye», que sí es suya: es la primera vez que lo que se repite es lo que él repite.

La fidelidad se queda igual (68 % frente a 71 %, dentro del ruido) y la longitud también.

Traer doce frases siempre, valgan lo que valgan

La recuperación devolvía las doce más parecidas, pasara lo que pasara. El dueño del proyecto lo puso en duda con un ejemplo que lo desmonta:

Y tenía otra corrección de fondo, más importante: la premisa del proyecto no es que la recuperación se use, sino que el traductor funcione. Un corpus de verdad tenía que mejorar el resultado frente a cuatro ejemplos inventados, y eso no obliga a que aporte algo en cada frase.

Se midió el parecido de las doce primeras para tres tipos de texto:

Para la estantería de IKEA, la frase «más parecida» que devolvía el corpus era «No, ahora, ¿cómo la recupero yo? Ya me había habituado.» Ruido, presentado al modelo bajo una etiqueta que afirmaba: «cosas que has dicho sobre asuntos parecidos».

El arreglo tiene tres partes. Se descartan las frases por debajo del suelo, quedándose las que pasen aunque sean cero. No se rellena el hueco con las siguientes de la lista, que son peores por definición. Y cuando pasan pocas, se compensa con más ejemplos sorteados: enseñan cómo habla, que sirve hable de lo que hable, mientras que una frase que encajó al 0,3 no sirve para nada.

Medido con el umbral puesto, contra la misma configuración sin él:

El umbral no cuesta nada y limpia bastante. La fidelidad se queda igual, la repetición baja a su mejor marca y el solapamiento incluso sube un poco, que era lo esperable: al dejar de mandar frases que no venían a cuento, lo que llega al modelo se parece más a lo que acaba usando.

La única cifra que baja es el vocabulario, de 241 palabras distintas a 215. Tiene sentido: en las peticiones donde la recuperación no aporta nada, el modelo se apoya más en los ejemplos, y los ejemplos son 1.103 frases mientras que el corpus entero son 3.144. Es el precio de no decir tonterías cuando no hay nada que decir, y parece barato.

Y hay un ahorro que no sale en la tabla: en esas peticiones se dejan de enviar 241 tokens de frases inútiles.

Lo que se eligió, y qué fijó cada cosa

Lo que se lleva uno de esta etapa

1. Separa el estilo del contenido. El núcleo enseña cómo habla y siempre está; la recuperación aporta de qué hablar y sólo a veces puede.
2. Cuando la recuperación no tenga nada que ofrecer, que haya un suelo. Si el corpus no cubre lo que pide el usuario, sin núcleo el modelo se queda sin nada delante.
3. Puntúa por densidad, no por total. Contar recursos premia al que divaga; dividir por longitud premia al que es un buen ejemplo.
4. Lo fijo antes del corte de caché, lo variable después. Equivocarse aquí no produce ningún error: produce una factura.
5. Que funcione no es que sirva. Guarda la línea base desde el principio, porque sin ella la mejora no se puede medir.