HaHafeng
8137e3cde2
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>
167 lines
7.5 KiB
Markdown
167 lines
7.5 KiB
Markdown
# **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. **可追溯**：详尽的审计日志为未来的“自我进化”（根据用户反馈优化工具推荐）提供了数据基础。 |