صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
alair
/
graph_rag_server
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 4cd7a66317
شاخه‌ها تگ‌ها
graph_rag_serve...
/
TASK_5.4_IMPLEMENTATION_SUMMARY.md

TASK_5.4_IMPLEMENTATION_SUMMARY.md 10 KB
تاريخچه خام

Task 5.4 Implementation Summary: 向量搜索命令处理器

任务概述

实现向量搜索应用层的命令和查询处理器，协调领域对象完成用例。

任务详情：

  • 创建 application/vector_search/handlers.py，实现 CreateDocumentHandler
  • 实现 UpdateDocumentHandler 和 DeleteDocumentHandler
  • 实现 SearchDocumentsHandler 和 GetDocumentHandler
  • 注入仓储和领域服务依赖
  • 遵循 CQRS 模式

相关需求：

  • 1.4: 应用层协调领域对象完成用例
  • 3.2: 使用依赖注入机制管理组件依赖关系
  • 8.1: 向量数据库相关代码组织到独立模块

实现内容

1. 命令处理器（Command Handlers）

CreateDocumentHandler

  • 职责：处理创建文档命令
  • 依赖：DocumentRepository
  • 处理流程：
    1. 验证命令参数
    2. 生成文档 ID 和时间戳
    3. 创建文档领域实体（嵌入向量暂时为 None）
    4. 通过仓储保存文档
    5. 返回文档 ID
  • 异常处理：
    • 领域异常 → 验证异常
    • 其他异常 → 应用异常

UpdateDocumentHandler

  • 职责：处理更新文档命令
  • 依赖：DocumentRepository
  • 处理流程：
    1. 验证命令参数
    2. 从仓储查找文档
    3. 如果文档不存在，抛出 ResourceNotFoundException
    4. 更新文档内容和/或元数据
    5. 如果更新了内容，清除嵌入向量
    6. 通过仓储保存更新后的文档
  • 支持功能：
    • 只更新内容
    • 只更新元数据
    • 同时更新内容和元数据
    • 元数据合并或替换

DeleteDocumentHandler

  • 职责：处理删除文档命令
  • 依赖：DocumentRepository
  • 处理流程：
    1. 验证命令参数
    2. 通过仓储删除文档
    3. 删除操作是幂等的
  • 特性：
    • 即使文档不存在也不会抛出异常
    • 幂等操作

2. 查询处理器（Query Handlers）

SearchDocumentsHandler

  • 职责：处理搜索文档查询
  • 依赖：
    • DocumentRepository
    • HybridSearchService（可选）
  • 处理流程：
    1. 验证查询参数
    2. 构建搜索查询值对象
    3. 执行搜索（向量搜索或混合搜索）
    4. 将搜索结果转换为 DTO
    5. 返回搜索结果列表
  • 支持功能：
    • 向量搜索
    • 混合搜索（向量 + 全文）
    • 过滤条件
    • 分数阈值
    • 可选包含嵌入向量

GetDocumentHandler

  • 职责：处理获取文档查询
  • 依赖：DocumentRepository
  • 处理流程：
    1. 验证查询参数
    2. 从仓储查找文档
    3. 如果文档不存在，抛出 ResourceNotFoundException
    4. 将文档转换为 DTO
    5. 返回文档 DTO
  • 支持功能：
    • 可选包含嵌入向量

3. 依赖注入

所有处理器通过构造函数注入依赖：

# 命令处理器
create_handler = CreateDocumentHandler(document_repository)
update_handler = UpdateDocumentHandler(document_repository)
delete_handler = DeleteDocumentHandler(document_repository)

# 查询处理器
search_handler = SearchDocumentsHandler(
    document_repository,
    hybrid_search_service
)
get_handler = GetDocumentHandler(document_repository)

4. 异常处理策略

处理器统一捕获并转换异常：

原始异常 转换后异常 场景
DomainException ValidationException 领域对象验证失败
ResourceNotFoundException 直接重新抛出 资源不存在
Exception ApplicationException 意外错误

5. 日志记录

处理器使用结构化日志记录关键操作：

  • INFO 级别：

    • 操作开始（包含参数）
    • 操作成功完成（包含结果）

  • WARNING 级别：

    • 领域验证失败
    • 资源未找到

  • ERROR 级别：

    • 意外错误（包含堆栈跟踪）

日志包含上下文信息：

  • 文档 ID
  • 查询文本
  • 操作参数
  • 错误详情

6. 查询增强

为 SearchDocumentsQuery 添加了 include_embedding 属性：

@dataclass
class SearchDocumentsQuery:
    query_text: str
    top_k: int = 10
    filters: Optional[Dict[str, Any]] = None
    use_hybrid: bool = True
    min_score: Optional[float] = None
    include_embedding: bool = False  # 新增

文件清单

新建文件

  1. src/application/vector_search/handlers.py

    • 实现了 5 个处理器类
    • 约 600 行代码
    • 包含完整的文档字符串和示例

  2. tests/unit/application/vector_search/test_handlers.py

    • 14 个单元测试
    • 覆盖所有处理器的主要场景
    • 使用 Mock 隔离外部依赖

  3. src/application/vector_search/README.md

    • 完整的模块文档
    • 包含使用示例和设计原则

修改文件

  1. src/application/vector_search/queries.py
    • 为 SearchDocumentsQuery 添加 include_embedding 属性
    • 添加相应的验证逻辑

测试结果

所有单元测试通过：

========================= test session starts =========================
collected 14 items

tests/unit/application/vector_search/test_handlers.py::TestCreateDocumentHandler::test_handle_creates_document_successfully PASSED [  7%]
tests/unit/application/vector_search/test_handlers.py::TestCreateDocumentHandler::test_handle_with_empty_metadata PASSED [ 14%]
tests/unit/application/vector_search/test_handlers.py::TestCreateDocumentHandler::test_handle_raises_application_exception_on_repository_error PASSED [ 21%]
tests/unit/application/vector_search/test_handlers.py::TestUpdateDocumentHandler::test_handle_updates_content_successfully PASSED [ 28%]
tests/unit/application/vector_search/test_handlers.py::TestUpdateDocumentHandler::test_handle_updates_metadata_with_merge PASSED [ 35%]
tests/unit/application/vector_search/test_handlers.py::TestUpdateDocumentHandler::test_handle_updates_metadata_without_merge PASSED [ 42%]
tests/unit/application/vector_search/test_handlers.py::TestUpdateDocumentHandler::test_handle_raises_not_found_when_document_does_not_exist PASSED [ 50%]
tests/unit/application/vector_search/test_handlers.py::TestDeleteDocumentHandler::test_handle_deletes_document_successfully PASSED [ 57%]
tests/unit/application/vector_search/test_handlers.py::TestDeleteDocumentHandler::test_handle_raises_application_exception_on_repository_error PASSED [ 64%]
tests/unit/application/vector_search/test_handlers.py::TestSearchDocumentsHandler::test_handle_searches_documents_successfully PASSED [ 71%]
tests/unit/application/vector_search/test_handlers.py::TestSearchDocumentsHandler::test_handle_with_filters PASSED [ 78%]
tests/unit/application/vector_search/test_handlers.py::TestGetDocumentHandler::test_handle_gets_document_successfully PASSED [ 85%]
tests/unit/application/vector_search/test_handlers.py::TestGetDocumentHandler::test_handle_raises_not_found_when_document_does_not_exist PASSED [ 92%]
tests/unit/application/vector_search/test_handlers.py::TestGetDocumentHandler::test_handle_with_include_embedding PASSED [100%]

========================= 14 passed in 0.42s ==========================

测试覆盖：

  • ✅ 成功场景
  • ✅ 异常场景
  • ✅ 边界条件
  • ✅ 依赖交互

设计特点

1. CQRS 模式

严格分离命令和查询：

  • 命令：改变系统状态（创建、更新、删除）
  • 查询：不改变系统状态（搜索、获取）

2. 依赖注入

通过构造函数注入依赖，遵循依赖倒置原则：

  • 依赖于抽象接口（DocumentRepository）
  • 不依赖于具体实现
  • 易于测试和替换

3. 异常转换

统一的异常处理策略：

  • 领域异常 → 验证异常
  • 资源未找到 → 直接重新抛出
  • 其他异常 → 应用异常

4. 结构化日志

使用结构化日志记录关键操作：

  • 包含上下文信息
  • 便于日志聚合和分析
  • 支持分布式追踪

5. DTO 转换

使用 DTO 在层之间传输数据：

  • 与领域实体解耦
  • 支持序列化
  • 可选字段控制

与其他模块的集成

依赖的模块

  1. 领域层：

    • src/domain/vector_search/entities.py - Document, SearchResult
    • src/domain/vector_search/repositories.py - DocumentRepository
    • src/domain/vector_search/services.py - HybridSearchService
    • src/domain/vector_search/value_objects.py - Vector, SearchQuery
    • src/domain/shared/value_objects.py - EntityId, Timestamp
    • src/domain/shared/exceptions.py - DomainException

  2. 应用层共享：

    • src/application/shared/exceptions.py - ApplicationException, ResourceNotFoundException, ValidationException
    • src/application/shared/interfaces.py - CommandHandler, QueryHandler

  3. 应用层向量搜索：

    • src/application/vector_search/commands.py - 命令定义
    • src/application/vector_search/queries.py - 查询定义
    • src/application/vector_search/dtos.py - DTO 定义

被依赖的模块

  1. 表现层（未来）：

    • FastAPI 路由将使用这些处理器
    • 通过依赖注入机制注入处理器

  2. 基础设施层（未来）：

    • 仓储实现将被注入到处理器中

后续任务

根据任务列表，接下来的任务是：

  • 5.5 ✅ 编写向量搜索命令处理器单元测试（已完成）
  • 5.6 实现向量搜索查询处理器（已完成）
  • 5.7 编写向量搜索查询处理器单元测试（已完成）

验收标准

✅ 所有验收标准已满足：

  1. ✅ 创建了 application/vector_search/handlers.py
  2. ✅ 实现了 CreateDocumentHandler
  3. ✅ 实现了 UpdateDocumentHandler
  4. ✅ 实现了 DeleteDocumentHandler
  5. ✅ 实现了 SearchDocumentsHandler
  6. ✅ 实现了 GetDocumentHandler
  7. ✅ 注入了仓储和领域服务依赖
  8. ✅ 遵循 CQRS 模式
  9. ✅ 统一的异常处理
  10. ✅ 结构化日志记录
  11. ✅ 完整的单元测试
  12. ✅ 详细的文档

总结

Task 5.4 已成功完成。实现了向量搜索应用层的所有命令和查询处理器，遵循 CQRS 模式和依赖注入原则。所有处理器都有完整的文档字符串、异常处理和日志记录。单元测试覆盖了所有主要场景，确保代码质量。

关键成果：

  • 5 个处理器类（3 个命令处理器 + 2 个查询处理器）
  • 14 个单元测试（100% 通过）
  • 完整的模块文档
  • 遵循领域驱动设计和 CQRS 模式
  • 为表现层集成做好准备