整个知识库，装进一个文件

Urna 把已经转换为向量的文本、图片和引用存进单个 .urna 文件。你的应用复制这个文件，就能回答问题并注明出处，无需服务器、无需联网、无需 API key。

开始使用下载数据集

v0.5.1 · 基于 MIT 开源 · Rust + Python

.csv

.jsonl

.sqlite

.jpg

Island

Basic Land · Island

corpus/

01001001 01110011 01101100 01100001 01101110 01100100

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段文件内容

一个文件夹加几行 TOML，变成一个 .urna：chunks、向量、索引、媒体和 manifest，每个段都有签名。

卡牌扫描图以 AV1 存进文件，向量换成更小的 preset。文件变小，引用保持不变。

model_hash 关卡核对模型，HNSW 沿图游走，BM25 匹配关键词，精确余弦决定顺序。

答案带着引用回到来源，urna validate 在第一次查询前离线核对每一层。

可审计，数据库本该如此

自包含、可校验、可复现、离线。

文件就是整个数据库

片段、向量、索引、媒体和 manifest 都在同一个 .urna 里。像复制 SQLite 文件一样复制它，用 git 做版本管理，随安装包一起分发。没有需要启动的服务，也没有需要同步的索引。

每个回答都指向一个可以核对的片段

每个 section 都有 SHA-256，整个文件有，解码后的内容也有。文本压缩之后，引用 urna://content_hash/chunk_id 保持不变，urna cite 会把它解析为存储的片段。

离线，没有例外

运行时从不打开 socket。默认文本模型随 Python 包附带，其他安装方式下由 urna setup 在安装时下载一次。如果查询所用的模型与文件的模型不一致，搜索会立即停止，而不是返回一堆看起来像答案的垃圾。

功能

都装进一个 .urna

每项功能都是文件的一个 section 或二进制的一个子命令。不依赖任何外部服务

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，再按精确余弦 rerank。输出的分数就是这个余弦，为每个候选重新计算。

在文档中查看: 混合搜索

图搜索

构建时加上 with_graph=True，每个片段会链接到文档中的下一个片段和最相近的邻居。search-graph 从最好的结果出发，沿这些链接扩展，再用精确余弦重新排序，于是答案周围的上下文也一起带回来。

在文档中查看: 图搜索

k=10

带引用的片段

不会变的引用

urna://content_hash/chunk_id 标识的是内容，而不是位置。重新压缩文本不会移动任何一条引用。

在文档中查看: 不会变的引用

SHA-256

四层 SHA-256

文件头、每个 section、整个文件和解码后的内容。urna validate 在第一次查询前全部检查一遍。

在文档中查看: 四层 SHA-256

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

model_hash gate

模型名称、维度和 snapshot fingerprint 必须一致。只有这项检查能发现名称相同、维度相同、模型却不同的情况。

在文档中查看: model_hash gate

JPEG

AV1

媒体在文件内

图像以 AV1、AVIF 或 JPEG XL 编码，作为按哈希寻址的 blob 存储，并记录每个片段的精确字节范围，读取不依赖 sidecar。

在文档中查看: 媒体在文件内

potion

clip

siglip2

jina

wemm-2b

minilm

多个模型，一个文件

potion、CLIP、SigLIP2、Jina、WEMM，或任何你在 Python 里运行的模型，各自位于命名的向量空间。在同一个 .urna 中做文本到图像搜索。

在文档中查看: 多个模型，一个文件

61%

hybrid，大小 vs exact

34%compressed

21%nano

61%hybrid

26%tiny

五个 preset

从 nano（int4，大小为 21%）到 exact（float32，作为基准）。内容相同，引用相同，大小和 recall 不同。

在文档中查看: 五个 preset

TOML

--dry-run

cache

--resume

声明式 build

数据源、媒体和模型写在一个 TOML 里。--dry-run 做规划，embeddings 缓存避免重复计算，--resume 从中断处继续。

在文档中查看: 声明式 build





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

每次查询 0.72 ms，recall 1.0

10 万个 384 维向量，200 次查询，单线程。hybrid preset 的 p50 为 0.72 ms，p99 为 1.02 ms。它是表中唯一在第一次查询前校验自身字节的引擎；这在打开时大约花费 360 ms。

在文档中查看: 每次查询 0.72 ms，recall 1.0

3.8 万张 Magic 卡牌，533 MB

4 GB 的 JPEG 扫描图变成了一个小 7.46 倍的文件，文本、向量、索引和 AV1 图像都在里面，搜索找到卡牌的比例与 lossless 文件一样。

在文档中查看: 3.8 万张 Magic 卡牌，533 MB

30,725

片段

7

数据集

FakeRecogna1.2万

Fake.br7200

FakeTrue.Br3600

factck-br1300

3 万个事实核查片段

truw 对照七个公开的假新闻数据集，为葡萄牙语的说法打分。语料是一个包含 30,725 个片段的 .urna：exact preset 下为 120 MB，tiny 下为 31 MB。

在文档中查看: 3 万个事实核查片段

基准测试日期 2026-09-10，arm64，单线程。Urna 不做的事：原地更新和删除、元数据过滤、并发写入。查看完整表格。

基准测试

urna 基准测试

在存入 .urna 文件的 38,627 张 Magic 卡牌（3.98 GB 的 JPEG）上测量压缩、搜索和延迟，并在相同的向量、同一台机器上对比 urna 与 usearch、hnswlib、sqlite-vec和lancedb

压缩与按名称搜索

7 个文件 · 每个 1,000 次查询

不损失搜索效果的压缩倍数7.46x

是相对 3.98 GB 源 JPEG 的缩小倍数。crf50 档的文件为 533 MB，按名称找到卡牌的比例与 3.61 GB 的 lossless 文件相当：txt@1 相差 +0.001，在标准误差之内。

这个指标衡量什么

txt@1 是 1,000 次查询中正确卡牌排在第一位的比例。查询是卡牌名称的文本（"artwork of the card {name}"），在 clip 的图像空间中搜索：模型只看得到卡图，所以每个文件的水平都很低；关键是它在哪里开始下降。

drift 是压缩图像的向量与原图向量之间的余弦：1.00 表示完全相同，值越低，codec 对模型所见内容的改动越大。最差十分位（p10）是变化最大的那 10% 卡牌边界上的那一张；中位数（p50）是居中的那一张。

如何阅读这张图

每一列是一个文件，包含同样的 38,627 张卡牌，从 lossless（3.61 GB）到 crf60 的 AV1（230 MB），按压缩程度排列。

上图中，两条 drift 线一路下降，从第二个文件起就跌破 gate floor。下图中，搜索效果到 crf50 为止保持平稳：绿色柱与 lossless 的差距在一个标准误差以内；虚线标出搜索开始下降的位置，红色柱是虚线之后的文件。

文件	大小	drift p10	txt@1	±1 标准误差	z vs lossless
lossless	3.61 GB	0.9968	0.092	0.0091	0.00
neardup	1.37 GB	0.9666	0.096	0.0093	0.31
avif q48	1.2 GB	0.9680	0.096	0.0093	0.31
crf40	981 MB	0.9594	0.089	0.0090	-0.23
crf50	533 MB	0.9389	0.093	0.0092	0.08
crf55	370 MB	0.9211	0.074	0.0083	-1.46
crf60	230 MB	0.8866	0.069	0.0080	-1.89

每个文件 1,000 次查询，所有文件使用相同的卡牌；二项分布标准误差；z 是每个文件的 txt@1 与 lossless 之间以合并标准误差计的距离：到 crf50 为止，没有一个超过 1。

测于 2026-09-12 · benchmark/experiments/14-utility-ladder/results.json

preset

选择大小，内容不变

五个 preset 组合了文本压缩、向量精度和索引，另有 micro 负责裁掉维度。这里列出三个，全部见文档

适合含缩写、专有名词、罕见术语的问题：

文本用 zstd 压缩

float32 向量

HNSW + BM25 作为候选

按精确余弦 rerank

查看 preset

在 30,725 个片段上测得。这里的 recall 衡量的是量化下排序的稳定性，而不是真实问题上的准确度。查看全部五个 preset 和 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 里，在仓库的 checkout 中运行。同一份 spec 在任何机器上都生成相同的数据库。

urna build --spec corpus.toml

带引用的片段，直接在终端里输出。

urna ask corpus.urna "离线能用吗？" -k 3

输出 JSONL，包含片段、来源、分数和引用，可以直接交给你的应用或 agent。

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())

分发前检查所有校验和：文件头、各 section、整个文件、内容。

urna validate corpus.urna

从引用回到存储的文本，并附上可以证明这一点的哈希。

urna cite corpus.urna "urna://content_hash/chunk_id"

在你的机器、你的语料上测量延迟和 recall。

urna benchmark corpus.urna -q 100 -k 10 --ann 100

渠道

一次发布，所有包管理器

crates.io、PyPI、npm 和 Homebrew 上是同一个 urna 0.5.1，每个文件旁边都有校验和与 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 和一份 sigstore attestation（用 gh attestation verify 校验），外加 CycloneDX SBOM 和用 cargo-auditable 构建的二进制。发布 tag 由 ssh 签名。

在文档中查看: 可以核验的发布

放进你的应用，不需要 CLI

urna-format 和 urna-runtime 在 crates.io 上供 Rust 使用，Python 包打开的是同一个文件。仓库里有 fastapi、flask 和 jupyter 的示例和一个 Dockerfile；cargo install urna --no-default-features 会得到一个只含 engine 的 2.1 MB CLI。

在文档中查看: 放进你的应用，不需要 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

输入文本或 spec，输出带引用的答案，经由离线的 Python embedder。

ask
retrieve
build

setup

每个渠道最后都要运行的安装器，以及终端里的浏览器。

setup
tui

开始之前

第一次阅读时常见的疑问。其余内容都在文档里，附有命令和输出

阅读文档

运行时没问题。默认 embedder 就不太行了：potion 是从英文模型蒸馏而来的，它在中文上的语义信号很弱。中文语料请使用多语言模型，例如 paraphrase-multilingual-MiniLM，truw 的语料（葡萄牙语）用的就是它。混合搜索还有一个限制：BM25 按空格和标点切词，所以中文、日文、泰文和老挝文会把每个字符当成一个 token，关键词的 recall 随之下降。这些语言请用 with_bm25=False 构建文件，让向量来完成检索。

你的知识库，随时可以带走

安装，构建语料，把文件复制进应用。剩下的交给 mmap

安装

v0.5.1 · MIT · macOS、Linux 和 Windows

整个知识库，装进一个文件

从一个文档文件夹到一个能回答问题的文件

都装进一个 .urna

公开基准测试，同一把尺子

urna 基准测试

压缩与按名称搜索

这个指标衡量什么

如何阅读这张图

一次发布，所有包管理器

三组子命令，外加一个操作界面

你的知识库，随时可以带走

从一个文档文件夹
到一个能回答问题的文件