AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md

SSA-Pro: 严谨型智能统计分析架构设计方案 (V4.0)

文档版本： v4.0 (Final Comprehensive Edition)

创建日期： 2026-02-06

最后更新： 2026-02-06

核心理念： 白盒化 (White-box)、严谨性 (Rigor)、透明交付 (Transparency)

架构特征： 同步 HTTP 微服务 + RAG 工具检索 + 统计护栏 + 人机回环 (HITL) + 代码交付

1. 执行摘要 (Executive Summary)

1.1 项目背景

壹证循科技拥有近百种经久考验的 R 语言统计工具（ST模块），这是我们的核心资产。随着 AI Agent 技术的发展，我们致力于将这些“静态工具”升级为“智能统计伙伴 (SSA)”，以降低临床医生的科研门槛。

1.2 核心决策演进

经过多轮技术选型与研报论证，我们的架构经历了三次关键迭代：

1. SSA-Lite (V1): 追求极致速度，采用同步 HTTP API，摒弃了重型的异步队列架构（针对 <2MB 小数据场景）。
2. SSA-Pro (V2): 引入行业研报建议，增加 RAG 工具检索（解决百种工具调度难）和 统计护栏（防止滥用统计方法）。
3. SSA-WhiteBox (V3/V4): 引入 人机回环 (HITL) 和 代码交付，将“黑盒 AI”转变为“透明导师”，解决医疗场景下的信任与合规问题。

1.3 最终方案价值主张

SSA-Pro V4 不是一个简单的“代码生成器”，而是一个**“懂统计、守规矩、乐于分享”的智能分析师**：

• 懂统计：先写计划 (SAP)，再做分析，就像真正的统计师一样。
• 守规矩：强制执行正态性、方差齐性等前置检查，不满足条件自动警告。
• 乐于分享：不仅给结果，还给可复现的 R 代码，支持医生本地二次运行。

2. 为什么选择这套架构？(Architecture Rationale)

在确定技术路线前，我们对三种主流方案进行了深度对比：

维度	方案 A: 异步队列 (pg-boss)	方案 B: 纯 LLM 代码生成 (Open Interpreter)	方案 C: SSA-Pro V4 (本方案)
核心机制	提交任务 -> 排队 -> 轮询结果	LLM 现场写 Python/R 代码 -> 沙箱执行	LLM 调参 -> R 标准库执行
交互体验	🐢 慢 (异步断裂感)	🚀 快 (但不可控)	⚡ 极速 (同步对话感)
准确性	✅ 高 (使用固定脚本)	❌ 低 (容易幻觉、语法错误)	✅ 极高 (护栏 + 预验证)
数据隐私	🟡 数据需落地 OSS	🔴 数据需传给 LLM (高风险)	🟢 数据/认知分离 (最高级)
落地难度	🔴 重 (需维护队列/状态)	🟡 中 (需维护复杂沙箱)	🟢 中 (需封装 R 接口)

决策结论：

针对医疗科研中 90% 的 探索性数据分析 (EDA) 场景（数据量 < 2MB），SSA-Pro V4 (同步微服务 + 工具调用模式) 是平衡体验、安全与成本的最优解。

3. 系统架构蓝图 (System Blueprint)

本架构严格遵循 "Brain-Hand" 分离原则，并增加了 "User Check" 环节。

graph TD
User[用户 (React Chat)] -->|1. 上传 Data Schema (无敏感数据)| Node[Node.js 后端 (Brain)]
User -->|1b. 上传真实 CSV (仅用于执行)| R_Service[R Plumber 服务 (Hand)]

subgraph "Phase 1: 认知与规划 (Cognitive Layer)"  
    Node \--\>|2. 意图识别| LLM\_Plan\[DeepSeek-V3 (Planner)\]  
    Node \--\>|3. 语义检索 (pgvector)| VectorDB\[(Tools Knowledge Base)\]  
    VectorDB \--\>|4. 返回 Top-5 工具定义| Node  
    Node \--\>|5. 生成 SAP & 推荐参数| LLM\_Plan  
    Node \--\>|6. 返回 \[分析预习卡片\]| User  
end

subgraph "Phase 2: 确认与执行 (Execution Layer)"  
    User \--\>|7. 点击 \[确认执行\]| Node  
    Node \--\>|8. HTTP POST /run (Params Only)| R\_Service  
      
    R\_Service \--\>|9. 路由分发| Wrapper\[工具适配层\]  
      
    subgraph "R Runtime (Network Isolated)"  
        Wrapper \--\>|10. 记录执行路径 (Trace)| TraceLog  
        Wrapper \--\>|11. 统计护栏 (Guardrails)| CoreTools  
        CoreTools \--\>|12. 核心计算| CoreTools  
        CoreTools \--\>|13. 生成复现代码| CodeGen  
    end  
      
    Wrapper \--\>|14. 结果包 (Result+Trace+Code)| R\_Service  
end

subgraph "Phase 3: 反思与交付 (Reflection Layer)"  
    R\_Service \--\>|15. 原始结果| Node  
    Node \--\>|16. 结果解释 (Conservative)| LLM\_Critic\[DeepSeek-V3\]  
    LLM\_Critic \--\>|17. 最终报告 \+ R代码下载| User  
end

4. 核心业务流程详解

4.1 步骤一：智能规划 (The Planner)

解决痛点： 100 个工具怎么选？

• 动作：
  1. 用户输入自然语言需求。
  2. 系统提取关键词，在 tools_library 向量库中检索 Top-5 相关工具。
  3. LLM 基于检索结果，生成 统计分析计划 (SAP)。
• 产出：不仅是选工具，而是生成一份严谨的计划书（含分析目标、方法选择理由、假设验证条件）。

4.2 步骤二：人机回环确认 (HITL Confirmation)

解决痛点： AI 瞎跑，用户不敢信。

• 动作：在执行代码前，系统弹出一个 “分析预习卡片”。
• 卡片内容：📊 分析方案预览：独立样本 T 检验
  • 目标：比较吸烟组与非吸烟组的 BMI 差异
  • 参数：Group=Smoke, Value=BMI
  • 前置检查：将自动执行 Shapiro-Wilk 正态性检验。
  • 降级策略：若正态性不满足，自动切换为 Wilcoxon 检验。

[ 🛠️ 修改参数 ] [ ✅ 确认并执行 ]

4.3 步骤三：透明化执行与护栏 (Transparent Execution)

解决痛点： 统计滥用 (P-hacking)。

• 动作：
  1. 统计护栏 (Guardrails)：R 代码强制执行前置检查（如正态性、方差齐性）。如果检查失败，代码会自动记录日志并可能切换方法（降级）。
  2. 路径可视化 (Trace)：前端展示执行树。
     ├─ 🔍 正态性检验: P=0.23 (通过)
     ├─ 🔍 方差齐性检验: P=0.45 (通过)
     └─ 🚀 执行 T 检验: t=2.5, P=0.012

4.4 步骤四：代码交付与解释 (Handover & Critic)

解决痛点： 结果不可复现，P 值过度解读。

• 动作：
  1. 代码生成：R Wrapper 根据本次执行的参数，拼接出一份可独立运行的 .R 脚本，供用户下载。
  2. 保守解释：Critic Agent (DeepSeek) 将结果翻译成人话，严禁使用“证明了”等绝对词汇，强调置信区间。

5. 关键技术实现细节

5.1 元数据工程 (Metadata Engineering)

这是连接 R 和 AI 的桥梁。我们不手动写 JSON，而是从 R 代码注释中自动提取。

R 代码规范 (roxygen2 风格):

#' @title 执行独立样本T检验
#' @description 比较两组独立正态分布数据的均值差异。
#' @usage_context 当因变量为连续变量，且在两组间独立时使用。
#' @param data 数据框
#' @param group_col 分组列名 (Character)
#' @param val_col 数值列名 (Numeric)
#' @guardrails check_normality=TRUE, check_variance=TRUE
st_t_test_ind <- function(data, group_col, val_col) { ... }

• Pipeline：编写脚本扫描 R 目录 -> 提取注释 -> 生成 tools_library.json -> 存入 pgvector。

5.2 R 服务接口设计

所有工具通过统一入口调用，简化后端逻辑。

• API: POST /api/v1/ssa/execute

• Request Payload:
  {
  "tool_code": "ST_T_TEST_IND",
  "data": [ ...rows... ],
  "params": { "group_col": "group", "val_col": "bmi" },
  "options": { "return_code": true }
  }

• Response Payload:
  {
  "status": "success",
  "results": { "p_value": 0.012, "conf_int": [0.5, 2.1] },
  "plots": ["base64_string..."],
  "trace_log": ["Checking normality... Passed."],
  "reproducible_code": "data <- read.csv('data.csv'); t.test(data$bmi ~ data$group)..."
  }

5.3 安全与隐私设计

1. 数据本地化 (Data Residency)：
   • 原则：LLM (Brain) 永远只看 Schema (列名)，不看 Data (行内容)。
   • 流程：前端提取 Schema -> 发给 LLM 规划 -> LLM 返回参数 -> 前端将 参数+Data 发给 R 服务。
   • 结果：敏感的患者数据只在内网 R 服务中流转，从未触达公网 LLM。
2. 网络隔离：
   • SAE 部署 R 容器时，配置 Egress Policy (出站策略) 为 Deny All。防止 R 脚本恶意上传数据。

---

6. 实施路线图 (Roadmap)

Phase 1: 地基建设 (2周)

• 目标：跑通链路，实现 T 检验的自动化。
• 任务：
  1. Metadata Pipeline：编写 R 注释提取脚本。
  2. R Wrapper v1：实现支持 Trace 和 CodeGen 的通用 Wrapper。
  3. R Docker：集成 Plumber 和 10 个核心工具。

Phase 2: 智能体与交互 (3周)

• 目标：实现“对话 -> 确认 -> 执行”闭环。
• 任务：
  1. Planner Agent：接入 RAG 检索，优化 SAP Prompt。
  2. 前端组件：开发 ConfirmationCard (确认卡片) 和 ExecutionTrace (执行路径图)。
  3. 统计护栏：在 T 检验中实装正态性检查。

Phase 3: 全量迁移与打磨 (持续)

• 目标：覆盖 100+ 工具。
• 任务：
  1. 批量为旧 R 脚本添加 roxygen2 注释。
  2. 全量更新向量库。
  3. 收集用户反馈，微调护栏阈值。

---

7. 总结

SSA-Pro V4.0 是一套**“为了医疗科研而生”**的架构。

它没有盲目追求“全自动写代码”的噱头，而是选择了**“同步微服务 + 统计护栏 + 白盒交付”**这条最难走但最稳健的路。

• 对于用户：它像一位耐心的导师，教你方法，帮你检查，最后把代码送给你。
• 对于开发团队：它复用了现有的 R 资产，工程边界清晰。
• 对于平台：它建立了极高的数据隐私壁垒和学术严谨性壁垒。

这是目前行业内最务实、最可落地的智能统计解决方案。