RAG 架构演进：从 macOS 本地推理到跨环境部署的生死考验

在开发 Sparkle 的过程中，我们利用 Apple Silicon 的强劲性能，通过 MLX 框架构建了一套极速的本地 RAG（检索增强生成）系统。这种“本地优先”的策略在 M1/M2/M3 机型上表现惊艳：零网络延迟、零成本 API 调用、极致的响应速度。

然而，当我们试图将这套架构从开发者手中的 MacBook 移动到通用的 Linux VPS（Docker 环境）时，系统在 RAG 触发（调用 askQuestion）的一瞬间直接崩溃。

本文记录了这次从“本地自嗨”到“跨环境交付”过程中的四个致命冲突点及其解决方案。

1. 致命的技术冲突：为什么 VPS 跑不动本地模型？

在现有的 Docker 体系下直接部署当前架构，会引发一系列连锁报错。核心原因在于我们的 AI 逻辑与操作系统环境耦合过深。

冲突一：硬件架构的不可调和 (MLX 与 Linux)

我们使用的 packages/sentinel/scripts/mlx_embed.py 脚本极其依赖 mlx_embeddings。

冲突二：Docker 镜像的极简主义

当前的 Dockerfile 采用的是 node:20-alpine 基础镜像。

• 环境缺失：Alpine 镜像中不仅没有 python3，更没有复杂的 AI 推理库。
• 体积矛盾：如果强行在 Docker 中安装 Python 链，Web 容器的大小将从几百 MB 膨胀到数 GB。

冲突三：硬编码的命令路径

在 packages/ai/src/index.ts 中，我们存在硬编码行为：

const uvPath = "/opt/homebrew/bin/uv";

/opt/homebrew 是 macOS Homebrew 的专属路径。在 Linux 容器中，这个路径不复存在，调用 spawnSync 会直接抛出 ENOENT 错误。

冲突四：Next.js Standalone 的隔离

Next.js 的 standalone 模式只会打包追踪到的依赖。

• 物理隔离：它不会自动将工作区外层的 packages/sentinel/scripts/ 目录打包进最终容器。这意味着即使环境配好了，生产环境也找不到 .py 脚本文件。

2. 深度剖析：前端为什么要当场做 Embedding？

这是一个典型且容易产生疑惑的问题：既然数据已经存进数据库了，前端只是“拉数据”，为什么还要跑模型？

RAG 的“对等”原则

前端调用 Embedding 模型不是为了解码，而是为了编码。

1. 用户提问：用户发送：“如何优化 Next.js 渲染？”
2. 即时向量化：代码必须把这句“人话”转换成一组高维数组（如 [0.015, -0.42, ...]）。
3. 坐标匹配：Neon 数据库利用 pgvector 进行数学比对，寻找与提问向量“距离最近”的内容。

结论：如果前端无法产生提问的向量，数据库就不知道该返回哪些知识片段。

3. 演进方案：三条可选的架构升级路线

针对上述冲突，我们权衡了以下三种解法：

方案 A：全流程切换为云端 API (最推荐)

将本地 MLX 模型计算全部替换为统一的线上接口（如 DeepSeek、SiliconFlow 的 BGE 、或 OpenAI）。

• 优势：彻底实现 Frontend Docker 与 Python 环境解耦。
• 落地：保证入库向量与查询向量使用同一个算子，检索精度最高。

方案 B：引入跨平台推理引擎 (Transformers.js)

在 Node.js 侧引入 @huggingface/transformers (v3)，使用 C++/Wasm 运行时。

• 逻辑：在收到问题后，直接用 pure-JS/Wasm 推理执行编码，无需安装臃肿的 Python 链。
• 注意：必须确保导出的 ONNX 模型与本地 MLX 跑的模型在表征上保持一致。

方案 C：胖容器模式 (不推荐)

改用 python:3.11-slim 基础镜像，手工复制脚本。

总结：目前的最佳实践

为了在保证本地开发体验的同时实现顺滑的 VPS 部署，我们的优化方向是：

• Sentinel（入库端）：保留 macOS 本地加速优势或使用 API。
• Frontend（查询端）：优先采用方案 A（API 统合）或方案 B（轻量化 Wasm 算子）。

这种“逻辑对等、计算解耦”的策略是 RAG 系统走出实验室、迈向生产环境的必经之路。

相关阅读：

• RAG 语义表征基础
• 2026 本地检索模型选型指南