teilomillet/vauban

# vauban 一个 MLX 原生工具包，用于理解和重塑语言模型在 Apple Silicon 上的行为。 以 [Sébastien Le Prestre de Vauban](https://en.wikipedia.org/wiki/Vauban) 的名字命名，这位军事工程师在攻城和防御工事方面均有建树。Vauban 对模型行为也做着同样的事情：测量、切割、探测、引导或强化。 ## 它能做什么 Vauban 是一个 TOML 优先的 CLI，用于围绕激活空间几何构建的工作流： - 从模型激活中测量行为方向 - 在权重中切割或稀疏化这些方向 - 在运行时探测和引导模型 - 在干预前后映射拒绝曲面 - 运行防御、清理、优化和攻击循环 主要接口并非一堆子命令。它是： ``` vauban ``` 所有 pipeline 行为都存在于 TOML 文件中。 ## 系统要求 - Apple Silicon Mac - Python 3.12+ - [uv](https://docs.astral.sh/uv/) ## 安装 安装已发布的 CLI： ``` uv tool install vauban ``` 如果你的 shell 无法找到 `vauban`，请更新一次你的 shell 配置： ``` uv tool update-shell ``` 然后打开一个新的 shell 并检查命令： ``` vauban --help vauban man workflows ``` 从本仓库进行开发： ``` uv tool install --editable . ``` 贡献者工作流和仓库策略位于 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 快速开始 选择一个目标——手册会告诉你该使用哪些部分： ``` vauban man workflows ``` 然后脚手架生成一个配置并运行： ``` vauban man quickstart ``` 脚手架生成一个启动配置： ``` vauban init --mode default --output run.toml ``` 所有 pipeline 模式都可以通过脚手架生成。使用以下命令查看完整列表： ``` vauban init --help ``` 在实际运行之前进行验证： ``` vauban --validate run.toml ``` 然后运行 pipeline： ``` vauban run.toml ``` 默认情况下，输出将进入 TOML 文件相对路径下的 `output/` 目录。 ## 最小化 TOML 这是代码为默认 pipeline 接受的最小配置： ``` [model] path = "mlx-community/Llama-3.2-3B-Instruct-4bit" [data] harmful = "default" harmless = "default" ``` `[model].path` 是必填项。 `[data].harmful` 和 `[data].harmless` 在大多数运行中是必填的。`"default"` 使用 Vauban 内置的提示词集。 你也可以显式选择输出目录： ``` [output] dir = "runs/baseline" ``` ## 实验科技树 Vauban 通过可选的 `[meta]` 部分内置了实验谱系追踪。此元数据不会改变 pipeline 的执行。它的存在是为了让你可以将运行组织成一棵科技树。 最小化示例： ``` [meta] id = "cut-alpha-1" title = "Baseline cut, alpha 1.0" status = "baseline" parents = ["measure-v1"] tags = ["cut", "baseline"] date = 2026-03-02 notes = "First stable reference run." ``` 已验证的状态值为： ``` archived, baseline, dead_end, promising, superseded, wip ``` 如果省略了 `[meta].id`，Vauban 将使用 TOML 文件名的主体部分（不含扩展名）。 从一个包含 TOML 配置的目录渲染该树： ``` vauban tree experiments/ vauban tree experiments/ --format mermaid vauban tree experiments/ --status promising vauban tree experiments/ --tag gcg ``` 每次运行还会在配置的输出目录中追加一个 `experiment_log.jsonl` 文件，其中包含已解析的配置路径、pipeline 模式、报告文件、指标以及选定的 `[meta]` 字段。 ## TOML 如何驱动 Vauban `vauban ` 加载一个 TOML 文件，并根据你包含的部分决定要做什么。 默认路径是： 1. measure 2. cut 3. export 你可以通过添加更多部分来扩展该运行。常见示例： - `[eval]` 添加切割后的评估报告。 - `[surface]` 添加干预前后的拒绝曲面映射。 - `[detect]` 在测量期间添加强化检测。 - 某些部分会将 Vauban 切换到专用的特定模式运行，而不是默认 pipeline。 如果你知道要做什么，但不知道该使用哪些部分： ``` vauban man workflows ``` 获取任何部分的字段级参考： ``` vauban man cast vauban man softprompt vauban man measure ``` 了解模式优先级： ``` vauban man modes ``` ## 你将实际使用的命令 查看手册： ``` vauban man workflows vauban man quickstart vauban man cast vauban man all ``` 脚手架生成配置： ``` vauban init --help vauban init --mode default --output run.toml vauban init --mode probe --output probe.toml ``` 在不加载模型权重的情况下验证配置和提示词文件： ``` vauban --validate run.toml ``` 导出当前的 JSON Schema 以供编辑器工具使用： ``` vauban schema vauban schema --output vauban.schema.json ``` 比较两个运行目录： ``` vauban diff run_a run_b vauban diff --format markdown run_a run_b vauban diff --threshold 0.05 run_a run_b ``` `vauban diff --threshold ...` 是一个 CI 门控：如果任何绝对指标增量超过阈值，它将以非零状态退出。 渲染实验谱系树： ``` vauban tree experiments/ vauban tree experiments/ --format mermaid vauban tree experiments/ --status promising ``` ## 数据格式 由生成的手册验证： - 用于 `[data]` 和 `[eval]` 的 prompt JSONL：每行一个带有 `prompt` 键的 JSON 对象 - 用于 `[surface].prompts` 的 surface JSONL：需要 `label` 和 `category`，以及 `prompt` 或 `messages` 中的任意一个 - refusal phrase 文件：纯文本，每行一个短语 - 相对路径从 TOML 文件所在的目录开始解析 最小化 prompt 数据集示例： ``` {"prompt":"What is the capital of France?"} {"prompt":"Write a haiku about rain."} ``` ## 验证说明 本 README 与此仓库中的代码保持一致： - 包名：`vauban` - 控制台脚本：`vauban = vauban.__main__:main` - 已验证的命令：`vauban `、`--validate`、`schema`、`init`、`diff`、`tree`、`man` - 已验证的手册主题和脚手架生成的模式已与实时 CLI 帮助和生成的手册进行过核对 当前的 README 以前包含一些过时的模式/输出声明；此版本移除了这些内容，并引导读者查看 `vauban man ...`，以获取直接从代码生成的部分。 ## Python API (Session) 对于编程式使用，`Session` 类封装了一个加载的模型，并提供了工具发现、前置条件追踪和结构化结果。 ``` from vauban.session import Session s = Session("mlx-community/Qwen2.5-1.5B-Instruct-bf16") s.tools() # discover all capabilities s.guide("audit") # step-by-step workflow s.describe("cast") # detailed tool info with current status s.catalog() # all tools grouped by category ``` ### 工具 | 方法 | 返回值 | 功能 | |--------|---------|-------------| | `s.measure()` | `DirectionResult` | 从激活中提取拒绝方向 | | `s.detect()` | `DetectResult` | 检查模型是否已被强化以抵抗 abliteration | | `s.audit(thoroughness=...)` | `AuditResult` | 完整的红队测试：越狱 + softprompt + surface + guard | | `s.evaluate()` | `EvalResult` | 拒绝率 + 困惑度 + KL 散度 | | `s.probe("prompt")` | `ProbeResult` | 每层对拒绝方向的投影 | | `s.scan("text")` | `ScanResult` | 逐 token 的注入检测 | | `s.surface()` | `SurfaceResult` | 跨提示词类别映射拒绝边界 | | `s.cast("prompt", threshold=0.3)` | `CastResult` | 条件激活引导（防御） | | `s.sic(["prompt", ...])` | `SICResult` | 迭代输入清理（防御） | | `s.steer("prompt", alpha=-1.0)` | `str` | 无条件激活引导 | | `s.cut(alpha=1.0)` | `dict[str, Array]` | 从权重中移除拒绝方向 | | `s.export("output/")` | `str` | 将修改后的模型保存到磁盘 | | `s.classify("text")` | harm scores | 根据 13 个领域的伤害分类体系进行评分 | | `s.score("prompt", "response")` | score result | 5 轴质量评估 | | `s.report()` | `str` | 根据审计结果生成 Markdown 报告 | ### 结果类型 **DirectionResult**（来自 `measure`）：`direction`（Array，形状为 d_model），`layer_index`（最佳层），`cosine_scores`（各层分离度），`d_model`，`model_path`。 **CastResult**（来自 `cast`）：`text`（生成的输出），`interventions`（CAST 进行了引导的 token，0 = 防御未启动），`considered`（总 token 数），`projections_before`/`projections_after`（各层）。 **SICResult**（来自 `sic`）：`prompts_clean`（清理后的文本），`prompts_blocked`（每个提示词的布尔值），`initial_scores`/`final_scores`（方向投影），`total_blocked`/`total_sanitized`/`total_clean`。 **DetectResult**（来自 `detect`）：`hardened`（布尔值），`confidence`（0.0-1.0），`effective_rank`（>1.5 表示已强化），`evidence`（字符串列表）。 **AuditResult**（来自 `audit`）：`overall_risk`（"critical"/"high"/"medium"/"low"），`findings`（AuditFinding 列表），`jailbreak_success_rate`，`softprompt_success_rate`，`surface_refusal_rate`。 ### 决策指南 | 我想要... | 使用 | |--------------|-----| | 了解模型拒绝什么 | `measure()` 然后 `surface()` | | 检查模型是否已强化 | `detect()` | | 完整的安全审计 | `audit()` 然后 `report()` | | 防御对抗性输入 | `measure()` 然后 `sic()` + `cast()` | | 永久移除拒绝行为 | `measure()` 然后 `cut()` 然后 `export()` | | 评估响应质量 | `score("prompt", "response")`（无需模型） | ### 前置条件 ``` model (loaded at Session init) ├── measure() → direction │ ├── probe(), scan(), surface() │ ├── steer(), cast(), sic() │ ├── evaluate() │ └── cut() → modified_model → export() ├── detect(), audit() → report() └── jailbreak() classify(), score() → no prerequisites ``` ## 文档 完整文档：[docs.vauban.dev](https://docs.vauban.dev/) | 资源 | 描述 | |----------|-------------| | [概念](https://docs.vauban.dev/concepts/activation-geometry/) | 领域知识：激活几何、拒绝方向、测量、引导 | | [能力](https://docs.vauban.dev/capabilities/understand-your-model/) | 你可以做什么：理解、防御、压力测试、修改 | | [原则](https://docs.vauban.dev/principles/attack-defense-duality/) | 设计理念：二元性、可组合性、可重现性 | | [Abliteration 入门](https://docs.vauban.dev/class/) | 八部分渐进式课程 | | [配置参考](https://docs.vauban.dev/config/) | TOML 字段参考 | | [`examples/config.toml`](examples/config.toml) | 带有注释的示例配置 | ## 许可证 Apache-2.0

标签：Apex, Apple Silicon, CISA项目, DLL 劫持, Linux系统监控, LLM攻击, MLX, Python, Python安全, TOML配置, 人工智能, 大语言模型, 密码管理, 对抗性机器学习, 无后门, 服务器监控, 机器学习, 模型优化, 模型修剪, 模型安全, 模型干预, 模型微调, 模型行为分析, 模型防御, 激活空间几何, 特征提取, 用户模式Hook绕过, 稀疏化, 逆向工具