smart_rag 0.1.0 → 0.2.0

data/requirements.md

@@ -0,0 +1,376 @@
+# SmartRAG 需求文档
+
+## 1. 概述
+
+SmartRAG 是一个 Ruby gem，为知识管理和智能搜索提供检索增强生成（RAG）功能。它使用向量嵌入和语义搜索来提取、存储和检索信息。
+
+系统采用混合检索架构，结合以下两种检索方式：
+- **向量检索**：基于语义的相似度搜索，使用 pgvector 存储和查询 1024 维向量
+- **全文检索**：基于关键词的精确匹配，支持多语言分词和 BM25 排序算法
+
+这种混合检索方法充分发挥了向量检索的语义理解能力和全文检索的精确匹配优势，提供更准确、更全面的搜索结果。
+
+## 2. 核心需求
+
+### 2.1 向量嵌入管理
+
+#### 2.1.1 嵌入存储
+- 使用 PostgreSQL 数据库的 pgvector 扩展存储向量嵌入（1024 维）
+- 将嵌入与源内容（文档和片段）关联
+- 支持嵌入的 CRUD 操作
+
+#### 2.1.2 向量搜索
+- 使用余弦距离（`<->` 操作符）执行相似度搜索
+- 支持基于标签的搜索结果优先级提升
+- 返回带相似度分数的排序结果
+- 支持可配置的结果数量限制
+
+#### 2.1.3 搜索功能
+- `search_by_vector(query_vector, limit)` - 基础向量相似度搜索
+- `search_by_vector_with_tag_boost(query_vector, tags, limit)` - 增强搜索，支持标签优先级
+
+### 2.2 文档管理
+
+#### 2.2.1 源文档
+- 存储文档元数据：标题、作者、发布日期、语言、URL、描述
+- 跟踪下载状态（待处理、已完成、失败）
+- 支持 CRUD 操作
+
+#### 2.2.2 文档片段（分块）
+- 将文档拆分为可管理的分块（最大 4000 字符）
+- 优先按 Markdown 标题智能分块，其次按字符限制
+- 保持分块之间的重叠（100 字符）
+- 存储片段标题和内容
+- 跟踪片段编号以维护顺序
+
+### 2.3 查询处理
+
+#### 2.3.1 自然语言查询处理
+- 将自然语言查询转换为向量表示
+- 使用 LLM 从查询生成搜索关键词/标签
+- 支持多语言：简体中文、繁体中文、英语、日语
+
+#### 2.3.2 响应生成
+- 使用向量搜索查询知识库
+- 格式化和排序搜索结果
+- 使用 LLM 生成自然语言摘要
+
+### 2.4 标签系统
+
+#### 2.4.1 标签管理
+- 创建和管理层级标签
+- 支持多种标签类型（分类标签、内容标签）
+- 使用 LLM 为内容自动生成标签
+
+#### 2.4.2 基于标签的增强
+- 提升匹配查询标签的搜索结果
+- 支持标签匹配的加权评分
+
+### 2.5 内容处理管道
+
+#### 2.5.1 文档摄取
+- 从 URL 下载内容（网页、PDF、DOCX 等）
+- 使用外部工具将各种格式转换为 Markdown
+- 提取标题和元数据
+
+#### 2.5.2 嵌入生成
+- 使用外部嵌入服务为内容分块生成向量嵌入
+- 支持可配置的嵌入维度
+
+#### 2.5.3 标签处理
+- 为每个内容分块生成标签
+- 将标签链接到内容片段和文档
+- 支持层级标签关系
+
+### 2.6 数据模型
+
+#### 2.6.1 核心实体
+- **embeddings** - 内容片段的向量嵌入
+- **source_documents** - 源文档元数据
+- **source_sections** - 文档分块/片段
+- **tags** - 标签定义
+- **research_topics** - 研究主题分类
+- **section_tags** - 片段和标签之间的多对多关系
+- **research_topic_sections** - 研究主题和片段之间的关系
+- **section_fts** - 全文检索专用表，存储 tsvector 数据
+- **text_search_configs** - 语言配置映射表
+
+#### 2.6.2 数据库要求
+- PostgreSQL 12+ 与 pgvector 扩展
+- 支持 JSON 数据类型
+- 为性能优化的索引
+
+### 2.7 全文检索功能
+
+#### 2.7.1 多语言全文检索
+- 支持多语言文本分词和索引：英文、简体中文、繁体中文、日语、韩语及其他语言
+- 中文分词使用 pg_jieba 扩展，支持自定义词典
+- 英文使用 PostgreSQL 内置的 pg_catalog.english 配置
+- 其他语言使用 simple 配置，按非字母字符分词
+- 自动检测文本语言或基于文档语言元数据选择分词器
+
+#### 2.7.2 全文检索核心功能
+- `search_by_text(query, language, limit)` - 基础全文检索，支持自然语言查询和高级查询语法
+- `search_with_filters(query, filters, options)` - 带过滤条件的全文检索，支持按文档、标签、日期范围过滤
+- `hybrid_search(text_query, vector_query, options)` - 混合检索，融合全文检索和向量检索结果
+- 搜索结果包含相关性分数（BM25）、高亮片段和元数据
+
+#### 2.7.3 混合检索策略
+- 使用 RRF（Reciprocal Rank Fusion）算法融合全文检索和向量检索结果
+- 支持配置不同检索模式的权重
+- 全文检索：精确匹配、关键词敏感、可解释性强
+- 向量检索：语义理解、容错性高、支持近义词
+- 混合检索：结合两者优势，提升检索质量
+
+#### 2.7.4 查询解析与优化
+- 智能查询解析器，支持自然语言查询和高级查询语法（引号、AND、OR）
+- 查询预处理：语言检测、查询标准化、特殊字符处理
+- 支持查询扩展：同义词扩展、拼写纠错（可选）
+- 查询性能优化：使用 GIN 索引、分区索引、复合索引
+
+#### 2.7.5 索引管理
+- 自动维护全文索引：通过数据库触发器在内容更新时自动更新 tsvector
+- 支持增量索引构建和批量索引重建
+- 提供索引健康检查和优化工具
+- 支持索引预热和缓存策略
+
+## 3. 集成需求
+
+### 3.1 LLM 集成
+- 集成外部 LLM 服务以支持：
+  - 嵌入生成（`get_embedding` worker）
+  - 标签生成（`get_tags` worker）
+  - 搜索结果摘要（`summarize_search_results` worker）
+- 支持可插拔的 LLM 后端
+
+### 3.2 网页搜索集成
+- 可选的网页搜索 API 集成
+- 支持多个搜索提供商
+- 基于工具的搜索实现
+
+### 3.3 文档处理集成
+- 与 markitdown 集成进行文档转换
+- 支持 PDF、DOCX、HTML 和其他格式
+
+## 4. 搜索功能
+
+### 4.1 查询类型
+- 自然语言问题（支持向量检索和全文检索）
+- 基于关键词的搜索（全文检索，支持高级查询语法）
+- 标签筛选搜索
+- 混合检索（结合全文检索和向量检索）
+
+### 4.2 检索模式
+
+#### 4.2.1 向量检索
+- 基于语义的相似度搜索
+- 使用余弦距离计算相似度
+- 支持 1024 维向量嵌入
+- 对同义词和语义相近的内容有更好的召回率
+
+#### 4.2.2 全文检索
+- 基于关键词的精确匹配
+- 使用 BM25 算法排序
+- 支持多语言分词（中文、英文、日文等）
+- 支持高级查询语法：引号精确匹配、AND/OR 布尔操作
+- 提供高亮片段显示
+- 响应时间：P95 < 100ms
+
+#### 4.2.3 混合检索（推荐）
+- 同时执行全文检索和向量检索
+- 使用 RRF（Reciprocal Rank Fusion）算法融合结果
+- 结合全文检索的精确性和向量检索的语义理解能力
+- 相比纯向量检索，召回率提升 15-25%
+- 可配置不同检索模式的权重
+
+### 4.3 结果排序与评分
+- 向量检索：余弦距离评分（0-1，越小越相似）
+- 全文检索：BM25 相关性评分（越高越相关）
+- 混合检索：RRF 融合评分
+- 标签匹配：提升匹配标签结果的优先级
+- 支持自定义排序规则和加权策略
+- 重复项移除：基于内容相似度和 URL
+
+### 4.4 结果格式化
+- 带元数据的结构化结果对象
+- 支持分页（limit/offset）
+- 包含丰富的元数据：
+  - 文档标题、作者、发布日期、URL
+  - 内容片段（带关键词高亮）
+  - 相关性分数
+  - 匹配标签
+  - 检索模式标记（全文/向量/混合）
+
+## 5. 知识库管理
+
+### 5.1 文档操作
+- 通过 URL 添加文档
+- 下载和处理文档内容
+- 级联清理删除文档
+- 按研究主题列出文档
+
+### 5.2 研究主题
+- 按研究主题分类文档
+- 支持文档到主题的多对多关系
+- 基于内容自动推荐主题
+
+### 5.3 批量操作
+- 下载所有待处理的文档
+- 批量处理文档
+- 重新处理现有文档
+
+## 6. 性能需求
+
+### 6.1 搜索性能
+- 向量搜索应在 < 1 秒内完成典型查询
+- 全文检索 P95 响应时间 < 100ms
+- 混合检索总响应时间 < 1 秒（并行执行）
+- 支持向量列上的索引（IVFFLAT）
+- 全文检索使用 GIN 索引，支持快速查询
+- 高效的标签筛选和查询过滤
+
+### 6.2 内容处理
+- 文档分块应高效处理大型文档
+- 支持多文档的并行处理
+- 可配置的处理批量大小
+- 索引构建：100 万条记录 < 10 分钟
+- 增量索引更新实时同步
+
+### 6.3 可扩展性要求
+- 支持千万级文档的检索
+- 支持水平分片：按语言或主题分区
+- 查询缓存：Redis 缓存热门查询结果
+- 连接池：支持高并发查询（100+ QPS）
+
+## 7. 错误处理
+
+### 7.1 健壮的错误处理
+- 优雅处理嵌入生成失败
+- 文档下载错误处理与状态跟踪
+- 数据库操作错误处理
+- 网络错误恢复
+
+### 7.2 日志记录
+- 全面的调试日志
+- 日志级别（info、warning、error）
+- 结构化日志输出
+
+## 8. 配置管理
+
+### 8.1 数据库配置
+- 可配置的数据库连接设置
+- 支持连接池
+- 支持模式版本控制
+
+### 8.2 全文检索配置
+- 默认语言设置（en/zh/ja 等）
+- 最大搜索结果数（默认 100）
+- 混合检索权重配置（全文 vs 向量）
+- 缓存配置：启用/禁用、TTL 设置
+- 监控配置：慢查询阈值、日志记录
+- 分词器配置：自定义词典路径
+
+### 8.3 模型配置
+- 可配置的嵌入维度（默认 1024）
+- 可配置的分块大小（默认 4000）和重叠（默认 100）
+- 标签生成参数和模型选择
+- 检索结果数量限制
+- 标签匹配提升权重
+
+## 9. 测试需求
+
+### 9.1 单元测试
+- 所有模型的测试覆盖率（嵌入模型、文档模型、片段模型、全文检索表模型）
+- 模拟外部服务依赖（LLM 服务、嵌入服务）
+- 测试向量搜索准确性
+- 测试全文检索功能：多语言分词、查询解析、结果排序
+- 测试混合检索 RRF 算法正确性
+- 测试文档分块功能（Markdown 标题拆分、重叠处理）
+
+### 9.2 集成测试
+- 端到端文档处理测试（下载 → 分块 → 嵌入生成 → 全文索引）
+- 搜索功能测试：
+  - 向量搜索集成测试
+  - 全文检索集成测试（中英文）
+  - 混合检索集成测试
+  - 带过滤条件的检索测试
+- 错误处理测试（嵌入失败、数据库错误、网络超时）
+- 性能测试：
+  - 搜索响应时间（P95、P99）
+  - 索引构建速度
+  - 大规模数据查询性能
+- 质量评估：准确率、召回率、NDCG 排名质量
+
+## 10. 文档
+
+### 10.1 API 文档
+- 所有公共方法的清晰 API 文档
+- 使用示例
+- 最佳实践指南
+
+### 10.2 设置文档
+- 数据库设置说明（PostgreSQL 16+）
+- pgvector 安装指南
+- pg_jieba 安装和配置指南（支持 Ubuntu/Debian 和 macOS）
+- 自定义词典配置和使用说明
+- 全文检索配置示例和高级查询语法说明
+- 性能优化建议（索引、查询、缓存）
+- 从现有系统迁移到混合检索的迁移指南
+
+## 11. 依赖项
+
+### 11.1 Ruby 依赖
+- sequel - 数据库 ORM
+- pg - PostgreSQL 驱动
+- json - JSON 处理
+- httparty/faraday - HTTP 客户端（用于 LLM API 调用）
+- concurrent-ruby - 并发处理（支持异步检索）
+- 根据需要额外的 gems
+
+### 11.2 系统依赖
+- **数据库**：PostgreSQL 16+ 与以下扩展：
+  - pgvector - 向量存储和相似度搜索
+  - pg_jieba - 中文分词（可选，用于中文全文检索）
+  - pg_trgm - 模糊匹配和相似度计算（可选）
+- **外部服务**：
+  - 外部 LLM 服务访问（用于嵌入生成、标签生成、摘要）
+  - 可选：用于文档处理的 markitdown
+- **编译依赖**（用于安装 pg_jieba）：
+  - cmake 3.10+
+  - gcc/g++ 或 clang
+  - PostgreSQL 服务器开发包（postgresql-server-dev-${version}）
+
+## 12. 未来考虑
+
+### 12.1 高级功能
+
+#### 12.1.1 全文检索增强
+- **同义词扩展**：使用 PostgreSQL 同义词词典（ts_synonym）
+- **拼写纠错**：集成 pg_trgm 进行模糊匹配
+- **增量索引**：使用 PostgreSQL 13+ 的增量排序功能
+- **并行查询**：利用并行执行加速大规模检索
+- **知识图谱**：集成实体识别和关系抽取
+
+#### 12.1.2 多模态与跨语言
+- 多模态嵌入（图像、音频）
+- 跨语言搜索（支持跨语种查询）
+- 语义聚类（自动文档分类）
+- 查询扩展（自动添加相关词）
+- 相关度反馈（从用户交互中学习）
+
+### 12.2 可扩展性与运维
+
+#### 12.2.1 搜索可扩展性
+- 分布式向量搜索（多节点部署）
+- 全文检索分区索引（按语言或主题）
+- 水平分片和联邦搜索
+- 查询结果缓存（Redis 缓存层）
+- 多数据中心部署和同步
+
+#### 12.2.2 运维与监控
+- 索引健康检查和自动修复
+- 查询性能监控和告警
+- 慢查询分析工具和优化建议
+- 自动索引重建和碎片整理
+- 后台作业处理（文档下载、索引构建）
+- 存档/保留策略（冷热数据分离）