diff --git a/backend/search/api.py b/backend/search/api.py index 43f025c..f401aaf 100644 --- a/backend/search/api.py +++ b/backend/search/api.py @@ -21,7 +21,7 @@ from search.reviews import ReviewSnapshots, ReviewStore API_VERSION = "v1" -SEARCH_ALGORITHM_VERSION = "search-7" +SEARCH_ALGORITHM_VERSION = "search-8" LANGUAGES = {"ru", "ky"} CODE = re.compile(r"^[0-9]+$") MAX_PAGE_SIZE = 100 @@ -125,9 +125,12 @@ class Api: def search_url(self, suffix: str) -> str: return f"{self.base_url}/{urllib.parse.quote(self.index, safe='')}/{suffix}" - def query_opensearch(self, body: dict) -> dict: + def query_opensearch(self, body: dict, *, search_type: str | None = None) -> dict: try: - return request_json(self.search_url("_search"), "POST", json.dumps(body, ensure_ascii=False).encode(), "application/json") + url = self.search_url("_search") + if search_type is not None: + url = f"{url}?{urllib.parse.urlencode({'search_type': search_type})}" + return request_json(url, "POST", json.dumps(body, ensure_ascii=False).encode(), "application/json") except RuntimeError as error: raise ApiError(502, "search backend is unavailable") from error @@ -177,7 +180,8 @@ class Api: if sort == "date": body["sort"].append({"date_adopted": "desc"}) body["sort"].append({"_score": "desc"}) - response = self.query_opensearch(body) + search_type = "dfs_query_then_fetch" if "," in self.index else None + response = self.query_opensearch(body, search_type=search_type) try: hits = response["hits"]["hits"] except (KeyError, TypeError) as error: diff --git a/backend/test_search_api.py b/backend/test_search_api.py index ddc366f..44bad5c 100644 --- a/backend/test_search_api.py +++ b/backend/test_search_api.py @@ -3,6 +3,7 @@ import contextlib import io import tempfile import unittest +import urllib.parse from pathlib import Path from unittest.mock import Mock, patch @@ -190,6 +191,44 @@ class SearchApiTest(unittest.TestCase): self.assertIn("legal_force_code", body["aggs"]["legal_forces"]["terms"]["field"]) self.assertEqual(body["query"], {"term": {"is_current_edition": True}}) + def test_global_dfs_is_only_sent_for_explicit_multi_index_searches(self): + with tempfile.TemporaryDirectory() as temporary: + multi = Api("http://opensearch:9200", "base-v2,supplement-v1", Path(temporary), review_secret=b"test-secret") + alias = Api("http://opensearch:9200", "current", Path(temporary), review_secret=b"test-secret") + single = Api("http://opensearch:9200", "single-v2", Path(temporary), review_secret=b"test-secret") + one_hit = {"hits": {"hits": [{"_index": "base-v2", "_source": {"document_code": "5", "document_name_ru": "Кодекс", "document_name_ky": "Кодекс"}}]}} + empty = {"hits": {"hits": []}} + alias_hit = {"hits": {"hits": [{"_index": "current-20261103", "_source": {"document_code": "7", "document_name_ru": "Закон"}}]}} + aggregations = {"aggregations": {name: {"buckets": []} for name in ("document_types", "statuses", "authorities", "legal_forces")}} + with patch("search.api.request_json", side_effect=[one_hit, empty, alias_hit, one_hit, aggregations]) as request: + multi_ru = multi.search({"q": ["test"], "language": ["ru"], "page_size": ["10"]}) + multi_ky_empty = multi.search({"q": ["test"], "language": ["ky"], "page_size": ["10"]}) + alias_ru = alias.search({"q": ["test"], "language": ["ru"], "page_size": ["10"]}) + single_ky = single.search({"q": ["test"], "language": ["ky"], "page_size": ["10"]}) + alias.filters({"language": ["ru"]}) + + calls = request.call_args_list + multi_ru_url = urllib.parse.urlsplit(calls[0].args[0]) + multi_ky_url = urllib.parse.urlsplit(calls[1].args[0]) + self.assertEqual(multi_ru_url.path, "/base-v2%2Csupplement-v1/_search") + self.assertEqual(urllib.parse.parse_qs(multi_ru_url.query), {"search_type": ["dfs_query_then_fetch"]}) + self.assertEqual(urllib.parse.parse_qs(multi_ky_url.query), {"search_type": ["dfs_query_then_fetch"]}) + self.assertEqual([item["code"] for item in multi_ru["results"]], ["5"]) + self.assertEqual(multi_ky_empty["results"], []) + self.assertEqual(multi.review_snapshots.verify(multi_ru["review_token"])["index_name"], "base-v2,supplement-v1") + self.assertEqual(multi.review_snapshots.verify(multi_ky_empty["review_token"])["index_name"], "base-v2,supplement-v1") + + for call in calls[2:]: + parsed = urllib.parse.urlsplit(call.args[0]) + self.assertEqual(parsed.query, "") + self.assertEqual(alias.review_snapshots.verify(alias_ru["review_token"])["index_name"], "current-20261103") + self.assertEqual(single.review_snapshots.verify(single_ky["review_token"])["index_name"], "base-v2") + multi_body = json.loads(calls[0].args[2]) + alias_body = json.loads(calls[2].args[2]) + self.assertEqual(multi_body, alias_body) + self.assertNotIn("search_type", multi_body) + self.assertEqual(json.loads(calls[1].args[2])["query"]["bool"]["filter"][0], {"term": {"language": "ky"}}) + if __name__ == "__main__": unittest.main() diff --git a/backend/test_search_api_opensearch.py b/backend/test_search_api_opensearch.py index 26b697d..e4ffa42 100644 --- a/backend/test_search_api_opensearch.py +++ b/backend/test_search_api_opensearch.py @@ -47,5 +47,19 @@ class SearchRankingOpenSearchTest(unittest.TestCase): self.assertEqual(result["results"][0]["code"], "5") +@unittest.skipUnless( + os.getenv("AKYLDASH_OPENSEARCH_URL") and "," in os.getenv("AKYLDASH_OPENSEARCH_INDEX", ""), + "set AKYLDASH_OPENSEARCH_URL and a comma-separated AKYLDASH_OPENSEARCH_INDEX for read-only multi-index search", +) +class SearchMultiIndexDfsOpenSearchTest(unittest.TestCase): + def test_global_statistics_mode_accepts_read_only_multi_index_search(self): + base_url = os.environ["AKYLDASH_OPENSEARCH_URL"].rstrip("/") + index = os.environ["AKYLDASH_OPENSEARCH_INDEX"] + api = Api(base_url, index, Path(".")) + result = api.search({"q": ["расторжение договора аренды"], "language": ["ru"], "page_size": ["10"]}) + self.assertIsInstance(result["results"], list) + self.assertEqual(api.review_snapshots.verify(result["review_token"])["index_name"], index) + + if __name__ == "__main__": unittest.main() diff --git a/backend/test_search_reviews.py b/backend/test_search_reviews.py index 0ffd9cc..83358f1 100644 --- a/backend/test_search_reviews.py +++ b/backend/test_search_reviews.py @@ -3,7 +3,7 @@ import unittest from pathlib import Path from unittest.mock import patch -from search.api import Api, ApiError +from search.api import Api, ApiError, SEARCH_ALGORITHM_VERSION class SearchReviewTest(unittest.TestCase): @@ -148,6 +148,27 @@ class SearchReviewTest(unittest.TestCase): self.assertNotIn('id="error"', page) self.assertIn("localStorage", page) + def test_new_search_snapshots_use_search_8_without_invalidating_search_7(self): + with tempfile.TemporaryDirectory() as temporary: + api = Api("http://opensearch:9200", "current", Path(temporary), Path(temporary) / "reviews.sqlite3", b"test-secret") + with patch("search.api.request_json", return_value={"hits": {"hits": [{"_index": "current-v2", "_source": {"document_code": "7", "document_name_ru": "Закон"}}]}}): + result = api.handle("GET", "/search?q=test&language=ru")[1] + current = api.review_snapshots.verify(result["review_token"]) + self.assertEqual(SEARCH_ALGORITHM_VERSION, "search-8") + self.assertEqual(current["algorithm_version"], "search-8") + + legacy_token = api.review_snapshots.create( + "legacy query", "ru", "current-v1", [{"rank": 1, "code": "7"}], "search-7" + ) + legacy_saved = api.handle("POST", "/search-reviews", { + "review_token": legacy_token, + "reviewer": "Юрист", + "results": [{"rank": 1, "code": "7", "rating": 3}], + }) + self.assertEqual(legacy_saved[0], 201) + exported = api.handle("GET", "/search-reviews/export")[1]["reviews"] + self.assertEqual(exported[-1]["algorithm_version"], "search-7") + if __name__ == "__main__": unittest.main() diff --git a/docs/product/search-relevance-findings-2026-11-03.md b/docs/product/search-relevance-findings-2026-11-03.md index 4dcccb8..da84cb4 100644 --- a/docs/product/search-relevance-findings-2026-11-03.md +++ b/docs/product/search-relevance-findings-2026-11-03.md @@ -3,13 +3,15 @@ ## Решения и границы Эта заметка фиксирует исходные измерения от 2 ноября, узкое исправление -терминологии и контракт для закрытия пробела корпуса. Она не утверждает, что -поиск уже стал юридически релевантнее: новая выдача должна быть проверена -отдельно на изолированном стенде и сравнена с исходными снимками. Полный набор -из 7 500 запросов повторно не собирался. +терминологии, условный multi-index scoring и контракт для закрытия пробела +корпуса. Выдачи и AI-аннотации не являются юридической оценкой. Целевой A/B +прогон и полный benchmark для итогового SHA описаны ниже; они не заменяют +экспертную оценку. Изменён backend `0.13.3` → `0.13.4`, frontend внутренней лаборатории -`0.3.3` → `0.3.4`, версия алгоритма `search-6` → `search-7`. +`0.3.3` → `0.3.4`, версия алгоритма `search-6` → `search-8`. `search-7` +относится к предшествующему составу ranking semantics; новые подписанные +снимки этого PR помечаются `search-8`. Сохранённые отзывы не переписываются. ## Исходный benchmark @@ -74,23 +76,88 @@ Backend теперь сохраняет исходную строку и доб сочетания «договор [арендная форма]» вариант «договор [та же форма] имущественного найма». В частности, `договора аренды` превращается в `договора имущественного найма`. Расширение не срабатывает для аренды квартиры -или земельного участка, поднайма, найма работника или лизинга. Точный запрос остаётся в строгой -лексической ветке, поэтому его профильный муниципальный акт не выкидывается из -поиска. Фактический top-k после изменения и влияние на соседние запросы требуют -отдельного A/B прогона; кодовый тест проверяет только варианты и DSL. +или земельного участка, поднайма, найма работника или лизинга. Точный запрос +остаётся в строгой лексической ветке, поэтому его профильный муниципальный акт +не исключается из поиска. В read-only пробе предыдущей версии `aa6fabe` для общего запроса код 5 поднялся с позиции за пределами top 10 на #5, но нерелевантный индивидуальный акт 135066 -оставался первым. Поэтому новая ревизия усиливает только `match_phrase` для -синтетического варианта с юридическим термином (`boost=12`); исходная фраза -оставляет исходный вес 3. Это проверяемая гипотеза, а не подтверждённая починка: -текущий commit нужно повторно прогнать на изолированном индексе. Критерий -приёмки: для общего запроса код 5 — top 1; для явной формулировки «имущественный -наём» он остаётся top 1; для запросов о жилом помещении, земельном участке, -поднайме, трудовых отношениях, международном арбитраже и кыргызских запросов -расширение отсутствует, а контрольная выдача не ухудшается относительно -baseline. Вес не должен подниматься автоматически, если этот критерий не -выполняется. +оставался первым. На SHA `726b1ee` isolated code-only прогон на исходном индексе +поставил код 5 первым для общего запроса; из 7 500 запросов изменились 19 +выдач, 7 481 совпала с baseline, число пустых осталось 6. Этот результат +проверяет `search-7` с `match_phrase` boost 12 для синтетической юридической +фразы, исходный phrase boost 3; он не описывает multi-index DFS. После +подключения трёх актов в отдельном supplement на `e653f3b` изменились 184 +выдачи против code-only варианта и 38 top-1; все шесть пустых выдач +сохранились. Разные наборы индексов нельзя считать одним benchmark. Для +итогового conditional-DFS SHA нужен отдельный прогон; контроль запросов об +аренде жилья/земли, поднайме, трудовых отношениях, международном праве и KY +формулировках остаётся обязательным. Rank-метрики не являются юридической +оценкой. + +## Условный scoring для явного multi-index scope + +При поиске по явно настроенному comma-separated scope (`base,supplement`) API +передаёт `search_type=dfs_query_then_fetch` как URL query parameter. Запросы по +одному настроенному индексу или alias сохраняют прежний `query_then_fetch`; +одиночные wildcard и alias не классифицируются по результату их expansion. +DFS включается только при запятой в настроенной строке scope. +Тело DSL, фильтры, query weights, сортировка, индексы и документы не меняются. +Параметр применяется только к `/search`; фильтры и остальные API вызовы +используют прежний режим. + +OpenSearch описывает `query_then_fetch` как scoring по локальным term/document +frequencies шардов, а DFS — по глобальным frequencies через шарды; DFS обычно +точнее, но может быть медленнее. `search_type` поддерживается именно как +параметр Search API URL ([OpenSearch Search API](https://docs.opensearch.org/latest/api-reference/search-apis/search/)). +Поэтому ограниченный режим использует глобальные statistics для явной +multi-index конфигурации и не меняет behavior одиночного поиска. + +На изолированном OpenSearch 3.7.0 оба режима сравнили на одинаковых DSL bytes и +одном неизменном наборе данных: 300 заранее выбранных запросов, максимум 300. +Порядок менялся в 93 случаях, top-1 — в 29; из 9 именованных риск-кейсов +изменились 3, все 5 выбранных positive controls сохранили top-1. Контроль с +индивидуальным актом 135066 сохранил этот акт первым. Результат по пяти +педагогическим/научным запросам с медицинским актом на первом месте и по +запросу о болезнях животных не исправлен; это межтематические lexical overlaps, +а не основание вводить глобальные веса или специальные document ID. +Сравнение ограничено выборкой и не является разметкой юридической правильности. +Медианы 22,955 мс для default и 16,115 мс для DFS не используются как оценка +скорости: default всегда исполнялся первым, возможен cache/order bias. + +Frozen experiment metadata is stored outside the repository in +`reports/search-benchmark-2026-11-02/dfs-probe-e653-summary.json`. The paired +response-capture artifact `dfs-probe-e653.jsonl` has SHA-256 +`4a9373ba5236c5c5a1d85139b6dbe67bcf01df02216f8b2f292e5c451e6432c8`. +Выборка содержала base index (42 624 501 fragments) и read-only supplement +(8 934 fragments); UUID/count guards прошли, основной индекс и сохранённые +отзывы во время эксперимента не менялись. В PR не включены сырые ответы, +персональные данные или выдачи документов. + +Кодовый тест проверяет URL, encoded multi-index path, RU/KY, пустую выдачу, +прежнее тело запроса и неизменность single alias/index и filters. Read-only +integration gate для root-owned runtime: + +```bash +AKYLDASH_OPENSEARCH_URL=http://127.0.0.1:8081 \ +AKYLDASH_OPENSEARCH_INDEX='akyldash-fragments-v2,akyldash-benchmark-supplement-20261103-r1' \ +PYTHONPATH=backend python3 -m unittest \ + backend.test_search_api_opensearch.SearchMultiIndexDfsOpenSearchTest.test_global_statistics_mode_accepts_read_only_multi_index_search -v +``` + +Тест выполняет только поиск и проверяет подписанный scope; он не создаёт и не +удаляет индексы. Root запускает его только при подтверждении, что указанный +supplement ещё существует и доступен на read-only runtime. Полный benchmark на +7 500 запросах нужен для итогового pinned SHA с тем же frozen baseline. +300-query эксперимент и предыдущие benchmarks не следует выдавать за +результат нового SHA. + +Откат к предшествующему приложению возвращает `query_then_fetch` для multi-index +поиска. Индекс, документы, saved reviews и старые подписанные токены при этом +не требуют изменений или миграции; новые отзывы, сохранённые до rollback, +остаются помечены `search-8`. Для supplement действует отдельный rollback +контракт ниже: отключение его подключения скрывает только добавленные редакции, +не удаляя подготовленные файлы и базовый индекс. ## Пустые выдачи в лаборатории