Вся база знаний в одном файле

Urna хранит тексты, изображения и ссылки, уже превращённые в векторы, в одном файле .urna. Ваше приложение копирует этот файл и отвечает на вопросы со ссылкой на источник: без сервера, без интернета и без ключа API.
НачатьСкачать датасеты
v0.5.1 · открытый код, лицензия MIT · Rust + Python
.csv
.jsonl
.sqlite
.jpg
Island
Basic Land · Island
corpus/
01001001 01110011 01101100 01100001 01101110 01100100IslandBasic Land · Island256 чисел на чанк, модель potion
corpus.toml
[source] kind = "sqlite"
[[models]] preset = "potion"
[[models]] preset = "clip-vit-b32"
Island
JPEGAV1
Basic Land · Island
JPEGAV1
103 kB → 13 kBв среднем на картуJPEG, источник · AV1, в файле
drift p50 0,961
сканы карт4 GB
.urna533 MB
меньше
100 % от exact61 % от exact34 % от exact26 % от exact21 % от exact
model_hashclip-vit-b32
HNSW + BM25 → cosine
Island
Forest
Mountain
p50, текст в изображение
Island
Basic Land · Island
urna validateheaderсекциифайлсодержимое
Runtime никогда не открывает сокет

Папка и несколько строк TOML превращаются в один .urna: чанки, векторы, индекс, медиа и manifest, каждая секция подписана.

Сканы карт попадают в файл в AV1, а векторы переходят на пресет поменьше. Файл сжимается, цитата остаётся той же.

Гейт model_hash проверяет модель, HNSW проходит по графу, BM25 находит слово, а точный косинус задаёт порядок.

Ответ несёт цитату обратно к источнику, а urna validate проверяет каждый слой до первого запроса, офлайн.

как это работает

От папки с документами
к файлу, который отвечает

1
Соберите источники
Тексты, PDF, таблицы, изображения. Вы описываете, откуда берётся каждый источник и какая модель будет его читать, в TOML на несколько строк.
2
Сгенерируйте .urna
Остальное делает один вызов: urna.build в Python или urna build --spec из клона репозитория. Он режет на фрагменты, вычисляет векторы, строит индексы и подписывает каждую секцию хешем SHA-256. На выходе один файл, побайтово одинаковый на любой машине.
3
Спрашивайте прямо из приложения
Рантайм на Rust открывает файл через mmap и возвращает ближайшие фрагменты, каждый с цитатой urna://, которая ведёт обратно к исходному тексту.
Всё открыто для аудита, как и положено любой базе данных
Самодостаточный, проверяемый, воспроизводимый, офлайн.
Файл и есть вся база
Фрагменты, векторы, индексы, медиа и манифест в одном .urna. Копируйте его, как копировали бы файл SQLite, храните версии в git, кладите в установщик. Нет сервиса, который нужно поднимать, и нет индекса, который нужно синхронизировать.
Каждый ответ указывает на фрагмент, который можно проверить
SHA-256 есть у каждой секции, у всего файла и у декодированного содержимого. Цитата urna://content_hash/chunk_id не меняется после сжатия текста, а urna cite находит по ней сохранённый фрагмент.
Офлайн, без исключений
Рантайм никогда не открывает сокет. Текстовая модель по умолчанию входит в пакет Python, а при других способах установки urna setup скачивает её один раз. Если модель запроса не совпадает с моделью файла, поиск останавливается сразу, вместо того чтобы вернуть мусор под видом ответа.
возможности

Что помещается в .urna

Каждая возможность соответствует секции файла или команде бинарника. Ничто не зависит от внешних сервисов
urna://content_hash/chunk_id
01000010 01100101 01101110 01110100 01101111 00100000 01000100 01100101 01110011 01101001 01100111 01101110 00100000 01010011 01111001 01110011 01110100 01100101 01101101 00111010 00100000 01000011 01100001 01110010 01100100 01110011
ask
cite
build
py
Гибридный поиск
Кандидаты из HNSW и BM25, переранжированные по точному косинусу. Итоговый score и есть этот косинус, заново вычисленный для каждого кандидата.
Открыть в документации: Гибридный поиск
NEXT_CHUNK
Поиск по графу
С with_graph=True сборка связывает каждый фрагмент со следующим в документе и с ближайшими соседями. search-graph стартует с лучших результатов, проходит по этим связям и переранжирует всё по точному косинусу, так что контекст вокруг ответа приходит вместе с ним.
Открыть в документации: Поиск по графу
k=10
фрагменты с цитатами
urna://
Цитата, которая не сдвигается
urna://content_hash/chunk_id указывает на содержимое, а не на позицию. Повторное сжатие текста не сдвигает ни одной ссылки.
Открыть в документации: Цитата, которая не сдвигается
SHA-256
SHA-256 на четырёх уровнях
Заголовок, каждая секция, весь файл и декодированное содержимое. urna validate проверяет всё это до первого запроса.
Открыть в документации: SHA-256 на четырёх уровнях
potion
dim 384
snapshot
model_hash ok
01000010 01100101 01101110 01110100 01101111 00100000 01000100 01100101 01110011 01101001 01100111 01101110

00100000 01010011 01111001 01110011 01110100 01100101 01101101 00111010 00100000 01000011 01100001 01110010 01100100 01110011
Gate по model_hash
Имя модели, размерность и snapshot fingerprint должны совпадать. Это единственная проверка, которая ловит случай, когда имя и размерность те же, а модель другая.
Открыть в документации: Gate по model_hash
JPEG
AV1
Медиа внутри файла
Изображения в AV1, AVIF или JPEG XL хранятся как blob с адресацией по хешу, с точным диапазоном байтов для каждого фрагмента, так что чтение не зависит от sidecar.
Открыть в документации: Медиа внутри файла
Много моделей, один файл
potion, CLIP, SigLIP2, Jina, WEMM или любая модель, которую вы запускаете в Python, каждая в своём именованном векторном пространстве. Поиск изображений по тексту в том же .urna.
Открыть в документации: Много моделей, один файл
61 %
hybrid, размер vs exact
34 %compressed
21 %nano
61 %hybrid
26 %tiny
Пять пресетов
От nano (int4, 21 % размера) до exact (float32, эталон). То же содержимое, те же цитаты, другие размер и recall.
Открыть в документации: Пять пресетов
TOML
--dry-run
cache
--resume
Декларативная сборка
Источники, медиа и модели в одном TOML. --dry-run строит план, кэш embeddings избавляет от повторных вычислений, --resume продолжает с места остановки.
Открыть в документации: Декларативная сборка
Python собирает, Rust отдаёт
urna.build создаёт файл, urna.open и retrieve выполняют запросы. Бинарник на Rust статический, и Dockerfile из репозитория собирает его в образ scratch.
Открыть в документации: Python собирает, Rust отдаёт
на практике

Публичный бенчмарк, одна линейка

urna против usearch, hnswlib, sqlite-vec и lancedb на одной машине, с данными и командой для воспроизведения
0,72 ms
p50
1,02 ms
p99
recall 1,0
0,72 ms на запрос, recall 1,0
100 000 векторов размерности 384, 200 запросов, один поток. Пресет hybrid ответил с p50 0,72 ms и p99 1,02 ms. Только он в таблице проверяет собственные байты перед первым запросом; это стоит около 360 ms при открытии.
Открыть в документации: 0,72 ms на запрос, recall 1,0
38 000 карт Magic в 533 MB
4 GB сканов в JPEG превратились в файл в 7,46 раза меньше, с текстом, векторами, индексом и изображениями AV1 внутри, и поиск находит карту так же часто, как на lossless-файле.
Открыть в документации: 38 000 карт Magic в 533 MB
30 725
фрагменты
7
датасеты
FakeRecogna11,9 тыс.
Fake.br7,2 тыс.
FakeTrue.Br3,6 тыс.
factck-br1,3 тыс.
30 000 фрагментов для проверки фактов
truw оценивает утверждения на португальском по семи открытым датасетам фейковых новостей. Его корпус лежит в .urna из 30 725 фрагментов: 120 MB с пресетом exact, 31 MB с tiny.
Открыть в документации: 30 000 фрагментов для проверки фактов

Бенчмарк от 2026-09-10 на arm64, один поток. Чего Urna не умеет: обновление и удаление на месте, фильтры по метаданным, конкурентная запись. Открыть полную таблицу.

бенчмарки

Бенчмарки urna

Измеряем сжатие, поиск и задержку на наборе из 38 627 карт Magic (3,98 GB в JPEG), сохранённом в файле .urna, и сравниваем urna с usearch, hnswlib, sqlite-vec и lancedb на тех же векторах и той же машине

Сжатие против поиска по названию

файлов: 7 · запросов на файл: 1 000
индекс сжатия без потерь в поиске7,46x

во столько раз меньше, чем 3,98 GB исходных JPEG. Файл с crf50 весит 533 MB и находит карту по названию так же часто, как lossless-файл на 3,61 GB: разница по txt@1 составляет +0,001, в пределах стандартной ошибки.

lossless · 3,61 GB
neardup · 1,37 GB
crf50 · 533 MB

Что измеряет эта метрика

txt@1 означает долю запросов (всего 1 000), в которых нужная карта оказалась первой. Запросом служит название карты в виде текста ("artwork of the card {name}"), по нему ищут в пространстве изображений clip. Модель видит только иллюстрацию, поэтому уровень низкий во всех файлах; важно, где он начинает падать.

drift здесь означает косинус между вектором сжатого изображения и вектором оригинала: 1,00 значит идентичны, и чем ниже значение, тем сильнее кодек изменил то, что видит модель. Худший дециль (p10) соответствует карте на границе 10 % самых изменившихся, медиана (p50) соответствует карте посередине.

Как читать этот график

Каждый столбец соответствует файлу с тем же набором из 38 627 карт, от lossless (3,61 GB) до AV1 на crf60 (230 MB), по возрастанию сжатия.

Вверху обе линии drift падают на всём протяжении и пересекают gate floor уже на втором файле. Внизу поиск остаётся ровным до crf50: зелёные столбцы лежат в пределах одной стандартной ошибки от lossless; пунктир отмечает, где поиск проседает, а красные столбцы соответствуют файлам после него.

файлразмерdrift p10txt@1±1 стандартная ошибкаz vs lossless
lossless3,61 GB0,99680,0920,00910,00
neardup1,37 GB0,96660,0960,00930,31
avif q481,2 GB0,96800,0960,00930,31
crf40981 MB0,95940,0890,0090-0,23
crf50533 MB0,93890,0930,00920,08
crf55370 MB0,92110,0740,0083-1,46
crf60230 MB0,88660,0690,0080-1,89

запросов на файл: 1 000, во всех файлах одни и те же карты; стандартная ошибка биномиальная; z показывает, на сколько объединённых стандартных ошибок txt@1 каждого файла отличается от lossless: до crf50 включительно ни один не превышает 1.

измерено 2026-09-12 · benchmark/experiments/14-utility-ladder/results.json

пресеты
Выберите размер. Содержимое не меняется
Пять пресетов сочетают сжатие текста, точность векторов и индексы, плюс micro, который отрезает измерения. Здесь три, все в документации
Для вопросов с аббревиатурами, именами собственными, редкими терминами:
Текст сжат zstd
Векторы в float32
HNSW + BM25 как кандидаты
Rerank по точному косинусу
Открыть пресет
Измерено на корпусе из 30 725 фрагментов. Recall здесь показывает, насколько устойчиво ранжирование при квантизации, а не точность на реальных вопросах. Все пять пресетов и micro.
интеграция
Ставится одной командой. Встраивается в пять строк
Бинарник на Rust с тремя группами команд (engine, agent, setup) и Python API. После установки всё, что ниже, работает без сети
$
Установка
установщик
$
Сборка
urna build
$
Вопрос
urna ask
Установщик проверяет SHA-256 до записи на диск. urna setup один раз скачивает офлайн-embedder и заканчивается проверкой urna doctor, которая покажет, на каком уровне что-то сломалось.
curl -sSf https://raw.githubusercontent.com/hoffresearch/urna/main/scripts/install.sh | sh urna setup
Источники, медиа и модель в одном TOML, запуск из клона репозитория. Одна и та же спецификация даёт одну и ту же базу на любой машине.
urna build --spec corpus.toml
Фрагменты с цитатами прямо в терминале.
urna ask corpus.urna "работает офлайн?" -k 3
JSONL с фрагментом, источником, score и цитатой, готовый для вашего приложения или агента.
urna retrieve corpus.urna "работает офлайн?" -k 5 --format jsonl
Открывает файл через mmap, возвращает результаты с цитатами. Ожидаемый model_hash останавливает неподходящую модель ещё до поиска.
import urna from urna.embed_potion import potion_embedder emb, db = potion_embedder(), urna.open("corpus.urna") qvec = emb.embed_texts(["работает офлайн?"])[0] hits = db.retrieve(qvec, 5, expected_model_hash=emb.model_hash())
Все контрольные суммы перед поставкой: заголовок, секции, файл, содержимое.
urna validate corpus.urna
От цитаты обратно к сохранённому тексту, с хешами, которые это доказывают.
urna cite corpus.urna "urna://content_hash/chunk_id"
Задержка и recall на вашей машине и на вашем корпусе.
urna benchmark corpus.urna -q 100 -k 10 --ann 100
каналы

Один релиз, любой пакетный менеджер

Один и тот же urna 0.5.1 на crates.io, PyPI, npm и Homebrew, с контрольной суммой и attestation рядом с каждым файлом
Один и тот же бинарник везде
cargo, pip, npm, bun, pnpm, yarn, brew, однострочник с curl и PowerShell ставят одну и ту же сборку: macOS и Linux на arm64 и x86_64, Windows на x86_64. npx и uvx запускают его без установки.
Открыть в документации: Один и тот же бинарник везде
tar.xz
zip
sha256
sigstore
SBOM
ssh tag
Релиз, который можно проверить
У каждого архива свой .sha256 и attestation от sigstore, которую проверяет gh attestation verify, плюс SBOM в формате CycloneDX и бинарники, собранные с cargo-auditable. Теги релизов подписаны ssh.
Открыть в документации: Релиз, который можно проверить
Внутри вашего приложения, без CLI
urna-format и urna-runtime лежат на crates.io для Rust, а пакет Python открывает тот же файл. В репозитории есть примеры для fastapi, flask и jupyter и Dockerfile, а cargo install urna --no-default-features оставляет CLI только с engine на 2,1 MB.
Открыть в документации: Внутри вашего приложения, без CLI
Без установкиnpx @urna/cli validate corpus.urnauvx --from urna urna validate corpus.urnacargo binstall urna
в терминале

Три группы команд и экран для работы

urna tui открывает .urna, задаёт ему вопросы и проверяет установку, не выходя из терминала. urna setup показывает план, прежде чем что-то записать, и заканчивается проверками doctor
urna tui на вкладке ask: десять результатов с цитатами на вопрос, сохранённый текст выбранного и его цитата
urna tui
urna setup на шаге verify, все проверки пройдены
urna setup
engine

На входе файл и вектор, на выходе результаты. Без Python.

  • inspect
  • validate
  • stats
  • media
  • search
  • search-ann
  • search-graph
  • search-space
  • search-text
  • benchmark
  • cite
  • doctor
agent

На входе текст или спецификация, на выходе ответы с цитатами, через офлайн-embedder на Python.

  • ask
  • retrieve
  • build
setup

Установщик, которым заканчивается любой канал, и обозреватель в терминале.

  • setup
  • tui
Прежде чем начать
То, что обычно мешает при первом знакомстве. Остальное есть в документации, с командами и их выводом
Читать документацию

Ваша база знаний, готовая в дорогу

Установите, соберите корпус, скопируйте файл в приложение. Остальное делает mmap
Установить
v0.5.1 · MIT · macOS, Linux и Windows