flowchart TB
    subgraph API["接口层 - API Layer"]
        direction LR
        HTTPServer["FastAPI HTTP Server<br/>端口:8006"]
        Router["Router (/api/v1/rag)<br/>路由分发"]
        Validator["Pydantic Models<br/>参数验证"]
    end

    subgraph Service["业务层 - Service Layer"]
        direction TB
        RAGService["RAG Service<br/>业务编排"]
        AdaptiveRAG["Adaptive RAG Service<br/>自适应策略选择"]
        SelfRAG["Self-RAG Service<br/>自我反思迭代"]
        SemanticCache["Semantic Cache Service<br/>语义缓存"]
    end

    subgraph Core["核心层 - Core Layer"]
        direction TB
        QueryRewriter["Query Rewriter<br/>查询改写(Multi/HyDE)"]
        ContextBuilder["Context Builder<br/>上下文构建+Token截断"]
        AnswerGenerator["Answer Generator<br/>答案生成(流式/非流式)"]
        CitationGenerator["Citation Generator<br/>引用提取与标注"]
    end

    subgraph Infrastructure["基础设施层 - Infrastructure Layer"]
        direction LR
        RetrievalClient["Retrieval Client<br/>HTTP客户端"]
        LLMClient["Unified LLM Client<br/>统一LLM接口"]
        RedisCache["Redis Cache<br/>语义缓存存储"]
    end

    subgraph External["外部服务 - External Services"]
        direction TB
        RetrievalService["Retrieval Service<br/>:8007"]
        ModelAdapter["Model Adapter<br/>:8005"]
        Milvus["Milvus<br/>向量数据库"]
        Redis["Redis<br/>缓存"]
        LLMs["LLM Providers<br/>GPT-4/Claude/通义"]
    end

    subgraph Clients["上游调用方"]
        direction LR
        AIOrchestrator["AI Orchestrator"]
        ConversationService["Conversation Service"]
        DirectAPI["Direct HTTP API"]
    end

    Clients --> HTTPServer
    HTTPServer --> Router
    Router --> Validator
    Validator --> RAGService

    RAGService --> QueryRewriter
    RAGService --> ContextBuilder
    RAGService --> AnswerGenerator
    RAGService --> CitationGenerator
    RAGService --> RetrievalClient

    RAGService -.可选策略.-> AdaptiveRAG
    RAGService -.可选策略.-> SelfRAG
    RAGService -.查询缓存.-> SemanticCache

    QueryRewriter --> LLMClient
    AnswerGenerator --> LLMClient

    AdaptiveRAG --> QueryRewriter
    AdaptiveRAG --> RetrievalClient
    AdaptiveRAG --> LLMClient

    SelfRAG --> RetrievalClient
    SelfRAG --> LLMClient

    SemanticCache --> RedisCache

    RetrievalClient --> RetrievalService
    LLMClient --> ModelAdapter
    RedisCache --> Redis

    RetrievalService --> Milvus
    ModelAdapter --> LLMs

    style API fill:#e3f2fd
    style Service fill:#fff3e0
    style Core fill:#f3e5f5
    style Infrastructure fill:#fce4ec
    style External fill:#e8f5e9
    style Clients fill:#c8e6c9

self.query_rewriter = QueryRewriter(llm_client, model)
self.context_builder = ContextBuilder(model)
self.answer_generator = AnswerGenerator(llm_client, model)
self.citation_generator = CitationGenerator()

def __init__(
    self,
    redis_host: str = "localhost",
    redis_port: int = 6379,
    redis_db: int = 0,
    embedding_model: str = "all-MiniLM-L6-v2",
    similarity_threshold: float = 0.92,
    cache_ttl: int = 3600,
    max_cache_queries: int = 10000,
    use_faiss: bool = True,
)

async def get_cached_answer(query: str) -> Optional[CachedAnswer]
async def set_cached_answer(query: str, answer: str, sources: list = None, ttl: int = None)
async def clear_cache()
async def rebuild_faiss_index()
async def get_cache_stats() -> dict

self.stats = {
    "hits": 0,
    "misses": 0,
    "total_queries": 0,
    "avg_latency_ms": 0,
    "total_latency_ms": 0,
}

def __init__(
    self,
    llm_client: Optional[AsyncOpenAI] = None,
    model: str = "gpt-3.5-turbo",
)

async def rewrite_query(query: str, method: str = "multi", num_queries: int = 3) -> List[str]
async def rewrite_multi_query(query: str, num_queries: int = 3) -> List[str]
async def rewrite_hyde(query: str) -> str
async def decompose_query(query: str) -> List[str]

def __init__(
    self,
    model: str = "gpt-3.5-turbo",
    max_context_tokens: int = 3000,
    chunk_delimiter: str = "\n\n---\n\n",
)

def count_tokens(text: str) -> int
def truncate_chunks(chunks: List[Dict[str, Any]], max_tokens: Optional[int] = None) -> List[Dict[str, Any]]
def build_context(chunks: List[Dict[str, Any]], include_metadata: bool = True, max_tokens: Optional[int] = None) -> str
def build_prompt(query: str, context: str, system_prompt: Optional[str] = None, include_instructions: bool = True) -> List[Dict[str, str]]
def estimate_prompt_tokens(query: str, context: str, system_prompt: Optional[str] = None) -> int
def _truncate_text(text: str, max_tokens: int) -> str
def _format_metadata(metadata: Dict[str, Any]) -> str

def __init__(
    self,
    llm_client: AsyncOpenAI,
    model: str = "gpt-3.5-turbo",
    temperature: float = 0.7,
    max_tokens: int = 1000,
)

async def generate(messages: List[Dict[str, str]], temperature: Optional[float] = None, max_tokens: Optional[int] = None) -> Dict[str, Any]
async def generate_stream(messages: List[Dict[str, str]], temperature: Optional[float] = None, max_tokens: Optional[int] = None) -> AsyncIterator[str]
async def generate_with_functions(messages: List[Dict[str, str]], functions: List[Dict[str, Any]], function_call: Optional[str] = None) -> Dict[str, Any]
async def batch_generate(messages_list: List[List[Dict[str, str]]], temperature: Optional[float] = None, max_tokens: Optional[int] = None) -> List[Dict[str, Any]]

def __init__(self, citation_format: str = "inline")

def extract_citations(answer: str) -> List[int]
def generate_citations(chunks: List[Dict[str, Any]], answer: str, include_all: bool = False) -> List[Dict[str, Any]]
def format_citations(citations: List[Dict[str, Any]], format_type: str = "markdown") -> str
def add_inline_citations(answer: str, chunks: List[Dict[str, Any]]) -> str
def generate_response_with_citations(answer: str, chunks: List[Dict[str, Any]], include_inline: bool = False, citation_format: str = "markdown") -> Dict[str, Any]

def __init__(self, base_url: str = "http://retrieval-service:8012", timeout: int = 30)

async def retrieve(query: str, top_k: int = 10, mode: str = "hybrid", tenant_id: Optional[str] = None, rerank: bool = True, filters: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]
async def multi_retrieve(queries: List[str], top_k: int = 10, **kwargs) -> List[List[Dict[str, Any]]]
async def health_check() -> bool
async def close() -> None

sequenceDiagram
    autonumber
    participant Client as 上游调用方<br/>(AI Orchestrator)
    participant API as FastAPI<br/>HTTP Server
    participant Router as RAG Router<br/>(/api/v1/rag)
    participant Service as RAG Service<br/>业务编排
    participant Rewriter as Query Rewriter<br/>查询改写
    participant Context as Context Builder<br/>上下文构建
    participant Generator as Answer Generator<br/>答案生成
    participant Citation as Citation Generator<br/>引用生成
    participant RClient as Retrieval Client<br/>HTTP客户端
    participant LLMClient as AsyncOpenAI<br/>LLM客户端
    participant RService as Retrieval Service<br/>:8007
    participant ModelAdapter as Model Adapter<br/>:8005
    participant LLM as LLM Provider<br/>GPT-4/Claude

    Note over Client,LLM: 标准 RAG 流程（非流式，Multi-Query 模式）

    Client->>API: POST /api/v1/rag/generate
    Note right of Client: RAGRequest:<br/>query="如何优化MySQL性能?"<br/>tenant_id="tenant-123"<br/>rewrite_method="multi"<br/>top_k=10<br/>include_citations=true

    API->>Router: 路由匹配 /api/v1/rag
    Router->>Router: Pydantic 参数验证
    Note over Router: 验证字段：<br/>query: 1-5000字符<br/>top_k: 1-50<br/>rewrite_method: multi/hyde/none

    Router->>Service: generate(query, tenant_id, rewrite_method, top_k, ...)
    Note over Service: 启动RAG业务流程

    rect rgb(230, 240, 255)
        Note over Service,LLM: 阶段1：查询改写（0.5-1.5秒）
        Service->>Rewriter: rewrite_query(query, method="multi", num_queries=3)

        Rewriter->>LLMClient: chat.completions.create(<br/>  model="gpt-3.5-turbo",<br/>  messages=[...],<br/>  temperature=0.7,<br/>  max_tokens=200<br/>)
        Note over LLMClient: Prompt: 生成2个替代查询

        LLMClient->>ModelAdapter: POST /api/v1/chat/completions
        Note over ModelAdapter: 通过Model Adapter<br/>实现统一LLM调用

        ModelAdapter->>LLM: API调用（根据模型路由）
        LLM-->>ModelAdapter: "1. 提升MySQL数据库速度的方法\n2. MySQL性能调优技巧"
        ModelAdapter-->>LLMClient: response

        LLMClient-->>Rewriter: content
        Rewriter->>Rewriter: 解析输出（按行分割）
        Rewriter-->>Service: queries: [<br/>  "如何优化MySQL性能?",<br/>  "提升MySQL数据库速度的方法",<br/>  "MySQL性能调优技巧"<br/>]
    end

    rect rgb(240, 255, 240)
        Note over Service,RService: 阶段2：多查询检索+去重（1-2秒）

        loop 对每个查询执行检索
            Service->>RClient: retrieve(<br/>  query=q,<br/>  top_k=10,<br/>  tenant_id="tenant-123",<br/>  rerank=True<br/>)
            RClient->>RService: POST /api/v1/retrieval/retrieve
            Note over RService: 混合检索：<br/>向量 + BM25 + Rerank
            RService-->>RClient: chunks: List[Dict] (10个)
            RClient-->>Service: 检索结果
        end

        Service->>Service: _deduplicate_chunks(all_chunks)
        Note over Service: 基于chunk_id去重<br/>保留分数最高的<br/>3×10=30 → 去重后约18个
    end

    rect rgb(255, 250, 235)
        Note over Service,Context: 阶段3：上下文构建（0.1-0.3秒）
        Service->>Context: build_context(<br/>  chunks=unique_chunks,<br/>  include_metadata=True<br/>)

        Context->>Context: truncate_chunks(chunks, max_tokens=3000)
        Note over Context: tiktoken计算Token数<br/>按score排序，优先保留高分文档

        loop 遍历文档（按分数降序）
            Context->>Context: count_tokens(chunk.content)
            alt current_tokens + chunk_tokens <= 3000
                Context->>Context: 加入selected_chunks
            else 超限
                Context->>Context: 停止或截断
            end
        end

        Context->>Context: format_document(chunk, index)
        Note over Context: [Source N] (File: xxx, Page: N)<br/>content

        Context-->>Service: formatted_context (约2950 tokens)

        Service->>Context: build_prompt(query, context)
        Context->>Context: 构建messages列表
        Note over Context: [<br/>  {role:"system", content:"You are a helpful AI assistant..."},<br/>  {role:"user", content:"Context:\n...\n\nQuestion: ..."}<br/>]
        Context-->>Service: messages: List[Dict]
    end

    rect rgb(255, 240, 245)
        Note over Service,LLM: 阶段4：答案生成（2-5秒）
        Service->>Generator: generate(messages, temperature=0.7, max_tokens=1000)

        Generator->>LLMClient: chat.completions.create(<br/>  model="gpt-3.5-turbo",<br/>  messages=messages,<br/>  temperature=0.7,<br/>  max_tokens=1000<br/>)

        LLMClient->>ModelAdapter: POST /api/v1/chat/completions
        ModelAdapter->>LLM: API调用
        Note over LLM: LLM生成答案<br/>包含引用标记

        LLM-->>ModelAdapter: answer + usage
        Note right of LLM: {<br/>  answer: "MySQL性能优化包括...[Source 1]...",<br/>  usage: {<br/>    prompt_tokens: 3100,<br/>    completion_tokens: 420<br/>  }<br/>}

        ModelAdapter-->>LLMClient: response
        LLMClient-->>Generator: response

        Generator-->>Service: {<br/>  answer: "...",<br/>  model: "gpt-3.5-turbo",<br/>  usage: {...},<br/>  finish_reason: "stop"<br/>}
    end

    rect rgb(245, 245, 255)
        Note over Service,Citation: 阶段5：引用生成（0.05-0.1秒）
        Service->>Citation: generate_response_with_citations(<br/>  answer=answer,<br/>  chunks=unique_chunks<br/>)

        Citation->>Citation: extract_citations(answer)
        Note over Citation: 正则匹配 \[Source (\d+)\]<br/>提取 [1, 3, 5] 等编号

        Citation->>Citation: generate_citations(chunks, answer)
        Note over Citation: 关联文档片段<br/>构建引用列表

        Citation->>Citation: format_citations(citations, "markdown")
        Note over Citation: 格式化为Markdown<br/>**[1]** filename (Page N)

        Citation-->>Service: {<br/>  answer: "...",<br/>  citations: [...],<br/>  formatted_citations: "..."<br/>}
    end

    Service->>Service: 计算元数据
    Note over Service: total_time: 4.2秒<br/>rewrite_time: 0.8秒<br/>retrieve_time: 1.3秒<br/>generate_time: 2.0秒<br/>chunks_found: 18<br/>model: "gpt-3.5-turbo"<br/>usage: {...}

    Service-->>Router: {<br/>  answer: "...",<br/>  citations: [...],<br/>  metadata: {...}<br/>}
    Router-->>API: RAGResponse
    API-->>Client: 200 OK (JSON)
    Note right of API: {<br/>  "answer": "MySQL性能优化包括...",<br/>  "citations": [{...}, {...}],<br/>  "metadata": {<br/>    "total_time": 4.2,<br/>    "rewrite_time": 0.8,<br/>    "retrieve_time": 1.3,<br/>    "generate_time": 2.0,<br/>    "chunks_found": 18,<br/>    "model": "gpt-3.5-turbo",<br/>    "usage": {...}<br/>  }<br/>}

POST /api/v1/rag/generate (HTTP 请求)
  ↓
FastAPI 路由匹配 → app/routers/rag.py:router
  ↓
@router.post("/generate") async def generate(request: RAGRequest)
  ↓ Pydantic 自动验证 RAGRequest
  │ - query: str (1-5000 字符)
  │ - tenant_id: Optional[str]
  │ - rewrite_method: str = "multi"
  │ - top_k: int = 10 (1-50)
  │ - stream: bool = False
  │ - include_citations: bool = True
  ↓
RAGService.generate() (app/services/rag_service.py:41)
  │
  ├─ [阶段1] 查询改写 (lines 73-79)
  │   ├─ QueryRewriter.rewrite_query(query, method=rewrite_method)
  │   │   └─ if method == "multi":
  │   │       └─ rewrite_multi_query(query, num_queries=3)
  │   │           └─ AsyncOpenAI.chat.completions.create(
  │   │               model="gpt-3.5-turbo",
  │   │               temperature=0.7,
  │   │               max_tokens=200
  │   │           ) → Model Adapter → LLM
  │   └─ 返回: List[str] (例: [原始查询, 替代查询1, 替代查询2])
  │
  ├─ [阶段2] 多查询检索 + 去重 (lines 82-99)
  │   ├─ for q in queries:
  │   │   └─ RetrievalClient.retrieve(
  │   │       query=q,
  │   │       top_k=10,
  │   │       tenant_id=tenant_id,
  │   │       rerank=True
  │   │   )
  │   │   └─ httpx.AsyncClient.post(
  │   │       f"{base_url}/retrieve",
  │   │       json={...}
  │   │   ) → Retrieval Service (:8012)
  │   │   └─ 返回: List[Dict] (chunk_id, content, score, metadata)
  │   │
  │   └─ _deduplicate_chunks(all_chunks) (lines 230-260)
  │       └─ 基于 chunk_id 去重，保留最高分
  │
  ├─ [阶段3] 上下文构建 (lines 113-114)
  │   ├─ ContextBuilder.build_context(unique_chunks)
  │   │   ├─ truncate_chunks(chunks, max_tokens=3000)
  │   │   │   └─ 使用 tiktoken 计算 Token，按 score 排序
  │   │   └─ 格式化: "[Source N] (File: xxx)\n{content}\n\n---\n\n"
  │   │
  │   └─ ContextBuilder.build_prompt(query, context)
  │       └─ 返回: [
  │           {"role": "system", "content": "You are a helpful AI assistant..."},
  │           {"role": "user", "content": "Context:\n...\n\nQuestion: ..."}
  │       ]
  │
  ├─ [阶段4] 答案生成 (lines 125-127)
  │   └─ AnswerGenerator.generate(messages)
  │       └─ AsyncOpenAI.chat.completions.create(
  │           model="gpt-3.5-turbo",
  │           messages=messages,
  │           temperature=0.7,
  │           max_tokens=1000
  │       ) → Model Adapter → LLM
  │       └─ 返回: {
  │           "answer": "...",
  │           "model": "gpt-3.5-turbo",
  │           "usage": {...},
  │           "finish_reason": "stop"
  │       }
  │
  └─ [阶段5] 引用生成 (lines 134-138)
      └─ CitationGenerator.generate_response_with_citations(answer, unique_chunks)
          ├─ extract_citations(answer)
          │   └─ re.findall(r'\[Source (\d+)\]', answer)
          ├─ generate_citations(chunks, answer)
          │   └─ 关联 chunk_id、content、metadata
          └─ format_citations(citations, "markdown")
              └─ 返回: {
                  "answer": "...",
                  "citations": [...],
                  "formatted_citations": "..."
              }
  ↓
返回 RAGResponse (lines 142-154)
  {
    "answer": "...",
    "citations": [...],
    "metadata": {
      "total_time": 4.2,
      "rewrite_time": 0.8,
      "retrieve_time": 1.3,
      "generate_time": 2.0,
      "chunks_found": 18,
      "model": "gpt-3.5-turbo",
      "usage": {
        "prompt_tokens": 3100,
        "completion_tokens": 420,
        "total_tokens": 3520
      }
    }
  }

algo/rag-engine/
├── main.py                              # 应用入口，lifespan 管理
├── app/
│   ├── routers/
│   │   └── rag.py                       # API 路由定义，请求处理
│   ├── services/
│   │   ├── rag_service.py               # 核心 RAG 业务编排
│   │   ├── self_rag_service.py          # Self-RAG 自我反思
│   │   ├── adaptive_rag_service.py      # Adaptive RAG 自适应策略
│   │   └── semantic_cache_service.py    # 语义缓存（FAISS 优化）
│   ├── core/
│   │   ├── query_rewriter.py            # 查询改写（Multi/HyDE/Decomposition）
│   │   ├── context_builder.py           # 上下文构建与 Token 截断
│   │   ├── answer_generator.py          # LLM 答案生成（流式/非流式）
│   │   └── citation_generator.py        # 引用提取与标注
│   ├── infrastructure/
│   │   └── retrieval_client.py          # Retrieval Service HTTP 客户端
│   └── models/
│       └── rag.py                       # Pydantic 数据模型

sequenceDiagram
    autonumber
    participant Service as RAG Service
    participant Rewriter as Query Rewriter
    participant LLMClient as LLM Client
    participant LLM as LLM API

    Note over Service,LLM: Multi-Query Expansion 流程

    Service->>Rewriter: rewrite_query(query="如何优化MySQL性能?", method="multi", num_queries=3)

    Rewriter->>Rewriter: 构建Multi-Query Prompt
    Note over Rewriter: Prompt模板：<br/>"Given the following user query,<br/>generate 2 alternative queries..."

    Rewriter->>LLMClient: generate(prompt, temperature=0.7, max_tokens=200)

    LLMClient->>LLM: API调用
    Note over LLM: 生成替代查询

    LLM-->>LLMClient: response
    Note right of LLM: "1. 提升MySQL数据库速度的方法\n<br/>2. MySQL性能调优技巧"

    LLMClient-->>Rewriter: content

    Rewriter->>Rewriter: 解析输出（按行分割）
    Note over Rewriter: split("\n") → [query1, query2]

    Rewriter->>Rewriter: 合并原始查询
    Note over Rewriter: [原始查询] + [query1, query2]

    Rewriter-->>Service: queries: ["如何优化MySQL性能?", "提升MySQL数据库速度的方法", "MySQL性能调优技巧"]

sequenceDiagram
    autonumber
    participant Service as RAG Service
    participant Context as Context Builder
    participant Tokenizer as Tiktoken

    Note over Service,Tokenizer: 上下文构建与Token截断流程

    Service->>Context: build_context(chunks=[18个文档], include_metadata=True, max_tokens=3000)

    Context->>Context: truncate_chunks(chunks, max_tokens=3000)

    loop 遍历文档（按分数降序）
        Context->>Tokenizer: encode(chunk.content)
        Tokenizer-->>Context: tokens

        Context->>Context: 计算累计Token数
        Note over Context: current_tokens += len(tokens)

        alt current_tokens <= max_tokens
            Context->>Context: 加入selected_chunks
        else current_tokens > max_tokens
            alt 是第一个文档
                Context->>Context: 截断文档内容
                Note over Context: _truncate_text(content, remaining_tokens)
                Context->>Context: 加入截断后的文档
            else
                Context->>Context: 停止添加
                Note over Context: 已达到Token限制
            end
        end
    end

    Note over Context: selected_chunks: 8个文档

    Context->>Context: format_document(doc, index)

    loop 格式化每个文档
        Context->>Context: 提取元数据（filename, page, section）
        Context->>Context: 格式化为：<br/>"[Source N] (File: xxx, Page: N)\ncontent"
    end

    Context->>Context: 用分隔符连接
    Note over Context: "\n\n---\n\n".join(formatted_docs)

    Context-->>Service: formatted_context (2950 tokens)

    Service->>Context: build_prompt(query, context, system_prompt)

    Context->>Context: 构建messages
    Note over Context: messages = [<br/>  {role: "system", content: system_prompt},<br/>  {role: "user", content: "Context: ...\n\nQuestion: ..."}<br/>]

    Context-->>Service: messages: List[Dict]

sequenceDiagram
    autonumber
    participant Client as Web Client<br/>前端应用
    participant API as FastAPI<br/>SSE Server
    participant Service as RAG Service
    participant Rewriter as Query Rewriter
    participant RClient as Retrieval Client
    participant Context as Context Builder
    participant LLMClient as LLM Client
    participant LLM as LLM API

    Note over Client,LLM: 流式 RAG 调用（Server-Sent Events）

    Client->>API: POST /api/v1/rag/generate/stream
    Note right of Client: EventSource 或 fetch(stream=true)

    API->>Service: generate_stream(query, tenant_id, ...)

    Note over API,Client: 建立SSE连接<br/>Content-Type: text/event-stream

    rect rgb(230, 240, 255)
        Note over Service,LLM: 阶段1：查询改写
        Service->>Rewriter: rewrite_query(query, method="none")
        Note over Rewriter: 流式模式通常不做复杂改写<br/>（降低首Token延迟）
        Rewriter-->>Service: queries: [query]
    end

    rect rgb(240, 255, 240)
        Note over Service,RClient: 阶段2：检索
        Service->>RClient: retrieve(query, top_k=10, rerank=True)
        RClient-->>Service: chunks (10个文档)

        Service->>API: yield {type: "context", chunks_count: 10}
        API->>Client: data: {"type":"context","chunks_count":10}
        Note right of Client: 接收事件：上下文就绪
    end

    rect rgb(255, 250, 235)
        Note over Service,Context: 阶段3：上下文构建
        Service->>Context: build_context(chunks)
        Context-->>Service: context

        Service->>Context: build_prompt(query, context)
        Context-->>Service: messages
    end

    rect rgb(255, 240, 245)
        Note over Service,LLM: 阶段4：流式生成答案
        Service->>LLMClient: generate_stream(messages, temperature=0.7)

        LLMClient->>LLM: API调用（stream=True）

        loop 流式返回Token
            LLM-->>LLMClient: chunk (delta.content)
            LLMClient-->>Service: token

            Service->>API: yield {type: "chunk", content: token}
            API->>Client: data: {"type":"chunk","content":"MySQL"}
            Note right of Client: 逐Token渲染答案
        end

        LLM-->>LLMClient: [DONE]
        LLMClient-->>Service: 流结束
    end

    rect rgb(245, 245, 255)
        Note over Service,API: 阶段5：发送引用和完成信号
        Service->>Service: 生成引用列表

        Service->>API: yield {type: "citations", citations: [...]}
        API->>Client: data: {"type":"citations","citations":[...]}

        Service->>API: yield {type: "done"}
        API->>Client: data: {"type":"done"}
        Note right of Client: 流式响应结束
    end

    API->>Client: 关闭SSE连接

sequenceDiagram
    autonumber
    participant Client as 上游服务
    participant Service as Self-RAG Service
    participant RClient as Retrieval Client
    participant LLM as LLM Client

    Note over Client,LLM: Self-RAG 多轮迭代流程（最多3轮）

    Client->>Service: query(query, tenant_id, knowledge_base_id)

    Note over Service: 迭代1开始

    rect rgb(230, 240, 255)
        Note over Service,LLM: Step 1: 判断是否需要检索
        Service->>LLM: _should_retrieve(query, [])
        Note over LLM: LLM评估：<br/>是否为事实性问题？<br/>是否需要外部文档？
        LLM-->>Service: {needs_retrieval: true, reasoning: "..."}
    end

    rect rgb(240, 255, 240)
        Note over Service,RClient: Step 2: 执行检索
        Service->>RClient: retrieve(query, top_k=5)
        RClient-->>Service: documents (5个)
    end

    rect rgb(255, 250, 235)
        Note over Service,LLM: Step 3: 评估检索质量
        Service->>LLM: _evaluate_retrieval(query, documents)
        Note over LLM: LLM评估每个文档相关性<br/>打分0-10
        LLM-->>Service: {overall_score: 4.5/10, relevant_count: 2, issues: ["部分文档不相关"]}

        alt 检索质量低（< 7分）
            Note over Service: 检索质量不足，重新formulate查询
            Service->>LLM: _reformulate_query(query, poor_results)
            Note over LLM: 生成改进的查询<br/>添加更多关键词/上下文
            LLM-->>Service: reformulated_query

            Service->>RClient: retrieve(reformulated_query, top_k=5)
            RClient-->>Service: documents (5个)

            Service->>LLM: _evaluate_retrieval(reformulated_query, documents)
            LLM-->>Service: {overall_score: 7.8/10, relevant_count: 4}
        end
    end

    rect rgb(255, 240, 245)
        Note over Service,LLM: Step 4: 生成答案
        Service->>LLM: _generate_answer(query, documents)
        LLM-->>Service: answer
    end

    rect rgb(245, 245, 255)
        Note over Service,LLM: Step 5: 评估答案质量
        Service->>LLM: _evaluate_answer(query, answer, documents)
        Note over LLM: 评估维度：<br/>1. 相关性 2. 准确性<br/>3. 完整性 4. 清晰度
        LLM-->>Service: {overall_score: 6.5/10, relevance: 7/10, accuracy: 6/10, completeness: 6/10, clarity: 7/10}

        alt 答案质量低（< 7分）
            Note over Service: 答案质量不足，进入迭代2

            Note over Service: 迭代2开始
            Service->>RClient: retrieve(query, top_k=5)
            RClient-->>Service: documents

            Service->>LLM: _evaluate_retrieval(...)
            LLM-->>Service: evaluation

            Service->>LLM: _generate_answer(...)
            LLM-->>Service: answer_v2

            Service->>LLM: _evaluate_answer(...)
            LLM-->>Service: {overall_score: 8.2/10, ...}

            alt 答案质量达标（>= 7分）
                Note over Service: 质量达标，停止迭代
            else 答案质量仍低且未达最大迭代次数
                Note over Service: 继续迭代3...
            end
        end
    end

    Note over Service: 迭代结束，返回最佳答案

    Service-->>Client: {answer, quality_score: 8.2, iterations: 2, iteration_details: [...]}

Given the following user query, generate {num_queries-1} alternative queries that capture different aspects or phrasings of the same information need.

User Query: {query}

Requirements:
1. Each alternative should be semantically related but use different words
2. Cover different aspects or interpretations of the original query
3. Keep queries concise and clear

Generate {num_queries-1} alternative queries (one per line):

Given the following question, write a detailed and informative answer as if you were answering from a knowledge base document.

Question: {query}

Write a hypothetical answer (2-3 paragraphs):

[来源1] 标题：{doc1.title}
内容：{doc1.content}
相关性得分：{doc1.score}

[来源2] 标题：{doc2.title}
内容：{doc2.content}
相关性得分：{doc2.score}

...

for doc in docs:
    doc.content = doc.content[:max_tokens_per_doc]

docs = sorted(docs, key=lambda x: x.score, reverse=True)[:top_k]

summary = await llm.summarize(docs)
context = summary

def deduplicate(docs):
    seen = set()
    unique_docs = []
    for doc in docs:
        # 使用内容哈希或相似度检测重复
        content_hash = hash(doc.content[:100])
        if content_hash not in seen:
            seen.add(content_hash)
            unique_docs.append(doc)
    return unique_docs

for i, doc in enumerate(docs):
    doc.citation_id = f"[{i+1}]"
    doc.citation_label = f"来源{i+1}"

历史对话：
用户：{previous_query}
助手：{previous_answer}

当前问题：{query}

def extract_citations(answer, sources):
    citations = []
    # 正则匹配 [1]、[2] 等引用标记
    pattern = r'\[(\d+)\]'
    matches = re.finditer(pattern, answer)

    for match in matches:
        citation_num = int(match.group(1))
        if citation_num <= len(sources):
            citations.append({
                "position": match.start(),
                "citation_num": citation_num,
                "source": sources[citation_num - 1],
            })

    return citations

def calculate_confidence(citation, answer_segment):
    # 因素1：文档相关性得分
    doc_score = citation.source.score

    # 因素2：内容相似度
    similarity = cosine_similarity(
        embedding(answer_segment),
        embedding(citation.source.content)
    )

    # 因素3：引用频率（多次引用更可信）
    frequency = count_citations(answer, citation.source.id)

    # 综合评分
    confidence = 0.4 * doc_score + 0.4 * similarity + 0.2 * min(frequency / 3, 1.0)
    return confidence

def detect_hallucination(answer, sources):
    # 将答案分句
    sentences = split_sentences(answer)

    hallucination_flags = []
    for sentence in sentences:
        # 检查句子是否有引用标记
        has_citation = bool(re.search(r'\[\d+\]', sentence))

        if not has_citation:
            # 检查句子内容是否与任何source相似
            max_similarity = max([
                semantic_similarity(sentence, src.content)
                for src in sources
            ])

            if max_similarity < 0.5:
                # 相似度低，可能是虚构
                hallucination_flags.append({
                    "sentence": sentence,
                    "risk": "high",
                    "reason": "无引用且与来源不匹配"
                })

    return hallucination_flags

classDiagram
    class RAGEngine {
        +QueryRewriter query_rewriter
        +RetrievalClient retrieval_client
        +ContextBuilder context_builder
        +PromptGenerator prompt_generator
        +LLMClient llm_client
        +Dict stats
        +initialize()
        +generate(query, mode, top_k) Dict
        +generate_stream(query, mode, top_k) AsyncIterator
        -_rewrite_query(query) str
        -_retrieve_documents(query, top_k) List
        -_build_context(docs, query) str
        -_generate_prompt(query, context) str
    }

    class QueryRewriter {
        +LLMClient llm_client
        +str model
        +rewrite_multi_query(query, num) List~str~
        +rewrite_hyde(query) str
        +expand_query(query) str
    }

    class RetrievalClient {
        +str retrieval_service_url
        +HTTPClient http_client
        +initialize()
        +hybrid_search(query, top_k, mode) List~Document~
        +vector_search(query, top_k) List~Document~
        +bm25_search(query, top_k) List~Document~
    }

    class ContextBuilder {
        +build_context(docs, query) str
        +compress_context(context, max_tokens) str
        +deduplicate(docs) List~Document~
        +format_document(doc, index) str
    }

    class PromptGenerator {
        +generate_prompt(query, context, mode) str
        +get_system_prompt(mode) str
        +get_instruction_template(mode) str
        +integrate_history(prompt, history) str
    }

    class CitationTracker {
        +extract_citations(answer, sources) List~Citation~
        +calculate_confidence(citation) float
        +detect_hallucination(answer, sources) List~Warning~
        +link_sources(answer, sources) Dict
    }

    class Document {
        +str id
        +str content
        +str title
        +float score
        +str source
        +Dict metadata
        +str citation_id
        +str citation_label
    }

    class Citation {
        +int position
        +int citation_num
        +Document source
        +float confidence
        +str answer_segment
    }

    class GenerationResult {
        +str answer
        +List~Document~ sources
        +str query
        +str rewritten_query
        +int retrieved_count
        +float generation_time
        +List~Citation~ citations
        +Dict metadata
    }

    class SelfRAGEvaluator {
        +LLMClient llm_client
        +int max_iterations
        +evaluate_answer(answer, query, context) Dict
        +generate_feedback(evaluation) str
        +optimize_prompt(prompt, feedback) str
    }

    RAGEngine --> QueryRewriter
    RAGEngine --> RetrievalClient
    RAGEngine --> ContextBuilder
    RAGEngine --> PromptGenerator
    RAGEngine --> CitationTracker
    RAGEngine --> SelfRAGEvaluator

    RetrievalClient ..> Document
    ContextBuilder ..> Document
    CitationTracker ..> Citation
    Citation --> Document

    RAGEngine ..> GenerationResult
    GenerationResult --> Document
    GenerationResult --> Citation

class QueryRequest(BaseModel):
    query: str                              # 用户查询
    conversation_id: Optional[str] = None   # 会话ID
    tenant_id: Optional[str] = None         # 租户ID
    mode: str = "simple"                    # 模式
    top_k: int = 5                          # 检索结果数
    temperature: float = 0.7                # 生成温度
    include_sources: bool = True            # 是否包含来源

class QueryResponse(BaseModel):
    answer: str                             # 生成的答案
    sources: List[SourceInfo]               # 引用来源列表
    query: str                              # 原始查询
    rewritten_query: str                    # 改写后的查询
    retrieved_count: int                    # 检索到的文档数
    generation_time: float                  # 生成耗时(秒)
    citations: List[CitationInfo]           # 引用详情
    metadata: Dict                          # 元数据

class SourceInfo(BaseModel):
    id: str                                 # 文档ID
    title: str                              # 文档标题
    content: str                            # 文档内容片段
    score: float                            # 相关性得分
    source: str                             # 来源
    citation_id: str                        # 引用标识符

class CitationInfo(BaseModel):
    citation_num: int                       # 引用编号
    source_id: str                          # 源文档ID
    confidence: float                       # 置信度

# RAGEngine核心生成逻辑
async def generate(
    self,
    query: str,
    conversation_id: str = None,
    tenant_id: str = None,
    mode: str = "simple",
    top_k: int = 5,
    temperature: float = 0.7,
    include_sources: bool = True,
) -> Dict:
    start_time = time.time()
    self.stats["total_queries"] += 1

    try:
        # 1. 查询改写
        # （省略日志）
        rewritten_query = await self._rewrite_query(query, conversation_id)
        # （省略日志）

        # 2. 检索相关文档
        retrieved_docs = await self._retrieve_documents(
            rewritten_query, tenant_id, top_k, mode
        )
        # （省略日志）

        # 3. 构建上下文
        context = await self._build_context(retrieved_docs, query)
        # （省略日志）

        # 4. 生成Prompt
        prompt = await self._generate_prompt(query, context, mode)

        # 5. 调用LLM生成答案
        answer = await self.llm_client.generate(
            prompt=prompt,
            temperature=temperature,
            max_tokens=2000,
        )

        # 6. 后处理：提取引用来源
        if include_sources:
            sources = self._extract_sources(retrieved_docs)
        else:
            sources = []

        # 7. 更新统计
        generation_time = time.time() - start_time
        self.stats["successful_generations"] += 1
        # （省略平均时间计算）

        # （省略日志）

        return {
            "answer": answer,
            "sources": sources,
            "query": query,
            "rewritten_query": rewritten_query,
            "retrieved_count": len(retrieved_docs),
            "generation_time": generation_time,
            "conversation_id": conversation_id,
        }

    except Exception as e:
        self.stats["failed_generations"] += 1
        # （省略错误日志）
        raise

async def _rewrite_query(self, query: str, conversation_id: str = None) -> str:
    # 如果有conversation_id，加载历史上下文
    if conversation_id:
        history = await self._load_conversation_history(conversation_id)
        # 基于历史上下文改写查询
        return await self.query_rewriter.rewrite_with_context(query, history)

    # 简单查询直接返回
    if len(query) < 20:
        return query

    # 复杂查询使用HyDE
    return await self.query_rewriter.rewrite_hyde(query)

async def _retrieve_documents(
    self,
    query: str,
    tenant_id: str,
    top_k: int,
    mode: str
) -> List[Document]:
    # 根据模式调整检索策略
    if mode == "precise":
        # 精确模式：提高向量检索权重
        docs = await self.retrieval_client.hybrid_search(
            query=query,
            top_k=top_k,
            vector_weight=0.8,
            bm25_weight=0.2,
            tenant_id=tenant_id,
        )
    elif mode == "advanced":
        # 高级模式：使用Multi-Query扩展
        queries = await self.query_rewriter.rewrite_multi_query(query, num_queries=3)
        docs = []
        for q in queries:
            results = await self.retrieval_client.hybrid_search(q, top_k=top_k//3, tenant_id=tenant_id)
            docs.extend(results)
        # 去重和重排序
        docs = self.context_builder.deduplicate(docs)
        docs = sorted(docs, key=lambda x: x.score, reverse=True)[:top_k]
    else:
        # 简单模式：标准混合检索
        docs = await self.retrieval_client.hybrid_search(
            query=query,
            top_k=top_k,
            tenant_id=tenant_id,
        )

    return docs

HTTP Handler (routers/rag.py)
  ↓ 参数验证
query_endpoint
  ↓
RAGEngine.generate
  ↓
  ├─ _rewrite_query
  │   ├─ query_rewriter.rewrite_hyde (或 rewrite_multi_query)
  │   └─ llm_client.generate (生成假设答案)
  │
  ├─ _retrieve_documents
  │   └─ retrieval_client.hybrid_search
  │       ├─ HTTP POST http://retrieval-service:8004/api/v1/retrieval/hybrid_search
  │       └─ 返回 List[Document]
  │
  ├─ _build_context
  │   ├─ context_builder.deduplicate (去重)
  │   ├─ context_builder.format_document (格式化)
  │   └─ context_builder.compress_context (压缩，如果需要)
  │
  ├─ _generate_prompt
  │   ├─ prompt_generator.get_system_prompt(mode)
  │   ├─ prompt_generator.get_instruction_template(mode)
  │   └─ 组装完整Prompt
  │
  └─ llm_client.generate
      ├─ 调用LLM API (GPT-4/Claude)
      └─ 返回生成的答案

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant HTTP as FastAPI Server
    participant Engine as RAGEngine
    participant Rewriter as QueryRewriter
    participant Retrieval as RetrievalService
    participant Context as ContextBuilder
    participant Prompt as PromptGenerator
    participant LLM as LLM Client
    participant Milvus as Milvus
    participant ES as Elasticsearch

    Client->>HTTP: POST /api/v1/rag/query
    Note over Client,HTTP: {query: "如何优化MySQL性能？",<br/>mode: "advanced", top_k: 5}

    HTTP->>Engine: generate(query, mode, top_k, ...)

    Engine->>Rewriter: rewrite_hyde(query)
    Rewriter->>LLM: generate(假设答案Prompt)
    Note over LLM: 生成假设答案<br/>"MySQL性能优化包括索引优化、查询优化..."
    LLM-->>Rewriter: 假设答案文本
    Rewriter-->>Engine: rewritten_query (假设答案)

    Engine->>Retrieval: hybrid_search(rewritten_query, top_k)

    par 并行检索
        Retrieval->>Milvus: search(query_vector, top_k)
        Note over Milvus: 向量检索
        Milvus-->>Retrieval: Top-20 文档（向量得分）

        Retrieval->>ES: search(query_text, top_k)
        Note over ES: BM25检索
        ES-->>Retrieval: Top-20 文档（BM25得分）
    end

    Note over Retrieval: RRF融合排序<br/>LLM重排序

    Retrieval-->>Engine: Top-5 最相关文档

    Engine->>Context: build_context(docs, query)

    Note over Context: 去重<br/>deduplicate()
    Note over Context: 格式化<br/>format_document()
    Note over Context: 压缩（如需要）<br/>compress_context()

    Context-->>Engine: formatted_context

    Engine->>Prompt: generate_prompt(query, context, "advanced")

    Note over Prompt: 获取system_prompt<br/>获取instruction_template<br/>组装完整Prompt

    Prompt-->>Engine: complete_prompt

    Engine->>LLM: generate(prompt, temperature=0.7)
    Note over LLM: GPT-4生成答案<br/>包含引用标记[1][2]
    LLM-->>Engine: answer

    Note over Engine: 提取引用来源<br/>_extract_sources()

    Engine-->>HTTP: GenerationResult<br/>{answer, sources, citations, ...}
    HTTP-->>Client: 200 OK<br/>JSON响应

data: {"type": "query_rewritten", "content": "优化MySQL数据库性能"}

data: {"type": "documents_retrieved", "count": 5}

data: {"type": "generation_start"}

data: {"type": "token", "content": "MySQL"}

data: {"type": "token", "content": "性能"}

data: {"type": "token", "content": "优化"}

...

data: {"type": "generation_complete", "sources": [...], "citations": [...]}

data: [DONE]

# 服务配置
PORT=8001
WORKERS=4
MAX_CONCURRENT_QUERIES=200

# LLM配置
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4-turbo
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000

# 检索配置
RETRIEVAL_SERVICE_URL=http://retrieval-service:8004
DEFAULT_TOP_K=5
DEFAULT_MODE=simple

# 查询改写配置
ENABLE_QUERY_REWRITING=true
HYDE_ENABLED=true
MULTI_QUERY_ENABLED=true
MULTI_QUERY_NUM=3

# Self-RAG配置
ENABLE_SELF_RAG=false
SELF_RAG_MAX_ITERATIONS=3
SELF_RAG_SCORE_THRESHOLD=70

service:
  name: rag-engine
  version: 1.0.0

server:
  port: 8001
  workers: 4
  max_concurrent_queries: 200

llm:
  provider: openai
  api_key: ${OPENAI_API_KEY}
  model: gpt-4-turbo
  temperature: 0.7
  max_tokens: 2000

retrieval:
  service_url: http://retrieval-service:8004
  timeout: 10s
  default_top_k: 5
  default_mode: simple

query_rewriting:
  enabled: true
  hyde:
    enabled: true
    fallback_to_original: true
  multi_query:
    enabled: true
    num_queries: 3
  query_expansion:
    enabled: false

context:
  max_tokens: 3000
  compression:
    enabled: true
    strategy: truncate
  deduplication:
    enabled: true
    threshold: 0.9

prompt:
  modes:
    simple:
      system_prompt: '你是一个专业的知识问答助手。'
      instruction_template: '请根据以下参考资料简洁回答问题。'
    advanced:
      system_prompt: '你是一个专业的知识问答助手，擅长深入分析和综合推理。'
      instruction_template: '请根据以下参考资料，深入分析并详细回答问题。'
    precise:
      system_prompt: '你是一个严谨的知识问答系统。'
      instruction_template: '请仅基于提供的参考资料回答问题，不要推测。'

self_rag:
  enabled: false
  max_iterations: 3
  score_threshold: 70
  evaluation_model: gpt-4

citation:
  enabled: true
  confidence_threshold: 0.5
  hallucination_detection: true