| --- |
| language: |
| - ru |
| - en |
| license: apache-2.0 |
| base_model: DeepPavlov/rubert-base-cased |
| library_name: transformers |
| pipeline_tag: token-classification |
| tags: |
| - ner |
| - token-classification |
| - pii |
| - secret-detection |
| - credentials |
| - masking |
| - russian |
| - bert |
| --- |
| |
| # ner_rus_bert-secret_detection |
| |
| Дообученная голова `BertForTokenClassification` поверх `DeepPavlov/rubert-base-cased`, |
| которая размечает в русскоязычном тексте **учётные данные** (логины, пароли, |
| токены, ключи), **персональные данные** (ФИО, организации, локации) и **номера |
| договоров**. Основной сценарий, под который она обучалась - маскирование |
| пользовательских сообщений и фрагментов конфигов перед отправкой во внешнюю LLM. |
| |
| > **Модель — половина системы.** В проде она работает **в объединении с |
| > детерминированным regex-слоем**, и все опубликованные ниже цифры покрытия |
| > учётных данных относятся к объединению `NER ∪ regex`. Одна NER заметно слабее |
| > по recall — так и задумано: её задача добирать то, что не ловится регулярками |
| > (естественная формулировка, кириллица, контекст), не переусердствуя с ложными |
| > срабатываниями. Обе половины лежат в этом репозитории: `core/scrubber.py` + |
| > `gitleaks.toml` |
| > См. [Детерминированный слой](#детерминированный-слой). |
| |
| ## Метки |
| |
| 17 BIO-тегов, 8 типов сущностей: |
| |
| | Группа | Метки | |
| |---|---| |
| | Учётные данные | `LOGIN`, `PASSWORD`, `AUTH_TOKEN`, `SECRET_KEY` | |
| | ПДн | `PERSON`, `LOCATION`, `ORGANIZATION` | |
| | Прочее | `CONTRACT_NUMBER` | |
|
|
| Схема — `B-`/`I-`/`O`, полный список в `config.json` (`id2label`). |
|
|
| ## Быстрый старт |
|
|
| ```python |
| from transformers import pipeline |
| |
| ner = pipeline( |
| "token-classification", |
| model="fef2/ner_rus_bert-secret_detection", |
| aggregation_strategy="simple", |
| ) |
| |
| text = 'user = svc_billing, password = "Xt7#pQm2Zr", api_key: sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' |
| for e in ner(text): |
| print(f"{e['entity_group']:<12} {e['score']:.3f} {text[e['start']:e['end']]!r}") |
| ``` |
|
|
| ``` |
| LOGIN 0.936 'svc_billing' |
| PASSWORD 0.993 'Xt7#pQm2Zr' |
| SECRET_KEY 0.996 'sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' |
| ``` |
|
|
| Обратите внимание: режьте исходную строку по `start`/`end`, а **не** берите поле |
| `word` — pipeline отдаёт его склеенным из wordpiece, с лишними пробелами |
| (`'svc _ billing'`). |
|
|
| **У `pipeline()` три ограничения, из-за которых он годится только для проб.** |
| Он не режет длинный вход на окна — текст длиннее 512 wordpiece падает с |
| `RuntimeError: The size of tensor a (1218) must match the size of tensor b (512)`; |
| не нормализует юникод; и это **только NER**, без детерминированного слоя. Для |
| настоящей работы возьмите `predict.py` из этого репозитория. |
|
|
| ## Правильный путь: `predict.py` |
|
|
| `predict.py` — перенос инференс-логики развёрнутого сервиса целиком: |
| NFC-нормализация, нарезка на окна по 384 реальных wordpiece по границам |
| предложений, BIO-декод, детерминированный слой, смещения в символах, склейка |
| пересекающихся спанов. Нужны только `torch` и `transformers` — regex-половина |
| на чистом stdlib. |
|
|
| ```bash |
| python predict.py --text 'password = "Xt7#pQm2Zr"' # замаскированный текст |
| python predict.py --file документ.txt --spans # спаны построчно |
| cat лог.txt | python predict.py --json # спаны в JSON |
| cat лог.txt | python predict.py --json --no-rules # только NER, без regex |
| ``` |
|
|
| ```python |
| from predict import Detector |
| |
| det = Detector("fef2/ner_rus_bert-secret_detection", device="cpu") # cuda / mps |
| |
| text = ('Коллеги, доступ к стенду: user = svc_billing, password = "Xt7#pQm2Zr", ' |
| 'api_key: sk-live-4f9a2b7c1e6d8f3a0b5c9d2e. Ответственный — Петров Сергей ' |
| 'Иванович (ПАО «Сбербанк», Санкт-Петербург), договор № 77-АБ/2025-4412.') |
| |
| for s in det.spans(text): |
| print(f"{s.start:>4} {s.end:>4} {s.label:<16} {s.source:<5} {s.text!r}") |
| |
| print(det.mask(text)) |
| ``` |
|
|
| ``` |
| 33 44 LOGIN ner 'svc_billing' |
| 58 68 PASSWORD both 'Xt7#pQm2Zr' |
| 80 112 SECRET_KEY both 'sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' |
| 130 152 PERSON ner 'Петров Сергей Иванович' |
| 154 167 ORGANIZATION ner 'ПАО «Сбербанк' |
| 170 185 LOCATION ner 'Санкт-Петербург' |
| 198 213 CONTRACT_NUMBER ner '77-АБ/2025-4412' |
| ``` |
|
|
| `source` говорит, кто нашёл спан: `ner`, `regex` или `both` (нашли оба — |
| самый спокойный случай). У чисто regex-спанов `score` равен `None`: у |
| детерминированного правила нет вероятности, и подставлять туда единицу было бы |
| враньём. |
|
|
| Документ на 6800 символов режется на 4 окна и размечается целиком — граница окна |
| не теряет спаны, потому что нарезка идёт по концам предложений и абзацев. |
|
|
| ### Четыре контракта, которые легко нарушить |
|
|
| **Окно — 384 *реальных* wordpiece.** Модель обучалась на окнах такого размера, |
| и `plan_windows` закладывает 384 токена **без** учёта `[CLS]`/`[SEP]`, то есть |
| `max_length=386` при токенизации. Если считать по-хагингфейсовски — 384 вместе со |
| служебными, — в окно попадёт 382 реальных токена, и предсказания на длинных |
| текстах разойдутся: два лишних wordpiece меняют каждый контекстный эмбеддинг |
| последовательности. На эталонном сплите в этот зазор попадают 280 строк из 6312, |
| и 5 из них предсказываются иначе. |
|
|
| **Смещения — по NFC-нормализованному тексту.** `Detector.spans()` сам приводит |
| вход к NFC, и `start`/`end` — индексы кодовых точек **нормализованной** строки. |
| Для латиницы и обычной кириллицы это то же самое, но текст с составными символами |
| (диакритика, вставки из PDF) после нормализации меняет длину, и спаны «поедут». |
| Режьте по спанам нормализованную строку: |
|
|
| ```python |
| import unicodedata |
| normalized = unicodedata.normalize("NFC", text) # ровно то, что видела модель |
| fragment = normalized[span.start:span.end] |
| ``` |
|
|
| **Батчи, а не по одному.** Пропускная способность здесь берётся из батчей; |
| `Detector(batch_size=...)` задаёт размер микро-батча окон. На CPU замеренная |
| скорость NER-половины — около **9.5k токенов/с**; на GPU в FP16 (`fp16=True`, |
| включается автоматически при `device="cuda"`) она перестаёт быть узким местом |
| задолго до regex-слоя. |
|
|
| **Модель не решает, что делать со спаном.** `mask()` подставляет |
| `[REDACTED:LABEL]` — это пример, а не политика. Обратимое маскирование |
| (плейсхолдеры с обратной подстановкой), пороги по `score`, отдельная политика на |
| `PERSON` против `SECRET_KEY` — всё это ваш слой поверх спанов. |
|
|
| ## Детерминированный слой |
|
|
| Рядом с моделью по тому же тексту работает второй, полностью детерминированный |
| детектор — `core.scrubber.credential_sites`. Итоговый набор спанов есть |
| **объединение** двух источников с последующей склейкой. Он даёт постоянный, не |
| зависящий от чекпоинта пол по типовым форматам, а NER добирает то, что регуляркой |
| не описывается. Внутри — три детектора: |
|
|
| | Детектор | Что ищет | Метки | |
| |---|---|---| |
| | `kv` | `ключ = значение` с онтологией ключей (`password`, `пароль`, `api_key`, `токен`, `login`…) | `PASSWORD` `SECRET_KEY` `AUTH_TOKEN` `LOGIN` | |
| | `cli` | значения у известных флагов известных команд (`--password=…`, `curl -u user:pass`) | `PASSWORD` `AUTH_TOKEN` | |
| | `opaque` | непрозрачные высокоэнтропийные значения + правила gitleaks | `AUTH_TOKEN` `SECRET_KEY` `SECRET` | |
|
|
| Правила gitleaks отбираются по идентификатору (`…token…` → `AUTH_TOKEN`, |
| `…key…`/`…secret…` → `SECRET_KEY`), из 222 правил конфига до рантайма доходят |
| **168** — остальные отсеиваются фильтром по имени либо не компилируются под |
| `re` без предупреждений. `load_gitleaks_rules` возвращает вторым значением |
| именно счётчик отброшенных. |
|
|
| `cli` бьёт по таблице «команда → флаг» и отдаёт только само значение пароля или |
| токена; логин из `-u user:pass` в объединение не попадает, а голая строка |
| подключения (`postgres://user:pass@host`) не покрывается вовсе — это осознанная |
| граница релиза, см. [Ограничения](#ограничения). |
|
|
| Слой умеет отличать живое значение от инертного: `${DB_PASSWORD}`, |
| `os.environ["TOKEN"]`, `<your-key-here>`, `changeme` и уже проставленные маркеры |
| `[REDACTED:…]` он не трогает (`core._shim.is_inert_value`). Спан с меткой |
| `SECRET` — это опознанное непрозрачное значение, тип которого установить не |
| удалось; в модельный набор из 17 меток он не входит и приходит только отсюда. |
|
|
| Замеренная цена этой половины на тестовом сплите: 2891 срабатывание, из них 452 |
| не задевают ни одного gold-спана; вычёркивается 3.03 % всех символов, из которых |
| 0.37 % корпуса лежит вне gold-спанов. Слой чисто питоновский и держит GIL — |
| около 0.7 мс на текст (~460k токенов/с на ядро), так что в проде именно он, а не |
| GPU, упирается в потолок пропускной способности. |
|
|
| Отключается через `Detector(rules=None)` или `--no-rules` — но тогда цифры ниже |
| к вам не относятся. |
|
|
|
|
| ## Обучение |
|
|
| | | | |
| |---|---| |
| | Базовая модель | `DeepPavlov/rubert-base-cased` (vocab 119547, 12 слоёв, 768) | |
| | Шаги / batch / lr | 8000 · 32 · 3e-5, warmup 800, weight decay 0.1, grad clip 1.0, AMP | |
| | Окно | 384 wordpiece | |
| | Выбор чекпоинта | по `credential_any_f1` на валидации (максимизируется вклад NER в детекцию учётных данных: пол от регулярок постоянен) | |
| | Данные | синтетические семейства учётных данных в русскоязычном контексте (kv-pair в сообщениях, конфигах и коде) + replay-доля 0.35 на общий русский NER, чтобы не потерять ПДн | |
|
|
| ## Ограничения |
|
|
| * **CLI и DSN — вне зоны ответственности.** Строки подключения |
| (`postgres://user:pass@host`) и пароли в аргументах команд сознательно не входят |
| в целевую поверхность релиза и на ней не измерялись. Модель на них ведёт себя |
| неровно: `psql -U reporter -W 'Qw!7823ml' -h db.corp.ru` → спан `PASSWORD` |
| захватывает открывающую кавычку, а хвост имени хоста уезжает в `LOGIN`. |
| Детерминированный слой подстраховывает только известные флаги известных команд. |
| Целевая поверхность — **kv-pair**: `ключ = значение` в сообщениях, конфигах и |
| коде. |
| * **Границы спанов не всегда аккуратны.** Модель может отрезать закрывающую |
| кавычку (`'ПАО «Сбербанк'`) или разделить фразу на два спана. Для маскирования |
| это безопасно (спан всё равно вычёркивается), для извлечения сущностей — |
| учитывайте. |
| * **Не детектор «всех секретов».** Формат, не похожий ни на одно из обученных |
| семейств и не покрытый регуляркой, будет пропущен. Recall 0.967 — это про |
| объединение на распределении сплита, а не гарантия на вашем корпусе. |
| Измерьте на своих данных. |
| * **Один seed.** Веса выпущены под пилот, из одного прогона; трёхсидовая |
| сертификация релиза не проводилась. |
| * **Происхождение данных.** Общая NER-часть (`PERSON`/`ORGANIZATION`/`LOCATION`) |
| опирается на публичные русские NER-корпуса; учётные данные — синтетика. |
| Настоящих секретов в обучающем корпусе нет. |
|
|
| ## Файлы |
|
|
| ``` |
| config.json · model.safetensors веса (BertForTokenClassification, fp32, 709 МБ) |
| tokenizer.json · vocab.txt · … токенизатор (fast, BertTokenizer, cased) |
| predict.py инференс: окна · NFC · BIO-декод · объединение |
| gitleaks.toml правила детерминированного слоя |
| core/scrubber.py детерминированный слой: kv · cli · opaque |
| core/_shim.py инертные значения, NFC, вспомогательное |
| core/slot_ontology.yaml онтология ключей для kv-детектора |
| ``` |
|
|
| `core/` скопирован без изменений из `masking-service/core` бандла |
| `r3-2026-07-22` — того же кода, что крутится в проде; `predict.py` вызывает |
| `load_gitleaks_rules` и `credential_sites` из него, а не переписывает их. У |
| `scrubber.py` есть ещё и CLI датасетного пайплайна (`python -m core.scrubber`) - к инференсу он отношения не имеет, его можно игнорировать. |
