Groundlens: ein Korrekturleser für RAG-Antworten

groundlens.dev

So funktioniert es · Installation · Schnellstart · MCP-Server · Einschränkungen · Reproduzierbarkeit

Groundlens ist ein Korrekturleser für das, was Ihr Modell schreibt. Es markiert die Wörter, die Ihre Quellen nicht stützen – und zeigt Ihnen, was jedes einzelne hätte sagen sollen. Es prüft RAG-Antworten auf Grounding und Faithfulness gegenüber den abgerufenen Quellen – die Aufgabe, für die Menschen zu Halluzinationserkennung, Zitierprüfung oder RAG-Evaluierung greifen – und unterscheidet sich darin, dass es einer prüfenden Person Markierungen und Belege liefert statt eines Urteils oder eines Scores, den man mit einem Schwellwert abgleicht.

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'

Es sagt Ihnen nie, dass die Antwort falsch ist. Es sagt Ihnen, welches Wort Sie sich ansehen und welches Dokument Sie öffnen sollen. Dreißig Sekunden menschlicher Aufmerksamkeit statt fünf Minuten.

Funktionsweise

Groundlens vergleicht Wörter und Zahlen auf zwei verschiedene Arten:

Groundlens liefert den niedrigsten Wert als Ausgabe, nicht den Durchschnitt. Jede Token-Ähnlichkeitsmetrik aggregiert über den Mittelwert, und der Mittelwert ist der Ort, an dem Einzel-Token-Fehler sterben.

Ein praktisches Beispiel: zehn ist nicht hundert

Ein abgerufenes Dokument besagt, dass der Gesamtbetrag 10.000 Dollar beträgt. Die Antwort sagt 1.000 Dollar. Ein Mensch erkennt das sofort, ohne Finanzstudium.

Embedding-Ähnlichkeit erkennt es nicht. Der Kosinus zwischen der richtigen und der falschen Antwort liegt bei etwa 0,99 – der Fehler löst sich im Vektor auf, wie ein Tintentropfen in einem Becken. Ein LLM-Judge auch nicht: Er liest auf Plausibilität, und „der Gesamtbetrag beträgt 1.000 Dollar“ ist ein völlig plausibler Satz über eine Rechnung. Ein trainierter Span-Detektor auch nicht, weil Einzelziffern-Substitutionen in seinen Trainingslabels selten sind.

Satz-Encoder organisieren Text nach Vokabular, Thema und Struktur. Nie nach Wahrheit. Eine falsche Zahl in einem korrekten Satz ist für einen Paraphrase-kollabierenden Encoder beinahe eine Paraphrase.

Auf dieser Rechnung beträgt die mittlere Unterstützung der falschen Antwort 0,79 – was gut aussieht. Der schwächste Anker ist 0,00 – das ist eine Markierung am Rand.

Betrieblicher Schwellwert

Diese Bibliothek hat keinen Standard-Schwellwert. Ein Schwellwert ist eine Eigenschaft einer Bereitstellung, nicht einer Methode. Er hängt vom Encoder, von Ihren Daten und davon ab, was ein falsch Positives im Vergleich zu einem falsch Negativen kostet. Nichts davon ist hier bekannt.

Hinter der Regel steht eine Messung. Über das von uns durchlaufene Betriebspunkt-Raster lag die beste Falsch-Positiv-Rate bei 95 Prozent Recall bei 0,65, für jeden von uns getesteten Single-Pass-Detektor, einschließlich dieses. Bei dem Recall, den eine regulierte Prüfung tatsächlich braucht, ist kein fester Schnitt in diesem Raster brauchbar. Einen auszuliefern hieße, eine Zahl auszuliefern, von der wir bereits wissen, dass sie nicht hält.

Was groundlens bietet:

• Einen Unterstützungswert pro Wort, wobei niedriger bedeutet, dass die Quellen es weniger stützen.

• Markierungen mit Beleg: das Wort, seine Spanne, seine Unterstützung und der nächste Belegsatz, damit eine prüfende Person jede Markierung in Sekunden überprüfen kann.

• Eine Funktion calibrate(), die einen Schnitt auf Ihren eigenen gelabelten Daten anpasst. Sie weigert sich, mit weniger als 200 gelabelten Beispielen zu laufen, weil der Schnitt darunter Rauschen ist.

Wenn Sie einen Schwellwert in Ihrer Pipeline benötigen, führen Sie calibrate() auf Ihren gelabelten Daten aus:

from groundlens import calibrate

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

calibrate() benötigt mindestens 200 gelabelte Beispiele, weil darunter ein 95%-Recall-Schwellwert aus einer Handvoll Punkten geschätzt wird.

Related MCP server: Arkheia Hallucination Detection MCP

Installation

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

Die Kerninstallation zieht überhaupt kein Paket nach sich, und ein CI-Job lässt den Build fehlschlagen, falls sich das jemals ändert. Die vorherige Version installierte etwa zwei Gigabyte Deep-Learning-Stack, bevor man irgendetwas getan hatte.

Schnellstart

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'

Jede Markierung trägt ihren Beleg:

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

Aus der Shell:

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

MCP-Server

Derselbe Korrekturleser, in Ihrem Assistenten. Groundlens bringt einen MCP-Server mit, sodass Claude Desktop, Claude Code, Cursor, VS Code oder jeder andere MCP-Client eine Antwort gegen ihre Quellen prüfen kann, ohne das Gespräch zu verlassen. Er läuft lokal über stdio. Kein Text verlässt das System.

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

Dann richten Sie Ihren Client darauf aus. In claude_desktop_config.json – oder der entsprechenden mcp.json in Cursor und VS Code:

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

Verwenden Sie den absoluten Pfad zu dem Python, auf dem Groundlens installiert ist, falls es nicht das auf Ihrem PATH ist: /path/to/venv/bin/python.

Das eine Tool

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

Es gibt die schwächsten Anker mit ihren Belegen zurück, den Boden, die Encoder-ID und einen sha256 des Befunds:

{
  "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": "..."
}

Ein Tool, absichtlich. Der vorherige Server bewarb drei, und so wird aus einem Produkt drei Geschichten, bevor es jemand installiert hat.

Es gibt kein Urteil und keinen Schwellwert, hier wie überall sonst in dieser Bibliothek. Ein support von 0,00 bei einer Zahl bedeutet, dass dieser Wert in den Quellen fehlt. Bei einem Wort bedeutet es, dass kein lexikalischer Anker gefunden wurde, was in einer treuen Paraphrase normal ist. Der Server meldet die Markierungen; die Leserin entscheidet.

Der Encoder lädt beim ersten Aufruf, nicht beim Start, und das Modell wird einmal heruntergeladen (etwa 420 MB), wenn es zum ersten Mal verwendet wird.

Einschränkungen

• Es kann berechnete Werte nicht verifizieren – „der Umsatz hat sich verdreifacht“ gegen eine Quelle, die sagt „der Umsatz stieg von 5 Mio. auf 15 Mio.“.

• Der Wortkanal prüft, ob ein Wort von den Quellen unterstützt wird. Er prüft nicht, ob es am richtigen Ort hängt. Wenn eine Antwort „zahlbar in 30 Tagen“ über Rechnung A sagt und die 30 Tage woanders im selben Kontext zu Rechnung B gehören, ist das Wort unterstützt und es erscheint keine Markierung.

• Es kann keine Schlussfolgerungen prüfen. Das gehört zu Entailment-Modellen.

• Es erbt Ihr Retrieval. Wenn die Passage falsch ist, ist auch das Grounding der Antwort falsch.

• Die Segmentierung setzt Leerzeichen-getrennte Schriften voraus und warnt eher, als dass sie so tut, als ob der Text überwiegend CJK oder Thai wäre.

Reproduzierbarkeit

• Der Zahlenkanal ist exakt. Dezimalvergleich, fester Arithmetik-Kontext, Locale aus einem Argument und nie aus LC_ALL. Byte-für-Byte identisch auf jeder Maschine – CI beweist es auf zehn OS × Python-Kombinationen unter PYTHONHASHSEED=random und einer türkischen Locale.

• Der lexikalische Kanal ist ein float32-Kosinus aus einer festgepinnten Encoder-Revision – nicht einem Modellnamen, weil ein stilles Neu-Upload jede Zahl ändern würde, die Sie je veröffentlicht haben. Er reproduziert auf 1e-6 über Plattformen hinweg, und die Reihenfolge der schwächsten Anker ist stabil. Er ist nicht bit-identisch zwischen x86 und Apple Silicon, und wir behaupten das auch nicht.

• marks.sha256 deckt die Struktur und die Zahlenunterstützungen exakt ab und rundet lexikalische Unterstützungen auf sechs Dezimalstellen. Den Hash zu reproduzieren reproduziert den Befund, nicht die letzten Bits der Arithmetik.

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