让模型成为可执行工件:LARQL VINDEX3格式设计与encode/run/observe全流程

原创2026-10-14 12:29:011,359 阅读

让模型成为可执行工件: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 让模型像程序一样被编码、执行、观测——架构知识留在前端编译器里,后端执行器永远只认容器。🔍

登录后查看全文
larql