6.2 引入 Code Interpreter (代码沙盒执行器),终结数据幻觉
本节目标:把“让 LLM 口算/瞎猜”升级为“让 LLM 生成代码并在受控环境执行”,用可复核的计算结果替代“看似合理的自然语言结论”,并把执行过程纳入你现有的 BullMQ 异步任务与 WebSocket/SSE 实时回传体系。
6.2.1 为什么必须做 Code Interpreter:这是从 Demo 到可用产品的分水岭
在数据分析场景里,大模型的两类错误尤其致命:
- 计算型幻觉:总和、占比、环比、分位数、异常点等一旦算错,所有结论都崩
- 口径型幻觉:维度粒度混乱(按月/按周)、单位混乱(元/万元)、重复/缺失处理不一致
引入 Code Interpreter 的核心收益是:
- 结果可复核:每个数字来自一段可运行代码(或一次 SQL 查询)
- 可重复:同样的输入与代码,产出一致
- 可审计:可以保存代码、输入数据、输出摘要、耗时、资源消耗
- 可治理:可以做超时、限流、配额、禁网、白名单依赖等安全控制
6.2.2 选择哪种执行形态:三种路线与推荐
在 Node.js(NestJS)生态里常见有三种落地方式:
路线 A:Docker 隔离执行(推荐)
特点:
- 安全边界清晰:容器隔离 + 禁网 + 只读文件系统 + 资源限制
- 生态成熟:Python + pandas + duckdb + statsmodels 这些数据分析库都好用
- 可扩展:未来可以把执行器单独拆成微服务或 K8s Job
代价:
- 需要 Docker 运行时
- 冷启动会带来一点延迟(可通过镜像预热/长驻池化优化)
路线 B:WASM 执行(Pyodide / WebR 等)
特点:
- 不依赖 Docker,部署简单
- 理论上更易做沙箱
限制:
- 生态与性能不如原生 Python
- 与 Node 服务的集成、包管理、文件 IO 相对复杂
路线 C:Node 原生 VM/child_process(不推荐作为最终方案)
特点:
- 最好接入,最快跑通 Demo
风险:
- 很难做到强隔离(尤其是文件、网络、逃逸)
- 一旦做成产品,会在安全审计与多租户隔离上遇到大坑
结论:本项目的最佳路线是 A(Docker 隔离执行),并把执行放进 BullMQ Worker,避免阻塞 API。
6.2.3 执行器的“安全模型”:做产品必须具备的约束
无论你选择哪条路线,都建议把“安全约束”作为第一公民写进设计里:
资源限制(必须)
- 超时:例如 15s / 60s,按任务类型分级
- 内存:例如 512MB / 1GB
- CPU:例如 0.5 / 1 core
- 输出大小:stdout、结果 JSON、图表数据都要限制最大字节数
能力限制(强烈建议)
- 禁止外网:容器网络禁用,杜绝任意下载/回传
- 文件只读 + 临时目录:输入文件只读挂载,输出写到临时目录,任务结束销毁
- 依赖白名单:镜像内固定依赖版本,禁止 runtime pip install
数据与隐私(必须)
- 输入数据脱敏策略:日志里不得打印原始数据全量
- 结果可追踪但可控:保存“摘要 + 哈希”,需要时再走权限去拉原始产物
6.2.4 Agent ↔ 执行器协议:一定要结构化,拒绝自由文本
从 6.1 的多智能体骨架延续下来,Data Coder Agent 负责“生成执行计划”,执行器负责“按计划运行并返回结构化结果”。
建议定义一个统一的执行请求结构(并用 Zod 校验):
type ExecLanguage = 'python' | 'sql';
interface ExecRequest {
language: ExecLanguage;
code: string;
inputs: {
files?: Array<{ name: string; kind: 'csv' | 'json'; ref: string }>;
params?: Record<string, unknown>;
};
expected: {
resultKeys: string[];
};
}
返回结构:
interface ExecResponse {
ok: boolean;
stdout?: string;
stderr?: string;
results?: Record<string, unknown>;
artifacts?: Array<{ kind: 'plot' | 'table' | 'file'; name: string; ref: string }>;
metrics: { durationMs: number; cpuMs?: number; memoryMb?: number };
}
设计要点:
results必须是结构化 JSON(例如 tables、metrics、anomalies),而不是“把表格 print 出来”artifacts用于返回图片或文件(例如导出的聚合 CSV、生成的 plot)ref建议对接你在 Redis/DB 的 artifact 存储键(例如analysis:{id}:artifact:{name})
6.2.5 在 ai-data-analyzer 里怎么接:按步骤实现一条可用链路
下面按“从小到大”的路径给出落地步骤,保证每一步都能验收。
Step 1:先把“执行器”当成一种工具(Tool)
在 6.1 的工具体系里新增一个工具:
run_python:输入ExecRequest,输出ExecResponse
这一步的目标是:先跑通“LLM 生成代码 -> 执行 -> 回传结构化结果”的闭环。
Step 2:执行器服务化 + BullMQ Worker 化
建议将执行器放入 Worker(避免阻塞 API),并为其单独建立队列:
code-exec队列:专门执行代码沙盒任务
执行流程:
- Supervisor / Data Coder 生成
ExecRequest - 入队
code-exec - Worker 拉取任务 -> 调起 Docker 容器执行 -> 产出
ExecResponse - 写入 artifacts(Redis/DB/对象存储)并推送 WebSocket 状态
Step 3:结果回传与前端展示策略
建议把回传分成三类:
- 进度事件(WebSocket):
started / running / finished / failed - 可读输出(SSE):stdout 的“节选”或逐行流式输出(注意截断)
- 结构化产物(HTTP 拉取):图表数据、聚合表、异常点列表,按 artifact ref 获取
前端体验上,用户会明显感觉“AI 在做事”,而不是“等待一次性回答”。
Step 4:把 Data Coder 从“口算”升级为“默认写代码”
策略建议:
- 对所有涉及聚合/统计/排序/异常检测的任务,强制走执行器
- 只有纯文本总结、业务解释可以不走执行器
这样做能显著降低幻觉率,也能为 6.5 的“Token/成本账本”提供可解释的成本构成(LLM Tokens + Exec 耗时)。
6.2.6 典型任务模板:让 Agent 更稳定的关键
为了稳定产出,建议给 Data Coder 提供“任务模板”而不是让它自由写:
A. 数据剖析(Profile)
输入:CSV / JSON 表
输出(结构化):
- 字段类型推断(数值/类别/时间)
- 缺失率、重复率
- 数值字段的 min/max/mean/quantiles
- 类别字段 topK
B. 指标计算(Metrics)
输入:维度字段、度量字段、窗口(按月/按周)
输出(结构化):
- 聚合表
- 指标表(环比、同比、占比、贡献度)
C. 异常检测(Anomaly)
输入:时间序列或分布
输出(结构化):
- 异常点列表 + 异常原因(规则解释)
- 置信度与阈值(便于审阅)
这些模板会让 Reviewer 更容易做一致性审计。
6.2.7 风险与工程细节:提前避免返工
- 结果 JSON 的大小控制:大表不要直接塞进
results,只返回摘要 + artifact ref - 版本可重复:镜像版本要固定,否则同样代码在不同环境可能输出不同
- 代码注入与逃逸:不要让执行器拥有任何外网、凭证、主机读写权限
- 任务隔离:多租户时必须按 workspace 隔离 artifact key(6.4 章会接上)
6.2.8 验收标准:做到这一步,幻觉率会明显下降
- 对任意 CSV,能稳定生成一份 profile 结构化输出(缺失率/类型/基本统计)
- 对任意“求和、最大值、分组聚合”的问题,默认走执行器并返回可复核结果
- 前端能看到执行进度与关键产物(表/图/异常列表)
- 执行器具备基础安全约束:超时、输出限制、禁网(至少三项到位)
