轻量级Local数据语义搜索Skill的依赖与技术介绍

1. 功能概述

轻量级Local数据语义搜索，用于在构建的本地知识库中通过自然语言查询（支持中英文混合）检索最匹配的文档记录。

核心设计理念：零外部 ML 依赖——没有使用任何大型机器学习框架（如 TensorFlow、PyTorch、scikit-learn），仅依赖 numpy 实现向量化计算，极度轻量。

注意：以下仅为原理介绍，具体实现请自行OrAI实现，适合场景为轻量级地端知识库，DB查询依赖需根据数据库类型自行选择。

---

2. 依赖清单

项目仅有 2 个第三方依赖：

依赖	版本要求	用途
oracledb	无锁定	Oracle 数据库驱动，用于从数据库导出原始数据
numpy	无锁定	数值计算库，用于构建和查询 TF-IDF 向量索引

此外使用的 Python 标准库（无需安装）：

标准库模块	用途
json	数据的 JSON 序列化/反序列化
pickle	TF-IDF 索引的二进制序列化存储
re	正则表达式，用于分词时提取中文字符和英文单词
math	数学运算（log 用于 TF-IDF 权重计算）
argparse	命令行参数解析
os / sys	文件路径处理和系统交互
collections.Counter	词频统计

---

3. 依赖详细说明

3.1 oracledb — Oracle 数据库驱动

作用：连接 Oracle 数据库，执行 SQL 查询，导出原始数据。

使用场景：仅在数据导出脚本中使用。

关键行为：

• 以只读方式查询数据库中的目标表
• 提取名称、描述等文本字段
• 将查询结果序列化为本地 JSON 文件

为什么选它：oracledb 是 Oracle 官方维护的 Python 驱动（原 cx_Oracle 的继任者），支持 Thin 模式（无需安装 Oracle Client），部署更简单。

安装方式：

pip install oracledb

3.2 numpy — 数值计算库

作用：高性能数组运算，用于构建 TF-IDF 矩阵和执行余弦相似度计算。

使用场景：在索引构建和搜索查询脚本中使用。

关键行为：

• 构建 (N_docs × Vocab_size) 的浮点矩阵（TF-IDF 矩阵）
• L2 归一化每行向量
• 矩阵-向量乘法计算余弦相似度（tfidf_matrix @ query_vec）
• argsort 排序获取 Top-K 结果

为什么选它：numpy 是 Python 科学计算的事实标准，C 底层实现，矩阵运算速度远超纯 Python。在轻量级文档规模下(nk)，搜索响应几乎是即时的。

安装方式：

pip install numpy

---

4. 核心算法简介

4.1 TF-IDF（Term Frequency - Inverse Document Frequency）

一种经典的文本向量化方法，将文本转化为数值向量，用于衡量词语在文档集合中的重要程度。

\[\text{TF-IDF}(t, d) = \text{TF}(t, d) \times \text{IDF}(t) \]

其中：

• \(\text{TF}(t, d) = 1 + \log(\text{count}(t, d))\) — 词频的对数平滑
• \(\text{IDF}(t) = \log\frac{N}{1 + \text{df}(t)}\) — 逆文档频率，越稀有的词权重越高

4.2 分词策略（Tokenization）

由于文档内容是中英文混合文本，采用混合分词方案：

文本类型	方法	示例
英文	正则提取完整单词 ([a-z][a-z0-9_]+)	UserService → userservice
中文	单字（unigram）+ 双字（bigram）	查询订单 → 查, 询, 订, 单, 查询, 询订, 订单

为什么用 bigram：中文没有天然的空格分隔词语，单字语义弱，bigram 能捕获大部分常见词语搭配（如"查询""订单""删除"），同时避免引入分词工具（如 jieba）的额外依赖。

4.3 余弦相似度（Cosine Similarity）

用于衡量查询向量与每个文档向量的方向相似度：

\[\text{sim}(q, d) = \frac{q \cdot d}{\|q\| \cdot \|d\|} \]

由于文档向量已预先 L2 归一化，搜索时只需一次矩阵乘法即可得到所有文档的相似度分数。

4.4 词汇过滤

构建索引时会过滤词汇表：

• 最低频率：至少出现在 2 个文档中（过滤噪声/拼写错误）
• 最高频率：出现在不超过 80% 文档中（过滤无区分度的高频词）

---

5. 数据流架构

┌──────────────┐     数据导出脚本      ┌──────────────────┐
│  Oracle DB   │ ──────────────────→  │   data.json      │
│  (数据源)     │     oracledb        │  (本地 JSON)      │
└──────────────┘                      └────────┬─────────┘
                                               │
                                        索引构建脚本
                                        numpy + pickle
                                               │
                                      ┌────────▼─────────┐
                                      │ tfidf_index.pkl  │
                                      │  (TF-IDF 矩阵)   │
                                      └────────┬─────────┘
                                               │
                         搜索脚本               │
┌──────────────┐    numpy + json      ┌────────▼─────────┐
│  用户查询     │ ──────────────────→  │   余弦相似度计算   │ → Top-K 结果
│  (自然语言)   │     tokenize        │   矩阵乘法        │
└──────────────┘                      └──────────────────┘

脚本职责：

脚本	职责	依赖
数据导出脚本	从数据库导出数据到 JSON	oracledb, json
索引构建脚本	从 JSON 构建 TF-IDF 向量索引	numpy, pickle, re, math
搜索脚本	接收查询，计算相似度，返回排序结果	numpy, json, pickle, re, math
刷新脚本	编排脚本：先导出再重建索引	调用上述两个模块

---

6. 设计亮点

1. 极简依赖：仅 2 个第三方包，无需 GPU、无需下载模型权重
2. 离线可用：索引构建后，搜索完全离线运行，不依赖数据库连接
3. 中英文混合支持：基于 bigram 的分词方案，无需 jieba 等中文分词库
4. 毫秒级响应：轻量级文档 × 矩阵乘法，numpy 原生速度
5. 增量可维护：数据更新后一键重建索引

---

7. 适用场景

• 集成到 IDE 插件或 Agent 中，用自然语言描述需求检索匹配文档
• 适合中小规模知识库（轻量级文档），无需向量数据库
• 可作为更大系统的子模块被其他功能调用