RAG 高级框架使用指南

📚 概述

这是一个基于 LangGraph4j 和 LangChain4j 构建的高级 RAG（检索增强生成）框架，支持：

• ✅ 阶段即服务：每个 RAG 阶段都是独立的 Spring Service，可以单独调用
• ✅ 多种调用方式：Service 注入、REST API、LangGraph 编排、消息队列
• ✅ 自我修正：自动评估质量并触发修正循环
• ✅ 灵活编排：使用 LangGraph 构建复杂的 RAG 工作流
• ✅ 可观测性：完整的执行追踪和质量评估

🏗️ 架构

应用层 (Controller/API)
    ↓
编排层 (LangGraph/Pipeline)
    ↓
服务层 (各个 RAG 阶段服务) ⭐ 核心
    ↓
执行层 (LLM/Embedding/检索器)

📦 核心服务

1. QueryTransformService - 查询转换服务

支持多种查询转换策略：

• REWRITE - 查询重写
• EXPAND - 查询扩展
• DECOMPOSE - 查询分解
• MULTI_QUERY - 多查询生成
• COMPRESS - 上下文压缩

独立调用示例：

@Autowired
private QueryTransformService queryTransformService;

public void example() {
    QueryTransformRequest request = QueryTransformRequest.builder()
        .originalQuery("审计标准中关于内部控制的要求")
        .strategy(QueryTransformStrategy.MULTI_QUERY)
        .multiQueryCount(3)
        .build();

    QueryTransformResponse response = queryTransformService.transform(request);
    // 返回 3 个不同角度的查询
}

REST API 调用：

curl -X POST http://localhost:9010/ai/rag/stage/transform \
  -H "Content-Type: application/json" \
  -d '{
    "originalQuery": "审计标准中关于内部控制的要求",
    "strategy": "MULTI_QUERY",
    "multiQueryCount": 3
  }'

2. RetrievalService - 检索服务

支持多种检索模式：

• SIMPLE - 单检索器检索
• PARALLEL - 并行检索
• SEQUENTIAL - 顺序检索
• HYBRID - 混合检索

独立调用示例：

@Autowired
private RetrievalService retrievalService;

public void example() {
    RetrievalRequest request = RetrievalRequest.builder()
        .queries(List.of("查询1", "查询2"))
        .retrieverNames(List.of("vector", "keyword"))
        .executionMode(RetrievalExecutionMode.PARALLEL)
        .build();

    RetrievalResponse response = retrievalService.retrieve(request);
    // 并行执行 2个查询 × 2个检索器 = 4个检索任务
}

3. QualityAssessmentService - 质量评估服务

支持多种评估类型：

• RETRIEVAL_QUALITY - 检索质量综合评估
• RESPONSE_QUALITY - 响应质量评估
• RELEVANCE - 相关性评估
• COVERAGE - 覆盖度评估
• DIVERSITY - 多样性评估

独立调用示例：

@Autowired
private QualityAssessmentService qualityAssessmentService;

public void example() {
    QualityAssessmentRequest request = QualityAssessmentRequest.builder()
        .assessmentType(QualityAssessmentType.RETRIEVAL_QUALITY)
        .query("用户查询")
        .contents(retrievedContents)
        .build();

    QualityAssessmentResponse response = qualityAssessmentService.assess(request);
    // 返回质量得分 (0-1) 和发现的问题列表
}

🎯 使用场景

场景 1：简单的单阶段调用

@Service
@RequiredArgsConstructor
public class MyService {

    private final QueryTransformService queryTransformService;

    public List<String> expandQuery(String query) {
        QueryTransformRequest request = QueryTransformRequest.builder()
            .originalQuery(query)
            .strategy(QueryTransformStrategy.EXPAND)
            .build();

        return queryTransformService.transform(request).getTransformedQueries();
    }
}

场景 2：组合多个阶段

@Service
@RequiredArgsConstructor
public class CustomRagService {

    private final QueryTransformService queryTransformService;
    private final RetrievalService retrievalService;
    private final QualityAssessmentService qualityAssessmentService;

    public RagResult customRagFlow(String query) {
        // 1. 查询转换
        QueryTransformResponse transformResp = queryTransformService.transform(
            QueryTransformRequest.builder()
                .originalQuery(query)
                .strategy(QueryTransformStrategy.MULTI_QUERY)
                .build()
        );

        // 2. 检索
        RetrievalResponse retrievalResp = retrievalService.retrieve(
            RetrievalRequest.builder()
                .queries(transformResp.getTransformedQueries())
                .retrieverNames(List.of("vector", "keyword"))
                .executionMode(RetrievalExecutionMode.PARALLEL)
                .build()
        );

        // 3. 质量评估
        QualityAssessmentResponse assessResp = qualityAssessmentService.assess(
            QualityAssessmentRequest.builder()
                .assessmentType(QualityAssessmentType.RETRIEVAL_QUALITY)
                .query(query)
                .contents(retrievalResp.getContents())
                .build()
        );

        // 4. 根据质量决定下一步
        if (assessResp.getScore() > 0.7) {
            // 继续生成
            return generateAnswer(retrievalResp.getContents());
        } else {
            // 自我修正
            return retryWithCorrection(query);
        }
    }
}

场景 3：使用 LangGraph 编排（TODO）

// 完整的图编排示例将在后续版本中提供

🔧 配置

注册检索器

@Configuration
public class RagConfig {

    @Bean
    public CommandLineRunner registerRetrievers(RetrieverRegistry registry) {
        return args -> {
            // 注册向量检索器
            registry.register("vector", "向量检索器", vectorRetriever());

            // 注册关键词检索器
            registry.register("keyword", "关键词检索器", keywordRetriever());

            // 注册混合检索器
            registry.register("hybrid", "混合检索器", hybridRetriever());
        };
    }

    private ContentRetriever vectorRetriever() {
        // 返回向量检索器实例
        return ...;
    }
}

📊 监控和调试

每个服务调用都会记录详细日志：

===== QueryTransformService.transform =====
原始查询: 审计标准中关于内部控制的要求
转换策略: MULTI_QUERY
转换结果: 3 个查询

===== RetrievalService.retrieve =====
查询: [查询1, 查询2, 查询3]
检索器: [vector, keyword]
执行模式: PARALLEL
检索到 15 个内容

===== QualityAssessmentService.assess =====
评估类型: RETRIEVAL_QUALITY
评估得分: 0.82
发现问题: []

🎓 最佳实践

1. 选择合适的调用方式

• 简单场景：直接注入 Service 调用
• 外部系统集成：使用 REST API
• 复杂流程：使用 LangGraph 编排
• 异步处理：使用消息队列

2. 合理使用并行检索

// ✅ 推荐：多个查询 + 多个检索器 = 并行提速
RetrievalRequest.builder()
    .queries(List.of("查询1", "查询2", "查询3"))
    .retrieverNames(List.of("vector", "keyword", "hybrid"))
    .executionMode(RetrievalExecutionMode.PARALLEL)
    .build()

// ❌ 不推荐：单查询单检索器使用并行模式
RetrievalRequest.builder()
    .queries(List.of("查询1"))
    .retrieverNames(List.of("vector"))
    .executionMode(RetrievalExecutionMode.PARALLEL)  // 没有意义
    .build()

3. 质量评估的使用时机

• 检索后：评估检索质量，决定是否需要重试
• 生成后：评估响应质量，决定是否需要修正
• 调试时：使用相关性、覆盖度、多样性评估找问题

📝 开发计划

• [x] 查询转换服务
• [x] 检索服务
• [x] 质量评估服务
• [ ] 聚合服务（去重、重排序、过滤）
• [ ] 提示注入服务
• [ ] 生成服务
• [ ] 自我修正服务
• [ ] 完整的 LangGraph 编排示例
• [ ] 配置化的图构建器

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License