From 0a72d0d2428c4941463847b1c24c9bfa569bd36f Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Sun, 16 Aug 2026 09:10:36 +0300 Subject: [PATCH 1/2] docs: add relevance annotation guide --- backend/README.md | 5 +- backend/search/RELEVANCE_ANNOTATION.md | 106 +++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 backend/search/RELEVANCE_ANNOTATION.md diff --git a/backend/README.md b/backend/README.md index 5a4e5c9..850231f 100644 --- a/backend/README.md +++ b/backend/README.md @@ -171,8 +171,9 @@ Security plugin отключён только для локальной разр 25 кыргызских запросов. Для каждого запроса человек должен указать реальную формулировку и коды всех релевантных документов; пустая или неполная разметка должна быть отклонена при ручной проверке, а технически некорректная — самим -оценщиком. Рабочую копию следует хранить в игнорируемом каталоге `data/`, -пока набор не проверен и не разрешён к публикации. +оценщиком. Критерии выбора запросов, релевантности и двойной проверки описаны в +`search/RELEVANCE_ANNOTATION.md`. Рабочую копию следует хранить в игнорируемом +каталоге `data/`, пока набор не проверен и не разрешён к публикации. Baseline использует поля названия и текста соответствующего языка, оставляет в выдаче один результат на документ и вычисляет макро-средние Recall@10 и MRR@10: diff --git a/backend/search/RELEVANCE_ANNOTATION.md b/backend/search/RELEVANCE_ANNOTATION.md new file mode 100644 index 0000000..beb6a1b --- /dev/null +++ b/backend/search/RELEVANCE_ANNOTATION.md @@ -0,0 +1,106 @@ +# Инструкция по разметке relevance set v1 + +## Цель + +Набор проверяет, находит ли поиск нужные документы по реальным формулировкам +пользователей. Он не должен подгоняться под текущую выдачу: сначала фиксируются +запросы и релевантные документы, затем считается baseline и меняется +ранжирование. + +## Подготовка + +Создайте игнорируемую Git рабочую копию: + +```bash +mkdir -p data/search +cp backend/search/relevance-set-v1.template.json data/search/relevance-set-v1.json +``` + +Сохраните идентификаторы `ru-01`–`ru-25` и `ky-01`–`ky-25`. Заполняйте +`query` и `relevant_document_codes`; остальные поля и структуру JSON не меняйте. + +## Выбор запросов + +- Используйте 25 русских и 25 кыргызских запросов, реально заданных или + сформулированных носителем языка для практической юридической задачи. +- Не переводите русский набор дословно на кыргызский: оба набора должны + отражать естественные формулировки своего языка. +- Записывайте исходную формулировку без улучшения под поисковик. Допустимы + разговорные слова, распространённые сокращения и опечатки. +- Не используйте персональные данные, закрытые материалы и сведения, которых + нет в публичном корпусе Минюста. +- Не включайте запрос, если нельзя установить хотя бы один релевантный документ. +- Не повторяйте один информационный запрос в нескольких близких формулировках. + +Проверьте разнообразие набора: названия и номера актов, вопросы по жизненной +или рабочей ситуации, короткие тематические запросы, органы принятия, статусы и +даты. Это ориентир, а не квота: реальные запросы важнее искусственного баланса. + +## Критерий релевантности + +Документ релевантен, если его текст или реквизиты непосредственно отвечают +информационной потребности запроса. Добавляйте все такие документы, а не только +первый результат. + +Не отмечайте документ релевантным только потому, что он: + +- содержит отдельные слова запроса; +- упоминает нужный акт без ответа на запрос; +- относится к близкой теме; +- является утратившей силу редакцией, когда запрос явно требует действующую + норму, либо наоборот. + +Если запрос допускает несколько самостоятельных правильных документов, +добавьте коды каждого из них. Код берите из поля `document_code`, а не из ID +фрагмента или редакции. + +## Разметка одного запроса + +1. До просмотра выдачи зафиксируйте информационную потребность и формулировку + `query`. +2. Найдите кандидатов в локальном OpenSearch и в официальной ЦБД Минюста. + Проверьте исходный запрос, его короткий вариант и вариант с юридическим + термином или известным номером акта. +3. Просмотрите не только заголовки, но и текст, статус, дату и редакцию каждого + кандидата. +4. Запишите уникальные `document_code` всех документов, удовлетворяющих + критерию релевантности. +5. Повторите поиск по ключевым терминам найденных документов, чтобы обнаружить + пропущенные альтернативные акты. + +Пример структуры (код условный): + +```json +{ + "id": "ru-01", + "language": "ru", + "query": "как зарегистрировать общественное объединение", + "relevant_document_codes": ["12345"] +} +``` + +## Проверка качества + +Второй человек должен проверить формулировку, язык и полный список релевантных +документов для каждого запроса. Спорные случаи обсуждаются до единого решения; +результат голосования или непроверенную разметку в baseline не включайте. + +Перед запуском убедитесь, что: + +- заполнены ровно 50 записей: 25 `ru` и 25 `ky`; +- все запросы непустые и различаются по информационной потребности; +- у каждой записи есть хотя бы один уникальный `document_code`; +- язык запроса совпадает с `language`; +- JSON не содержит комментариев и дополнительных полей. + +Оценщик дополнительно проверит структуру файла. После ручной проверки +зафиксируйте копию набора и не меняйте её при настройке поиска: + +```bash +PYTHONPATH=backend python3 -m search.evaluate_relevance \ + data/search/relevance-set-v1.json \ + > data/search/baseline-v1.json +``` + +Разбирайте запросы с низкими Recall@10 и MRR@10 по отдельности. Меняйте веса, +анализаторы или словари только после сохранения исходного baseline. From e6c4848a7f1d99307fe38db4760c6bc1689a2d83 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Sun, 16 Aug 2026 09:13:05 +0300 Subject: [PATCH 2/2] docs: update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe0e06b..227afd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # История изменений +## Не выпущено + +- Добавлена инструкция по подготовке и независимой проверке relevance set. + ## 0.5.0 — 2026-08-15 - Добавлена воспроизводимая оценка качества поиска по Recall@10 и MRR@10.