Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ssa): Complete SSA-Pro MVP development plan v1.3

Browse Source 
Summary:

- Add PRD and architecture design V4 (Brain-Hand model)

- Complete 5 development guide documents

- Pass 3 rounds of team review (v1.0 -> v1.3)

- Add module status guide document

- Update system status document

Key Features:

- Brain-Hand architecture: Node.js + R Docker

- Statistical guardrails with auto degradation

- HITL workflow: PlanCard -> ExecutionTrace -> ResultCard

- Mixed data protocol: inline vs OSS

- Reproducible R code delivery

MVP Scope: 10 statistical tools

Status: Design 100%, ready for development
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HaHafeng
2026-02-18 21:58:37 +08:00
parent f9ed0c2528
commit 8137e3cde2
19 changed files with 5756 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
docs/03-业务模块/SSA-智能统计分析/02-技术设计/SSA-02 数据库与向量库 Schema 设计规范.md Normal file
View File

@@ -0,0 +1,167 @@
# **SSA-02: 数据库与向量库 Schema 设计规范**
**文档状态：** v1.0 (Draft)
**创建日期：** 2026-02-06
**关联模块：** SSA, Common RAG
**目标：** 定义存储 R 工具元数据、向量索引及执行审计日志的数据库结构。
## **1\. 设计原则**
### **1.1 复用平台能力**
* **向量引擎**：严格使用 pgvector (0.8.1)，向量维度固定为 **1024** (对应 text-embedding-v4)。
* **全文检索**：使用 pg\_bigm (1.2) 实现中英文混合的高性能关键词检索。
* **Schema 隔离**：所有表必须位于 ssa\_schema 命名空间下。
### **1.2 "工具即文档" (Tool-as-Document)**
与 PKB 模块将长文切分为 Chunk 不同，SSA 模块中**一个 R 工具就是一个原子检索单位**。我们不进行切分，而是进行**特征合成**。
## **2\. 核心表结构设计 (DDL)**
### **2.1 工具库表 (tools\_library) —— 核心资产**
这张表存储了 100+ 个 R 工具的定义、参数结构以及用于检索的向量数据。
\-- 确保扩展已启用 (通常在 platform\_schema 或 public)
\-- CREATE EXTENSION IF NOT EXISTS vector;
\-- CREATE EXTENSION IF NOT EXISTS pg\_bigm;
CREATE TABLE ssa\_schema.tools\_library (
id UUID PRIMARY KEY DEFAULT gen\_random\_uuid(),
\-- 1\. 业务标识
tool\_code VARCHAR(50) NOT NULL UNIQUE, \-- 例如: 'ST\_T\_TEST\_IND'
name VARCHAR(100) NOT NULL, \-- 例如: '独立样本 T 检验'
version VARCHAR(20) DEFAULT '1.0.0', \-- R 脚本版本
\-- 2\. 结构化元数据 (用于 LLM 生成参数)
description TEXT NOT NULL, \-- 简短描述
usage\_context TEXT, \-- 适用场景 (什么时候用?)
params\_schema JSONB NOT NULL, \-- 参数定义 (JSON Schema)
guardrails JSONB, \-- 护栏配置 (支持哪些检查?)
\-- 3\. 检索专用字段 (Search Optimization)
\-- 将 name \+ description \+ usage\_context \+ keywords 拼接
search\_text TEXT NOT NULL,
\-- 4\. 向量索引 (1024维)
embedding vector(1024),
\-- 5\. 审计字段
created\_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated\_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
is\_active BOOLEAN DEFAULT TRUE
);
\-- 索引策略 (Hybrid Search Ready)
\-- 1\. 向量索引 (IVFFlat 或 HNSW) \- 用于语义检索
CREATE INDEX idx\_ssa\_tools\_embedding ON ssa\_schema.tools\_library
USING hnsw (embedding vector\_cosine\_ops);
\-- 2\. 全文索引 (pg\_bigm) \- 用于关键词精确匹配 (如 "T检验", "ANOVA")
CREATE INDEX idx\_ssa\_tools\_search\_text\_bigm ON ssa\_schema.tools\_library
USING gin (search\_text gin\_bigm\_ops);
\-- 3\. 业务索引
CREATE INDEX idx\_ssa\_tools\_code ON ssa\_schema.tools\_library(tool\_code);
### **2.2 执行审计日志表 (execution\_logs) —— 优化之源**
这张表是 SSA-Pro **"白盒化"** 的证据。它完整记录了从用户提问到最终代码交付的全过程。
CREATE TABLE ssa\_schema.execution\_logs (
id UUID PRIMARY KEY DEFAULT gen\_random\_uuid(),
\-- 1\. 归属信息
user\_id VARCHAR(255) NOT NULL,
session\_id VARCHAR(255), \-- 关联的会话 ID
\-- 2\. 输入 (User Intent)
user\_query TEXT NOT NULL, \-- 用户原始提问
data\_summary JSONB, \-- 数据摘要 (Schema, 非原始数据)
\-- 3\. 规划 (AI Plan)
sap\_content TEXT, \-- AI 生成的统计分析计划 (Markdown)
selected\_tool VARCHAR(50), \-- 最终选择的 tool\_code
generated\_params JSONB, \-- AI 生成的参数
\-- 4\. 执行 (R Runtime)
execution\_status VARCHAR(20), \-- 'success', 'error', 'warning'
trace\_log JSONB, \-- R 返回的执行路径日志
error\_message TEXT, \-- 如果失败，记录报错
\-- 5\. 性能指标
duration\_ms INTEGER, \-- 总耗时
tokens\_used INTEGER, \-- LLM 消耗 Token
created\_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
\-- 索引
CREATE INDEX idx\_ssa\_logs\_user ON ssa\_schema.execution\_logs(user\_id);
CREATE INDEX idx\_ssa\_logs\_tool ON ssa\_schema.execution\_logs(selected\_tool);
CREATE INDEX idx\_ssa\_logs\_time ON ssa\_schema.execution\_logs(created\_at DESC);
## **3\. 向量检索策略 (Retrieval Strategy)**
### **3.1 检索字段合成策略 (The "Synthetic Document")**
为了保持高准确率，我们不能只 Embedding 描述字段。我们需要构造一个**富含语义的虚拟文档**。
**search\_text 字段的内容模板：**
工具名称: {name}
功能描述: {description}
适用场景: {usage\_context}
关键词: {keywords} (如: 差异, 比较, 连续变量, 正态分布)
模拟提问: {synthetic\_queries} (如: "怎么比较两组数据的均值?", "两组病人的血糖有区别吗?")
**策略说明：**
* **模拟提问 (Synthetic Queries)**：这是一个高级技巧。在录入工具时，利用 LLM 生成 3-5 个“用户可能会问的问题”，并入索引。这能极大缩短“用户口语”与“专业术语”之间的语义距离。
### **3.2 混合检索流程 (Hybrid Search Workflow)**
复用平台的 VectorSearchService，采用 **Brain-Hand** 模式。
1. **查询理解 (Brain Layer)**：
* 用户输入："看看这两组病人的 BMI 也没有差异"
* Query Rewriter (DeepSeek)：生成关键词 \["独立样本T检验", "两组差异", "连续变量"\]。
2. **双路召回 (Engine Layer)**：
* **路 A (Semantic)**：使用 embedding 字段进行向量相似度搜索 (Top 10)。
* **路 B (Keyword)**：使用 search\_text 字段进行 pg\_bigm 模糊匹配 (Top 10)。
3. **融合与重排 (Rerank)**：
* 使用 Reciprocal Rank Fusion (RRF) 合并两路结果。
* 使用 qwen3-rerank 模型，基于用户的 Data Schema (例如：数据是分类的还是数值的) 对候选工具进行重排。
* **截断**：取 Top 5 返回给 Planner。
## **4\. 数据流与写入流程**
### **4.1 工具注册流程 (DevOps Pipeline)**
1. **R 工程师**：在 R 脚本中编写 roxygen2 注释。
2. **CI/CD 脚本**：
* 解析 R 脚本，提取元数据。
* 调用 LLM 生成 synthetic\_queries (模拟提问)。
* 拼接 search\_text。
* 调用 EmbeddingService 生成向量。
* Upsert 到 ssa\_schema.tools\_library 表。
### **4.2 运行时流程**
1. **Node.js** 接收用户请求。
2. 调用 ssa\_schema.tools\_library 进行混合检索。
3. 将命中的工具 params\_schema 注入到 Planner 的 Prompt 中。
4. 执行结束后，将全过程写入 ssa\_schema.execution\_logs。
## **5\. 总结**
这套设计方案充分利用了我们现有的 **Postgres-Only** 架构优势：
1. **不需要额外的向量数据库**：直接用 RDS PostgreSQL，维护成本最低。
2. **高准确率保证**：通过 search\_text 的精心构造（特别是加入模拟提问）和 pg\_bigm 的关键词辅助，解决了“工具选错”的最大痛点。
3. **可追溯**：详尽的审计日志为未来的“自我进化”（根据用户反馈优化工具推荐）提供了数据基础。