Instructions to use Adiutant/word-line-e5 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Adiutant/word-line-e5 with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("feature-extraction", model="Adiutant/word-line-e5", trust_remote_code=True)# pip install -U transformers accelerate # Load model directly from transformers import AutoModel model = AutoModel.from_pretrained("Adiutant/word-line-e5", trust_remote_code=True, device_map="auto") - Notebooks
- Google Colab
- Kaggle
WordLine-E5: поиск рукописных слов и строк без OCR
WordLine-E5 переводит изображение рукописного слова или строки в векторное
пространство multilingual-e5-small. Модель не распознаёт текст буква за
буквой: она учится ставить изображение рядом с вектором его транскрипции,
чтобы похожие по написанию и смыслу фрагменты можно было искать косинусным
сходством.
Описание модели и системы на русском языке в DOCX
Назначение
- поиск рукописных слов по текстовому запросу (query-by-string);
- поиск страницы как набора векторов её строк с max-агрегацией;
- поиск многостраничных документов вместе с sanity-MLP через RRF;
- русскоязычные рукописные документы без OCR на этапе применения.
Архитектура
- Изображение приводится к квадрату 384×384 с сохранением пропорций и белым дополнением.
- Энкодер
microsoft/trocr-base-handwrittenпреобразует изображение в последовательность скрытых состояний. - CLS-токен и среднее остальных токенов объединяются (2×768=1536).
- MLP
1536 → 768 → 384проецирует сводку в пространство E5; выход нормируется по L2.
Текстовая сторона — замороженный intfloat/multilingual-e5-small; её веса
не входят в репозиторий и не менялись при обучении.
Обучение
- 64 627 внутренних обучающих пар «изображение ↔ транскрипция»; ещё 9 932 пары использованы для валидации.
- InfoNCE, температура 0,02, in-batch negatives и до 128 текстовых hard negatives на батч.
- 2 эпохи, batch 32, AdamW, lr 1e-4, weight decay 0,01, cosine schedule, gradient clipping 1,0, fp16 autocast; seed 13.
Метрики
Все числа — development-валидация, а не независимый закрытый тест.
| Проверка | Метрика | Значение |
|---|---|---|
| Слова | 10-NN same-text purity | 0,856 |
| Слова и строки | QbS mAP@10 | 0,839 |
| WordLine по страницам | MRR@10 | 0,1417 |
| WordLine по страницам | Hit@10 | 0,3819 |
| RRF WordLine + sanity по страницам | MRR@10 | 0,2173 |
| RRF WordLine + sanity по страницам | Hit@10 | 0,6181 |
| RRF по многостраничным документам | MRR@10 | 0,2183 |
| ColSmol zero-shot | MRR@10 | 0,1369 |
| Случайное ранжирование | MRR@10 | 0,0146 |
| Текстовый оракул по полям | MRR@10 | 0,8650 |
RRF значимо превосходит обоих родителей: ΔMRR против WordLine +0,0756 [+0,0525; +0,0970], против sanity-MLP +0,0429 [+0,0161; +0,0703]. Дообученные экспериментальные checkpoint с более низкой страничной метрикой в этот репозиторий не включены.
Память и CPU
Измерено на полной визуальной цепочке WordLine + sanity + E5:
| Ресурс | Измеренное значение |
|---|---|
Веса WordLine-E5 (model.safetensors) |
336 МиБ |
| Пик RAM на CPU | ≈2,1 ГБ |
| Пик reserved VRAM на GPU | ≈2,14 ГиБ |
| Загрузка моделей | ≈3,5 с |
| Одна визуальная страница на GPU | 0,96 с |
| Одна визуальная страница на CPU | 25,9 с |
| Первый текстовый запрос после загрузки E5 | ≈4 с |
Рекомендуется не менее 4 ГБ RAM или VRAM. CPU поддерживается явно через
--gpu -1; GPU не обязателен, но значительно ускоряет индексацию страниц.
Вес индекса
| Индекс | Вес на страницу | Комментарий |
|---|---|---|
| ColSmol multi-vector fp32 | 507,8 КиБ | измеренный кеш |
| WordLine-E5 fp32 | 26,9 КиБ | пул векторов строк |
| sanity-MLP fp32 | 7,5 КиБ | 5 регионов |
| RRF WordLine + sanity fp32 | 34,4 КиБ | 68,45 МиБ на 2 039 страниц |
| RRF в fp16 | 17,2 КиБ | 34,23 МиБ на тот же корпус |
| Один E5-вектор | 1,5 КиБ | на страницу или текстовый чанк |
Индекс RRF примерно в 14,8 раза компактнее ColSmol fp32, а в fp16 — примерно в 29,5 раза. При этом он требует больше памяти, чем одновекторный E5-индекс. Текстовый индекс зависит от числа чанков: 1,5 КиБ на чанк, а не фиксированный размер на документ.
Использование
import sys
import torch
from PIL import Image
from transformers import AutoModel
repo = "./hf/word-line-e5"
sys.path.insert(0, repo)
from processing_word_line_e5 import letterbox
model = AutoModel.from_pretrained(repo, trust_remote_code=True).eval()
image = Image.open("line.jpg")
with torch.no_grad():
embedding = model(pixel_values=letterbox(image).unsqueeze(0))
# embedding: torch.Tensor [1, 384], L2-normalized
Для текстового запроса используйте тот же E5, что и при обучении:
from sentence_transformers import SentenceTransformer
e5 = SentenceTransformer("intfloat/multilingual-e5-small")
query = e5.encode(["нужная фраза"], prompt="query: ",
convert_to_tensor=True)
scores = embedding @ query.t() / 0.02
Универсальная индексация и RRF-поиск
RRF и sanity-MLP включены в этот репозиторий: дополнительно к
WordLine-E5 поставляются sanity_mlp.pt, визуальный индексер, PDF/text
роутинг и retrieval_system.py. Основной проект не требуется.
Важно различать два способа использования. AutoModel.from_pretrained
загружает только визуальную модель и возвращает векторы изображений.
Полная поисковая система запускается через retrieval_system.py из
скачанного репозитория: это локальный пакет, а не hosted API Hugging Face.
Пример скачивания:
from huggingface_hub import snapshot_download
path = snapshot_download("Adiutant/word-line-e5")
print(path)
Для gated-репозитория сначала получите одобрение владельца и выполните
hf auth login. Затем перейдите в напечатанный каталог и установите
зависимости:
pip install -r requirements.txt
# для PDF также нужны системные pdftotext, pdfinfo и pdftoppm (poppler)
Из корня скачанного репозитория:
python retrieval_system.py index file.txt scan.png document.pdf \
--index-dir /tmp/retrieval-index --gpu 0
python retrieval_system.py search "нужная фраза" \
--index-dir /tmp/retrieval-index --top-k 10 --json
TXT/MD и PDF-страницы с текстовым слоем обрабатываются E5, визуальные страницы — WordLine-E5 вместе с sanity-MLP; многостраничные документы агрегируются через max по страницам, а выдачи родителей объединяются RRF (k=60), усреднённый по числу доступных родителей, чтобы текстовые документы не проигрывали визуальным просто из-за меньшего числа каналов.
Для CPU укажите --gpu -1. Это локальный исследовательский MVP без ANN и
веб-API. Результат включает путь к документу, RRF score, ранги каждого
родителя и номер лучшей страницы.
Ограничения
- Модель обучена на словах и отдельных строках, а не на целых страницах; для страниц нужна внешняя сегментация.
- Проверка велась преимущественно на русских рукописных формах; перенос на другие языки, наклонный текст и фотографии низкого качества не гарантирован.
- Один обучающий прогон и один seed; вариация качества между запусками не измерена.
- Сплит сделан по тексту. Нормализационные варианты одной фразы (регистр, пунктуация) потенциально могли встречаться в разных частях данных.
- Часть выигрыша над случайным ранжированием связана с отличием форм от тетрадей, а не только с качеством распознавания почерка.
- Это исследовательская модель, а не готовая продуктовая система.
Лицензия
Код репозитория распространяется под MIT (см. LICENSE). Использование
весов дополнительно зависит от условий upstream-моделей и внутренних
обучающих данных; перед распространением или коммерческим применением
необходима отдельная проверка прав. Названия внутренних корпусов в
документации намеренно не раскрываются.
- Downloads last month
- -
