RAG增强方案技术文档

1. 项目概述

1.1 项目背景

本项目实现了一套完整的检索增强生成（Retrieval-Augmented Generation, RAG）系统，旨在通过多阶段优化技术提升问答系统的准确性和可靠性。系统基于 Golang 实现，支持模块化配置，能够灵活应对不同的应用场景。

1.2 核心技术栈

编程语言: Go 1.x
向量数据库: Milvus 2.4+
LLM支持: OpenAI兼容协议
Embedding模型: 支持OpenAI兼容的嵌入模型
重排序器: Cohere、OpenAI、Qwen多种实现
评测框架: 支持HotpotQA、Natural Questions等标准数据集

1.3 核心创新点

完整的CRAG工作流实现：包含检索评估器、查询重写、外部搜索等完整纠正性检索机制
多维度检索后优化：实现重排序、去重、上下文压缩、句子级过滤等多种后处理技术
可量化的评测体系：提供完整的评测框架，支持Precision/Recall/F1和Factuality Score等指标
高度模块化设计：各组件独立可配置，支持灵活组合和替换

2. 架构设计

2.1 整体架构

graph TB subgraph sg1 ["检索前优化 Pre-Retrieval"] A[用户查询] --> B[查询重写
Query Rewriter] A --> B2[HyDE转换
Hypothetical Doc] B --> C[优化后查询] B2 --> C2[假设文档] end subgraph sg2 ["检索阶段 Retrieval"] C --> D[Embedding生成] C2 --> D D --> E[向量数据库检索
Milvus] E --> F[候选文档集] end subgraph sg3 ["检索后优化 Post-Retrieval"] F --> G[重排序
Reranker] G --> H[去重
Deduplication] H --> I[上下文压缩
Context Compression] I --> J[句子级过滤
Sentence Filter] J --> K[位置优化
Position Strategy] end subgraph sg4 ["CRAG纠正性检索"] K --> L{检索评估器
Evaluator} L -->|高质量| M[生成答案] L -->|低质量| N[查询重写] N --> O[外部搜索
Web Search] O --> L end subgraph sg5 ["生成阶段 Generation"] M --> P[Prompt构建] P --> Q[LLM生成] Q --> R[最终答案] end style A fill:#e1f5ff style R fill:#d4edda style L fill:#fff3cd style B2 fill:#ffe6cc

架构说明：

检索前优化层：
- 查询重写：通过 LLM 对用户查询进行优化重写，提升检索关键词质量
- HyDE 转换：生成假设性答案文档，用于语义检索，缩小问题-答案的语义鸿沟
- 两种策略可根据查询复杂度和场景需求灵活选择
检索层：基于 Milvus 向量数据库进行语义检索，支持查询向量或假设文档向量
检索后优化层：多级过滤和优化，确保上下文质量
CRAG纠正层：评估检索质量，必要时触发外部搜索补充
生成层：基于优化后的上下文生成最终答案

2.2 理论依据

本方案架构基于以下学术研究：

CRAG (Corrective Retrieval Augmented Generation)
- 论文: Yan S Q, Gu J C, Zhu Y, et al. Corrective retrieval augmented generation[J]. 2024.
- 核心思想: 通过检索评估器判断文档质量，对低质量检索结果触发纠正性行动
- 实现位置: crag/light_crag.go:65-97
Query Rewriting
- 论文:
  - Ma X, Gong Y, He P, et al. Query rewriting in retrieval-augmented large language models[C]//Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing. 2023: 5303-5315.
  - Gao L, Ma X, Lin J, et al. Precise zero-shot dense retrieval without relevance labels[C]//Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). 2023: 1762-1777.
- 基于LLM的查询优化技术，将自然语言转换为更适合搜索引擎的关键词
- 实现位置: llm/query_transformation.go:12-84
Re-ranking
- 论文：
  - Nogueira R, Cho K. Passage Re-ranking with BERT[J]. arXiv preprint arXiv:1901.04085, 2019.
  - Karpukhin V, Oguz B, Min S, et al. Dense Passage Retrieval for Open-Domain Question Answering[C]//EMNLP (1). 2020: 6769-6781.
- 使用Cross-Encoder或LLM对粗排结果进行精排
- 实现位置: rag_client.go:159-215

2.3 检索前优化 (Pre-Retrieval)

检索前优化通过对用户原始查询进行转换和增强,提升检索效果。本系统实现了两种主要技术：查询重写和 HyDE (Hypothetical Document Embeddings)。

2.3.1 查询转换机制 (Query Transformation)

查询转换是检索前优化的核心技术，通过 LLM 对用户原始查询进行智能改写，使其更适合向量检索引擎。本系统实现了三种互补的查询转换策略，分别针对不同的检索挑战场景。

策略 1：查询重写 (Query Rewrite)

核心思想：

查询重写通过增强查询的具体性和细节性，提升检索的精确度。许多用户查询过于简略或表述模糊，直接检索容易产生语义偏差。查询重写通过 LLM 将原始查询改写为更详细、更明确的表述，使其与知识库中的文档表述更加匹配。

Prompt 模板 (llm/prompt.go:28-38):

const RewriteQueryPromptTemplate = ` You are an AI assistant tasked with reformulating user queries to improve retrieval in a RAG system. 
        Given the original query, rewrite it to be more specific, detailed, and likely to retrieve relevant information.

        Original query: {original_query}

        Rewritten query:`

工作原理：

语义扩展：将简短查询扩展为包含更多上下文的完整表述
术语规范化：将口语化表达转换为技术文档中常用的专业术语
歧义消除：明确查询意图，减少多义性词汇的干扰
关键词强化：补充隐含的关键概念，提升语义匹配度

使用场景：

用户查询过于简略（如"怎么用？"）
口语化表达与文档用词不匹配（如"搞定登录"→"实现用户身份验证"）
查询包含代词或隐含引用（如"它支持什么功能？"）
需要补充领域特定术语的场景

示例转换：

原始查询: "怎么加缓存？"
重写查询: "如何在应用程序中集成 Redis 缓存系统以提升数据访问性能？"

原始查询: "登录失败"
重写查询: "用户身份验证失败的常见原因及排查方法"

策略 2：后退提问 (Step-back Prompting)

核心思想：

后退提问通过生成更宽泛、更抽象的查询，帮助检索系统找到相关的背景知识和原理性文档。当用户提出具体的细节问题时，系统可能因过度聚焦而错过包含答案的宏观文档。后退提问先退一步，检索更通用的知识，再结合原始查询提供综合性答案。

Prompt 模板 (llm/prompt.go:40-50):

const GenerateStepBackQueryPromptTemplate = `You are an AI assistant tasked with generating broader, more general queries to improve context retrieval in a RAG system.
        Given the original query, generate a step-back query that is more general and can help retrieve relevant background information.

        Original query: {original_query}

        Step-back query:`

工作原理：

抽象层级提升：从具体问题抽象到更高层次的概念或原理
背景知识召回：检索包含基础知识、原理说明的宏观文档
知识桥接：通过通用知识连接到具体答案
多层次检索：结合原始查询和后退查询的检索结果

使用场景：

用户提出非常具体的技术细节问题
需要理解基础概念才能回答的问题
原始查询过于狭窄，导致召回率低
知识库中更多以原理性文档形式存在答案

示例转换：

原始查询: "为什么 Kubernetes Pod 启动时出现 ImagePullBackOff 错误？"
后退查询: "Kubernetes Pod 生命周期和镜像拉取机制的基本原理"

原始查询: "如何优化 React useEffect 的依赖数组？"
后退查询: "React Hooks 的工作原理和最佳实践"

与查询重写的区别：

查询重写：横向扩展，增加细节，保持同一抽象层级
后退提问：纵向抽象，提升层级，关注原理 and 背景知识

策略 3：查询分解 (Query Decomposition)

核心思想：

查询分解将复杂的多维度查询拆解为 2-4 个简单、独立的子查询。许多用户问题同时涉及多个方面或概念，单次检索难以全面覆盖。通过分解为多个聚焦的子问题，每个子查询独立检索，最后综合所有结果提供完整答案。

Prompt 模板 (llm/prompt.go:52-68):

const DecomposeQueryPromptTemplate = `You are an AI assistant tasked with breaking down complex queries into simpler sub-queries for a RAG system.
        Given the original query, decompose it into 2-4 simpler sub-queries that, when answered together, would provide a comprehensive response to the original query.

        Original query: {original_query}

        example: What are the impacts of climate change on the environment?

        Sub-queries:
        1. What are the impacts of climate change on biodiversity?
        2. How does climate change affect the oceans?
        3. What are the effects of climate change on agriculture?
        4. What are the impacts of climate change on human health?`

工作原理：

复杂性分析：识别查询中包含的多个独立方面或维度
智能分解：使用 LLM 将复杂查询分解为 2-4 个相互关联但独立的子查询
并行检索：每个子查询独立检索相关文档，获得更精准的结果
结果整合：综合所有子查询的检索结果，提供全面的答案

使用场景：

查询包含多个并列的概念或维度（如"对比 A 和 B"）
需要从多个角度回答的问题（如"影响、原因、解决方案"）
复杂的因果关系或流程性问题
需要结构化、分条理的答案

示例转换：

原始查询: "如何设计一个高可用的微服务架构？"
分解查询:
1. 微服务架构中如何实现服务发现和负载均衡？
2. 如何设计微服务的容错和熔断机制？
3. 微服务架构中的数据一致性如何保证？
4. 如何监控和追踪微服务的健康状态？

优势：

提升召回率：每个子查询独立检索，避免复杂查询导致的语义模糊
增强精确度：子查询更具体，可以匹配到更相关的文档段落
结构化答案：分解后的子查询有助于生成更有条理的答案
覆盖全面性：确保复杂问题的各个方面都得到检索和回答

代码实现与集成

查询转换接口 (llm/query_transformation.go:12-47):

系统通过 QueryTransformation 方法统一调用这些转换策略，可以根据配置灵活选择使用哪种 Prompt：

func (o *OpenAIProvider) QueryTransformation(ctx context.Context, query string) (string, error) {
    // 根据配置选择不同的 Prompt 构建方法
    // prompt := BuildRewriteQueryPrompt(query)           // 策略1: 查询重写
    // prompt := BuildGenerateStepBackQueryPrompt(query)  // 策略2: 后退提问
    prompt := BuildDecomposeQueryPrompt(query)            // 策略3: 查询分解
    
    // Create chat request
    params := openai.ChatCompletionNewParams{
        Model: o.model,
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage(prompt),
        },
    }

    // Set optional parameters
    if o.temperature > 0 {
        temperature := float64(o.temperature)
        params.Temperature = param.Opt[float64]{Value: temperature}
    }

    if o.maxTokens > 0 {
        maxTokens := int64(o.maxTokens)
        params.MaxTokens = param.Opt[int64]{Value: maxTokens}
    }

    // Send request
    response, err := o.client.Chat.Completions.New(ctx, params)
    if err != nil {
        return "", fmt.Errorf("openai llm error: %w", err)
    }

    // Check response
    if len(response.Choices) == 0 {
        return "", errors.New("openai llm: empty choices")
    }

    // Return generated content
    return response.Choices[0].Message.Content, nil
}

三种策略的选择建议：

查询特征	推荐策略	理由
简短、模糊的查询	查询重写	需要补充细节和上下文
具体的技术细节问题	后退提问	需要先理解背景知识和原理
多维度、复杂问题	查询分解	需要拆分为独立子问题并行检索
口语化表达	查询重写	需要转换为文档化的专业术语
对比类问题	查询分解	每个对比项独立检索更精确
召回率过低	后退提问	扩大检索范围到更宏观的知识

组合使用策略：

在实际应用中，可以组合使用多种策略：

串行组合：先后退提问检索背景知识，再查询重写检索具体答案
并行组合：同时使用查询重写和查询分解，融合检索结果
动态选择：根据查询复杂度和长度，自动选择最合适的策略

2.3.2 HyDE (Hypothetical Document Embeddings)

核心思想：

HyDE 是一种创新的检索前优化技术,其核心思想是"以答案搜答案"。传统检索直接将用户问题转换为向量进行检索,而 HyDE 先让 LLM 生成一个假设性的答案文档,然后用这个假设文档的向量去检索真实文档。

工作原理：

假设文档生成：使用 LLM 根据用户查询生成一个详细的、结构化的假设文档,就像从权威来源提取的真实答案段落
语义对齐优势：假设文档与真实答案文档在语义空间中距离更近,比原始问题更容易匹配到正确文档
检索增强：使用假设文档的 embedding 进行向量检索,提升检索相关性和召回率

代码实现 (llm/query_transformation.go:49-84):

func (o *OpenAIProvider) HyDETransformation(ctx context.Context, query string) (string, error) {
    prompt := BuildHyDEPrompt(query)
    // Create chat request
    params := openai.ChatCompletionNewParams{
        Model: o.model,
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage(prompt),
        },
    }

    // Set optional parameters
    if o.temperature > 0 {
        temperature := float64(o.temperature)
        params.Temperature = param.Opt[float64]{Value: temperature}
    }

    if o.maxTokens > 0 {
        maxTokens := int64(o.maxTokens)
        params.MaxTokens = param.Opt[int64]{Value: maxTokens}
    }

    // Send request
    response, err := o.client.Chat.Completions.New(ctx, params)
    if err != nil {
        return "", fmt.Errorf("openai llm error: %w", err)
    }

    // Check response
    if len(response.Choices) == 0 {
        return "", errors.New("openai llm: empty choices")
    }

    // Return generated hypothetical document
    return response.Choices[0].Message.Content, nil
}

Prompt 模板 (llm/prompt.go:70-78):

const HyDEPromptTemplate = `You are an AI assistant tasked with generating a hypothetical document that would perfectly answer the given query.
This hypothetical document will be used for retrieval in a RAG system to find similar real documents.

Given the user's query, write a detailed, well-structured document passage that directly answers the query as if it were extracted from an authoritative source.
The document should be informative, specific, and contain relevant details and terminology that would appear in actual documents covering this topic.

User query: {original_query}

Hypothetical document:`

使用场景：

复杂查询：当用户查询涉及多个概念或需要综合性答案时
术语匹配：通过生成包含专业术语的假设文档,提升术语匹配准确性
语义扩展：自动扩展查询的语义范围,覆盖相关但表述不同的文档

优势：

缩小问题-答案之间的语义鸿沟
无需依赖查询历史或外部知识库
与现有向量检索系统无缝集成

注意事项：

增加一次 LLM 调用的延迟成本
适合知识密集型任务,简单查询可能过度优化
建议与查询重写配合使用,根据查询复杂度动态选择策略

2.3.3 多路召回 (Multi-Path Retrieval)

设计动机

传统单路召回的局限性：

复杂查询通常包含多个维度或方面，单次向量检索难以全面覆盖所有相关信息
对比类问题（如"比较React和Vue的性能差异"）需要分别检索两个对象的信息
多跳推理问题需要逐步检索中间步骤的知识
单一查询向量可能因语义模糊导致检索结果偏向某一方面

多路召回的核心价值：

提升召回率：通过多个独立的检索路径，确保复杂查询的各个方面都能被覆盖
增强结果多样性：避免检索结果过度集中在某一主题或角度
支持结构化答案：为生成分条理、多角度的答案提供更全面的上下文
降低语义偏差：多个子查询的综合检索可以平衡单一查询向量的语义偏差

技术实现原理

多路召回基于**查询分解（Query Decomposition）**技术实现，核心思路是将一个复杂查询分解为2-4个简单、聚焦的子查询，每个子查询独立执行向量检索，最后融合所有检索结果。

核心接口设计 (qrewrite/query_rewrite.go:14-16):

1
2
3

type QueryRewriter interface {
    rewrite(ctx context.Context, query string) ([]string, error)
}

关键特性：

返回类型：[]string - 支持一对多的查询转换，每个字符串代表一个子查询
并行检索：多个子查询可以并行执行向量检索，降低总体延迟
结果融合：所有子查询的检索结果合并后统一处理（去重、重排序）

查询分解实现 (qrewrite/decompose.go:43-50):

func (h *QueryDecomposeTransformer) rewrite(ctx context.Context, query string) ([]string, error) {
    prompt := BuildDecomposeQueryPrompt(query)
    completion, err := h.llm.GenerateCompletion(ctx, prompt)
    if err != nil {
        return nil, err
    }
    // 按双换行符分割LLM返回的子查询列表
    subQueries := strings.Split(completion, "\n\n")
    return subQueries, nil
}

Prompt工程 (qrewrite/decompose.go:12-32):

const DecomposeQueryPromptTemplate = `
You are an AI assistant tasked with breaking down complex queries into simpler sub-queries for a RAG system.
Given the original query, decompose it into 2-4 simpler sub-queries that, when answered together, would provide a comprehensive response to the original query.
        
Format Requirements:
1. Each sub-query must be separated by two newline characters (\\n\\n).
2. Only return the sub-queries in the response, with no additional content (such as numbering, introductory text, explanations, or example-related content) to facilitate subsequent extraction from the response.

example: What are the impacts of climate change on the environment?

Sub-queries (for reference only, do not return numbered content):
What are the impacts of climate change on biodiversity?

How does climate change affect the oceans?

What are the effects of climate change on agriculture?

What are the impacts of climate change on human health?

User query: {original_query}
`

Prompt设计要点：

严格的格式要求：要求LLM只返回子查询，不包含编号、说明等额外内容
分隔符规范：使用双换行符（\n\n）分隔子查询，便于程序化解析
Few-Shot示例：提供气候变化示例，引导LLM理解分解粒度和方式
数量控制：限制生成2-4个子查询，平衡覆盖度和检索效率

完整工作流程

flowchart TB A[用户原始查询] --> B[QueryDecomposeTransformer
查询分解器] B --> C[LLM生成2-4个子查询] C --> D1[子查询1:
方面A] C --> D2[子查询2:
方面B] C --> D3[子查询3:
方面C] C --> D4[子查询4:
方面D] D1 --> E1[Embedding生成1] D2 --> E2[Embedding生成2] D3 --> E3[Embedding生成3] D4 --> E4[Embedding生成4] E1 --> F1[向量检索1
TopK=20] E2 --> F2[向量检索2
TopK=20] E3 --> F3[向量检索3
TopK=20] E4 --> F4[向量检索4
TopK=20] F1 --> G[结果池合并
总计约60-80个文档] F2 --> G F3 --> G F4 --> G G --> H[去重处理
Deduplication] H --> I[重排序
Reranker] I --> J[TopN筛选
保留最优5-10个] J --> K[最终检索结果] style B fill:#fff3cd style G fill:#ffe6cc style I fill:#d4edda

流程说明：

查询分解阶段：使用LLM将复杂查询分解为2-4个独立子查询
并行检索阶段：每个子查询独立生成Embedding并检索TopK文档（如20个）
结果合并阶段：将所有检索结果合并到统一的结果池（约60-80个文档）
后处理阶段：
- 去重：移除重复或高度相似的文档
- 重排序：使用Cross-Encoder对所有文档统一打分
- TopN筛选：保留最相关的5-10个文档用于生成

实际应用场景

场景1：对比分析查询

原始查询: "比较React和Vue的性能差异"

分解结果:
1. React框架的性能特点和优化方式
2. Vue框架的性能特点和优化方式
3. React和Vue性能基准测试对比数据
4. 实际项目中React和Vue的性能表现差异

检索效果:
- 子查询1和2分别检索各框架的专属文档
- 子查询3检索对比测试报告
- 子查询4检索实践案例
- 综合结果覆盖多个维度，避免偏向某一框架

场景2：多维度复杂查询

原始查询: "如何设计一个高可用的微服务架构？"

分解结果:
1. 微服务架构中如何实现服务发现和负载均衡？
2. 如何设计微服务的容错和熔断机制？
3. 微服务架构中的数据一致性如何保证？
4. 如何监控和追踪微服务的健康状态？

检索效果:
- 每个子查询聚焦一个技术维度
- 检索结果覆盖服务治理的多个关键方面
- 生成的答案结构化、分条理

场景3：多跳推理查询

原始查询: "谁发明了运行世界上第一个Web服务器的计算机所使用的操作系统？"

分解结果:
1. 世界上第一个Web服务器运行在哪台计算机上？
2. 该计算机使用的操作系统是什么？
3. 该操作系统的发明者是谁？

检索效果:
- 子查询1检索Web服务器历史
- 子查询2检索计算机配置信息
- 子查询3检索操作系统创作者
- 逐步推理得出最终答案

性能优化策略

并行检索优化：

// 伪代码示例：并行执行多路检索
func MultiPathRetrieval(subQueries []string) []Document {
    var wg sync.WaitGroup
    results := make([][]Document, len(subQueries))
    
    for i, query := range subQueries {
        wg.Add(1)
        go func(index int, q string) {
            defer wg.Done()
            results[index] = VectorSearch(q, topK=20)
        }(i, query)
    }
    
    wg.Wait()
    return MergeAndDeduplicate(results)
}

优势：

多个子查询的检索并行执行，总延迟接近单次检索
充分利用向量数据库的并发能力

结果融合策略：

去重：
- MD5哈希快速去重：移除完全相同的文档
- Jaccard相似度精准去重：移除高度相似文档（阈值0.9）
重排序：
- 使用Reranker对合并后的所有文档统一打分
- 基于原始查询（而非子查询）进行相关性评估
- 确保最终结果与用户意图高度对齐
TopN选择：
- 保留得分最高的5-10个文档
- 平衡上下文丰富度和生成质量
与其他优化技术的协同：
- 查询分解 + 重排序：必选组合，确保融合结果的质量
- 查询分解 + CRAG：对每个子查询的检索结果独立评估，触发纠正
- 查询分解 + HyDE：先分解再为每个子查询生成假设文档

2.4 检索阶段

2.4.1 Embedding生成与向量检索

技术选型：

支持OpenAI兼容的Embedding模型（如text-embedding-v4）
默认维度：1536维（可配置）

检索流程 (rag_client.go:141-156):

将查询文本转换为向量表示
在Milvus中执行向量相似度搜索
返回TopK个最相关文档

索引配置：

索引类型：HNSW（高性能近似最近邻）
度量方式：IP（内积）或L2（欧氏距离）
参数：M=4, efConstruction=32

2.5 检索后优化 (Post-Retrieval)

检索后优化是RAG系统的关键环节，通过重排序、去重、压缩和位置优化等技术，显著提升检索质量和生成效果。

2.5.1 重排序 (Reranker)

核心价值

解决双塔模型（Embedding）的语义匹配局限性
通过交叉编码器进行精细的文档-查询相关性评分
典型提升：Top-5准确率提升15-30%

多Provider支持

Cohere Rerank API: 支持多语言，效果业界领先
OpenAI Cross-Encoder: 基于GPT的语义理解能力
Qwen Reranker（阿里云）: 针对中文优化

重排序流程

(rag_client.go:159-215)

graph LR A[候选文档
20-50个] --> B[提取文档内容] B --> C[调用Reranker API
批量打分] C --> D[获取新的相关性分数
0-1之间] D --> E[按分数重新排序
降序排列] E --> F[应用TopN和MinScore过滤] F --> G[输出精排文档
5-10个]

配置参数

RerankTopN: 重排序后保留的文档数量（默认5，建议3-10）
RerankMinScore: 最低分数阈值（默认0.3，建议0.2-0.5）
RerankProvider: 重排序服务提供商
RerankModel: 具体使用的重排序模型

性能优化

// 批量重排序，减少API调用次数
func (r *RAGClient) rerankDocuments(docs []Document, query string) []Document {
    if len(docs) <= r.config.RerankTopN {
        return docs // 跳过不必要的重排序
    }
    // 批量处理，一次API调用处理所有文档
    scores := r.callRerankAPI(docs, query)
    return r.sortAndFilter(docs, scores)
}

2.5.2 去重 (Deduplication)

为什么需要去重

向量检索可能返回内容高度重复的文档片段
重复内容浪费Token预算，降低信息密度
可能误导LLM产生重复性回答

去重策略

(rag_client.go:310-347)

1. 快速哈希去重

计算文档内容的MD5哈希
O(n)时间复杂度，秒级处理
适用于完全相同的文档

2. 语义相似度去重

使用Jaccard相似度计算文本重叠度
基于词集合的交集/并集比例
捕获改写或部分重复的内容

3. 阈值控制

相似度超过0.9视为重复（可配置）
保留得分更高的文档

核心代码

func (r *RAGClient) computeTextSimilarity(text1, text2 string) float64 {
    words1 := r.tokenizeWords(text1)  // 中文分词/英文split
    words2 := r.tokenizeWords(text2)
    
    // Jaccard相似度计算
    intersection := computeIntersection(words1, words2)
    union := len(words1) + len(words2) - intersection
    
    if union == 0 {
        return 0.0
    }
    return float64(intersection) / float64(union)
}

// 去重主流程
func (r *RAGClient) deduplicateDocuments(docs []Document) []Document {
    seen := make(map[string]bool)
    result := []Document{}
    
    for _, doc := range docs {
        hash := computeHash(doc.Content)
        if seen[hash] {
            continue  // 哈希去重
        }
        
        // 语义去重
        isDuplicate := false
        for _, existing := range result {
            if r.computeTextSimilarity(doc.Content, existing.Content) > 0.9 {
                isDuplicate = true
                break
            }
        }
        
        if !isDuplicate {
            seen[hash] = true
            result = append(result, doc)
        }
    }
    return result
}

性能考量

语义去重的时间复杂度为O(n²)
建议先进行哈希去重，减少比较次数
对于大量文档（>100），可考虑MinHash或LSH算法

2.5.3 上下文压缩 (Context Compression)

压缩目标

减少Token消耗（节省API成本）
降低LLM推理延迟
保留最相关的核心信息

压缩流程

(rag_client.go:267-287)

graph TD A[原始文档集
可能5000+ tokens] --> B[按分数过滤
移除低分文档] B --> C[去重处理
移除重复内容] C --> D[句子级压缩
提取关键句] D --> E[Token预算控制
硬截断] E --> F[压缩后文档
2000 tokens以内]

关键技术

1. 分数过滤 (rag_client.go:289-307)

func (r *RAGClient) filterByScore(docs []Document) []Document {
    filtered := []Document{}
    for _, doc := range docs {
        if doc.Score >= r.config.MinScore {
            filtered = append(filtered, doc)
        }
    }
    // 限制最大文档数量
    if len(filtered) > r.config.MaxDocs {
        filtered = filtered[:r.config.MaxDocs]
    }
    return filtered
}

移除低于MinScore阈值的文档
限制最大文档数量（避免过载）

2. 句子级压缩 (rag_client.go:421-480)

func (r *RAGClient) compressSentences(text string, query string) string {
    sentences := r.splitSentences(text)
    scored := []ScoredSentence{}
    
    for i, sent := range sentences {
        score := r.scoreSentence(sent, query, i, len(sentences))
        scored = append(scored, ScoredSentence{sent, score})
    }
    
    // 排序并保留高分句子
    sort.Slice(scored, func(i, j int) bool {
        return scored[i].Score > scored[j].Score
    })
    
    // 保留Top 50%的句子
    topN := len(scored) / 2
    return r.reconstructText(scored[:topN])
}

评分策略：

关键词匹配（权重0.5）: 包含查询词的句子得分更高
位置权重（权重0.3）: 首尾句子通常更重要
长度惩罚（权重0.2）: 避免过长或过短的句子

func (r *RAGClient) scoreSentence(sent, query string, pos, total int) float64 {
    // 关键词匹配得分
    keywordScore := r.countKeywordMatches(sent, query) * 0.5
    
    // 位置权重（U型曲线，首尾重要）
    positionScore := 0.0
    if pos < 2 || pos >= total-2 {
        positionScore = 0.3
    }
    
    // 长度惩罚
    length := len([]rune(sent))
    lengthScore := 0.2
    if length < 10 || length > 200 {
        lengthScore = 0.0
    }
    
    return keywordScore + positionScore + lengthScore
}

3. Token预算管理 (rag_client.go:539-561)

func (r *RAGClient) enforceTokenBudget(docs []Document) []Document {
    totalTokens := 0
    result := []Document{}
    
    for _, doc := range docs {
        docTokens := r.estimateTokens(doc.Content)
        if totalTokens + docTokens > r.config.MaxContextTokens {
            // 尝试截断当前文档
            remaining := r.config.MaxContextTokens - totalTokens
            if remaining > 100 {  // 至少保留100 tokens
                doc.Content = r.truncateToTokens(doc.Content, remaining)
                result = append(result, doc)
            }
            break
        }
        totalTokens += docTokens
        result = append(result, doc)
    }
    return result
}

Token估算：中文字符/2.5，英文单词数×1.3
动态截断：确保不超过MaxContextTokens（默认2000）
优先级保障：高分文档优先分配Token预算

压缩效果示例

原始: 15个文档，6000 tokens
↓ 分数过滤（MinScore=0.3）
10个文档，4000 tokens
↓ 去重（Jaccard阈值=0.9）
8个文档，3200 tokens
↓ 句子级压缩（保留50%句子）
8个文档，1600 tokens
↓ Token预算控制（MaxTokens=2000）
最终: 8个文档，1600 tokens（压缩率73%）

2.5.4 位置优化策略

背景：LLM的"大海捞针"问题

研究表明LLM对长上下文中间部分的信息提取能力较弱
首尾位置的信息被更好地"记住"和利用
论文参考：Liu N F, Lin K, Hewitt J, et al. Lost in the middle: How language models use long contexts[J]. Transactions of the Association for Computational Linguistics, 2024, 12: 157-173.

支持的策略

(rag_client.go:612-630)

1. top_first（默认）

1 2	// 保持原有排序，按相关性得分降序 // 适用场景：文档数量少（<5个），或已经过精心重排序

2. sandwich（推荐）

func (r *RAGClient) applySandwichStrategy(docs []Document) []Document {
    if len(docs) <= 2 {
        return docs
    }
    
    result := []Document{}
    mid := len(docs) / 2
    
    // 高分文档放首部
    result = append(result, docs[:mid]...)
    // 低分文档放中间
    reversed := reverse(docs[mid:])
    result = append(result, reversed...)
    
    return result
}

原理：高分文档放首尾，低分文档放中间
效果：Top-1准确率提升10-20%
适用：文档数量中等（5-15个）

3. reverse（实验性）

1 2	// 完全反转顺序 // 适用场景：某些LLM可能对后面的内容更敏感（需要实验验证）

Sandwich策略详解

原始排序（按得分降序）:
[Doc1:0.95] [Doc2:0.90] [Doc3:0.85] [Doc4:0.75] [Doc5:0.70] [Doc6:0.60]

Sandwich策略后:
[Doc1:0.95] [Doc2:0.90] [Doc3:0.85]  <- 高分放前
[Doc6:0.60] [Doc5:0.70] [Doc4:0.75]  <- 低分倒序放后

LLM注意力分布:
首部 ████████ 高
中部 ████     低  <- 放低分文档，降低误导风险
尾部 ████████ 高  <- 放中等文档，提升召回

策略选择建议

文档数量	文档质量	推荐策略	原因
1-3个	任意	top_first	无需优化
5-15个	质量参差	sandwich	最大化利用LLM注意力
15+个	已精排序	top_first	保持排序一致性
任意	实验场景	reverse	A/B测试

配置示例

post_retrieval:
  rerank:
    enabled: true
    provider: cohere
    top_n: 8
    min_score: 0.3
  
  deduplication:
    enabled: true
    similarity_threshold: 0.9
  
  compression:
    max_context_tokens: 2000
    sentence_compression_ratio: 0.5
    min_score_filter: 0.25
  
  position_strategy: sandwich  # top_first | sandwich | reverse

2.6 纠正性检索 (CRAG)

2.6.1 CRAG核心理论

论文来源: Yan S Q, Gu J C, Zhu Y, et al. Corrective retrieval augmented generation[J]. 2024.

核心问题: 传统RAG系统存在的关键缺陷

静态信任假设: 默认所有检索结果都是高质量的，缺乏质量评估机制
闭环知识局限: 仅依赖向量数据库内的知识，无法应对知识库覆盖不足的场景
误导性文档风险: 低相关度或错误文档会严重影响LLM生成质量
缺乏自适应能力: 无法根据检索质量动态调整策略

CRAG核心思想:

质量感知: 引入检索评估器对每个文档进行细粒度相关性评分
自适应纠正: 当检索质量不足时，自动触发补救措施（查询重写+外部搜索）
知识扩展: 突破向量数据库边界，利用Web搜索补充新鲜、全面的外部知识
闭环优化: 重新评估合并后的结果，确保达到质量阈值后再生成答案

技术价值:

显著降低误导性文档导致的幻觉问题
提升对冷门、新鲜、跨领域问题的回答能力
在HotpotQA、PopQA等基准测试中取得SOTA性能

2.6.2 CRAG工作流设计

flowchart TD A[用户查询] --> B[向量数据库检索] B --> C[检索评估器打分] C --> D{质量评估决策} D -->|高质量文档≥minDocNeed| E[直接生成答案] D -->|高质量文档不足| F[查询重写模块] F --> G[外部Web搜索] G --> H[结果合并] H --> I[重新评估] I --> J{达到质量要求?} J -->|是| E J -->|否且重试<3| F J -->|重试≥3| E style D fill:#fff3cd style J fill:#fff3cd style F fill:#ffe6cc

工作流分阶段说明:

阶段1: 初始检索与评估

向量检索返回topK个候选文档
评估器并发评估所有文档，计算相关性分数
过滤低于阈值的文档，统计高质量文档数量

阶段2: 质量决策

判断条件: relevantCount >= minDocNeed
充足: 直接进入生成阶段
不足: 触发纠正性检索流程

阶段3: 查询重写

使用LLM将自然语言查询转换为搜索引擎友好的关键词
去除口语化表达，提取核心实体和意图
优化查询结构以提升Web搜索命中率

阶段4: 外部搜索

调用Google/Bing等搜索引擎API
提取搜索结果的snippet作为补充知识
重试机制确保API调用的鲁棒性

阶段5: 重新评估与迭代

合并原有文档与Web搜索结果
重新执行评估流程
若仍不满足质量要求且重试次数<3，返回阶段3
达到最大重试次数后强制进入生成阶段（防止无限循环）

实现代码 (crag/light_crag.go:65-97):

func (l *LightCRAG) run(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    var err error
    // 第一轮评估
    filteredDocs := l.evaluator.Score(query, docs)
    maxRetries := 3
    retries := 0
    
    // 自适应纠正循环
    for l.evaluator.IsNeedWebSearch() && retries < maxRetries {
        // 1. 查询重写
        queries := []string{query}
        for index, q := range queries {
            queries[index], err = l.queryRewriter.Convert(q)
            if err != nil {
                continue
            }
        }
        
        // 2. 外部搜索
        webResults, err := l.externalSearcher.Search(queries)
        if err != nil {
            break
        }
        
        // 3. 结果合并
        for _, result := range webResults {
            for _, item := range result.Results {
                searchResult := &schema.SearchResult{
                    Document: schema.Document{
                        Content: item.Snippet,
                    },
                }
                filteredDocs = append(filteredDocs, searchResult)
            }
        }
        
        // 4. 重新评估
        filteredDocs = l.evaluator.Score(query, filteredDocs)
        retries++
    }
    
    return filteredDocs
}

2.6.3 检索评估器深度设计

本方案实现了两种互补的评估器架构，满足不同场景需求：

1. LLM-based Evaluator (crag/evaluator/evaluator_llm.go)

设计动机:

LLM具备强大的语义理解能力，能够深度理解查询意图和文档内容
通过多维度评分体系，精细量化文档与查询的相关性
支持复杂推理场景（如需要常识推理、时间推理的查询）

八维度评分体系 (基于信息检索理论):

维度	英文名称	说明	评分标准
主题对齐度	TopicalAlignment	文档主题与查询主题的匹配度	0.0:完全无关 → 1.0:完全一致
意图对齐度	IntentAlignment	文档是否符合用户意图(事实查询/操作指南/比较分析等)	基于查询类型判断文档是否提供对应信息
关键实体匹配	KeyEntityMatch	文档是否包含查询中的关键实体、术语、数字	统计实体覆盖率和准确性
直接回答能力	DirectAnswerAbility	文档是否直接包含答案或能够推导出答案	1.0:直接包含答案；0.5:可推导；0.0:无法回答
覆盖深度	CoverageDepth	文档对查询涉及方面的覆盖完整性和深度	评估信息的全面性和详细程度
查询特异性	SpecificityToQuery	文档内容是否针对性强，还是过于宽泛或离题	1.0:高度针对性；0.0:泛泛而谈
时间相关性	TemporalFit	文档时间信息与查询时间需求的一致性	适用于时效性敏感的查询
语言术语对齐	LanguageTerminologyAlignment	文档语言风格和专业术语与查询的匹配度	评估语言风格和领域术语的一致性

评分机制 (crag/evaluator/evaluator_llm.go:94-130):

func (L *LLMEvaluator) Score(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    var wg sync.WaitGroup
    
    // 并发评估所有文档（充分利用LLM API的并发能力）
    for _, doc := range docs {
        wg.Add(1)
        go func(doc *schema.SearchResult) {
            defer wg.Done()
            eval_prompt := buildPrompt(query, doc.Document.Content)
            ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
            defer cancel()
            
            completion, err := L.llm.GenerateCompletion(ctx, eval_prompt)
            if err != nil {
                log.Println(err)
                return
            }
            
            // 解析LLM返回的JSON格式评分
            score, err := parseJSONCompletion(completion)
            if err != nil {
                log.Println(err)
                return
            }
            doc.Score = score.Score  // 8维度平均分
        }(doc)
    }
    wg.Wait()
    
    // 过滤低分文档并统计高质量文档数量
    var filterResult []*schema.SearchResult
    relevantCount := 0
    for _, doc := range docs {
        if doc.Score > L.threshold {
            filterResult = append(filterResult, doc)
            relevantCount++
        }
    }
    
    // 判断是否需要触发Web搜索
    if relevantCount < L.minDocNeed {
        log.Printf("high quality doc number is %d, not match need %d", relevantCount, L.minDocNeed)
        L.webSearch = true
    }
    
    return filterResult
}

Prompt工程设计 (crag/evaluator/evaluator_llm.go:49-73):

明确角色定位: “You are a relevance judge”
严格输出格式: JSON-only输出，避免LLM生成冗余文本
评分粒度: 0.0-1.0，步长0.1，确保评分的可量化性
计算公式: OverallScore = mean(8个维度分数)

2. Cross-Encoder Evaluator (crag/evaluator/evaluator_cross_encoder.go)

Cross-Encoder 是自然语言处理领域中专注于文本对关系建模的神经网络架构，核心特点是采用联合编码策略处理两段文本。它先将待比较的文本对通过 (CLS) 和 (SEP) 等特殊标记拼接为单一序列，再输入 Transformer 模型（如 BERT、RoBERTa）进行整体编码，借助自注意力机制深度捕获文本间的细粒度交互特征，最终通过输出层生成表示两者相关性的分数。这种设计让它在语义相似度分析、法律 / 医学文本深度匹配、释义识别及检索重排序等高精度需求场景中表现突出，但因需对每个文本对独立执行前向传播，计算成本较高、推理速度较慢，难以直接应对大规模实时检索任务，常与高效的 Bi-Encoder 配合形成 “检索 - 重排序” 混合架构，平衡效率与精度。

设计动机:

LLM评估器虽然准确，但推理成本高、延迟大
Cross-Encoder模型专门为相似度计算优化，推理速度快10-100倍
适合实时性要求高、查询量大的生产环境

技术原理:

基于BERT架构的预训练模型（如ms-marco-MiniLM-L-6-v2）
将query和document拼接为单个序列输入
通过[CLS] token的输出层直接预测相关性分数
无需像Bi-Encoder那样先分别编码再计算相似度

实现逻辑 (crag/evaluator/evaluator_cross_encoder.go:56-76):

func (c *CrossEncoderEvaluator) Score(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    // 提取所有文档内容
    docsContentList := []string{}
    for _, doc := range docs {
        docsContentList = append(docsContentList, doc.Document.Content)
    }
    
    // 批量计算相关性分数（一次推理完成所有文档的评分）
    relevantScoreList := c.CE.CalculateRelevant(query, docsContentList)
    
    var filterResult []*schema.SearchResult
    relevantCount := 0
    for i, doc := range docs {
        doc.Score = relevantScoreList[i]
        if doc.Score > c.threshold {
            filterResult = append(filterResult, doc)
            relevantCount++
        }
    }
    
    // 判断是否需要Web搜索
    if relevantCount < c.minDocNeed {
        log.Printf("high quality doc number is %d, not match need %d", relevantCount, c.minDocNeed)
        c.webSearch = true
    }
    
    return filterResult
}

性能对比:

特性	LLM Evaluator	Cross-Encoder Evaluator
评估精度	多维度深度理解	单一相关性分数
推理速度	100-500ms/文档	5-20ms/文档
成本	高 (LLM API调用费用)	低 (本地模型推理)
适用场景	复杂查询、高价值场景	高并发、实时性要求
可解释性	强 (8维度详细评分)	弱 (仅输出总分)

工程实践建议:

默认策略: 使用Cross-Encoder进行初步过滤，对保留的topN文档用LLM精细评估
混合模式: 简单事实查询用Cross-Encoder；复杂推理查询用LLM
AB测试: 根据业务指标选择最优评估器

2.6.4 查询重写与SEO优化

文件位置: crag/qrewrite/llm_query_rewriter.go

核心任务: 将自然语言查询转换为搜索引擎友好的关键词查询

转换示例:

原始查询	重写后查询	转换策略
“我想知道为什么我的Python代码一直报list index out of range错误”	“Python list index out of range error solution”	去除口语化，提取语言+错误信息+意图
“你能告诉我RTX 4070和RX 7800 XT哪个更适合玩游戏吗？”	“RTX 4070 vs RX 7800 XT gaming benchmark review”	比较查询用"vs"，添加"benchmark"
“从成田机场到新宿站带着行李怎么去最方便？”	“Narita Airport to Shinjuku Station transport with luggage guide”	提取地点+交通+特殊条件

Prompt设计 (crag/qrewrite/llm_query_rewriter.go:33-75):

角色定义:

1	You are an expert Search Engine Optimization (SEO) specialist and Query Refinement Assistant.

四步转换策略:

意图分析: 识别查询类型（信息型/交易型/导航型）
实体提取: 提取技术术语、关键实体、约束条件
去噪声: 移除"I want to know"、"Can you help me"等口语化表达
重排序: 遵循"主题+方面+修饰词"的标准搜索模式

实现代码 (crag/qrewrite/llm_query_rewriter.go:81-90):

func (q *QueryToBetterSearchQuery) Convert(query string) (string, error) {
    prompt := strings.ReplaceAll(LLM_QUERY_CONVERT_PROMPT, "{{USER_QUERY}}", query)
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    response, err := q.llm.GenerateCompletion(ctx, prompt)
    if err != nil {
        return "", err
    }
    
    return response, nil
}

Few-Shot示例设计:

Prompt中包含3个精心设计的转换示例
每个示例展示完整的推理过程（Chain of Thought）
引导LLM学习转换模式，提升输出质量

2.6.5 外部搜索与知识扩展

文件位置: crag/search/web_search.go

设计目标: 突破向量数据库的知识边界，引入实时、全面的外部知识

支持的搜索引擎:

Google Custom Search API
Bing Search API
可扩展其他搜索服务

GoogleSearch实现 (crag/search/web_search.go:64-135):

核心流程:

func (g *GoogleSearch) Search(queries []string) ([]*QuerySearchResult, error) {
    var allResults []*QuerySearchResult
    
    for _, query := range queries {
        var apiResponse map[string]interface{}
        var err error
        
        // 重试机制（确保API调用的鲁棒性）
        for retry := 0; retry < g.maxRetries; retry++ {
            reqBody := map[string]string{"q": query}
            reqBodyJSON, _ := json.Marshal(reqBody)
            
            req, _ := http.NewRequest("POST", g.baseUrl, bytes.NewBuffer(reqBodyJSON))
            req.Header.Set("X-API-KEY", g.apiKey)
            req.Header.Set("Content-Type", "application/json")
            
            resp, err := g.client.Do(req)
            if err != nil {
                fmt.Printf("Request failed (retry %d): %v\n", retry+1, err)
                continue
            }
            defer resp.Body.Close()
            
            respBody, _ := io.ReadAll(resp.Body)
            err = json.Unmarshal(respBody, &apiResponse)
            if err == nil {
                break  // 成功则跳出重试循环
            }
        }
        
        // 解析搜索结果（提取snippet作为补充知识）
        var searchItems []*SearchResultItem
        if organicResults, ok := apiResponse["organic"].([]interface{}); ok {
            for i, item := range organicResults {
                if i >= 10 {  // 限制最多10条结果
                    break
                }
                itemMap := item.(map[string]interface{})
                searchItem := &SearchResultItem{
                    Title:   getStringFromMap(itemMap, "title"),
                    Link:    getStringFromMap(itemMap, "link"),
                    Snippet: getStringFromMap(itemMap, "snippet"),
                }
                searchItems = append(searchItems, searchItem)
            }
        }
        
        queryResult := &QuerySearchResult{
            Queries: query,
            Results: searchItems,
        }
        allResults = append(allResults, queryResult)
    }
    
    return allResults, nil
}

工程优化:

超时控制: timeout: 5s，避免阻塞主流程
重试机制: 最多重试3次，应对网络抖动和API限流
结果限制: 每个查询最多返回10条结果，控制上下文长度
统一格式: 将snippet转换为schema.SearchResult格式，与向量检索结果无缝合并

知识扩展价值:

覆盖向量数据库未收录的新鲜知识（新闻、最新技术等）
补充长尾、冷门领域的信息
提供多源验证，降低单一数据源的偏差风险

2.7 模块化设计与统一抽象

2.7.1 接口设计

Provider模式：

// Embedding Provider
type Provider interface {
    GetEmbedding(ctx context.Context, text string) ([]float64, error)
}

// Reranker Provider
type Provider interface {
    Rerank(ctx context.Context, query string, documents []string) ([]float64, error)
}

// LLM Provider
type Provider interface {
    GenerateCompletion(ctx context.Context, prompt string) (string, error)
}

支持的Provider：

Embedding: OpenAI兼容协议
VectorDB: Milvus
Reranker: Cohere, OpenAI, Qwen
LLM: OpenAI兼容协议

2.7.2 配置驱动架构

配置结构 (config/config.go:6-13):

type Config struct {
    RAG           RAGConfig
    LLM           LLMConfig
    Embedding     EmbeddingConfig
    VectorDB      VectorDBConfig
    ReRanker      RerankerConfig
    PostRetrieval PostRetrievalConfig
}

模块独立开关：

LLM可选：未配置时仅提供检索功能
Reranker可选：未配置时跳过重排序
各优化技术均可通过配置独立启用/禁用

3. 核心实现

3.1 检索前优化实现 (Pre-Retrieval)

文件位置: rag/llm/query_transformation.go

关键函数:

QueryTransformation
HyDETransformation

技术特点:

Few-Shot Prompt工程：提供3个典型示例
CoT推理链：展示从对话式查询到搜索查询的转换思路

示例转换:

输入: “I’m trying to figure out why my python code keeps giving me a list index out of range error.”
输出: “Python list index out of range error solution”

3.2 检索后优化实现 (Post-Retrieval)

3.2.1 重排序实现

多Provider架构 (reranker/provider.go:42-57):

var providerInitializers = map[string]providerInitializer{
    "cohere": &CohereInitializer{},
    "openai": &OpenAIInitializer{},
    "qwen": &QwenInitializer{},
}

func NewRerankerProvider(cfg config.RerankerConfig) (Provider, error) {
    initializer := providerInitializers[cfg.Provider]
    return initializer.CreateProvider(cfg)
}

Cohere实现示例 (reranker/cohere.go):

API: https://api.cohere.ai/v1/rerank
模型: rerank-english-v3.0 / rerank-multilingual-v3.0
返回: 每个文档的相关性分数 (0-1)

OpenAI实现示例 (reranker/openai.go):

使用GPT-4等模型进行文档相关性判断
支持批量评分
返回标准化分数

3.2.2 上下文压缩实现

完整流程 (rag_client.go:267-287):

分数过滤 (行289-307)

func (r *RAGClient) filterDocumentsByScore(ctx context.Context, query string, docs []schema.SearchResult) []schema.SearchResult {
    minScore := r.config.PostRetrieval.RerankMinScore
    maxDocs := r.config.PostRetrieval.MaxDocuments
    // 过滤低分文档
    // 限制最大数量
    return filteredDocs
}

去重 (行310-347)

MD5哈希快速去重
Jaccard相似度精准去重
阈值：0.9

句子级压缩 (行421-480)

智能分句：按.!?。!?分割
句子评分：关键词匹配 + 位置加权 + 长度惩罚
动态保留：至少保留3句或50%句子

Token预算 (行539-561)

估算Token数：中文字符数/3
动态截断：确保总Token不超过MaxContextTokens

3.3 CRAG机制实现

3.3.1 核心工作流实现

文件位置: crag/light_crag.go

架构设计:

type LightCRAG struct {
    evaluator        evaluator.Evaluator           // 检索评估器接口
    externalSearcher search.ExternalSearcher       // 外部搜索接口
    queryRewriter    qrewriter.QueryRewriter       // 查询重写接口
}

初始化流程 (crag/light_crag.go:45-63):

func NewLightCRAG(cfg *config.CRAGConfig) (*LightCRAG, error) {
    // 1. 创建评估器（LLM或Cross-Encoder）
    eval, err := evaluator.NewEvaluator(&cfg.Evaluator)
    if err != nil {
        return nil, err
    }
    
    // 2. 创建外部搜索器（Google/Bing）
    searcher, err := search.NewExternalSearcher(&cfg.Search)
    if err != nil {
        return nil, err
    }
    
    // 3. 创建查询重写器
    rewriter, err := qrewriter.NewQueryToBetterSearchQuery(&cfg.Rewriter)
    if err != nil {
        return nil, err
    }
    
    return &LightCRAG{
        evaluator:        eval,
        externalSearcher: searcher,
        queryRewriter:    rewriter,
    }, nil
}

自适应纠正主流程 (crag/light_crag.go:65-97):

执行逻辑:

func (l *LightCRAG) run(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    var err error
    
    // === 阶段1: 初始评估 ===
    filteredDocs := l.evaluator.Score(query, docs)
    
    maxRetries := 3
    retries := 0
    
    // === 阶段2: 自适应纠正循环 ===
    for l.evaluator.IsNeedWebSearch() && retries < maxRetries {
        // 步骤1: 查询重写（将自然语言转换为搜索引擎查询）
        queries := []string{query}
        for index, q := range queries {
            queries[index], err = l.queryRewriter.Convert(q)
            if err != nil {
                continue  // 重写失败则使用原查询
            }
        }
        
        // 步骤2: 外部Web搜索（突破向量数据库边界）
        webResults, err := l.externalSearcher.Search(queries)
        if err != nil {
            break  // 搜索失败则终止循环
        }
        
        // 步骤3: 结果合并（将Web搜索的snippet添加到候选文档集）
        for _, result := range webResults {
            for _, item := range result.Results {
                searchResult := &schema.SearchResult{
                    Document: schema.Document{
                        Content: item.Snippet,  // 使用搜索结果的摘要作为文档内容
                    },
                }
                filteredDocs = append(filteredDocs, searchResult)
            }
        }
        
        // 步骤4: 重新评估（对合并后的文档集重新打分）
        filteredDocs = l.evaluator.Score(query, filteredDocs)
        
        retries++
    }
    
    // === 阶段3: 返回最终结果 ===
    return filteredDocs
}

关键设计点:

退出条件: IsNeedWebSearch() == false 或 retries >= 3
容错处理: 查询重写失败时使用原查询，避免整个流程中断
增量扩展: Web结果追加到现有文档，保留高质量的向量检索结果
迭代优化: 每轮合并后重新评估，确保新增文档也经过质量筛选

3.3.2 检索评估器实现

统一接口设计 (crag/evaluator/evaluator.go:14-17):

type Evaluator interface {
    Score(query string, docs []*schema.SearchResult) []*schema.SearchResult
    IsNeedWebSearch() bool
}

工厂模式实现 (crag/evaluator/evaluator.go:32-38):

func NewEvaluator(cfg *config.EvaluatorConfig) (Evaluator, error) {
    initializer, ok := evaluatorInitializers[cfg.Provider]
    if !ok {
        return nil, fmt.Errorf("no initializer found for evaluator provider type: %s", cfg.Provider)
    }
    return initializer.CreateProvider(cfg)
}

支持的评估器类型:

EVALUATOR_LLM: LLM-based多维度评估器
EVALUATOR_CROSS_ENCODER: Cross-Encoder相似度评估器

3.3.2.1 LLM Evaluator深度实现

文件位置: crag/evaluator/evaluator_llm.go

配置参数:

type LLMEvaluator struct {
    llm        llm.Provider  // LLM服务提供者
    webSearch  bool          // 是否需要Web搜索标志位
    threshold  float64       // 文档质量阈值（默认0.6）
    minDocNeed int           // 最少需要的高质量文档数（默认3）
    maxRetries int           // LLM调用最大重试次数（默认3）
    timeout    int           // 单次评估超时时间（默认3秒）
}

初始化逻辑 (crag/evaluator/evaluator_llm.go:142-154):

func NewLLMEvaluator(cfg *config.EvaluatorConfig) (Evaluator, error) {
    provider, err := llm.NewLLMProvider(cfg.LLM)
    if err != nil {
        return nil, fmt.Errorf("failed to create LLM provider")
    }
    return &LLMEvaluator{
        llm:        provider,
        threshold:  cfg.Threshold,      // 如0.6
        maxRetries: cfg.MaxRetries,     // 如3
        timeout:    cfg.Timeout,        // 如3秒
        minDocNeed: cfg.MinDoc,         // 如3个
    }, nil
}

评分主流程 (crag/evaluator/evaluator_llm.go:94-130):

func (L *LLMEvaluator) Score(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    var wg sync.WaitGroup
    
    // === 并发评估所有文档 ===
    for _, doc := range docs {
        wg.Add(1)
        go func(doc *schema.SearchResult) {
            defer wg.Done()
            
            // 1. 构建评估Prompt
            eval_prompt := buildPrompt(query, doc.Document.Content)
            
            // 2. 调用LLM API（带超时控制）
            ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
            defer cancel()
            
            completion, err := L.llm.GenerateCompletion(ctx, eval_prompt)
            if err != nil {
                log.Println(err)
                return  // 单个文档失败不影响其他文档
            }
            
            // 3. 解析JSON响应
            score, err := parseJSONCompletion(completion)
            if err != nil {
                log.Println(err)
                return
            }
            
            // 4. 更新文档分数
            doc.Score = score.Score
        }(doc)
    }
    wg.Wait()
    
    // === 过滤低分文档 ===
    var filterResult []*schema.SearchResult
    relevantCount := 0
    for _, doc := range docs {
        if doc.Score > L.threshold {
            filterResult = append(filterResult, doc)
            relevantCount++
        }
    }
    
    // === 判断是否需要Web搜索 ===
    if relevantCount < L.minDocNeed {
        log.Printf("high quality doc number is %d, not match need %d", relevantCount, L.minDocNeed)
        L.webSearch = true
    }
    
    return filterResult
}

并发优化策略:

使用goroutine并发评估，充分利用LLM API的并发处理能力
单个文档评估失败不影响其他文档（容错设计）
超时控制避免慢查询阻塞整个流程

评估Prompt设计 (crag/evaluator/evaluator_llm.go:49-73):

const LLMEvaluatorPrompt = `
You are a relevance judge. Evaluate how relevant the DOCUMENT is to answering the QUESTION.

Instructions:

1. Read the QUESTION and the DOCUMENT carefully.
2. Assign scores for each criterion below using only the set {0.0, 0.1, 0.2, ..., 1.0}. Round each score to one decimal place.
3. Score the following eight criteria:
   - TopicalAlignment: How well the main topic of the document matches the question's topic.
   - IntentAlignment: How well the document aligns with the user's intent (e.g., factual answer, how-to, comparison, troubleshooting).
   - KeyEntityMatch: Presence and correctness of key entities, terms, names, numbers, or concepts central to the question.
   - Direct Answer ability: Whether the document contains the direct answer or clearly enables deriving it.
   - CoverageDepth: Completeness and depth covering the essential aspects needed to answer the question.
   - SpecificityToQuery: Specific focus on the question versus being generic or tangential.
   - TemporalFit: Time relevance (recency, version, date consistency) relative to any time constraints implied by the question.
   - LanguageTerminologyAlignment: Language match and domain terminology consistency aiding accurate interpretation.
4. Compute OverallScore as the mean of the eight criterion scores, then round to the nearest 0.1.
5. Output strictly a JSON object with the exact structure below. Do not include any explanations or extra text.
{"score":}

Input: QUESTION: {{QUESTION}} DOCUMENT: {{DOCUMENT}}

Output format (JSON only):
{"score": x.x}
`

Prompt工程技巧:

明确指令: “Do not include any explanations or extra text” 确保LLM严格输出JSON
量化要求: “using only the set {0.0, 0.1, 0.2, …, 1.0}” 避免任意浮点数
结构化输出: 预定义JSON格式，简化解析逻辑

JSON解析 (crag/evaluator/evaluator_llm.go:132-136):

func parseJSONCompletion(completion string) (*relevantScore, error) {
    var rs relevantScore
    err := json.Unmarshal([]byte(completion), &rs)
    return &rs, err
}

type relevantScore struct {
    Score float64 `json:"score"`
}

3.3.2.2 Cross-Encoder Evaluator实现

文件位置: crag/evaluator/evaluator_cross_encoder.go

配置参数:

type CrossEncoderEvaluator struct {
    CE         service.CrossEncoderService  // Cross-Encoder推理服务
    threshold  float64                      // 相关性阈值
    minDocNeed int                          // 最少需要的高质量文档数
    webSearch  bool                         // Web搜索标志位
}

评分逻辑 (crag/evaluator/evaluator_cross_encoder.go:56-76):

func (c *CrossEncoderEvaluator) Score(query string, docs []*schema.SearchResult) []*schema.SearchResult {
    // 1. 提取所有文档内容
    docsContentList := []string{}
    for _, doc := range docs {
        docsContentList = append(docsContentList, doc.Document.Content)
    }
    
    // 2. 批量计算相关性（一次推理完成所有文档评分）
    relevantScoreList := c.CE.CalculateRelevant(query, docsContentList)
    
    // 3. 过滤低分文档
    var filterResult []*schema.SearchResult
    relevantCount := 0
    for i, doc := range docs {
        doc.Score = relevantScoreList[i]
        if doc.Score > c.threshold {
            filterResult = append(filterResult, doc)
            relevantCount++
        }
    }
    
    // 4. 判断是否需要Web搜索
    if relevantCount < c.minDocNeed {
        log.Printf("high quality doc number is %d, not match need %d", relevantCount, c.minDocNeed)
        c.webSearch = true
    }
    
    return filterResult
}

性能优势:

批量推理: 一次API调用完成所有文档的评分，减少网络往返
推理速度快: Cross-Encoder模型比LLM小10-100倍，推理速度快
无并发需求: 批量推理避免了LLM Evaluator的复杂并发逻辑

适用场景:

高并发查询场景（QPS > 100）
实时性要求严格（延迟 < 100ms）
成本敏感场景（避免LLM API费用）

3.3.3 查询重写实现

文件位置: crag/qrewrite/llm_query_rewriter.go

接口设计 (crag/qrewrite/query_rewriter.go):

1
2
3

type QueryRewriter interface {
    Convert(query string) (string, error)
}

LLM Query Rewriter实现 (crag/qrewrite/llm_query_rewriter.go:77-90):

type QueryToBetterSearchQuery struct {
    llm llm.Provider
}

func (q *QueryToBetterSearchQuery) Convert(query string) (string, error) {
    // 1. 替换模板变量
    prompt := strings.ReplaceAll(LLM_QUERY_CONVERT_PROMPT, "{{USER_QUERY}}", query)
    
    // 2. 调用LLM API（带超时）
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    response, err := q.llm.GenerateCompletion(ctx, prompt)
    if err != nil {
        return "", err
    }
    
    return response, nil
}

Prompt策略分析 (crag/qrewrite/llm_query_rewriter.go:33-75):

角色设定:

1	You are an expert Search Engine Optimization (SEO) specialist and Query Refinement Assistant.

四步转换方法论:

Analyze intent: 分析查询类型（Informational/Transactional/Navigational）
Extract entities: 识别技术术语、关键实体、约束条件
Remove filler: 删除口语化表达（“I want to know”、“Can you help me”）
Reorder terms: 遵循"主题+方面+修饰词"模式

Few-Shot示例:

User Input: "I'm trying to figure out why my python code keeps giving me a list index out of range error."
Reasoning:
- Intent: Troubleshooting a specific coding error.
- Keywords: Python, list index out of range, error, fix/solution.
- Removal: "I'm trying to figure out why my", "keeps giving me a".
- Refinement: Combine language + error message + intent.
Refined Query: Python list index out of range error solution

输出要求:

1 2	Output ONLY the final Refined Query. Do not add quotes, explanations, or conversational filler.

工程价值:

显著提升Web搜索的召回率和准确性
将自然语言转换为搜索引擎最优解的查询形式
Few-Shot学习确保转换质量的稳定性

3.3.4 外部搜索实现

文件位置: crag/search/web_search.go

统一接口 (crag/search/search.go:12-14):

1
2
3

type ExternalSearcher interface {
    Search(queries []string) ([]*QuerySearchResult, error)
}

数据结构 (crag/search/search.go:16-25):

type SearchResultItem struct {
    Title   string `json:"title,omitempty"`
    Link    string `json:"link,omitempty"`
    Snippet string `json:"snippet,omitempty"`  // 核心字段：用作补充知识
}

type QuerySearchResult struct {
    Queries string              `json:"queries"`
    Results []*SearchResultItem `json:"results"`
}

Google Search实现 (crag/search/web_search.go:46-62):

type GoogleSearch struct {
    client     *http.Client    // HTTP客户端
    baseUrl    string          // Google Custom Search API地址
    apiKey     string          // API密钥
    maxRetries int             // 最大重试次数（默认3）
    timeout    time.Duration   // 请求超时时间（默认5秒）
}

func NewGoogleSearch(cfg *config.ExternalSearchConfig) *GoogleSearch {
    return &GoogleSearch{
        client:     &http.Client{Timeout: time.Duration(cfg.Timeout) * time.Second},
        baseUrl:    cfg.BaseURL,
        apiKey:     cfg.APIKey,
        maxRetries: cfg.MaxRetries,
        timeout:    time.Duration(cfg.Timeout) * time.Second,
    }
}

搜索主流程 (crag/search/web_search.go:64-135):

func (g *GoogleSearch) Search(queries []string) ([]*QuerySearchResult, error) {
    var allResults []*QuerySearchResult
    
    for _, query := range queries {
        var apiResponse map[string]interface{}
        var err error
        
        // === 重试机制 ===
        for retry := 0; retry < g.maxRetries; retry++ {
            // 1. 构建请求体
            reqBody := map[string]string{"q": query}
            reqBodyJSON, err := json.Marshal(reqBody)
            
            // 2. 创建HTTP请求
            req, err := http.NewRequest("POST", g.baseUrl, bytes.NewBuffer(reqBodyJSON))
            req.Header.Set("X-API-KEY", g.apiKey)
            req.Header.Set("Content-Type", "application/json")
            
            // 3. 发送请求
            resp, err := g.client.Do(req)
            if err != nil {
                fmt.Printf("Request failed (retry %d): %v\n", retry+1, err)
                continue
            }
            defer resp.Body.Close()
            
            // 4. 解析响应
            respBody, _ := io.ReadAll(resp.Body)
            err = json.Unmarshal(respBody, &apiResponse)
            if err == nil {
                break  // 成功则跳出重试循环
            }
        }
        
        // === 提取搜索结果 ===
        var searchItems []*SearchResultItem
        if organicResults, ok := apiResponse["organic"].([]interface{}); ok {
            for i, item := range organicResults {
                if i >= 10 {  // 限制最多10条
                    break
                }
                itemMap := item.(map[string]interface{})
                searchItem := &SearchResultItem{
                    Title:   getStringFromMap(itemMap, "title"),
                    Link:    getStringFromMap(itemMap, "link"),
                    Snippet: getStringFromMap(itemMap, "snippet"),
                }
                searchItems = append(searchItems, searchItem)
            }
        }
        
        queryResult := &QuerySearchResult{
            Queries: query,
            Results: searchItems,
        }
        allResults = append(allResults, queryResult)
    }
    
    return allResults, nil
}

工程优化细节:

1. 重试机制:

应对场景: 网络抖动、API限流、超时
策略: 最多重试3次，任意一次成功即跳出
容错: 重试失败后返回错误，由上层决定是否继续流程

2. 结果限制:

每个查询最多返回10条结果
控制上下文长度，避免超出LLM的token限制
提取snippet而非完整网页，减少噪声

3. 错误处理:

单个查询失败不影响其他查询
最终失败返回错误，触发CRAG流程的提前退出

4. 性能监控:

打印重试日志，便于排查API问题
超时控制避免阻塞主流程

扩展性设计:

工厂模式支持多种搜索引擎（Google、Bing等）
统一接口便于新增自定义搜索服务
配置化管理API密钥 and 超时参数

3.4 可复现效果验证

3.4.1 评测框架

文件位置: evaluation/evaluator.go

支持的数据集 (evaluation/dataset.go):

HotpotQA
Natural Questions
自定义数据集

评测流程 (evaluation/evaluator.go:122-200):

graph TD A[加载数据集] --> B[遍历每个问题] B --> C[执行检索] C --> D[计算检索指标] D --> E[生成答案] E --> F[计算生成指标] F --> G[聚合统计] G --> H[生成报告]

核心代码:

func (e *Evaluator) Evaluate(ctx context.Context) (*EvaluationResult, error) {
    dataset, _ := LoadDataset(e.config.DatasetType, e.config.DatasetPath)
    
    for _, question := range dataset.Questions {
        // 1. 检索评估
        retrievedDocs, _ := e.ragClient.SearchChunks(question.Question, topK, threshold)
        retrievalMetrics := CalculateRetrievalMetrics(retrievedDocs, question.RelevantDocs)
        
        // 2. 生成评估
        generatedAnswer, _ := e.ragClient.Chat(question.Question)
        generationMetrics, _ := CalculateFactualityScore(ctx, llm, question.Question, generatedAnswer, question.Answer)
        
        results = append(results, QuestionResult{...})
    }
    
    // 聚合指标
    aggregateMetrics := CalculateAggregateMetrics(retrievalMetrics, generationMetrics)
    return result
}

3.4.2 量化指标实现

检索指标 (evaluation/metrics.go:82-137):

指标	计算公式	说明
Precision	TP / (TP + FP)	检索文档中相关文档的比例
Recall	TP / (TP + FN)	相关文档中被检索出的比例
F1 Score	2 * P * R / (P + R)	Precision和Recall的调和平均

生成指标 (evaluation/metrics.go:139-169):

Factuality Score分级:

A级(5.0分): 生成答案是标准答案的子集，完全准确
B级(4.0分): 生成答案是标准答案的超集，包含额外正确信息
C级(3.0分): 生成答案与标准答案完全一致
D级(2.0分): 生成答案与标准答案存在矛盾
E级(1.0分): 表述不同但事实一致

评估Prompt (evaluation/metrics.go:172-191):

func buildFactualityPrompt(question, generated, reference string) string {
    return fmt.Sprintf(`你是一个专业的答案质量评估专家。
请根据以下标准评估生成答案的事实性：

问题: %s
参考答案: %s
生成答案: %s

评分标准:
- A级: 生成答案是参考答案的子集，包含的信息都正确但不完整
- B级: 生成答案是参考答案的超集，包含了参考答案的所有信息，还额外提供了正确的相关信息
- C级: 生成答案与参考答案完全一致
- D级: 生成答案与参考答案存在事实矛盾
- E级: 生成答案表述方式不同，但事实内容一致

请按以下格式回答:
等级: [A/B/C/D/E]
理由: [简要说明]`, question, reference, generated)
}

3.4.3 评测示例

测试代码示例：

func TestRAGEvaluation(t *testing.T) {
    ragClient, _ := getRAGClient()
    llmProvider, _ := llm.NewLLMProvider(config)
    
    evalConfig := &evaluation.EvaluationConfig{
        DatasetPath: "/dataset/hotpotqa.json",
        DatasetType: "hotpotqa",
        TopK: 10,
        Threshold: 0.5,
        MaxSamples: 100,
    }
    
    evaluator := evaluation.NewEvaluator(ragClient, llmProvider, evalConfig)
    result, _ := evaluator.Evaluate(context.Background())
    
    // 输出结果
    fmt.Printf("平均Precision: %.4f\n", result.AggregateMetrics.AvgPrecision)
    fmt.Printf("平均Recall: %.4f\n", result.AggregateMetrics.AvgRecall)
    fmt.Printf("平均F1 Score: %.4f\n", result.AggregateMetrics.AvgF1Score)
    fmt.Printf("平均Factuality Score: %.4f\n", result.AggregateMetrics.AvgFactualityScore)
}

预期输出示例:

平均Precision: 0.8234
平均Recall: 0.7891
平均F1 Score: 0.8058
平均Factuality Score: 4.2
等级分布: {A: 45, B: 32, C: 15, D: 5, E: 3}

4. 非功能性指标

4.1 代码质量

4.1.1 代码组织

目录结构:

rag/
├── common/           # 公共工具
├── config/           # 配置管理
├── crag/             # CRAG实现
│   ├── evaluator/    # 评估器
│   ├── qrewrite/     # 查询重写
│   └── search/       # 外部搜索
├── embedding/        # 嵌入模型
├── evaluation/       # 评测框架
├── llm/              # LLM接口
├── reranker/         # 重排序
├── schema/           # 数据结构
├── textsplitter/     # 文本分割
└── vectordb/         # 向量数据库

设计模式:

工厂模式: Provider初始化器
策略模式: 位置优化策略、文本分割策略
模板方法: 评测流程
接口隔离: 各Provider独立接口

4.1.2 测试覆盖

单元测试文件:

rag_client_test.go
server_test.go
crag/crag_workflow_test.go
evaluation/evaluator_test.go
textsplitter/recursive_character_test.go

测试场景覆盖:

✅ RAG基础功能测试
✅ CRAG工作流测试
✅ 评测框架测试
✅ 文本分割测试

4.2 性能与效率

4.2.1 性能优化技术

1. 并发处理:

LLM评估器使用goroutine并发打分 (crag/evaluator/evaluator_llm.go:95-116)
加速文档评估过程

2. 缓存机制:

支持Rerank结果缓存
配置项: PostRetrieval.CacheEnabled, CacheTTL

3. 批量操作:

向量数据库批量插入
Embedding批量生成

4. 超时控制:

查询重写: 5秒超时
LLM评估: 10秒超时
整体评测: 30分钟超时

4.2.2 性能基准

端到端延迟分解:

阶段	延迟	占比
查询重写	~200ms	5%
Embedding生成	~100ms	2.5%
向量检索	~50ms	1.25%
重排序	~500ms	12.5%
CRAG评估	~2000ms	50%
LLM生成	~1000ms	25%
其他处理	~150ms	3.75%
总计	~4000ms	100%

未来优化建议:

异步CRAG评估可减少50%延迟
使用本地Cross-Encoder可减少评估延迟至500ms
启用缓存可减少重复查询的90%延迟

4.2.3 资源消耗

内存占用:

基础RAG服务: ~100MB
加载10000文档: ~500MB
评测100问题: ~200MB峰值

并发能力:

支持goroutine并发
推荐配置: 每个评估器实例限制10并发

4.3 学术文献引用

Yan S Q, Gu J C, Zhu Y, et al. Corrective retrieval augmented generation[J]. 2024.
- CRAG框架核心论文
- 检索评估器设计参考
Ma X, Gong Y, He P, et al. Query rewriting in retrieval-augmented large language models[C]//Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing. 2023: 5303-5315.
- 查询重写技术参考
Gao L, Ma X, Lin J, et al. Precise zero-shot dense retrieval without relevance labels[C]//Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). 2023: 1762-1777.
- HyDE (Hypothetical Document Embeddings) 原始论文
- 检索前优化技术参考
Nogueira R, Cho K. Passage Re-ranking with BERT[J]. arXiv preprint arXiv:1901.04085, 2019.
- Cross-Encoder重排序理论基础
Lewis P, Perez E, Piktus A, et al. Retrieval-augmented generation for knowledge-intensive nlp tasks[J]. Advances in neural information processing systems, 2020, 33: 9459-9474.
- RAG范式奠基论文
Karpukhin V, Oguz B, Min S, et al. Dense Passage Retrieval for Open-Domain Question Answering[C]//EMNLP (1). 2020: 6769-6781.
- 密集检索技术参考

5. 创新点与技术优势

5.1 核心创新点

完整的CRAG闭环实现
- 业界少数完整实现CRAG论文机制的开源方案
- 支持多轮纠正性检索
- 双评估器架构（LLM + Cross-Encoder）
多维度检索后优化pipeline
- 重排序 → 去重 → 压缩 → 句子过滤 → 位置优化
- 每个环节独立可配，可灵活组合
生产级评测框架
- 支持标准数据集（HotpotQA, NQ）
- 完整的量化指标（Precision/Recall/F1 + Factuality）
- 可复现的评测流程
高度模块化设计
- Provider接口统一抽象
- 支持多种后端（Embedding、VectorDB、LLM、Reranker）
- 配置驱动，无需代码修改

5.2 技术优势

优势维度	具体表现
完整性	覆盖Pre/Post-Retrieval、CRAG全流程
准确性	多级优化确保高质量上下文
灵活性	模块化设计，各组件可独立配置
可扩展性	Provider模式支持快速接入新服务
可验证性	完整评测框架，量化效果提升
生产就绪	超时控制、错误处理、并发支持

5.3 与基线RAG的对比

对比项	基线RAG	本方案
检索前优化	❌	✅ 查询重写
重排序	❌	✅ 多Provider支持
上下文压缩	❌	✅ 去重+句子过滤+Token控制
CRAG机制	❌	✅ 完整实现
评测框架	❌	✅ 多指标评测
模块化	部分	✅ 高度模块化

6. 配置示例与最佳实践

6.1 完整配置示例

rag:
  splitter:
    provider: recursive
    chunk_size: 500
    chunk_overlap: 50
  top_k: 10
  threshold: 0.5

llm:
  provider: openai
  api_key: sk-xxx
  base_url: https://api.openai.com/v1
  model: gpt-4o
  temperature: 0.5
  max_tokens: 2048

embedding:
  provider: openai
  api_key: sk-xxx
  base_url: https://api.openai.com/v1
  model: text-embedding-ada-002
  dimensions: 1536

vectordb:
  provider: milvus
  host: localhost
  port: 19530
  database: default
  collection: rag_collection
  mapping:
    fields:
      - standard_name: id
        raw_name: id
      - standard_name: content
        raw_name: content
      - standard_name: vector
        raw_name: vector
    index:
      index_type: HNSW
      params:
        M: 4
        efConstruction: 32
    search:
      metric_type: IP
      params:
        ef: 32

reranker:
  provider: cohere
  api_key: xxx
  model: rerank-english-v3.0
  timeout: 10

post_retrieval:
  enable_rerank: true
  rerank_top_n: 5
  rerank_min_score: 0.3
  enable_compression: true
  max_context_tokens: 4000
  max_documents: 10
  enable_sentence_filter: true
  sentence_min_score: 0.3
  enable_dedup: true
  dedup_threshold: 0.9
  position_strategy: sandwich

6.2 最佳实践建议

1. 检索阶段:

TopK设置为10-20（后续重排序会过滤）
Threshold设置为0.5-0.6（召回优先）

2. 重排序阶段:

RerankTopN设置为3-5（平衡质量和延迟）
RerankMinScore设置为0.3-0.4

3. 上下文压缩:

MaxContextTokens根据LLM上下文窗口设置（GPT-4: 4000, Claude: 8000）
启用句子过滤可减少30%无关内容

4. CRAG配置:

Evaluator Threshold: 0.6-0.7
MinDoc: 3（至少需要3个高质量文档）
MaxRetries: 3

7. 未来优化方向

7.1 技术增强

混合检索
- 结合BM25稀疏检索和向量检索
- 实现Reciprocal Rank Fusion融合策略
自适应检索
- 根据查询复杂度动态调整TopK
- 基于历史数据优化阈值
增量索引
- 支持实时文档更新
- 增量式向量索引构建
多模态支持
- 图片、表格的向量化
- 多模态Reranker

7.2 性能优化

异步CRAG
- 评估和生成并行执行
- 预测性Web搜索
本地模型支持
- 本地Embedding模型（BGE-M3）
- 本地Reranker（BGE-Reranker）
- 减少API调用延迟
智能缓存
- 查询语义缓存
- 检索结果缓存
- 生成答案缓存

7.3 功能扩展

多语言支持
- 跨语言检索
- 多语言评测
领域适配
- 医疗、法律等专业领域定制
- 领域知识图谱融合
可解释性
- 检索路径可视化
- 评分依据展示
- 答案溯源

8.Agentic RAG 设计

8.1. 概述

8.1.1 什么是 Agentic RAG

Agentic RAG（Agent-based Retrieval-Augmented Generation）是一种新型的检索增强生成架构，它将传统RAG系统与自主Agent能力相结合。不同于传统RAG的线性流水线处理方式，Agentic RAG通过引入智能决策层，使系统能够：

自主规划：将复杂查询分解为多个子任务，制定执行计划
动态决策：根据中间结果动态选择下一步行动
工具编排：智能选择和组合多种检索、重排、搜索等工具
自我反思：评估结果质量，必要时触发重试和优化
记忆管理：维护对话上下文和历史决策，支持多轮交互

8.1.2 与现有RAG方案的关系

本项目已实现完整的增强RAG方案，包括：

✅ 检索前优化：查询重写、意图识别
✅ 检索后优化：重排序、去重、上下文压缩、句子级过滤
✅ CRAG纠正性检索：检索评估器、外部搜索、多轮纠正

Agentic RAG的定位：

传统RAG:     查询 → 检索 → 生成
增强RAG:     查询 → 检索前优化 → 检索 → 检索后优化 → CRAG → 生成
Agentic RAG: 查询 → [Agent规划] → [动态工具调用] → [反思优化] → 生成
                     ↑______________|__________________|
                              自主决策循环

Agentic RAG将现有的优化组件（Query Rewriter、Reranker、CRAG等）作为可调用的工具，由Agent层进行智能编排。

8.1.3 核心创新价值

相比现有方案，Agentic RAG带来以下创新：

智能任务分解
- 传统方案：所有查询走相同流水线
- Agentic方案：根据查询复杂度动态规划处理策略
- 价值：简单查询快速响应，复杂查询深度处理
自适应工具选择
- 传统方案：固定启用所有优化组件
- Agentic方案：根据需求按需调用工具
- 价值：降低延迟，提升资源利用率
闭环优化机制
- 传统方案：单次处理，缺乏质量反馈
- Agentic方案：持续评估结果，自动触发优化
- 价值：提升答案准确性和可靠性
多跳推理能力
- 传统方案：单次检索生成
- Agentic方案：支持多轮检索-推理-再检索
- 价值：处理需要多步推理的复杂问题

8.2. 技术架构

8.2.1 整体架构设计

graph TB subgraph sg6 ["用户交互层"] A[用户查询] --> B[查询理解] B --> C[任务路由] end subgraph sg7 ["Agentic 决策层"] C --> D[Planning Agent
任务规划器] D --> E[Task Decomposer
任务分解] E --> F[Orchestrator
编排器] F --> G{决策中心} G --> H[Retrieval Agent
检索决策] G --> I[Tool Agent
工具调用] G --> J[Reflection Agent
反思评估] end subgraph sg8 ["工具层 - 复用现有组件"] H --> K1[向量检索
Milvus] I --> K2[查询重写
Query Rewriter] I --> K3[重排序
Reranker] I --> K4[CRAG评估器
Evaluator] I --> K5[外部搜索
Web Search] I --> K6[上下文压缩
Compressor] end subgraph sg9 ["记忆层"] L[短期记忆
当前任务上下文] M[长期记忆
历史对话/知识] end subgraph sg10 ["生成层"] J --> N{质量检查} N -->|通过| O[Prompt构建] N -->|不通过| F O --> P[LLM生成] P --> Q[最终答案] end K1 --> I K2 --> I K3 --> I K4 --> I K5 --> I K6 --> I F -.记忆读写.-> L F -.记忆读写.-> M style A fill:#e1f5ff style Q fill:#d4edda style G fill:#fff3cd style N fill:#fff3cd

架构说明：

用户交互层：负责查询理解和初步分类，将简单查询直接路由到传统RAG，复杂查询进入Agentic层
Agentic决策层：核心控制中枢，包含规划、编排、决策三大能力
工具层：封装现有检索优化组件为可调用工具
记忆层：维护对话状态和历史信息
生成层：集成质量检查和反馈循环

8.2.2 Agent 组件设计

8.2.2.1 Planning Agent (任务规划器)

职责：

分析查询复杂度和意图
将复杂查询分解为子任务
生成执行计划（Plan）

输入输出：

type PlanningAgent interface {
    // 分析查询并生成执行计划
    CreatePlan(ctx context.Context, query string, history []Message) (*Plan, error)
    
    // 根据中间结果调整计划
    AdaptPlan(ctx context.Context, currentPlan *Plan, feedback *Feedback) (*Plan, error)
}

type Plan struct {
    Tasks      []Task           // 子任务列表
    Strategy   string           // 执行策略: sequential, parallel, adaptive
    MaxRetries int              // 最大重试次数
    Timeout    time.Duration    // 超时时间
}

type Task struct {
    ID          string
    Type        TaskType         // retrieve, rerank, search, evaluate
    Input       interface{}
    DependsOn   []string         // 依赖的任务ID
    Priority    int
}

决策逻辑：

flowchart TD A[接收查询] --> B{查询类型分析} B -->|事实型| C[简单检索计划] B -->|多跳推理| D[多步骤计划] B -->|对比分析| E[并行检索计划] C --> F[生成Plan] D --> G[分解子问题] G --> H[构建依赖关系] H --> F E --> I[设定并行任务] I --> F F --> J[估算资源需求] J --> K[返回执行计划]

8.2.2.2 Retrieval Agent (检索决策器)

职责：

决定何时、如何进行检索
选择检索策略（向量检索、混合检索、外部搜索）
动态调整检索参数（TopK、阈值等）

接口定义：

type RetrievalAgent interface {
    // 决定检索策略
    DecideStrategy(ctx context.Context, task *Task, context *Context) (*RetrievalStrategy, error)
    
    // 执行检索
    Retrieve(ctx context.Context, strategy *RetrievalStrategy) ([]*SearchResult, error)
}

type RetrievalStrategy struct {
    Method      RetrievalMethod  // vector, hybrid, web
    TopK        int
    MinScore    float64
    UseReranker bool
    RerankModel string
}

type RetrievalMethod string
const (
    VectorRetrieval RetrievalMethod = "vector"
    HybridRetrieval RetrievalMethod = "hybrid"
    WebSearch       RetrievalMethod = "web"
)

决策流程：

flowchart TD A[接收检索任务] --> B{查询特征分析} B -->|知识库内容| C[向量检索] B -->|实时信息| D[Web搜索] B -->|高精度要求| E[混合检索] C --> F{是否需要重排?} D --> G[调用外部搜索工具] E --> H[向量+关键词组合] F -->|是| I[启用Reranker] F -->|否| J[直接返回] I --> K[执行检索] J --> K G --> K H --> K K --> L[返回检索结果]

8.2.2.3 Tool Agent (工具调用器)

职责：

管理可用工具注册表
根据任务选择合适的工具
执行工具调用并处理结果

接口定义：

type ToolAgent interface {
    // 注册工具
    RegisterTool(tool Tool) error
    
    // 选择并执行工具
    SelectAndExecute(ctx context.Context, task *Task) (*ToolResult, error)
    
    // 获取可用工具列表
    ListTools() []ToolInfo
}

type Tool interface {
    Name() string
    Description() string
    Execute(ctx context.Context, input interface{}) (interface{}, error)
}

// 现有组件封装为工具
type QueryRewriterTool struct {
    rewriter *qrewrite.QueryRewriter
}

type RerankerTool struct {
    reranker *reranker.Provider
}

type CRAGEvaluatorTool struct {
    evaluator *evaluator.Evaluator
}

工具注册表：

工具名称	对应现有组件	功能描述
`query_rewriter`	`crag/qrewrite/llm_query_rewriter.go`	查询优化重写
`vector_retriever`	`vectordb/provider.go`	向量检索
`reranker`	`reranker/provider.go`	结果重排序
`crag_evaluator`	`crag/evaluator/evaluator_llm.go`	检索质量评估
`web_searcher`	`crag/search/web_search.go`	外部Web搜索
`context_compressor`	`rag_client.go:compressContext`	上下文压缩
`deduplicator`	`rag_client.go:deduplicateDocs`	文档去重

8.2.2.4 Reflection Agent (反思评估器)

职责：

评估中间结果和最终答案的质量
识别问题和改进点
决定是否需要重试或调整策略

接口定义：

type ReflectionAgent interface {
    // 评估结果质量
    Evaluate(ctx context.Context, result *IntermediateResult) (*EvaluationReport, error)
    
    // 生成改进建议
    Suggest(ctx context.Context, report *EvaluationReport) (*Suggestion, error)
}

type EvaluationReport struct {
    QualityScore    float64           // 0-1质量分数
    Dimensions      map[string]float64 // 各维度分数
    Issues          []Issue            // 发现的问题
    NeedImprovement bool
}

type Issue struct {
    Type        IssueType  // low_relevance, incomplete, factual_error
    Severity    string     // high, medium, low
    Description string
}

type Suggestion struct {
    Action      ActionType  // retry, adjust_params, use_different_tool
    Reason      string
    NewStrategy *Strategy
}

评估流程：

flowchart TD A[接收检索结果] --> B[多维度评估] B --> C[相关性评分] B --> D[完整性评分] B --> E[准确性评分] C --> F{综合评分} D --> F E --> F F -->|>0.8| G[高质量,通过] F -->|0.5-0.8| H[中等质量,可优化] F -->|<0.5| I[低质量,需重试] G --> J[返回通过] H --> K[生成优化建议] I --> L[生成重试策略] K --> M[返回建议] L --> M

8.2.2.5 Orchestrator (编排器)

职责：

协调各Agent的执行
管理任务队列和依赖关系
处理并发 and 异步执行

接口定义：

type Orchestrator interface {
    // 执行计划
    Execute(ctx context.Context, plan *Plan) (*ExecutionResult, error)
    
    // 处理单个任务
    ExecuteTask(ctx context.Context, task *Task) (*TaskResult, error)
}

type ExecutionResult struct {
    FinalAnswer  string
    Steps        []StepRecord    // 执行步骤记录
    TotalTime    time.Duration
    ToolsCalled  []string
}

type StepRecord struct {
    TaskID      string
    ToolUsed    string
    Input       interface{}
    Output      interface{}
    Duration    time.Duration
    Success     bool
}

8.3. 核心流程设计

8.3.1 任务规划流程

flowchart TD A[用户查询] --> B[Planning Agent分析] B --> C{查询复杂度} C -->|简单| D[单步检索计划] C -->|中等| E[两步计划:
检索→重排] C -->|复杂| F[多步计划:
分解→检索→评估→搜索] D --> G[生成Plan] E --> G F --> H[任务分解] H --> I[子任务1:
提取关键实体] H --> J[子任务2:
多角度检索] H --> K[子任务3:
结果聚合] I --> L[设置依赖关系] J --> L K --> L L --> G G --> M{需要并行执行?} M -->|是| N[标记并行任务] M -->|否| O[顺序执行] N --> P[返回执行计划] O --> P style C fill:#fff3cd style M fill:#fff3cd

示例场景：

场景1：简单事实查询

查询: "Python中如何读取文件?"
计划:
  Task 1: 向量检索 (TopK=5)
  Task 2: 生成答案

场景2：对比分析查询

查询: "比较React和Vue的性能差异"
计划:
  Task 1: 并行检索
    - SubTask 1a: 检索"React性能"
    - SubTask 1b: 检索"Vue性能"
  Task 2: 重排序合并结果
  Task 3: 生成对比答案

场景4：多跳推理查询

查询: "谁发明了运行世界上第一个Web服务器的计算机所使用的操作系统?"
计划:
  Task 1: 检索"第一个Web服务器"
  Task 2: 从结果中提取计算机型号
  Task 3: 检索该计算机的操作系统
  Task 4: 检索该操作系统的发明者
  Task 5: 生成答案

8.3.2 工具调用时序图

sequenceDiagram participant U as 用户 participant O as Orchestrator participant PA as Planning Agent participant TA as Tool Agent participant RA as Reflection Agent participant QR as QueryRewriter工具 participant VR as VectorRetriever工具 participant RK as Reranker工具 participant CE as CRAGEvaluator工具 U->>O: 提交查询 O->>PA: 创建执行计划 PA->>PA: 分析查询复杂度 PA-->>O: 返回Plan loop 执行每个Task O->>TA: 执行Task 1 (查询重写) TA->>QR: 调用query_rewriter QR-->>TA: 优化后查询 O->>TA: 执行Task 2 (向量检索) TA->>VR: 调用vector_retriever VR-->>TA: 检索结果 O->>TA: 执行Task 3 (重排序) TA->>RK: 调用reranker RK-->>TA: 重排后结果 O->>RA: 评估结果质量 RA->>CE: 调用crag_evaluator CE-->>RA: 质量评分 alt 质量不足 RA-->>O: 建议重试,调整参数 O->>PA: 调整计划 else 质量满足 RA-->>O: 通过评估 end end O-->>U: 返回最终答案

8.3.3 反思与优化流程

flowchart TD A[检索结果] --> B[Reflection Agent评估] B --> C[相关性检查] B --> D[完整性检查] B --> E[事实性检查] C --> F{综合评分} D --> F E --> F F -->|Score >= 0.8| G[质量优秀] F -->|0.5 <= Score < 0.8| H[质量中等] F -->|Score < 0.5| I[质量不足] G --> J[直接生成答案] H --> K{问题分析} K -->|文档不够相关| L[调整检索参数] K -->|信息不完整| M[扩大检索范围] K -->|排序不理想| N[启用/调整Reranker] I --> O{问题分析} O -->|查询不明确| P[查询重写] O -->|知识库无相关内容| Q[触发Web搜索] O -->|检索策略不当| R[切换检索方法] L --> S[重新执行] M --> S N --> S P --> S Q --> S R --> S S --> T{重试次数检查} T -->|< MaxRetries| B T -->|>= MaxRetries| U[使用现有最佳结果] U --> J style F fill:#fff3cd style K fill:#fff3cd style O fill:#fff3cd style T fill:#fff3cd

优化策略表：

问题类型	检测指标	优化动作
低相关性	AvgScore < 0.5	查询重写、调整TopK
信息不完整	覆盖度 < 60%	扩大检索范围、多查询策略
排序不佳	Top1分数低但Top5有高分	启用Reranker
知识库缺失	所有文档分数 < 0.3	触发Web搜索
时效性问题	文档时间过旧	优先外部搜索

8.3.4 完整端到端工作流

sequenceDiagram participant U as 用户 participant QU as 查询理解 participant PA as Planning Agent participant O as Orchestrator participant ToolLayer as 工具层 participant RA as Reflection Agent participant Gen as 生成模块 U->>QU: 输入查询 QU->>QU: 意图识别、实体提取 QU->>PA: 传递查询特征 PA->>PA: 分析复杂度 PA->>PA: 任务分解 PA-->>O: 执行计划Plan Note over O: 执行阶段 loop 遍历Plan中的Tasks O->>ToolLayer: 执行Task alt Task类型=检索 ToolLayer->>ToolLayer: 查询重写(可选) ToolLayer->>ToolLayer: 向量检索 ToolLayer-->>O: 检索结果 else Task类型=优化 ToolLayer->>ToolLayer: 重排序/去重/压缩 ToolLayer-->>O: 优化后结果 else Task类型=评估 ToolLayer->>ToolLayer: CRAG评估器 ToolLayer-->>O: 质量评分 end O->>RA: 评估中间结果 RA->>RA: 多维度打分 alt 质量不达标 RA-->>PA: 请求调整计划 PA->>PA: 生成补救策略 PA-->>O: 新的Task else 质量满足 RA-->>O: 继续执行 end end Note over O,Gen: 生成阶段 O->>Gen: 传递最终上下文 Gen->>Gen: 构建Prompt Gen->>Gen: LLM生成 Gen-->>RA: 生成的答案 RA->>RA: 答案质量检查 alt 答案可信度低 RA-->>O: 建议重新检索 O->>PA: 调整策略 else 答案质量OK RA-->>Gen: 确认通过 Gen-->>U: 返回最终答案 end

8.4. 与现有系统集成

8.4.1 架构集成点

复用现有组件作为工具：

现有架构                          Agentic架构
├── crag/                         ├── agent/
│   ├── qrewrite/                 │   ├── planning/
│   │   └── llm_query_rewriter    │   ├── retrieval/
│   ├── evaluator/         ────>  │   ├── tool/       (封装现有组件)
│   │   └── evaluator_llm         │   ├── reflection/
│   └── search/                   │   └── orchestrator/
├── reranker/              ────>  ├── tools/
│   └── provider                  │   ├── query_rewriter_tool.go
├── vectordb/              ────>  │   ├── retriever_tool.go
│   └── milvus                    │   ├── reranker_tool.go
└── pipeline/                     │   ├── evaluator_tool.go
    └── rag_workflow       ────>  │   ├── web_search_tool.go
                                  │   └── compressor_tool.go
                                  └── workflow/
                                      └── agentic_workflow.go

集成方式：

工具化现有组件

// tools/query_rewriter_tool.go
type QueryRewriterTool struct {
    rewriter *qrewrite.LLMQueryRewriter
}

func (t *QueryRewriterTool) Execute(ctx context.Context, input interface{}) (interface{}, error) {
    query := input.(string)
    return t.rewriter.Convert(query)
}

扩展现有Workflow

// workflow/agentic_workflow.go
type AgenticWorkflow struct {
    // 复用现有组件
    ragClient    *rag.RAGClient
    cragWorkflow *crag.Workflow
    
    // 新增Agent组件
    planner      *planning.PlanningAgent
    orchestrator *orchestrator.Orchestrator
    reflector    *reflection.ReflectionAgent
}

保持向后兼容

// 提供统一入口,支持传统模式和Agentic模式
type UnifiedRAG interface {
    Query(ctx context.Context, req *QueryRequest) (*QueryResponse, error)
}

type QueryRequest struct {
    Query      string
    Mode       RAGMode  // traditional, agentic
    Config     *Config
}

type RAGMode string
const (
    TraditionalMode RAGMode = "traditional"  // 使用现有pipeline
    AgenticMode     RAGMode = "agentic"      // 使用Agentic流程
)

8.4.2 接口设计

8.4.2.1 Agent核心接口

// agent/agent.go
package agent

type Agent interface {
    // Agent名称
    Name() string
    
    // 执行Agent逻辑
    Execute(ctx context.Context, input *AgentInput) (*AgentOutput, error)
}

type AgentInput struct {
    Query       string
    Context     *ExecutionContext
    Parameters  map[string]interface{}
}

type AgentOutput struct {
    Result      interface{}
    Metadata    map[string]interface{}
    NextActions []Action
}

type ExecutionContext struct {
    SessionID   string
    Memory      Memory
    ToolRegistry *ToolRegistry
}

8.4.2.2 工具注册接口

// agent/tool/registry.go
package tool

type ToolRegistry struct {
    tools map[string]Tool
    mu    sync.RWMutex
}

func (r *ToolRegistry) Register(tool Tool) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    r.tools[tool.Name()] = tool
    return nil
}

func (r *ToolRegistry) Get(name string) (Tool, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    
    tool, exists := r.tools[name]
    if !exists {
        return nil, fmt.Errorf("tool %s not found", name)
    }
    return tool, nil
}

// 初始化注册现有组件
func InitializeTools(ragClient *rag.RAGClient, cragWorkflow *crag.Workflow) *ToolRegistry {
    registry := &ToolRegistry{tools: make(map[string]Tool)}
    
    // 注册工具
    registry.Register(NewQueryRewriterTool(cragWorkflow.QueryRewriter))
    registry.Register(NewRetrieverTool(ragClient.VectorDB))
    registry.Register(NewRerankerTool(ragClient.Reranker))
    registry.Register(NewEvaluatorTool(cragWorkflow.Evaluator))
    registry.Register(NewWebSearchTool(cragWorkflow.ExternalSearcher))
    registry.Register(NewCompressorTool(ragClient))
    
    return registry
}

8.4.2.3 状态管理接口

// agent/memory/memory.go
package memory

type Memory interface {
    // 短期记忆：当前会话
    SetShortTerm(key string, value interface{}) error
    GetShortTerm(key string) (interface{}, error)
    
    // 长期记忆：跨会话
    SetLongTerm(key string, value interface{}) error
    GetLongTerm(key string) (interface{}, error)
    
    // 清除记忆
    Clear() error
}

type InMemoryStorage struct {
    shortTerm map[string]interface{}
    longTerm  map[string]interface{}
    mu        sync.RWMutex
}

// 记忆内容示例
type ConversationHistory struct {
    Messages []Message
}

type RetrievalHistory struct {
    Query   string
    Results []*schema.SearchResult
    Score   float64
}

8.5. 实现路线图

8.5.1 模块划分与目录结构

plugins/golang-filter/mcp-server/servers/rag/
├── agent/                          # Agentic RAG核心模块
│   ├── agent.go                    # Agent基础接口定义
│   ├── planning/                   # 规划Agent
│   │   ├── planner.go              # Planning Agent实现
│   │   ├── task_decomposer.go      # 任务分解器
│   │   └── strategy.go             # 策略定义
│   ├── retrieval/                  # 检索Agent
│   │   ├── retrieval_agent.go      # Retrieval Agent实现
│   │   └── strategy.go             # 检索策略
│   ├── tool/                       # 工具Agent
│   │   ├── tool_agent.go           # Tool Agent实现
│   │   ├── registry.go             # 工具注册表
│   │   └── tools/                  # 具体工具实现
│   │       ├── query_rewriter_tool.go
│   │       ├── retriever_tool.go
│   │       ├── reranker_tool.go
│   │       ├── evaluator_tool.go
│   │       ├── web_search_tool.go
│   │       └── compressor_tool.go
│   ├── reflection/                 # 反思Agent
│   │   ├── reflection_agent.go     # Reflection Agent实现
│   │   ├── evaluator.go            # 结果评估器
│   │   └── suggestion.go           # 建议生成器
│   ├── orchestrator/               # 编排器
│   │   ├── orchestrator.go         # Orchestrator实现
│   │   ├── executor.go             # 任务执行器
│   │   └── coordinator.go          # 协调器
│   └── memory/                     # 记忆模块
│       ├── memory.go               # Memory接口
│       ├── short_term.go           # 短期记忆
│       └── long_term.go            # 长期记忆
├── workflow/                       # 工作流集成
│   ├── agentic_workflow.go         # Agentic工作流
│   └── unified_rag.go              # 统一RAG入口
├── config/
│   └── agentic_config.go           # Agentic配置
└── examples/
    └── agentic_rag_example.go      # 使用示例

8.5.2 分阶段实现计划

Phase 1: 基础框架搭建

目标：建立Agent框架和工具注册机制

任务清单：

[ ] 定义Agent核心接口 (agent/agent.go)
[ ] 实现ToolRegistry工具注册表 (agent/tool/registry.go)
[ ] 封装现有组件为Tool
- [ ] QueryRewriterTool
- [ ] RetrieverTool
- [ ] RerankerTool
- [ ] EvaluatorTool
[ ] 实现基础Memory模块 (agent/memory/)
[ ] 编写单元测试

验收标准：

所有现有组件成功注册为Tool
工具可通过Registry调用
单元测试覆盖率>80%

Phase 2: Planning Agent实现

目标：实现任务规划和分解能力

任务清单：

[ ] 实现PlanningAgent (agent/planning/planner.go)
[ ] 实现TaskDecomposer任务分解器
[ ] 设计Prompt模板用于查询分析
[ ] 支持三种查询复杂度识别：简单/中等/复杂
[ ] 实现Plan结构和依赖关系管理
[ ] 编写测试用例覆盖各种查询类型

验收标准：

能正确识别查询复杂度
复杂查询能分解为合理的子任务
生成的Plan包含正确的依赖关系

Phase 3: Orchestrator与执行引擎

目标：实现任务编排和执行

任务清单：

[ ] 实现Orchestrator (agent/orchestrator/orchestrator.go)
[ ] 实现任务调度器（支持顺序/并行执行）
[ ] 实现ExecutionContext上下文管理
[ ] 集成ToolAgent进行工具调用
[ ] 实现执行日志和追踪
[ ] 错误处理和重试机制

验收标准：

能正确执行简单Plan（单任务）
能正确执行复杂Plan（多任务+依赖）
支持并行任务执行
异常情况能正确处理

Phase 4: Reflection Agent实现

目标：实现结果评估和反思优化

任务清单：

[ ] 实现ReflectionAgent (agent/reflection/reflection_agent.go)
[ ] 设计多维度评估指标
- 相关性评分
- 完整性评分
- 事实性评分
[ ] 实现问题诊断逻辑
[ ] 实现优化建议生成
[ ] 集成到Orchestrator的反馈循环

验收标准：

能正确评估检索结果质量
低质量结果能触发合理的优化建议
反馈循环能有效提升结果质量

Phase 5: 完整集成与优化

目标：端到端集成并优化性能

任务清单：

[ ] 实现AgenticWorkflow (workflow/agentic_workflow.go)
[ ] 实现UnifiedRAG统一入口
[ ] 集成所有Agent组件
[ ] 性能优化（并发、缓存）
[ ] 配置化支持（config/agentic_config.go）
[ ] 编写完整的集成测试
[ ] 编写使用文档和示例

验收标准：

端到端流程正常工作
支持传统模式和Agentic模式切换
延迟在可接受范围（<5s for 简单查询）
通过10+复杂场景测试

8.5.3 技术挑战与解决方案

挑战1: LLM调用开销大

问题：Planning、Reflection等环节多次调用LLM，延迟累积严重

解决方案：

智能路由：简单查询跳过Planning，直接使用传统流程
并行调用：规划和检索并行进行
缓存机制：对常见查询类型缓存Plan模板
流式处理：LLM生成采用流式返回，减少等待时间

// 智能路由示例
func (w *AgenticWorkflow) Query(ctx context.Context, query string) (*Response, error) {
    complexity := w.analyzeComplexity(query)  // 轻量级分析
    
    if complexity == Simple {
        // 直接走传统流程，避免Agent开销
        return w.ragClient.Query(ctx, query)
    }
    
    // 复杂查询才启用完整Agentic流程
    return w.agenticQuery(ctx, query)
}

挑战2: 错误传播和重试死循环

问题：某个工具失败可能导致整个流程失败，或陷入无限重试

解决方案：

熔断机制：工具连续失败N次后熔断
降级策略：关键工具失败时自动切换到备用方案
最大重试限制：全局和单工具两级限制
异常隔离：工具异常不影响其他工具

type CircuitBreaker struct {
    failureCount int
    threshold    int
    state        State  // closed, open, half_open
}

func (cb *CircuitBreaker) Call(fn func() error) error {
    if cb.state == Open {
        return errors.New("circuit breaker open")
    }
    
    err := fn()
    if err != nil {
        cb.failureCount++
        if cb.failureCount >= cb.threshold {
            cb.state = Open
        }
        return err
    }
    
    cb.reset()
    return nil
}

挑战3: 多Agent协调复杂度高

问题：多个Agent并发执行，状态同步和协调困难

解决方案：

中心化编排：由Orchestrator统一协调，避免Agent间直接通信
消息传递：通过消息队列传递Agent间的数据
状态机模型：定义清晰的状态转换规则
事件驱动：基于事件触发Agent行为，解耦依赖

// 事件驱动示例
type Event struct {
    Type      EventType
    Data      interface{}
    Timestamp time.Time
}

type EventType string
const (
    PlanCreated      EventType = "plan_created"
    TaskCompleted    EventType = "task_completed"
    EvaluationDone   EventType = "evaluation_done"
    RetryRequired    EventType = "retry_required"
)

func (o *Orchestrator) handleEvent(event *Event) {
    switch event.Type {
    case TaskCompleted:
        o.checkDependencies()
    case EvaluationDone:
        o.processEvaluation(event.Data)
    case RetryRequired:
        o.scheduleRetry(event.Data)
    }
}

挑战4: 与现有系统兼容性

问题：新增Agentic层可能破坏现有API和配置

解决方案：

适配器模式：为现有组件提供统一适配器
配置兼容：扩展现有配置结构，保持向后兼容
版本化API：提供v1(传统)和v2(Agentic)两套API
功能开关：通过配置控制Agentic功能的启用

// 配置兼容示例
type RAGConfig struct {
    // 现有配置
    VectorDB    *VectorDBConfig
    Reranker    *RerankerConfig
    CRAG        *CRAGConfig
    
    // 新增Agentic配置（可选）
    Agentic     *AgenticConfig  `yaml:"agentic,omitempty"`
}

type AgenticConfig struct {
    Enabled     bool
    MaxRetries  int
    Timeout     time.Duration
    PlannerLLM  string
}

8.6. 参考文献

8.6.1 核心论文

Yao S, Zhao J, Yu D, et al. React: Synergizing reasoning and acting in language models[C]//The eleventh international conference on learning representations. 2022.
- 核心思想：交替执行推理(Reasoning)和行动(Acting)
- 应用实践：Planning Agent的设计
Shinn N, Cassano F, Labash B, et al. Reflexion: Language agents with verbal reinforcement learning, 2023[J]. URL https://arxiv. org/abs/2303.11366, 2023, 1.
- 核心思想：通过语言反馈进行自我反思和改进
- 应用实践：Reflection Agent的评估和优化机制
Yan S Q, Gu J C, Zhu Y, et al. Corrective retrieval augmented generation[J]. 2024.
- 核心思想：评估检索质量并触发纠正行动
- 应用实践：已集成到现有系统，Agentic层进一步增强
Asai A, Wu Z, Wang Y, et al. Self-rag: Learning to retrieve, generate, and critique through self-reflection[J]. 2024.
- 核心思想：自适应检索和生成，带自我批评
- 应用实践：反思机制的多维度评估
Schick T, Dwivedi-Yu J, Dessì R, et al. Toolformer: Language models can teach themselves to use tools[J]. Advances in Neural Information Processing Systems, 2023, 36: 68539-68551.
- 核心思想：LLM自主学习工具使用
- 应用实践：Tool Agent的工具选择策略
Wei J, Wang X, Schuurmans D, et al. Chain-of-thought prompting elicits reasoning in large language models[J]. Advances in neural information processing systems, 2022, 35: 24824-24837.
- 应用实践：Planning Agent的推理 Prompt设计
Liu N F, Lin K, Hewitt J, et al. Lost in the middle: How language models use long contexts[J]. Transactions of the Association for Computational Linguistics, 2024, 12: 157-173.
- 应用实践：位置优化策略（Sandwich）的理论依据

8.7. 总结与展望

8.7.1 核心优势总结

Agentic RAG相比现有方案的核心价值：

智能化：从固定流水线到自主决策
自适应：根据查询特点动态调整策略
可扩展：新增工具无需修改核心逻辑
可解释：完整的执行日志和决策路径

8.7.2 应用场景

高价值场景：

复杂多跳推理问题
需要多源信息聚合的对比分析
开放域问答（知识库+实时搜索）
需要高准确性的专业领域问答

不适用场景：

简单事实查询（直接用传统RAG更快）
对延迟极度敏感的场景
资源受限环境

8.7.3 未来优化方向

更小的Planning模型：探索使用7B级别模型替代GPT-4进行规划
强化学习优化：通过RL训练Agent的决策策略
知识图谱融合：结合KG进行结构化推理
多模态支持：扩展到图像、表格等多模态检索
联邦学习：隐私保护场景下的分布式Agentic RAG

9. 总结

本RAG增强方案实现了从检索前优化到纠正性检索的完整pipeline，具有以下突出特点：

✅ 完整性: 覆盖Pre-Retrieval、Retrieval、Post-Retrieval、CRAG、Agentic RAG全流程
✅ 理论支撑: 基于CRAG、Query Rewriting等前沿研究
✅ 模块化: 高度解耦，各组件独立可配
✅ 可验证: 完整评测框架，量化效果提升
✅ 生产就绪: 超时控制、并发支持、错误处理完善