Skip to content
项目

fishonbike/vault-engine has 26 GitHub stars and 4 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 03:09 UTC. Last push 2026-07-02.

这些数字如何统计

实测星标增长

24小时
0
7天
更新延迟
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

A local-LLM privacy layer for anything you paste into a cloud model — detect, tokenize, restore. Zero deps, reversible, strong on Chinese.

人工智能

README.zh-CN.md

原文

vault-engine

English · 简体中文

给一切要粘进云端大模型的文本,加一层本地大模型隐私层。

在文本到达 ChatGPT / Claude / Gemini 之前,先把身份信息脱掉——一个跑在你自己电脑上的模型找出人名、机构、地点和准标识符,替换成稳定代号,并把"代号↔真名"这唯一的钥匙留在本地。云端用代号回复后,你在本地把真实身份还原回来。

尽力而为的脱敏——不是法律意义上的匿名化,也不是隐私保证。高敏感材料发送前请人工复查。

出云前做身份脱敏:本地模型检测 → 代号化 → 云端用代号分析 → 本地还原真身。 检测不出本机,身份映射只存本地,大模型一行换。零依赖。

vault-engine 在文本出云前把中英文人名与 PII 换成代号,事后在本地还原

CI  ·  Python ≥3.9  ·  纯标准库  ·  Apache-2.0

# notes.txt  ── 私有,留在你电脑上
林若曦是星澜资本的合伙人,在深圳见了字节跳动的陈大壮,邮箱 [email protected]

        ▼  vault-engine scrub  (本地 qwen3.6:27b)

# safe.txt  ── 云端只看到这个:身份已被换成代号
P-n1 是 ORG_1 的合伙人,在 LOC_1 见了 ORG_2 的 P-n2,邮箱 EMAIL_1

为什么需要它

你想让前沿云端模型分析敏感笔记——但不想让云端知道这些内容是关于谁的。只屏蔽你已知的名字,会漏掉你不知道的一切:一个没登记的人名、一个雇主、"某城市 + 某罕见职务"、一个项目代号。基于规则的正则脱敏,根本看不见这些。

vault-engine 在最前面放一个本地模型当检测器,于是语义层面的身份也能被抓到——而且除了脱敏后的文本,什么都不会离开本机。

工作原理

 private text                                    cloud model
      │                                          (sees only tokens)
      ▼                                                ▲
┌─────────────────────────── vault-engine ────────────┼───────────┐
│  ① regex PII detectors  (offline floor)              │           │
│  ② LLM detector         (local model finds names,    │           │
│                          orgs, places, quasi-IDs)    │           │
│  ③ consistent pseudonyms (张三→P-n1, 同名同号)        │           │
│  ④ residual-risk critic  (re-scan: anything left?)   │  ① send   │
│        │                                             │           │
│   sanitized text ────────────────────────────────────┘           │
│        ▲                                                          │
│   reverse map (token → real identity) ── stays LOCAL ──┐  ② reply │
│        └───────────────────── ⑤ rehydrate ◀────────────┘          │
└──────────────────────────────────────────────────────────────────┘
      ▼
 real identities restored locally → use in your own system

评测 benchmark

在一个带标注的双语数据集上,各检测器到底能抓到多少身份(用 python eval/run_eval.py 可复现;方法学见 eval/):

⚠️ 这是一个小规模合成集,仅用于回归测试和粗略对比——不代表法律意义上的匿名化或完整隐私保护。"召回"指"被标记去脱敏";LLM 检测是非确定性的。详见 威胁模型。

检测器 人物 机构 地点 项目 联系方式 证件 总召回 过度脱敏
纯正则 0% 0% 0% 0% 69% 33% 13% 0%
Microsoft Presidio (en/zh lg) 78% 59% 80% 33% 38% 0% 61% 4%
vault-engine (qwen2.5:7b, 4.7 GB) 100% 100% 100% 100% 100% 100% 100% 2%
vault-engine (qwen3.5:9b, 6.6 GB) 100% 94% 100% 100% 100% 100% 99% 0%
vault-engine (qwen3.6:27b, 17 GB) 100% 100% 100% 100% 100% 100% 100% 0%

同一份数据集上 Presidio 的 NER 拿 61%,本地大模型清到 ~100%——差距最大的是项目代号、@账号、证件号、以及中文人名/机构。检测并不需要大模型:4.7GB 的 qwen2.5:7b 与 27b 同样打满召回,约 4 秒/篇(27b 约 25 秒/篇),普通笔记本即可。Presidio 在其覆盖范围内仍然快得多(约 0.4 秒/篇)。

重点不是刷榜,而是形态差异:纯模式匹配对人名、机构、地点、代号完全失明,本地大模型能看见。

安装

pip install vault-engine

或直接从源码装最新版:

pip install git+https://github.com/fishonbike/vault-engine

默认后端用本地 Ollama,先拉个模型:

ollama pull qwen3.6:27b

还没装模型?确定性的正则兜底(邮箱、电话、证件、卡号、URL)零配置即可用,加 --no-llm 即可。

快速上手

vault-engine scrub notes.txt -o notes.safe.txt

它会写出 notes.safe.txt(这份发给云端)和 notes.safe.txt.map.json(只存本地——里面是真实身份)。把脱敏文本粘进你的模型,存下它的回复,再还原真实身份:

vault-engine rehydrate reply.json --map notes.safe.txt.map.json -o reply.real.json

剪贴板一行流

最快的用法——贴进聊天机器人前,就地把剪贴板洗一遍:

vault-engine clip               # 脱敏当前剪贴板
#   …粘进 ChatGPT/Claude,复制它的回复,然后:
vault-engine clip --rehydrate   # 把剪贴板里的代号还原成真实身份

支持 macOS、Windows、Linux(Linux 需 xclip/xsel/wl-clipboard)。

库调用:

from vaultengine import deidentify, rehydrate, Config

result = deidentify(open("notes.txt").read(), Config(model="qwen3.6:27b"))
send_to_cloud(result.text)                  # 只有代号出门
restored = rehydrate(get_cloud_reply(), result.vault)   # 本地还原真实身份
result.vault.save("notes.map.json")         # 反向映射——留在本地

适用场景

  • 贴进 ChatGPT/Claude 前先假名化——分析私密笔记、合同、聊天记录时,先把直接标识符脱掉。
  • 共享或喂给 LLM 前脱敏日志与工单。
  • 匿名化一份数据集做 LLM 辅助分析,再把结果映射回去。
  • 气隙式审阅闭环——锁死环境里的模型自始至终只看到代号。

与其他方案的对比

Presidio 和 LLM Guard 都是优秀、成熟的工具。vault-engine 的赌注不同:用本地大模型当检测器,抓住基于标签的 NER 漏掉的语义/准标识符,并且零运行时依赖、中文一流。

vault-engine Presidio LLM Guard (Anonymize) regex / scrubadub
检测方式 本地 LLM + 正则 NER (spaCy) + 正则 NER / transformers 仅正则模式
未登记人名 / 机构 / 准标识符 ✅ LLM ⚠️ 仅 NER 标签 ⚠️ 受限于 NER ❌
可逆往返 ✅ 本地映射 ✅ 反匿名化 ✅ Vault ❌
完全本地 / 离线 ✅ Ollama ✅ ⚠️ 视情况 ✅
运行时依赖 无(纯标准库) spaCy + 模型 若干 视情况
中文 ✅ 强 ⚠️ 需模型 ⚠️ ❌
换模型 ✅ 一行 — 部分 —
检测失败即报错 ✅ 降级 + 非零退出 — — —

脱敏力度(隐私 ↔ 可用性)

--policy 人物 机构 / 地点 / 职务 日期 代号形态
balanced (默认) ✅ ✅ 带类型(ORG_1、LOC_2) 保留 类型化
max ✅ ✅ 不透明 R_1(隐藏类型) 粗化 不透明
light ✅ 原样保留 保留 类型化

balanced 保留粗粒度结构——云端仍能读到"ORG_1 在 LOC_1 把 P-n2 招为 ROLE_1"并据此推理,但没有任何真实身份出门。人物在任何力度下都会被代号化。

换模型

vault-engine models                                   # 列出本地 Ollama 已装模型
vault-engine scrub notes.txt --model qwen3.6:35b-a3b  # 任意本地模型
vault-engine scrub notes.txt --provider null          # 离线,仅正则

内置 provider:ollama(默认)、openai-compat(任意 OpenAI 兼容端点——选用;⚠️ 会把原文发往该端点)、null(离线)。实现一个方法(complete)并注册,即可接入你自己的后端。

⚠️ 安全模型——务必阅读

  • 反向映射 *.map.json 就是身份本身。 它是把代号链回真人的唯一东西。只存本地,绝不发给云端、绝不提交进仓库——.gitignore 已屏蔽 *.map.json,CLI 每次运行都会提醒。加 --one-way 可不产出映射(不可逆发布)。
  • 检测默认全程本地。 只有脱敏后的文本才该离开本机,且只在你主动发送时。

威胁模型与局限(诚实)

  • LLM 检测是尽力而为,不是不可识别的保证——模型可能漏掉一个名字或一个罕见的准标识符。它不是 k-匿名,也不是差分隐私。
  • 残留风险复审和风险报告能降低并暴露残留风险,但不能证明其不存在。即便去掉名字,文风和领域独有事实仍可能定位到人——高敏材料请用 max。
  • 模型后端不可达时,运行会降级为纯正则并以非零退出(--allow-degraded 可覆盖)——它绝不会静默吐出脱敏不足的文本。

保护代码与 schema(--format markdown)

加 --format markdown(或 auto,遇到围栏代码块自动开启)时,围栏 ``` 代码块内的内容会原样保留——你为模型附带的 JSON 回执 schema 或代码样例不会被动,而周围的正文照常脱敏。文本中已存在的占位符(如 P-7)也原样穿过。

开发

python -m unittest discover -t . -s tests -v   # 全部单元测试,离线、无需模型
python eval/run_eval.py --provider ollama       # 复现 benchmark

全程离线、确定性(用 null/fake provider);所有 fixture 都是合成数据——本仓库不含任何真实数据。

许可证

Apache-2.0 © 2026 fishonbike。见 LICENSE 与 NOTICE。