Skip to main content
Glama

Groundlens: корректор ответов RAG

Groundlens

PyPI Python License Runtime dependencies groundlens MCP server

CI OpenSSF Best Practices OpenSSF Scorecard Determinism

groundlens.dev

Как это работает · Установка · Быстрый старт · MCP-сервер · Ограничения · Воспроизводимость

Groundlens — это корректор того, что пишет ваша модель. Он отмечает слова, которые не подтверждаются вашими источниками, и показывает, что каждое из них должно было сказать. Он проверяет ответы RAG на обоснованность и точность относительно извлечённых источников — ту задачу, для которой люди обращаются к обнаружению галлюцинаций, проверке цитат или оценке RAG, — и отличается тем, что возвращает пометки и доказательства для рецензента, а не вердикт или оценку для порога.

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'

Он никогда не говорит, что ответ неверен. Он говорит, на какое слово посмотреть и какой документ открыть. Тридцать секунд внимания человека вместо пяти минут.

Как это работает

How Groundlens checks words and numbers

Groundlens подходит к сравнению слов и чисел двумя разными способами:

Слова

Числа

Слова привязаны к смыслу. Поддержка слова — это наибольшее косинусное сходство, которое оно достигает с любым словом источников, с использованием замороженного готового энкодера — того же типа, который уже использует ваша система поиска.

Числа привязаны к арифметике. Числительное разбирается в значение с нормализованным форматированием — 10,000, 10000, $10,000, 10 000 и (при указанной локали) 10.000 — это одно число, — затем проверяется по каждому значению в источниках. Поддержка равна ровно 1.0 или ровно 0.0. Сходству не разрешается голосовать.

Groundlens выдаёт наименьшую оценку, а не среднюю. Каждая метрика сходства токенов агрегируется по среднему, и именно в среднем одиночные ошибки токенов умирают.

Практический пример: десять — это не сто

Извлечённый документ говорит, что общая сумма к оплате составляет 10 000 долларов. Ответ говорит 1 000 долларов. Человек замечает это мгновенно, без финансового образования.

Сходство эмбеддингов — нет. Косинус между правильным и неправильным ответом составляет около 0,99 — ошибка растворяется в векторе, как капля чернил в бассейне. Судья LLM тоже не замечает: он читает на правдоподобие, и «общая сумма составляет 1 000 долларов» — вполне правдоподобное предложение о счёте. Обученный детектор фрагментов тоже не замечает, потому что замены одной цифры редки в его обучающих метках.

Кодировщики предложений организуют текст по словарю, теме и структуре. Никогда по истине. Неправильное число внутри правильного предложения для энкодера, схлопывающего перефразирования, почти перефразирование.

В этом счёте средняя поддержка неправильного ответа составляет 0,79 — что выглядит нормально. Самое слабое якорное значение — 0,00 — это пометка на полях.

Эксплуатационный порог

В этой библиотеке нет порога по умолчанию. Порог — это свойство развёртывания, а не метода. Он зависит от энкодера, от ваших данных и от того, сколько вам стоит ложноположительный результат по сравнению с ложноотрицательным. Ничего из этого здесь неизвестно.

За правилом стоит измерение. По сетке рабочих точек, которую мы прогнали, лучшая частота ложноположительных результатов при 95% полноте составила 0,65 для каждого протестированного нами однопроходного детектора, включая этот. При полноте, которая действительно нужна регулируемой проверке, ни одно фиксированное отсечение в этой сетке не применимо. Выпустить его означало бы выпустить число, которое, как мы уже знаем, не выполняется.

Support scores and the weakest anchor

Что предоставляет groundlens:

  • Оценка поддержки для каждого слова, где меньшее значение означает меньшую поддержку источниками.

  • Пометки с подтверждениями: слово, его диапазон, его поддержка и ближайшее предложение-доказательство, чтобы рецензент мог проверить любой вызов за секунды.

  • Функция calibrate(), которая подбирает отсечение на ваших собственных размеченных данных. Она отказывается работать на менее чем 200 размеченных примерах, потому что ниже этого отсечение — это шум.

Если вам нужен порог в вашем конвейере, запустите calibrate() на ваших размеченных данных:

from groundlens import calibrate

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

calibrate() требует как минимум 200 размеченных примеров, потому что ниже этого порог 95% полноты оценивается по нескольким точкам.

Related MCP server: Sentry MCP

Установка

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

Основная установка не тянет ни одного пакета, и задание CI ломает сборку, если это когда-либо изменится. Предыдущая версия устанавливала примерно два гигабайта стека глубокого обучения, прежде чем вы что-либо сделали.

Быстрый старт

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'

Каждая пометка несёт своё подтверждение:

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

Из оболочки:

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

MCP-сервер

Тот же корректор внутри вашего ассистента. Groundlens поставляется с MCP-сервером, поэтому Claude Desktop, Claude Code, Cursor, VS Code или любой другой MCP-клиент может проверить ответ по его источникам, не покидая разговор. Он работает локально через stdio. Никакой текст никуда не отправляется.

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

Затем укажите вашему клиенту на него. В claude_desktop_config.json — или эквивалентном mcp.json в Cursor и VS Code:

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

Используйте абсолютный путь к Python, на котором установлен Groundlens, если это не тот, что в вашем PATH: /path/to/venv/bin/python.

Единственный инструмент

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

answer

вывод модели для проверки

sources

[{"id": "policy.pdf#p3", "text": "..."}]. Идентификатор возвращается в результатах, чтобы читатель знал, какой документ открыть

k

сколько самых слабых якорей вернуть

locale

как эти документы записывают числа. es читает 1.234 как 1234, en читает как 1.234, und сохраняет оба прочтения

Он возвращает самые слабые якоря с их подтверждениями, нижнюю границу, идентификатор энкодера и sha256 результата:

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

Один инструмент, намеренно. Предыдущий сервер рекламировал три, и именно так один продукт превращается в три истории, прежде чем кто-либо его установил.

Здесь нет вердикта и порога, как и везде в этой библиотеке. support 0.00 для числа означает, что это значение отсутствует в источниках. Для слова это означает, что лексический якорь не найден, что обычно для точного перефразирования. Сервер сообщает пометки; читатель решает.

Энкодер загружается при первом вызове, а не при запуске, и модель загружается один раз (около 420 МБ) при первом использовании.

Ограничения

  • Он не может проверить вычисленные значения — «выручка утроилась» против источника, говорящего «выручка выросла с 5M до 15M».

  • Канал слов проверяет, поддерживается ли слово источниками. Он не проверяет, привязано ли оно к правильному объекту. Если ответ говорит «оплата в течение 30 дней» о счёте A, а 30 дней относятся к счёту B в другом месте того же контекста, слово поддерживается, и пометка не появляется.

  • Он не может проверить рассуждения. Это относится к моделям энтайлмента.

  • Он наследует ваш поиск. Если фрагмент неверен, то и обоснованность ответа неверна.

  • Сегментация предполагает скрипты с разделителями-пробелами и предупреждает, а не притворяется, когда текст в основном на CJK или тайском.

Воспроизводимость

  • Числовой канал точен. Десятичное сравнение, фиксированный арифметический контекст, локаль из аргумента и никогда из LC_ALL. Побайтово идентичен на любой машине — CI доказывает это на десяти комбинациях ОС × Python под PYTHONHASHSEED=random и турецкой локалью.

  • Лексический канал — это косинус float32 от закреплённой ревизии энкодера — не имени модели, потому что тихая повторная загрузка изменила бы каждое число, которое вы когда-либо публиковали. Он воспроизводится до 1e-6 на разных платформах, и порядок самых слабых якорей стабилен. Он не побитово идентичен между x86 и Apple Silicon, и мы не утверждаем, что это так.

  • marks.sha256 покрывает структуру и числовые поддержки точно, а лексические поддержки округляет до шести десятичных знаков. Воспроизведение хэша воспроизводит результат, а не последние биты арифметики.

groundlens.dev · PyPI · Опровержения · Вклад · Apache-2.0

Available Tools

3 tools
verify_answerA

Check an answer against the passages it was written from, before you send it.

    Every figure must be in the passages or follow from figures that are; no model
    is used. Returns PASS, REVIEW or FAIL with the reasons, and the signed record.

    sources: (id, text) pairs, {"id","text","provenance"} dicts, or bare strings.
    policy: a built-in name (e.g. "eu_ai_act_high_risk_v1"), a path, or YAML.
    scope: what the request is about, e.g. {"entity": "UPS"}; a figure taken
    from a source whose provenance is another entity fails.
    risk_class: the request's risk class, when the policy defines them.
    Returns the decision (PASS/REVIEW/FAIL), the evidence, the regulatory
    mapping and the record with its content hash.
    

Inputs: answer (required), sources (required), scope, locale, +3 more. Returns: object

verify_recordsA

Verify a log of records offline: every hash, every link, every signature.

    records: the JSON Lines text of an answer-record or run-record log.
    Returns {"ok", "verified", "kind"}; fails if any record or link was altered.
    

Inputs: records (required). Returns: object

verify_runA

Verify an MCP execution trace under an execution policy and return the run record.

    trace: the MCP session as JSON-RPC messages (JSON Lines).
    policy: the execution policy, as YAML/JSON text or a path.
    Returns the gate (ALLOW/REVIEW/DENY), any breaches, and the signed run record.
    

Inputs: trace (required), policy (required), run_id (required), system (required), +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation4/5

    Each tool takes a clearly different input shape: a JSON-RPC session trace, answer passages, and a JSON Lines record log. There is mild overlap because verify_records can validate run records that verify_run also produces/validates, which could cause a brief hesitation, but the described inputs keep them separable.

    Naming Consistency5/5

    All three tools follow a strict verb_noun pattern (verify_run, verify_answer, verify_records), with the same verb used consistently for the same conceptual action.

    Tool Count4/5

    Three tools is on the lean side but each covers a distinct verification target (run trace, answer grounding, record log), so nothing feels redundant or padded.

    Completeness4/5

    The core verification lifecycle (verify runs, verify answers, verify logs offline) is covered, and records are produced by the verify calls themselves. A minor gap is that no tool enumerates available built-in policies (e.g. 'eu_ai_act_high_risk_v1'), though agents can work around this by passing policy text or a path.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers