在现代 AI 开发中，笔记本工具已成为研究者和工程师的核心工作台。然而，传统云依赖的笔记本往往受限于网络延迟、隐私风险和供应商锁入。Deta Surf 等 local-first AI 笔记本的兴起，提供了一种工程化方案：支持离线 AI 推理、实时协作和无缝同步。本文聚焦于使用 ONNX Runtime Web 实现离线推理、Yjs 基于 CRDT 的协作机制，以及无锁入的本地-云同步策略。通过这些技术栈，我们可以构建高效、隐私友好的 AI 工作环境。
离线 AI 推理：ONNX Runtime Web 的工程实践
观点：离线 AI 推理是 local-first 笔记本的核心，允许用户在无网络环境下运行模型，减少延迟并保护数据隐私。ONNX Runtime Web 作为浏览器友好的推理引擎，是 Electron-based 笔记本的理想选择。
证据：ONNX (Open Neural Network Exchange) 是一种跨框架的模型格式，支持从 PyTorch 或 TensorFlow 导出模型。ONNX Runtime Web 通过 WebAssembly (WASM) 和 WebGL 后端，在浏览器中实现近原生性能推理。根据微软官方文档，ORT Web 可加速 CPU/GPU 推理，支持多平台部署。在 Deta Surf 中，本地模型集成允许用户加载 ONNX 格式文件，直接在笔记中生成内容，而无需云 API 调用。
可落地参数/清单：
- 模型准备：使用
torch.onnx.export 将 PyTorch 模型转换为 ONNX 格式，确保 opset_version ≥ 11 以兼容 Web 后端。量化模型 (e.g., INT8) 以减少大小至 100MB 以内。
- 集成步骤：
- 安装
onnxruntime-web via npm。
- 在 Electron 渲染进程中加载：
const session = await ort.InferenceSession.create('./model.onnx', { executionProviders: ['webgl'] });。
- 输入预处理：使用 Tensor 对象包装数据，e.g.,
new ort.Tensor('float32', inputData, [1, 3, 224, 224])。
- 运行推理：
const output = await session.run({ input: inputTensor });。
- 性能阈值：针对消费级硬件，设置 batch_size=1，监控推理时间 < 500ms。使用 Web Workers 隔离计算，避免 UI 阻塞。
- 监控点：集成性能日志，追踪加载时间 (目标 < 2s) 和内存使用 (< 500MB)。回滚策略：若 WebGL 不可用，fallback 到 WASM CPU 后端。
- 风险缓解：浏览器兼容性测试 (Chrome 90+、Firefox 90+)，处理 OOM 错误通过模型分片。
这种方案确保了笔记本的离线可用性，例如在航班上分析 PDF 时，直接运行本地 ONNX 模型生成摘要。
实时协作：Yjs 基于 CRDT 的机制
观点：实时协作是多用户场景下的必需，但传统锁机制会牺牲可用性。Yjs 的 CRDT (Conflict-free Replicated Data Types) 实现允许无冲突合并，支持离线编辑和 P2P 同步，完美契合 notebook 架构。
证据：Yjs 是一个网络无关的 CRDT 框架，支持共享类型如 Y.Text、Y.Array，用于富文本笔记。社区基准显示，Yjs 在合并 1000+ 操作时性能优于 Automerge，O(log N) 复杂度。Deta Surf 使用 Tiptap 编辑器 (兼容 Yjs binding)，允许 @-mention 生成笔记，并在多用户间同步，而无需中央服务器。
可落地参数/清单：
- 数据建模：使用 Y.Doc() 创建共享文档，Y.Text('notes') 存储富文本。集成 Tiptap：
new Y.Tiptap(ydoc.getText('content'), editor)。
- 同步提供者：
- WebSocket：
new WebsocketProvider('ws://localhost:1234', 'room', ydoc)，适合云同步。
- WebRTC：P2P 模式，
new WebRTCRoomProvider(...)，用于低延迟协作。
- IndexedDB：本地持久化，
new IndexeddbPersistence('doc-id', ydoc)。
- 协作参数：Awareness 模块显示用户光标，设置
user: { name: 'User1', color: '#ff0000' }。UndoManager 配置：new Y.UndoManager(ytxt, { clientId })，仅撤销本地操作。
- 阈值与优化：限制文档大小 < 1MB，批量更新操作 (debounce 100ms)。监控合并冲突率 < 1%，使用向量时钟确保因果顺序。
- 回滚策略：离线时缓存更新，重新连接后应用 Y.applyUpdate。测试场景：模拟 10 用户并发编辑，验证最终一致性。
Yjs 确保了 notebook 的协作流畅，例如团队实时审阅 AI 生成的代码块。
无锁入同步：本地-云策略
观点：无缝本地-云同步避免了供应商依赖，使用开放格式和去中心化协议，实现数据主权。
证据：Deta Surf 的 SFFS (Surf Flat File System) 使用开放格式存储库，支持离线访问和云备份。结合 Yjs 的增量同步，可实现双向云同步，而不绑定特定提供商。
可落地参数/清单：
- 存储格式：使用 JSON + Delta 编码 Yjs 状态，导出为 .surf 文件 (ZIP + manifest)。
- 同步流程：
- 本地变更：Yjs 更新后，序列化
Y.encodeStateAsUpdate(ydoc)。
- 云上传：使用 WebDAV 或 S3-compatible API (e.g., MinIO)，分块上传 (< 1MB/chunk)，支持断点续传。
- 冲突解决：云端合并使用 Yjs 的 merge 更新，优先本地版本。
- 拉取：
Y.applyUpdate(ydoc, cloudUpdate)，增量应用。
- 参数设置：同步间隔 5s (idle 时)，带宽限 1MB/s。加密：端到端 AES-256，密钥本地生成。
- 无锁入设计：支持多云 (AWS S3、Google Drive via API)，导出为 Markdown/JSON。监控同步延迟 < 2s，失败率 < 0.1%。
- 回滚：版本快照，每日备份，恢复点粒度 1h。
此策略让用户自由迁移数据，例如从本地到自建云。
总结与工程建议
通过 ONNX Runtime Web、Yjs 和开放同步，local-first AI 笔记本如 Deta Surf 实现了高效工程化。实际部署时，从小规模原型开始，逐步优化性能。未来，WebGPU 支持将进一步提升推理速度。
资料来源：