Config模块架构

目标

Config模块提供灵活的 ONNX Runtime 配置以解决： 1. 硬编码路径 – 避免将 WASM 位置写入源文件。 2. 时序问题 – 处理 ORT 在配置之前或之后加载的情况。 3. 适应性 – 支持单个或多个回退路径。

设计

模块结构

Config模块
├─ 路径存储 (模块级状态)
├─ 初始化器 (initOrtEnvironment)
├─ 路径设置器/获取器
└─ 实用辅助函数 (延迟应用、验证)

配置流程

应用引导 – App 模块在 App.init() 期间调用 initOrtEnvironment()
路径配置 – 通过 setOrtWasmPaths() 设置路径，或直接传递给 initOrtEnvironment()
ORT 可用性检查 – 检查 ORT 是否已加载：
是 → 立即通过 ort.env.wasm.wasmPaths 应用配置
否 → 启动轮询机制，在 ORT 加载时应用配置
配置已应用 – 当路径成功设置时记录确认信息

延迟配置

如果配置运行时 ORT 不存在，模块会轮询直到其加载： - 轮询间隔：50 ms。 - 一旦 window.ort 可用，路径即被应用，轮询停止。 - 避免阻塞主线程。

轮询策略： - 轮询间隔: 50ms（非阻塞） - 轮询函数: applyConfigWhenReady() 检查 window.ort 可用性 - 自动应用: 一旦 window.ort 可用，路径即被应用，轮询停止 - 非阻塞: 使用 setTimeout 避免阻塞主线程

实现：

const applyConfigWhenReady = () => {
  if ((window as any).ort) {
    const ort = (window as any).ort;
    ort.env.wasm.wasmPaths = getOrtWasmPaths();
    console.log(`[Visionary] ONNX Runtime WASM 路径已配置（延迟）: ${getOrtWasmPaths()}`);
  } else {
    // 如果 ORT 尚未可用，继续轮询
    setTimeout(applyConfigWhenReady, 50);
  }
};

优势： - 无论 ORT 加载顺序如何都能工作 - 无阻塞操作 - 自动重试直到 ORT 可用 - 清晰的日志记录便于调试

路径配置

路径格式

单个路径: '/src/ort/' → 按原样存储
多个路径: ['/path1/', '/path2/'] → 存储为 '/path1/,/path2/'（逗号分隔）

路径应用

最终值设置在 ort.env.wasm.wasmPaths 中。ORT 按顺序尝试每个位置，直到文件解析成功：

首先尝试第一个路径
如果文件未找到，尝试第二个路径
继续直到找到文件或所有路径都尝试完毕

默认路径

模块提供默认路径：/src/ort/

在以下情况下使用： - 调用 initOrtEnvironment() 时未提供参数 - 显式调用 getDefaultOrtWasmPaths()

路径存储

路径存储在模块级状态中：

let ortWasmPaths: string = '/src/ort/';

这确保： - 配置在函数调用之间持久化 - 可以在 ORT 可用之前设置 - 可以随时通过 getOrtWasmPaths() 检索

错误处理

Config模块使用优雅的错误处理方法：

警告（非致命）

ORT 不可用: 记录警告但不抛出异常：

console.warn('[Visionary] ONNX Runtime 不可用，配置将在 ort 加载时应用');

- 延迟应用: 自动启动轮询机制

成功日志

立即应用: 当 ORT 已加载时记录：

console.log(`[Visionary] ONNX Runtime WASM 路径已配置: ${getOrtWasmPaths()}`);

- 延迟应用: 在轮询后应用配置时记录：

console.log(`[Visionary] ONNX Runtime WASM 路径已配置（延迟）: ${getOrtWasmPaths()}`);

配置验证

使用 isOrtConfigured() 验证配置状态：

if (isOrtConfigured()) {
  console.log('ORT 已就绪并已配置');
} else {
  console.warn('ORT 配置待处理...');
}

使用模式

1. 在引导期间配置（推荐）

由 App 模块在初始化期间使用：

import { initOrtEnvironment, getDefaultOrtWasmPaths } from 'src/config';

// 在 App.init() 中
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);

2. 使用自定义路径配置

在初始化之前显式设置路径：

import { setOrtWasmPaths, initOrtEnvironment } from 'src/config';

setOrtWasmPaths('/custom/ort/path/');
initOrtEnvironment();

3. 多个回退路径

提供多个路径以实现冗余：

setOrtWasmPaths([
  'https://cdn.example.com/ort/',  // 首先尝试 CDN
  '/local/cache/ort/',              // 回退到本地缓存
  '/src/ort/'                       // 最终回退
]);
initOrtEnvironment();

4. 检查配置状态

在加载模型之前验证 ORT 是否就绪：

import { isOrtConfigured, initOrtEnvironment } from 'src/config';

if (!isOrtConfigured()) {
  initOrtEnvironment();
  // 等待延迟配置
  setTimeout(() => {
    if (isOrtConfigured()) {
      console.log('ORT 就绪');
    }
  }, 100);
}

5. 运行时路径更新

动态更新路径（罕见用例）：

// 获取当前路径
const currentPaths = getOrtWasmPaths();

// 使用新路径更新
setOrtWasmPaths(['/new/path/']);
initOrtEnvironment();

集成点

App 模块集成

App 模块自动初始化 ORT 配置：

// 在 App.init() 中 - 第 110-113 行
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);
console.log(`[App] 使用路径初始化 ORT 环境: ${wasmPaths}`);

时序： 1. ORT 配置首先发生（在 WebGPU 初始化之前） 2. WebGPU 初始化可能与 ORT 共享设备 3. 配置后可以加载 ONNX 模型

ONNX 模块依赖

ONNX 模块依赖 Config模块以确保： - ORT 环境已正确配置 - 在模型加载之前设置 WASM 路径 - GPU 设备共享正常工作

WebGPU 上下文集成

initWebGPU_onnx() 函数受益于 ORT 配置： - 共享设备创建需要配置 ORT - 必须设置 WASM 路径才能使 ORT 工作 - 配置确保 ORT 和 WebGPU 之间的兼容性

模块状态

Config模块维护内部状态：

let ortWasmPaths: string = '/src/ort/';

状态管理： - 模块级存储 – 在函数调用之间持久化 - 无公共状态对象 – 为安全而封装 - 获取器函数 – getOrtWasmPaths() 提供读取访问 - 设置器函数 – setOrtWasmPaths() 提供写入访问