Groundlens: un corrector para respuestas RAG

groundlens.dev

Cómo funciona · Instalación · Inicio rápido · Servidor MCP · Limitaciones · Reproducibilidad

Groundlens es un corrector de lo que escribe tu modelo. Marca las palabras que tus fuentes no respaldan — y te muestra qué debería haber dicho cada una. Comprueba la fundamentación y la fidelidad de las respuestas RAG frente a sus fuentes recuperadas, la tarea para la que la gente recurre a la detección de alucinaciones, la verificación de citas o la evaluación de RAG — y se diferencia en que devuelve marcas y evidencias para un revisor, no un veredicto o una puntuación a la que aplicar un umbral.

QUESTION    What is the invoice total?
SOURCE      ...the total amount due is 10,000 dollars, payable within 30 days...
ANSWER      The invoice total is 1,000 dollars, due in 30 days.

GROUNDLENS  1,000   nothing supports this.   Closest in invoice.pdf#p1: '10,000'

Nunca te dice que la respuesta es incorrecta. Te dice qué palabra debes mirar y qué documento debes abrir. Treinta segundos de atención humana en lugar de cinco minutos.

Cómo funciona

Groundlens aborda la comparación de palabras y números de dos maneras diferentes:

Groundlens proporciona la puntuación más baja como resultado, no el promedio. Toda métrica de similitud por tokens agrega mediante la media, y la media es donde mueren los errores de un solo token.

Un ejemplo práctico: diez no es cien

Un documento recuperado dice que el total adeudado es de 10,000 dólares. La respuesta dice 1,000 dólares. Un humano lo detecta al instante, sin título en finanzas.

La similitud por incrustaciones no lo detecta. El coseno entre la respuesta correcta y la incorrecta es de aproximadamente 0.99 — el error se disuelve en el vector como una gota de tinta se disuelve en un estanque. Un juez LLM tampoco: lee buscando plausibilidad, y "el total es de 1,000 dólares" es una frase perfectamente plausible sobre una factura. Un detector de tramos entrenado tampoco, porque las sustituciones de un solo dígito son raras en sus etiquetas de entrenamiento.

Los codificadores de oraciones organizan el texto por vocabulario, tema y estructura. Nunca por verdad. Un número incorrecto dentro de una oración correcta es, para un codificador que colapsa paráfrasis, casi una paráfrasis.

En esa factura, el respaldo medio de la respuesta incorrecta es 0.79 — que parece correcto. El ancla más débil es 0.00 — que es una marca en el margen.

Umbral operativo

Esta biblioteca no tiene umbral predeterminado. Un umbral es una propiedad de un despliegue, no de un método. Depende del codificador, de tus datos y de lo que te cueste un falso positivo en comparación con un falso negativo. Nada de eso se conoce aquí.

Hay una medición detrás de la regla. En la cuadrícula de puntos operativos que ejecutamos, la mejor tasa de falsos positivos con un 95 por ciento de recuperación fue de 0.65, para cada detector de una sola pasada que probamos, incluido este. En la recuperación que una revisión regulada realmente necesita, ningún corte fijo en esa cuadrícula es utilizable. Publicar uno significaría publicar un número que ya sabemos que no se sostiene.

Lo que groundlens proporciona es:

• Una puntuación de respaldo por palabra, donde un valor más bajo significa menos respaldo de las fuentes.

• Marcas con recibos: la palabra, su tramo, su respaldo y la oración de evidencia más cercana, para que un revisor pueda verificar cualquier llamada en segundos.

• Una función calibrate(), que ajusta un corte con tus propios datos etiquetados. Se niega a ejecutarse con menos de 200 ejemplos etiquetados, porque por debajo de eso el corte es ruido.

Si necesitas un umbral en tu canalización, ejecuta calibrate() con tus datos etiquetados:

from groundlens import calibrate

point = calibrate(labelled, target_recall=0.95)
print(point.threshold, point.fpr, point.fpr_ci95)   # read the fpr first

calibrate() necesita al menos 200 ejemplos etiquetados, porque por debajo de eso un umbral de 95% de recuperación se estima a partir de un puñado de puntos.

Related MCP server: Arkheia Hallucination Detection MCP

Instalación

pip install groundlens              # zero runtime dependencies. Not numpy, not torch
pip install "groundlens[encoder]"   # + the reference sentence encoder
pip install "groundlens[encoder,mcp]"   # + the MCP server, for Claude Desktop and friends

La instalación principal no incorpora ningún paquete, y un trabajo de CI hace fallar la compilación si eso cambia alguna vez. La versión anterior instalaba aproximadamente dos gigabytes de pila de aprendizaje profundo antes de que hubieras hecho nada.

Inicio rápido

from groundlens import proofread, SentenceTransformerEncoder

answer = "The invoice total is 4.75% payable within 45 days."
sources = [("policy.pdf#p3", "The rate stated in the policy is 3.90% and the term is 30 days.")]

marks = proofread(answer, sources, encoder=SentenceTransformerEncoder(), k=2)

print(marks.report())
#  4.75%   support 0.00    nearest in policy.pdf#p3: '3.90%'
#  45      support 0.00    nearest in policy.pdf#p3: '30'

Cada marca lleva su recibo:

for anchor in marks.weakest:
    anchor.text            # '4.75%'          the word in the answer
    anchor.span            # (21, 26)         where it sits
    anchor.kind            # 'numeral'        checked by arithmetic, not meaning
    anchor.support         # 0.0              absent from the sources
    anchor.evidence_id     # 'policy.pdf#p3'  which document to open
    anchor.evidence_text   # '3.90%'          what it should have matched

Desde la terminal:

groundlens read --answer answer.txt --context policy.pdf#p3=policy.txt

Servidor MCP

El mismo corrector, dentro de tu asistente. Groundlens incluye un servidor MCP, de modo que Claude Desktop, Claude Code, Cursor, VS Code o cualquier otro cliente MCP puede comprobar una respuesta frente a sus fuentes sin salir de la conversación. Se ejecuta localmente sobre stdio. Ningún texto sale a ningún sitio.

pip install "groundlens[encoder,mcp]"
python -m groundlens.mcp

Luego apunta tu cliente hacia él. En claude_desktop_config.json — o el equivalente mcp.json en Cursor y VS Code:

{
  "mcpServers": {
    "groundlens": {
      "command": "python",
      "args": ["-m", "groundlens.mcp"]
    }
  }
}

Usa la ruta absoluta al Python que tiene Groundlens instalado si no es el que está en tu PATH: /path/to/venv/bin/python.

La única herramienta

find_unsupported_words(answer, sources, k=4, locale="und")

Devuelve las anclas más débiles con sus recibos, el mínimo, el id del codificador y un sha256 del hallazgo:

{
  "weakest_anchors": [
    {
      "word": "4.75%",
      "support": 0.0,
      "checked_by": "arithmetic",
      "closest_in_sources": "3.90%",
      "source_id": "policy.pdf#p3",
      "notes": []
    }
  ],
  "floor": 0.0,
  "n_marked": 12,
  "encoder_id": "all-mpnet-base-v2@<revision-sha>",
  "sha256": "..."
}

Una sola herramienta, a propósito. El servidor anterior anunciaba tres, y así es como un producto se convierte en tres historias antes de que nadie lo haya instalado.

No hay veredicto ni umbral, aquí como en todas partes de esta biblioteca. Un support de 0.00 en un número significa que ese valor está ausente de las fuentes. En una palabra significa que no se encontró ningún ancla léxica, lo cual es normal en una paráfrasis fiel. El servidor informa de las marcas; el lector decide.

El codificador se carga en la primera llamada, no al inicio, y el modelo se descarga una vez (aproximadamente 420 MB) la primera vez que se utiliza.

Limitaciones

• No puede verificar valores calculados — "los ingresos se triplicaron" frente a una fuente que dice "los ingresos pasaron de 5M a 15M".

• El canal de palabras comprueba si una palabra está respaldada por las fuentes. No comprueba que esté vinculada a lo correcto. Si una respuesta dice "pagadero en 30 días" sobre la factura A y los 30 días pertenecen a la factura B en otro lugar del mismo contexto, la palabra está respaldada y no aparece ninguna marca.

• No puede comprobar el razonamiento. Eso corresponde a los modelos de implicación.

• Hereda tu recuperación. Si el pasaje es incorrecto, también lo es la fundamentación de la respuesta.

• La segmentación asume escrituras separadas por espacios, y advierte en lugar de fingir cuando el texto es mayoritariamente CJK o tailandés.

Reproducibilidad

• El canal de numerales es exacto. Comparación decimal, contexto aritmético fijo, configuración regional desde un argumento y nunca desde LC_ALL. Idéntico byte a byte en cualquier máquina — CI lo demuestra en diez combinaciones de SO × Python bajo PYTHONHASHSEED=random y una configuración regional turca.

• El canal léxico es un coseno float32 de una revisión de codificador fijada — no un nombre de modelo, porque una re-subida silenciosa cambiaría cada número que hayas publicado. Se reproduce hasta 1e-6 entre plataformas y el orden de las anclas más débiles es estable. No es bit-idéntico entre x86 y Apple Silicon, y no afirmamos que lo sea.

• marks.sha256 cubre la estructura y los respaldos de numerales exactamente, y redondea los respaldos léxicos a seis decimales. Reproducir el hash reproduce el hallazgo, no los últimos bits de la aritmética.

groundlens.dev · PyPI · Retractions · Contributing · Apache-2.0