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