让模型成为可执行工件:LARQL VINDEX3格式设计与encode/run/observe全流程
让模型成为可执行工件:LARQL VINDEX3格式设计与encode/run/observe全流程
LARQL 是 VINDEX3 格式的代表性参考实现,一个把模型当作"可执行工件"来执行、查询与研究的开源系统。VINDEX3 将模型检查点编译为自描述、可校验、可独立运行的容器,让模型不再只是"一堆权重文件"。本文将用面向新手的方式讲清楚 VINDEX3 格式的设计核心,并完整走通 encode(编码)、run(运行)、observe(观测)三大全流程。🚀
一、为什么模型不再只是"权重文件"
一次现代模型发布往往不是一个权重文件,而是一个系统:目标模型、内嵌在同一检查点里的感知塔、通过声明式接口消费隐状态的投机 drafter、同一逻辑操作数的多个量化配置。
传统格式(如 GGUF)回答的是"如何存储和运行这些张量";而 LARQL 的 VINDEX3 回答的是更根本的问题:
这些模型对象是什么?哪些操作能消费它们?哪些表示是等价的?哪些部分应该常驻?未来的计算还需要它们做什么?
为此,VINDEX3 采用了一条刻意设计成"编译器形状"的流水线:
HF artifacts → inventory(G0 源语义)→ representability(G1/G2 类型检查)
→ system graph(G2 语义 IR)→ physical encoding(G3 物化)
→ verification(G4 四权威校验)→ execution(G5 仅凭容器执行)
这条流水线背后有 4 条设计原则(详见 docs/vindex3-format.md):
| 原则 | 含义 |
|---|---|
| 单一语义权威 | 系统图只构建一次,planner、编码器、执行器都消费它,绝不各自重新解释检查点 |
| Fail-closed | 未判定的配置键、无主的张量组直接阻断,"没判过"不等于"可接受" |
| 无静默转换 | 张量按生产者写入的样子摆放,默认值绝不冒充声明值 |
| 无模型族分支 | 角色与策略来自证据(声明接口、形状算术),而非 model_type 匹配 |
简单说:架构是容器描述的一个"实例",而不是执行器内置的"实现"。
二、VINDEX3 格式设计核心:系统图 + 容器布局
2.1 系统图(SystemGraph)
VINDEX3 把模型结构显式表达为一张系统图,由三部分构成:
SystemGraph
├── components 组件(target / vision / draft),角色由证据推导
├── objects 逻辑对象(embedding、decoder_stack、output_head…)
└── edges 隐状态边(HiddenStateEdge:跨组件的逻辑数据流)
关键设计:逻辑对象的身份是概念性的,物理张量名可以绑定对象但永远不定义身份。这正是同一个 decoder_stack 可以同时拥有 BF16 规范字节、K-quant 量化包、Metal 原生打包等多种表示,而所有引用一个都不用改动的原因。
2.2 容器布局:编码完成后,HF 检查点即"退休"
执行 encode 后产出一个自包含目录:
<container>/
├── index.json 唯一根权威:格式版本、图引用、表示→段文件目录
├── system_graph.json 系统图,逐字保存
└── segments/
├── target.decoder_stack.bin
├── target.embedding.bin
├── vision.perception_tower.bin
└── draft.decoder_stack.bin
从此,图的边不再引用任何 safetensors 文件名——原始 HF 检查点从编码完成那一刻起就不再是权威。每个规范表示还记录源载荷 SHA-256 哈希,为后续字节级校验埋下伏笔。
2.3 G4 验证:四个权威必须一致
vindex verify 会把四个权威做结构化 + 语义比较:
| 权威 | 来源 |
|---|---|
| Declared | HF 声明了什么(config.json、分片头) |
| Resolved | LARQL 解释出了什么 |
| Graph | G2 构建的逻辑系统 |
| Encoded | 容器里实际装了什么 |
不变量是 Declared ≡ Resolved ≡ Graph ≡ Encoded,再加上逐表示的字节载荷哈希等价。"编码前后张量数量相同"不算验证,张量表(名、dtype、形状、偏移、长度)必须逐条比对——因为对相同字节重贴 dtype 标签,容器里任何哈希都看不出来。完整的格式契约见候选规范。
三、encode 流程:四条命令产出可校验容器
用仓库固定版本构建 vindex-cli 与 larql-cli 后,一条典型工作流只有四条命令(完整说明见 docs/vindex3/execution.md):
vindex plan /path/to/checkpoint --json # G1/G2 语义可表示性计划
vindex encode /path/to/checkpoint --output model.vindex3 # G3 编码
vindex inspect model.vindex3 # 仅凭容器重建整个系统
vindex verify model.vindex3 # G4 四权威 + 字节校验
各步骤的职责边界非常清晰:
- plan:输出类型化的 findings(representable / mismatched / unrepresented / interface),存在阻断项时以非零退出码结束,方便脚本化门禁;
- encode:只消费构建好的系统图,拒绝不可表示的计划——"消除两个语义权威之后又引入一个"是明令禁止的回归;
- inspect:验证路径拿不到源检查点,没有 transformers config、没有 HF 文件名,全部从容器自身重建;
- verify:两端重新哈希,检查点漂移(source ≠ recorded)与容器损坏(encoded ≠ recorded)会以不同方式失败。
💡
plan和encode还支持hf://org/repo@revision形式的远端源,计划会记录其不可变 commit,保证两个判定版本可比。
四、run 流程:零架构分支执行容器
编码只是开始,VINDEX3 最有野心的承诺在运行阶段——仅用容器里已有的语义信息执行系统。
larql vindex3 ops model.vindex3 # 输出通用操作程序
larql vindex3 exec model.vindex3 \
--backend production --tokens 1,2,3 --generate 8 # 仅凭容器执行
larql run model.vindex3 # 文进文出的交互外壳
larql serve model.vindex3 --port 8080 # HTTP 服务面
执行器只拥有通用操作(embedding、norm、attention、RoPE/NoPE、滑动/全注意力 span、FFN 激活、线性层、感知塔投影、drafter 验证),并遵守严格的"删除不变量":
- ❌ 没有
if family == X分支——span、window、位置策略全部读自容器内持久化的AttentionLayerPolicy逐层表; - ❌ 没有
layer % 4 == 3这类层模式算术——交错已在构建期展开成表; - ❌ 没有硬编码 tap 常量——drafter 从
HiddenStateEdge里发现自己该从哪些层采隐状态。
删除原始检查点、config.json、HF 模型类型和架构名,执行结果必须不变。同一份操作计划还可以跑在 naive f32 参考实现、larql-compute 生产内核或 Metal 后端上——只有算术不同,解释器和模型语义完全共享(运行时栈见 docs/vindex3-runtime.md)。
ops 命令背后是"操作数闭合"门禁:每个张量必须归类到某个通用操作消费的角色,未归类的操作数直接阻断。这正是 VINDEX3 能"先发现缺失、再拒绝执行"而不是"尽力而为跑一半"的底气。
五、observe 流程:让模型留下可审计的执行证据
VINDEX3 把"观察"提升为一等公民:一次解码可以留下带身份、带出处、带回执的证据记录。
larql vindex3 observe model.vindex3 --backend production \
--prompt "The capital of France is" --record run.jsonl
Observatory 可视化平台 LARQL VINDEX3 Observatory 观测平台预览:观看模型计算逐层展开
记录内容包含:
- 载体写记录:哪个执行边界、写了什么、规范与增量统计(载体观测);
- 可选透镜:用执行镜像自己的归一化和词表头读取状态(logit lens 需
--lens-tokens显式武装); - 运行身份与出处:模型/表示身份、事件、已验证回执;
- 干预声明:
--intervene declarations.json支持对载体与注意力头做zero/add/replace等受控反事实实验。
产出的 JSONL 可导入 Observatory 做结构化校验与回放。需要强调的是证据边界:投影出来的贡献不是因果;归因需要真实的干预加声明过的对照(详见 observation-and-intervention.md)。
六、进阶:用 represent 编译"带证据的替代表示"
VINDEX3 把逻辑身份与物理编码分离后,量化不再是"换个格式重新打包",而是在同一系统图旁编译一个新的表示包:
larql vindex3 represent model.vindex3 --output deploy-nvfp4.vindex3 \
--encoding NVFP4 --deployment
- 每个编译对象写入
segments/<object>@<ENCODING>.bin,在系统图中标记为approximate; --protect v_proj --protect-layers 0-1可把关键投影保在源精度;- "更小的包"本身不是行为可接受的证据——
token-bank+measure会在密封词元库上双臂强制对照,输出 KL、top-1 一致率与回执,Inadmissible状态意味着"数字存在但不是证据"。
完整策略见 docs/vindex3/representation.md。
七、小结:一张能力地图
| 动词 | 命令 | 回答的问题 |
|---|---|---|
| encode | vindex plan / encode / inspect / verify |
源系统能不能被如实装进容器? |
| run | larql vindex3 ops / exec / run / serve |
能否仅凭容器执行且结果可校验? |
| observe | larql vindex3 observe |
计算实际写了什么?留下什么证据? |
| represent | larql vindex3 represent / measure |
替代表示的质量证据是什么? |
对新手最实用的切入路径:先读 What is VINDEX3? 建立概念,再按 execution 指南 跑通 plan → encode → exec → observe,最后用 status 页 对照当前已实现与规划中的能力边界(分片执行、多模态 embedding 交接目前仍被显式拒绝)。更多 crate 分工与层间关系可查阅 docs/vindex3/architecture.md,全部子命令参考见 docs/cli.md。
一句话总结:LARQL 的 VINDEX3 让模型像程序一样被编码、执行、观测——架构知识留在前端编译器里,后端执行器永远只认容器。🔍