Как проверить метаданные источника перед передачей фрагмента в RAG

Шаблон входа для переноса примера на свою коллекцию: для каждого вопроса заведите поля id, question, expected_doc_ids, retrieved_doc_ids и, где требуется, index_version. Согласуйте с предметным владельцем, что именно считается релевантным, доступным и актуальным источником. Это рабочая схема сбора данных, а не универсальный формат API. В таблице ревью отдельно отметьте спорные случаи, которые нельзя разрешить одной лишь строковой операцией.

Пошаговая проверка

1. Создайте файл scripts/check_retrieval.py; скопируйте Python-шаблон целиком. Использованные названия библиотечных функций сверены с официальными страницами в конце статьи.
2. Запустите python scripts/check_retrieval.py локально. Сопоставьте консольный вывод с ожидаемым результатом в описании входа; демонстрация обязана проходить без внешнего API и ключей.
3. Сначала перечислите поля своего контракта и подтвердите у владельца базы, откуда допустимы ссылки. Запустите синтетический тест, после чего удалите title у D-1: он должен дать missing_title; восстановите исходный пример. В рабочем конвейере фильтруйте или карантинируйте ошибочный фрагмент до передачи текста модели. Сохраняйте source_id и код ошибки для редактора, а не полный текст. Для ссылок, ведущих к внешним ресурсам, отдельно проверяйте перенаправления и разрешённый доступ: urlsplit разбирает URL, но не делает его доверенным.
4. Для регрессии положите тот же файл в репозиторий и добавьте workflow из второго блока в .github/workflows/rag-retrieval.yml. Проверка запускается на pull_request с разрешением contents: read; не передавайте в неё настоящие секреты и закрытые документы.
5. Откройте job retrieval-check в Actions на конкретном коммите. Сравните исходные ID и обнаруженные нарушения с локальным прогоном. При расхождении проверьте версию фикстур и скрипта, а не меняйте эталон до выяснения причины.

# scripts/check_retrieval.py
from urllib.parse import urlsplit

rows = [
    {"source_id":"D-1","title":"Правила возврата",
     "url":"https://docs.example.org/policy","text":"Возврат оформляют по заявлению."},
    {"source_id":"D-2","title":"Копия правил",
     "url":"https://outside.example.net/copy","text":"Другой текст."},
]
def check(row):
    for key in ("source_id","title","url","text"):
        if not isinstance(row.get(key),str) or not row[key].strip():
            return "missing_" + key
    parts = urlsplit(row["url"])
    if parts.scheme != "https" or parts.hostname != "docs.example.org":
        return "unapproved_origin"
    if parts.username or parts.password or parts.fragment:
        return "unexpected_url_component"
    return "ok"
status = {row["source_id"]:check(row) for row in rows}
assert status == {"D-1":"ok","D-2":"unapproved_origin"}
print(status)

name: RAG retrieval contract
on:
  pull_request:
permissions:
  contents: read
jobs:
  retrieval-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: python scripts/check_retrieval.py

Реалистичный пример результата

Вход: Два фрагмента: D-1 с адресом https://docs.example.org/policy и D-2 с адресом https://outside.example.net/copy. Ожидается допуск только D-1 и указание причины отказа D-2. После запуска ожидается исход, явно проверяемый инструкциями assert в коде. Не публикуйте вымышленное значение как измеренную характеристику вашей поисковой системы. Для рабочего отчёта приложите версию индекса, выбранные фильтры, размер размеченного набора, дату фиксации эталона и список ID провалившихся случаев. По каждому ID откройте первичный документ, прежде чем менять конфигурацию ранжирования: неправильно размеченный источник может выглядеть как технический дефект.

Типовые ошибки и ограничения

Проверка полей не гарантирует, что адрес действительно существует или документ актуален. Совпадение hostname не доказывает корректность конкретного пути. Если используется внутренний протокол или подписанная ссылка, нужен отдельный контракт и подтверждённый порядок её публикации, а не механическая замена HTTPS. При расширении теста сначала добавьте отрицательный случай: намеренно испортите один элемент фикстуры и убедитесь, что проверка обнаружила его. Затем верните исходный набор и проверьте положительный случай. Это важнее зелёного CI на данных, где ошибка случайно отсутствует. Не логируйте полный ответ модели, содержимое закрытых документов или персональные сведения только ради диагностики.

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

Чек-лист финальной проверки

• Задача теста и применимость понятны владельцу корпуса.
• Входные ID и эталон не взяты из ответа оцениваемой модели.
• Демо запускается локально и даёт ожидаемый результат.
• Преднамеренно неверный вход обнаруживается проверкой.
• Зафиксированы версия индекса, редакция документов и условия доступа.
• В логах CI нет приватных документов и секретов.
• Разделены ошибка поиска, ошибка эталона и ошибка генерации.
• После исправления проверены соседние пограничные случаи.