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

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