Skip to content

REFACTORING_PLAN.md

Latest commit

 

History

History
109 lines (86 loc) · 5.84 KB

REFACTORING_PLAN.md

File metadata and controls

109 lines (86 loc) · 5.84 KB
Raw

PyRAG-Kit 重构与演进路线图

历史归档（2025-07-03 定稿，不再维护）：本文档记录 v1.0.0 → v1.2.0 的重构蓝图与 已完成的实施过程，不含任何未结任务。当前架构与用法请见 开发者指南 与 CHANGELOG（当前版本 1.4.0）。

阅读时注意三处已过时的表述：

  1. 文中的 PipelineManager 已重命名为 Pipeline（src/etl/pipeline.py）， 调用方是 src/services/knowledge_build_service.py，而非 main.py。
  2. 依赖已在 pyproject.toml 声明、由 uv 管理；requirements.txt 是 uv export --locked 的生成产物，不应手工编辑。
  3. 配置格式当时为 config.ini，现已迁移到 config.toml。

src/etl/、src/retrieval/ 为 Dify 衍生代码，遵循 DIFY_LICENSE 并保留上游版权声明。

1. 愿景与目标

将本项目从一个功能验证原型，系统性地演进为一个 “Dify核心逻辑的轻量级本地验证器”。这意味着我们的架构需要与Dify官方源码中先进的、松耦合的设计思想对齐，实现一个高内聚、松耦合、可扩展、易于测试的现代化Python应用。

2. 当前状态评估 (截至 v1.2.0)

经过 v1.2.0 的迭代，项目在架构现代化方面取得了决定性进展，核心重构蓝图已基本完成：

  • 已完成:

    • 支柱一：模型管理系统 - 已成功引入工厂模式 (ModelProviderFactory)。
    • 支柱二：向量存储系统 - 已成功解耦向量存储，实现了可插拔的向量数据库层。
    • 支柱三：文档处理流水线 - 已成功构建了灵活、可扩展的数据处理流水线 (ETL)。
    • 健壮性与开发者体验 - 已为核心模块编写了单元测试，并优化了日志记录和项目文档。

  • 待优化:

    • 持续完善：在现有架构基础上，持续进行代码优化、增加更多实现（如新的模型提供商、向量数据库支持）并完善文档。

3. 优化计划：完成并深化重构蓝图

项目已完成核心重构，进入持续迭代和优化阶段。

graph TD
    subgraph "起点: v1.1.0"
        A[部分实现的模型工厂]
        B[紧耦合的向量存储]
        C[独立的向量化脚本]
    end

    subgraph "已完成的重构 (v1.2.0)"
        direction LR
        P1[配置与环境现代化]
        P2[解耦向量存储]
        P3[构建文档处理流水线]
        P4[提升健壮性与DX]
    end

    subgraph "终点: 现代化架构"
        Z1[可插拔的模型层]
        Z2[可替换的向量存储]
        Z3[可扩展的文档流水线]
        Z4[高内聚、松耦合、可测试]
    end

    A --> P1
    B --> P2
    C --> P3
    P1 --> P2 & P3
    P2 --> Z2
    P3 --> Z3
    A --> Z1
    P4 --> Z4
Loading

4. 实施阶段详解

第一阶段：配置与环境现代化

  • 目标: 统一并强化配置管理，为后续的工厂模式提供更可靠的配置源。
  • 核心任务:
    1. 引入 Pydantic: 声明 pydantic 依赖（当时记录为编辑 requirements.txt； 该文件现为 uv export 生成产物，依赖应改在 pyproject.toml 中声明）。
    2. 创建配置模型: 在src/utils/config.py中，使用Pydantic模型来定义强类型的配置结构，替代当时分散读取的 config.ini。
    3. 提供全局配置实例: 提供一个全局可访问的、经过验证的配置对象。

第二阶段：向量存储系统解耦 (实施重构支柱二)

  • 目标: 解除对 FAISS 和 Pickle 的硬编码依赖，实现可插拔的向量数据库层。
  • 核心任务:
    1. 定义抽象基类: 在 src/retrieval/ 下创建 vdb/ 目录，并在 vdb/base.py 中定义 VectorStoreBase 抽象类，包含 add_documents(), search(), save(), load() 等标准接口。
    2. 封装FAISS实现: 创建 vdb/faiss_store.py，实现 FaissStore 类，将当前与FAISS相关的逻辑全部封装进去。
    3. 创建工厂: 创建 vdb/factory.py，实现 VectorStoreFactory，根据配置返回一个具体的 VectorStore 实例。
    4. 改造核心逻辑: 重构 Chatbot 和 embed_knowledge_base.py，使其通过工厂获取向量存储实例，面向接口编程。

第三阶段：构建文档处理流水线 (实施重构支柱三)

  • 目标: 将固化的向量化脚本，改造成灵活、可扩展的数据处理流水线 (ETL)。
  • 核心任务:
    1. 创建ETL模块: 在src/下创建etl/目录，用于存放所有数据处理逻辑。
    2. 定义处理器基类: 在etl/下创建extractors, cleaners, splitters子目录，并为每种处理器定义抽象基类。
    3. 实现具体处理器: 提供针对Markdown的抽取器、基础的文本清洗器和递归文本分割器的具体实现。
    4. 创建流水线管理器: 在etl/pipeline.py中创建一个流水线管理器（当时记作 PipelineManager，实际落地为 Pipeline），它可以根据文件类型和配置，动态地组合这些处理器来处理文档。
    5. 整合: 由 main.py 经服务层调用该流水线执行处理（实际路径：main.py → src/services/knowledge_build_service.py → Pipeline.from_file_path）。

第四阶段：提升健壮性与开发者体验 (DX)

  • 目标: 为项目未来的健康发展和社区贡献奠定基础。
  • 核心任务:
    1. 编写单元测试: 在 tests/ 目录下，为新创建的工厂、Pydantic模型和核心组件编写单元测试。
    2. 统一日志: 审查并统一项目中的日志记录风格和格式，确保关键操作都有日志输出。
    3. 更新文档: 在所有重构完成后，更新 README.md 以反映最终的架构和使用方法。