跳转至

Config模块 API 参考

Config模块管理 Visionary 的 ONNX Runtime (ORT) 配置。使用它来设置 WASM 资源路径并在运行推理之前初始化 ORT。

目录

函数

setOrtWasmPaths(paths: string | string[]): void

存储一个或多个候选 WASM 基础路径。

参数： - paths – 单个字符串或字符串数组。尾随斜杠是可选的。

行为： - 单个路径：按原样存储（例如，'/src/ort/'） - 多个路径：用逗号连接（例如，['/path1/', '/path2/'] → '/path1/,/path2/'） - 模块在内部保留该值，直到 ORT 就绪 - 提供多个路径时，ORT 按顺序尝试每个位置，直到文件解析成功

示例：

setOrtWasmPaths('/custom/ort/path/');
// 或
setOrtWasmPaths(['https://cdn.example.com/ort/', '/local/ort/']);

getOrtWasmPaths(): string

返回当前配置的 WASM 路径。

返回： - 当前路径字符串（如果多个路径则用逗号分隔） - 默认值：如果未设置路径，则为 '/src/ort/'

示例：

const paths = getOrtWasmPaths();
console.log(paths); // '/src/ort/' 或 '/path1/,/path2/'

getDefaultOrtWasmPaths(): string

获取模块使用的默认 WASM 路径。

返回： - 默认路径字符串：'/src/ort/'

用例： - 由 App 模块在初始化期间使用 - 为开发环境提供合理的默认值

示例：

const defaultPath = getDefaultOrtWasmPaths();
initOrtEnvironment(defaultPath);

initOrtEnvironment(wasmPaths?: string | string[]): void

使用配置的路径初始化 ONNX Runtime。

参数： - wasmPaths – 可选的要使用的路径。如果提供，首先调用 setOrtWasmPaths()。如果未提供，使用先前设置的路径或默认值。

行为： 1. 设置路径（如果提供）通过 setOrtWasmPaths() 2. 检查 ORT 可用性： - 如果 ORT 已加载：立即通过 ort.env.wasm.wasmPaths 应用路径并记录成功 - 如果 ORT 未加载：启动轮询机制（50ms 间隔）在 ORT 可用时应用路径 3. 日志记录：记录配置成功或警告消息

注意： 此函数是同步的（不返回 Promise）。延迟配置通过轮询自动发生。

示例：

// 使用默认路径
initOrtEnvironment();

// 使用自定义路径
initOrtEnvironment('/custom/ort/');

// 使用多个路径
initOrtEnvironment(['/path1/', '/path2/']);

isOrtConfigured(): boolean

检查 ONNX Runtime 是否已正确配置。

返回： - 如果 ORT 已加载且 ort.env.wasm.wasmPaths 设置为真值，则返回 true - 如果 ORT 不可用或链的任何部分缺失，则返回 false - 如果 ORT 已加载但 ort.env.wasm.wasmPaths 显式设置为 undefined，则返回 undefined

注意： 由于实现使用逻辑 AND (&&) 运算符，如果 wasmPaths 是 undefined，函数可能返回 undefined 而不是 false。为了类型安全，在检查结果时考虑使用 !!isOrtConfigured() 或显式布尔转换。

实现：

return typeof window !== 'undefined' && 
       (window as any).ort && 
       (window as any).ort.env && 
       (window as any).ort.env.wasm && 
       (window as any).ort.env.wasm.wasmPaths;

用例： - 在加载 ONNX 模型之前验证 ORT 是否就绪 - 在错误处理中检查配置状态

示例：

// 推荐：使用布尔转换以确保类型安全
if (!!isOrtConfigured()) {
  console.log('ORT 已就绪');
  // 可以安全地加载 ONNX 模型
} else {
  console.warn('ORT 配置待处理...');
  initOrtEnvironment();
}

// 或显式检查
const configured = isOrtConfigured();
if (configured === true) {
  console.log('ORT 已就绪');
} else {
  console.warn('ORT 配置待处理...');
  initOrtEnvironment();
}

使用模式

基本用法（App 模块模式）

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

// 在应用初始化期间
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);
console.log(`ORT 环境已使用路径初始化: ${wasmPaths}`);

自定义路径配置

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

// 显式设置路径
setOrtWasmPaths('/custom/ort/path/');
initOrtEnvironment();

多个回退路径

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

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

配置验证

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

// 初始化
initOrtEnvironment();

// 检查是否已配置
if (isOrtConfigured()) {
  console.log('ORT 就绪:', getOrtWasmPaths());
} else {
  console.warn('ORT 仍在初始化...');
  // 等待延迟配置
  setTimeout(() => {
    if (isOrtConfigured()) {
      console.log('ORT 现在已就绪');
    }
  }, 100);
}

与 App 模块集成

App 模块在初始化期间自动调用此函数：

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

重要： 在以下操作之前调用 initOrtEnvironment： - 加载 ONNX 模型 - 初始化 WebGPU（如果使用 ORT 设备共享） - 运行 ONNX 推理

这确保 GPU 缓冲区与渲染器保持兼容，并且 ORT 可以找到其 WASM 文件。