Web 运行时与类型化工件

@arti-fit/web 是 Alpha、仅推理的绑定。Python 定义并导出计算图；浏览器验证工件、选择执行设备、运行具名 float32 张量并释放资源。JavaScript 不会重新实现 Half、Fold、Pulse、Recall 或其他 ARTI 机制。

导出契约

import arti

result = arti.web.export(
    layer,
    "layer-web",
    example_inputs={"x": x},
)

格式 v2 工件包含 model.onnx、arti-web.json、arti-web.lock.json 与 artifact.ts。生成的 TypeScript 客户端属性名来自已哈希的 manifest。单输入单输出工件提供 forward()；具名多输入图提供类型化 run()。

面向应用的推理接口

import { loadArti } from "@arti-fit/web";

const module = await loadArti("/layer-web/", {
  device: "auto",
  signal: abortController.signal,
  onProgress: ({ stage, loadedBytes, totalBytes }) => {
    console.log(stage, loadedBytes, totalBytes);
  },
});

const output = await module.predict({
  x: { data: values, dims: [batch, tokens, dim] },
});
console.log(output.y.data);
await module.dispose();

predict() 接受 CPU 常驻的 float32 数据，并负责其创建的临时 ONNX Runtime 张量。需要让输出保留在 GPU 或由调用方管理缓冲区时，使用底层 run() API。

由 Python 拥有的可检查运行

ARTI 1.7.0 与 @arti-fit/web 0.1.0-alpha.5 可以从模块真实的 forward(..., return_info=True) 结果中导出选定 tensor leaf。Python 在带哈希的 manifest 中声明每个输出的名称、dtype、logical type、role、dynamic axes、字节预算和数值容差。

result = arti.web.export(
    fusion,
    "fusion-web",
    example_inputs={"pulses": pulses, "mask": mask, "source_mask": source_mask},
    forward_kwargs={"return_info": True},
    include_outputs=("fused", "survival", "workspace", "unfold_source_index"),
)

const result = await module.inspect(
  { pulses, mask, source_mask },
  { outputs: ["fused", "survival", "workspace", "unfold_source_index"] },
);
console.log(result.device, result.timings.inferenceMs);
const { workspace } = await result.download(["workspace"]);
await result.dispose();

inspect() 只要求 ONNX Runtime 获取被选中的、由 Python 声明的输出。在 WebGPU 上，保留输出会一直停留在设备上，直到显式调用 download()。OwnedRunResult 必须释放；释放父 module 也会让所有保留或执行中的结果失效。workspace、diagnostic、mask、index 等角色对 JavaScript 而言只是元数据，不是第二套 ARTI 机制实现。

工作区证据实验室会运行仓库锁定的 FusionPulse fixture，并把浏览器结果与 Python parity 数据核对。

设备与失败行为

device: "auto" 会尝试 WebGPU，并可回退到 WASM。锁定 WebGPU 时必须暴露失败，不能静默切换 provider。ArtiWebError 提供稳定的 code、stage、已清理的工件 URL、设备和张量契约上下文。加载进度覆盖 manifest、lock、模型、校验、初始化和 ready 阶段。

Stateful Recall

Stateful Recall 使用成对的 Python 导出 read/update 图与显式固定尺寸状态。浏览器 API 支持 commit、snapshot、restore、fork、异步 reset 与 dispose，并允许调用方设置状态和工件总大小预算。这是有界推理状态，不是浏览器训练或无限内存。

Module Worker

参考 Worker 协议支持 load、run、inspect、dispose 与 cancel，并且只在线程间转移 CPU ArrayBuffer。WebGPU 张量、GPU buffer 和 OwnedRunResult 始终由 Worker 持有。取消是协作式的：进行中的 ONNX 调用可能完成，但其过期结果会被抑制并释放。

信任边界

Manifest 与 lock 哈希只能检测相对于该 lock 的漂移，不能证明发布者身份。应从可信来源托管工件，强制大小预算，验证张量名称与 shape，并释放所有由调用方拥有的 module 和 tensor 生命周期。