电网运维 RAG 智能问答系统

flowchart TB
    classDef l1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    classDef l2 fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef l3 fill:#fce4ec,stroke:#c62828,stroke-width:2px
    classDef l4 fill:#ede7f6,stroke:#6a1b9a,stroke-width:2px
    classDef l5 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef l6 fill:#eceff1,stroke:#455a64,stroke-width:2px

    L1["🖥️ 接入层<br/>Vue3 前端 :5173 · nginx 反代 · JWT 鉴权<br/>Chat / Documents / Dashboard / KgGraph / Diagnose / Admin / RetrievalDebug"]:::l1

    L2["⚙️ 应用层 · FastAPI<br/>routers(qa/document/retrieval/kg/domain/system)<br/>RBAC require_perm · slowapi 限流 · 插件 hook"]:::l2

    subgraph L3G["🧠 RAG 引擎层(核心·三大能力)"]
        direction LR
        L3R["🔍 检索 Retrieval<br/>路由·双路召回·RRF·rerank·MMR·GraphRAG"]:::l3
        L3A["✚ 增强 Augmentation<br/>三级缓存·CRAG纠错·证据缺口·prompt"]:::l3
        L3G2["✍️ 生成 Generation<br/>SSE流式·多轮·LLM-judge·双RAG热备"]:::l3
    end

    L4["🤖 模型层 · Provider(三家可切换)<br/>LLM: DeepSeek/Qwen/Doubao · Embedding: 云1024 + 本地bge512<br/>Rerank: gte-rerank-v2 · VLM: Qwen-VL · Agent 引擎"]:::l4

    subgraph L5G["💾 存储层 · 各司其职"]
        direction LR
        L5M[("MySQL 元数据+缓存")]:::l5
        L5V[("Milvus 双向量")]:::l5
        L5N[("Neo4j 图谱")]:::l5
        L5R[("Redis 热点缓存")]:::l5
        L5O[("MinIO 原文")]:::l5
    end

    L6["🐳 基础设施层<br/>Docker Compose 11 服务 · Prometheus 采集 · Grafana 22面板<br/>Alembic 迁移 · CI/CD · 定时任务(备份/归档/自进化)"]:::l6

    L1 --> L2 --> L3G
    L3R --> L3A --> L3G2
    L3G --> L4
    L3G --> L5G
    L4 -.->|云API| L5G
    L5G --> L6

flowchart LR
    classDef fe fill:#e1f5fe,stroke:#0288d1
    classDef app fill:#fff3e0,stroke:#ef6c00
    classDef dep fill:#e8f5e9,stroke:#2e7d32
    classDef obs fill:#ede7f6,stroke:#6a1b9a

    USER([👤 用户]):::fe

    subgraph EDGE["接入"]
        FE["frontend :5173<br/>nginx"]:::fe
        BE["backend :8001<br/>FastAPI/gunicorn"]:::app
    end

    subgraph CORE["核心依赖"]
        MYSQL[("mysql :3307<br/>8.0")]:::dep
        REDIS[("redis :6379<br/>7-alpine")]:::dep
        MILVUS[("milvus :19530<br/>v2.4.10")]:::dep
        NEO4J[("neo4j :7474/:7687<br/>5")]:::dep
        MINIO[("minio :9000/:9001<br/>原文")]:::dep
    end

    subgraph MILVUSDEP["Milvus 依赖"]
        ETCD[("etcd<br/>v3.5.5")]:::dep
        MMINIO[("milvus-minio<br/>专用对象存储")]:::dep
    end

    subgraph OBS["可观测"]
        PROM["prometheus :9090"]:::obs
        GRAFANA["grafana :3000<br/>admin/admin"]:::obs
    end

    USER -- HTTPS --> FE
    FE -- "/api 反代" --> BE
    BE --> MYSQL & REDIS & MILVUS & NEO4J & MINIO
    MILVUS --> ETCD & MMINIO
    BE -. /metrics .-> PROM
    PROM --> GRAFANA

sequenceDiagram
    autonumber
    participant FE as 前端
    participant GW as API层<br/>(鉴权+限流+插件+护栏)
    participant Cache as 三级缓存
    participant Ret as 检索<br/>(路由+召回+精排)
    participant Aug as 增强<br/>(CRAG+GraphRAG+prompt)
    participant LLM as LLM 流式生成
    participant Async as 异步闭环

    FE->>GW: POST /qa/answer(stream) + JWT
    GW->>GW: ① 鉴权 require_perm + 限流 30/min
    GW->>GW: ② 插件 query_preprocess(length_guard)
    GW->>GW: ③ 护栏: injection 告警 + Self-RAG 非运维拒答
    GW->>Cache: ④ 单轮查 L1 Redis → L2 MySQL → L1.5 Semantic
    alt 缓存命中
        Cache-->>FE: 秒回(cacheLayer=redis/mysql/semantic)
    else miss(多轮不读缓存)
        GW->>Ret: ⑤ 指代消解 → 6维路由 → 改写/双路召回/RRF/rerank/MMR
        Ret-->>Aug: contexts(已过 ACL+治理过滤)
        Aug->>Aug: ⑥ CRAG 分级(复用 rerank 分,不调 LLM)
        opt incorrect(低相关 < 0.3)
            Aug->>Ret: 改写 force 重检索
            Note right of Aug: 仍低分 → refused 保守拒答(零幻觉)
        end
        Aug->>Aug: ⑦ GraphRAG 查 Neo4j 三元组(topk=8)
        Aug->>LLM: ⑧ prompt(父块 + 图谱 + 置信度指令)
        loop 逐 token(SSE: meta → token×N → done)
            LLM-->>FE: 答案片段(打字机)
        end
        LLM->>GW: ⑨ 脱敏(PII) + 证据角标自动补全
        GW->>Cache: ⑩ Write-Through 回写 L2→L1(仅单轮 + confidence=high)
        GW->>GW: ⑪ 持久化对话(user + assistant)
    end
    Note over GW,Async: ⑫ 以下异步,不阻塞首字/响应
    GW->>Async: LLM-judge 质量采样(rel/faith/completeness)
    GW->>Async: 证据缺口收集(confidence = medium/refused)
    FE->>GW: 反馈 👍 / 👎
    GW->>Async: dislike 沉淀 → 知识自进化扫描入队

flowchart LR
    classDef ans fill:#e3f2fd,stroke:#1976d2
    classDef gap fill:#ffebee,stroke:#c62828
    classDef evo fill:#ede7f6,stroke:#6a1b9a
    classDef kb fill:#e8f5e9,stroke:#2e7d32

    ANS([答案返回]):::ans
    ANS --> FB{"用户反馈"}:::ans
    ANS -. "medium/refused" .-> EG([证据缺口 EvidenceGap]):::gap
    FB -. "👎 dislike" .-> EVO([知识自进化扫描]):::evo

    EG --> DEEP["deep_draft<br/>Agent 多轮补全<br/>cron 180s 批量5"]:::evo
    DEEP --> RV1{"人工审核"}:::evo
    RV1 -- approved --> SY1["回流: MinIO + Document<br/>+ Milvus<br/>doc_type=证据补全FAQ"]:::kb

    EVO --> BL["dislike 聚类(0.82)<br/>→ Milvus 盲区(top1&lt;0.55)<br/>→ LLM 规程草稿"]:::evo
    BL --> RV2{"人工审核"}:::evo
    RV2 -- approved --> SY2["回流 Milvus<br/>doc_type=ai_evolution<br/>quality=0.6 降权<br/>周配额 ≤20"]:::kb

    SY1 --> NXT([下次检索:新证据可命中]):::kb
    SY2 --> NXT
    NXT -. "quality 降权 + 治理 blocked" .-> IMP([影响检索排序/过滤]):::kb

flowchart LR
    classDef layer fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef perm fill:#e1f5fe,stroke:#0288d1
    classDef acl fill:#fce4ec,stroke:#c62828

    REQ([🔐 请求 Bearer JWT]):::perm

    subgraph L1["① 路由级 RBAC"]
        direction TB
        RP["require_perm('doc:delete')<br/>dependencies.py:32"]:::layer
        RP --> H1{"has_perm?<br/>permissions.py:75"}:::perm
        H1 -- 否 --> D403((403)):::acl
    end

    subgraph L2["② 三层权限叠加"]
        direction TB
        C["code 默认映射<br/>ROLE_PERMISSIONS :49"]:::layer
        DB["DB role_permission 覆盖<br/>models/permission.py :16"]:::layer
        H1 -- 是 --> C --> DB
    end

    subgraph L3["③ 文档级 ACL"]
        direction TB
        A["_assert_acl :46<br/>document_service.py"]:::layer
        A --> CK{"dept 匹配?<br/>allowed_roles 命中?<br/>admin 放行"}:::perm
        CK -- 否 --> D403
        CK -- 是 --> OK([✅ 放行]):::perm
    end

    DB --> A

flowchart TB
    classDef admin fill:#ffebee,stroke:#c62828
    classDef editor fill:#fff8e1,stroke:#f9a825
    classDef operator fill:#e3f2fd,stroke:#1976d2
    classDef audit fill:#f3e5f5,stroke:#7b1fa2

    subgraph BIZ["业务域"]
        direction TB
        QA["🤖 智能问答<br/>/qa/answer(stream)<br/>检索+CRAG+GraphRAG+流式"]:::operator
        DOC["📚 知识管理<br/>上传/解析/向量化/版本/回滚<br/>五库联动删除"]:::editor
        KG["🧠 知识图谱<br/>三元组抽取/多跳影响链/枢纽"]:::editor
        DOM["🩺 领域诊断<br/>故障诊断Agent/相似案例/两票/审核"]:::operator
        SYS["⚙️ 系统管理<br/>用户/配置/备份/告警/日志/插件"]:::admin
        OBS["📊 运维观测<br/>Grafana/降级/Provider探测/故障预测"]:::audit
    end

    ADMIN([admin]):::admin
    EDI([editor]):::editor
    OPE([operator]):::operator
    AUD([auditor]):::audit

    ADMIN ===> QA & DOC & KG & DOM & SYS & OBS
    EDI ==> DOC & KG & QA
    OPE ==> QA & DOM
    AUD ==> OBS

flowchart TD
    classDef guard fill:#ffebee,stroke:#c62828
    classDef route fill:#fff8e1,stroke:#f9a825
    classDef recall fill:#e3f2fd,stroke:#1976d2
    classDef refine fill:#e8f5e9,stroke:#2e7d32
    classDef grph fill:#f3e5f5,stroke:#7b1fa2

    A["term 归一 + 安全 guard<br/>qa_service.py:209-210"]:::guard
    B{"多轮?"}:::route
    B -- 是 --> S["standalone 指代消解<br/>standalone_query.py:12"]:::route
    B -- 否 --> R
    S --> R
    R["智能路由 6维决策<br/>routing_service.route_query"]:::route
    R --> M["mixed_search 编排<br/>retrieval_service.py:182"]:::recall
    M --> RW["query 改写/多查询/HyDE<br/>query_rewrite / multi_query / hyde"]:::recall
    RW --> D["双路并行召回<br/>BM25 + 云dense + bge dense"]:::recall
    D --> F["RRF 融合 k=60<br/>rrf.py"]:::refine
    F --> RR["Rerank gte-rerank-v2<br/>rerank_service.py:41"]:::refine
    RR --> MF["元数据后置过滤<br/>docType/equipment/ACL<br/>retrieval_service.py:302"]:::refine
    MF --> MM["MMR λ=0.5 去冗余<br/>mmr.py:18"]:::refine
    MM --> PB["small-to-big 父块召回<br/>(可选)"]:::refine
    PB --> G["GraphRAG 图谱上下文<br/>kg_service.graph_context<br/>qa_service.py:351"]:::grph
    G --> OUT([→ 交给增强/生成]):::refine

flowchart TD
    classDef feat fill:#e3f2fd,stroke:#1976d2
    classDef dec fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    classDef out fill:#e8f5e9,stroke:#2e7d32

    Q([用户 query]):::feat
    Q --> CL["query_classifier.classify<br/>6维特征:<br/>长度/数字/术语命中/同义词/口语度/标准引用"]:::feat
    CL --> DT{"决策树<br/>routing/config.py"}:::dec

    DT -- "标准号/超短词<br/>(如 GB/T 14285)" --> SP["sparse<br/>仅 BM25"]:::out
    DT -- "纯数值/型号" --> SPF["sparse_first<br/>BM25优先+向量补"]:::out
    DT -- "故障口语/同义词<br/>(如 跳闸/发烫)" --> DN["dense<br/>仅向量召回"]:::out
    DT -- "默认/复杂问题" --> HY["hybrid<br/>全链路(双路+BM25)"]:::out

    SP --> CF{"置信度 ≥ 0.85?"}:::dec
    CF -- 是 --> SR["跳过 rerank 省成本<br/>should_skip_rerank"]:::out
    CF -- 否 --> KEEP(["保留 rerank"]):::out

    DT -. "置信度 &lt; 0.6" .-> HY

flowchart LR
    classDef multi fill:#fff3e0,stroke:#ef6c00
    classDef llm fill:#ede7f6,stroke:#6a1b9a
    classDef cache fill:#fff8e1,stroke:#f9a825

    Q([原始 query]):::multi

    subgraph ST["多轮指代消解(仅多轮)"]
        STQ["rewrite_standalone<br/>standalone_query.py:12<br/>'它的处置呢'→'主变跳闸的处置步骤'"]:::multi
    end

    subgraph RW["LLM 改写闭环 v2"]
        direction TB
        CLS["Classifier 判定是否需改写"]:::llm
        RC["Redis 改写缓存 hit?"]:::cache
        LL["few-shot LLM 改写<br/>temp=0, max_tokens=120"]:::llm
        EV["Evaluator 评估<br/>REWRITE_EVAL_MARGIN=0.05<br/>更优才用否则回退原query"]:::llm
        CLS --> RC --> LL --> EV
    end

    subgraph MQ["多查询分解(hybrid/dense)"]
        MQD["decompose n=3 子问题<br/>multi_query.py:15<br/>并行检索后跨查询 RRF"]:::llm
    end

    subgraph HD["HyDE 假设文档"]
        HYD["generate_hypothetical<br/>hyde.py:12<br/>LLM 生 80-150字假设答案<br/>用其向量做 dense(BM25仍用原q)"]:::llm
    end

    Q --> STQ
    STQ --> RW
    RW --> MQ
    MQ --> HD
    HD --> OUT([→ 进入双路召回]):::multi

flowchart TD
    classDef q fill:#e3f2fd,stroke:#1976d2
    classDef dense fill:#ede7f6,stroke:#6a1b9a
    classDef sparse fill:#fff8e1,stroke:#f9a825
    classDef store fill:#e8f5e9,stroke:#2e7d32

    Q([search_q]):::q

    subgraph DENSE["稠密双路(asyncio.gather 并行)·_dense_and_sparse :114"]
        direction TB
        EQ["embed_query(带 Redis 缓存 ex=3600)<br/>embedding_service.py:23"]:::dense
        EQ --> CL["云路 EMB_PROVIDER=qwen<br/>text-embedding-v3 1024d<br/>qwen_embedding.py:23"]:::dense
        EQ --> BG["本地 bge 路<br/>bge-small-zh-v1.5 512d CPU<br/>bge_embedding.py:27"]:::dense
        CL --> MC1[("Milvus grid_chunks<br/>HNSW search<br/>milvus_client.py:63")]:::store
        BG --> MC2[("Milvus grid_chunks_bge<br/>HNSW search")]:::store
    end

    subgraph SP["稀疏 BM25·bm25_service.py"]
        SY["expand_synonyms 同义词扩展"]:::sparse
        BM["BM25Okapi + jieba<br/>内存全量+pickle冷启<br/>search :115 cand=max(topk*4,20)"]:::sparse
        SY --> BM
    end

    Q --> EQ
    Q --> SY
    MC1 --> POOL
    MC2 --> POOL
    BM --> POOL([候选 pool]):::store

flowchart LR
    classDef in fill:#e3f2fd,stroke:#1976d2
    classDef fuse fill:#fff8e1,stroke:#f9a825
    classDef rr fill:#ede7f6,stroke:#6a1b9a
    classDef out fill:#e8f5e9,stroke:#2e7d32
    classDef warn fill:#ffebee,stroke:#c62828

    DC["云 dense hits"]:::in
    DB["bge dense hits"]:::in
    BM["BM25 hits"]:::in

    DC --> RRF["RRF 融合<br/>rrf.py<br/>k=60 dense/sparse等权1.0/1.0"]:::fuse
    DB --> RRF
    BM --> RRF
    RRF --> POOL["fused pool<br/>[: topk*2]"]:::fuse

    POOL --> CHK{"skip_rerank?<br/>(高置信sparse≥0.85<br/>或单路)"}:::rr
    CHK -- 是 --> SKIP(["保留 pool 排序"]):::out
    CHK -- 否 --> RER["Reranker.rerank<br/>rerank_service.py:41<br/>gte-rerank-v2 · top_n=min(topk*2,len)"]:::rr
    RER --> OK["精排结果<br/>(原始索引,分数)"]:::out
    RER -. "失败/欠费" .-> DEG["降级: 回退 RRF 排序<br/>degraded('rerank')<br/>DEGRADED 指标可见"]:::warn
    DEG --> OK

flowchart TD
    classDef in fill:#e3f2fd,stroke:#1976d2
    classDef filter fill:#fff8e1,stroke:#f9a825
    classDef mmr fill:#ede7f6,stroke:#6a1b9a
    classDef parent fill:#fce4ec,stroke:#c62828
    classDef out fill:#e8f5e9,stroke:#2e7d32

    P([rerank pool]):::in
    P --> DOC["查 Document 表<br/>retrieval_service.py:302<br/>select id,doc_type,equipment_tags,<br/>tenant_id,dept,allowed_roles"]:::filter
    DOC --> ACL{"_acl_ok :159<br/>tenant / docType / equipment<br/>dept+allowed_roles(RBAC ACL)"}:::filter
    ACL -- 拒 --> DROP((丢弃)):::filter
    ACL -- 过 --> CMP["docType 无条件补全 :324<br/>(来源卡片展示)"]:::filter

    CMP --> MQ{"len(pool) &gt; topk?"}:::mmr
    MQ -- 是 --> MM["MMR 多样性<br/>mmr.py:18<br/>λ=0.5(相关性 vs 多样性)<br/>jieba Jaccard 相似度<br/>score=λ*rel-(1-λ)*max_sim"]:::mmr
    MQ -- 否 --> SB
    MM --> SB{"SMALL_TO_BIG_ENABLE?"}:::parent
    SB -- 是 --> PC["_expand_parents<br/>子块聚合同组父块全文<br/>给 LLM 完整上下文"]:::parent
    SB -- 否 --> GOV
    PC --> GOV["知识治理硬门禁<br/>knowledge_governance<br/>blocked_document_ids<br/>(撤回/过期 fail-closed)"]:::filter
    GOV --> OUT([contexts → 生成]):::out

flowchart LR
    classDef q fill:#e3f2fd,stroke:#1976d2
    classDef kg fill:#f3e5f5,stroke:#7b1fa2
    classDef store fill:#e8f5e9,stroke:#2e7d32
    classDef llm fill:#ede7f6,stroke:#6a1b9a

    Q([nq 原问题]):::q
    Q --> GC["kg_service.graph_context<br/>qa_service.py:351"]:::kg
    GC --> JB["jieba 抽关键词"]:::kg
    JB --> CYP["neo4j_client.query_triples_by_keywords<br/>UNWIND words<br/>MATCH (n:Entity)-[r:REL]-(m:Entity)<br/>WHERE n.name CONTAINS w"]:::store

    CYP --> OK{"Neo4j 可用?"}:::store
    OK -- 是 --> TXT["文本化为<br/>['s --rel--> o', ...]<br/>topk=8"]:::kg
    OK -- 否/降级 --> FB["回退 MySQL KgTriple 表<br/>kg_service.py:296"]:::store
    FB --> TXT

    TXT --> PROMPT["与文档 contexts 并列<br/>进 prompt【知识图谱】段<br/>build_messages_with_history"]:::llm

    Q -. 多跳影响链 .-> PATH["get_paths<br/>MATCH path=(n)-[:REL*1..5]->(m)<br/>depth=3 限1-5"]:::store
    Q -. 枢纽实体 .-> HUB["get_hubs<br/>出度排行找核心设备"]:::store

flowchart TD
    classDef q fill:#e3f2fd,stroke:#1976d2
    classDef l1 fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef l2 fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    classDef l15 fill:#fce4ec,stroke:#c62828,stroke-width:2px
    classDef gate fill:#e8f5e9,stroke:#2e7d32
    classDef write fill:#ede7f6,stroke:#6a1b9a

    Q([单轮 query]):::q
    Q --> KV["_cache_key<br/>qa:{tenant}:{model}:{normalized}"]:::q
    KV --> GATE{"_cache_knowledge_valid<br/>qa_service.py:41<br/>复核 doc租户归属 +<br/>治理 blocked_ids(fail-closed)"}:::gate

    GATE --> L1["① L1 Redis<br/>cache_get_json<br/>redis_client.py:19<br/>TTL=259200(3天) maxmemory=300mb"]:::l1
    L1 -- 命中 1ms --> HIT([秒回 cacheLayer=redis]):::l1
    L1 -- miss --> L2["② L2 MySQL qa_cache<br/>cache_get_mysql<br/>cache_persist.py:25<br/>MD5 hash + expires_at>now<br/>分层TTL: 手册7d/案例3d/实时5min"]:::l2
    L2 -- 命中 1-50ms --> HIT2([秒回 cacheLayer=mysql<br/>异步 backfill Redis]):::l2
    L2 -- miss --> L15["③ L1.5 Semantic Cache<br/>semantic_cache_get<br/>semantic_cache.py:61<br/>embed + fp16余弦<br/>≥0.92 high / ≥0.85 medium"]:::l15
    L15 -- 命中 --> HIT3([返回 cacheLayer=semantic]):::l15
    L15 -- miss --> MISS([→ 进入检索/生成]):::l15

    MISS -. 生成后写回 .-> W{"confidence==high<br/>&& !blacklisted?"}:::write
    W -- 是 --> W2["Write-Through 双写<br/>qa_service.py:412<br/>① MySQL 先写(持久优先)<br/>② Redis 后写 TTL=3天<br/>③ Semantic 索引异步"]:::write
    W -- medium/refused --> NO([不进缓存<br/>→ 证据缺口收集]):::l15

flowchart TD
    classDef in fill:#e3f2fd,stroke:#1976d2
    classDef grade fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    classDef correct fill:#e8f5e9,stroke:#2e7d32
    classDef amb fill:#fff3e0,stroke:#ef6c00
    classDef refuse fill:#ffebee,stroke:#c62828,stroke-width:2px

    CTX([rerank 后 contexts<br/>top1_score]):::in
    CTX --> V{"CRAG 版本?"}:::grade
    V -- "CRAG_PERDOC_ENABLE" --> V2["v2 LLM 逐条评估<br/>crag_v2.grade_with_llm<br/>relevant/partial/irrelevant<br/>timeout=5s"]:::grade
    V -- "v1(默认)" --> G["grade(top1, n, rerank_ok)<br/>crag.py:21<br/>复用 rerank 分不调 LLM"]:::grade
    V2 -. 失败/空 .-> G

    G --> C0{"rerank_ok?"}:::grade
    C0 -- 否 --> AMB((ambiguous 保守)):::amb
    C0 -- 是 --> C1{"top1 ≥ 0.6?"}:::grade
    C1 -- 是 --> COR((correct)):::correct
    C1 -- 否 --> C2{"top1 &lt; 0.3?"}:::grade
    C2 -- 是 --> INC((incorrect)):::refuse
    C2 -- 中间0.3-0.6 --> AMB

    COR --> CH["confidence=high<br/>正常作答"]:::correct
    AMB --> AW{"邻域扩展?"}:::amb
    AW -- 是 --> EX["_expand_neighbors ±1 chunk<br/>max_add=4<br/>同文档相邻补全"]:::amb
    AW -- 否 --> AMH["confidence=medium<br/>prompt 追加'标注不确定'"]:::amb

    INC --> RW["rewrite_query force=True<br/>绕过开关强制改写"]:::refuse
    RW --> RE["mixed_search 重检索"]:::refuse
    RE --> RG["再分级"]:::grade
    RG -- 仍 incorrect --> RF["confidence=refused<br/>保守拒答(零幻觉)<br/>→ evidence_gap collect"]:::refuse
    RG -- 改善 --> COR

flowchart LR
    classDef trig fill:#ffebee,stroke:#c62828
    classDef state fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    classDef ai fill:#ede7f6,stroke:#6a1b9a
    classDef sync fill:#e8f5e9,stroke:#2e7d32

    TRIG["触发: confidence∈{medium,refused}<br/>EVIDENCE_GAP_AUTO_COLLECT<br/>qa_service.py:454<br/>asyncio.create_task(collect)"]:::trig

    TRIG --> P((pending)):::state
    P -- "deep_draft_stream<br/>evidence_gap_service.py:121<br/>agent_runtime + qa persona<br/>多轮工具交叉验证<br/>SSE: meta→tool_step→token→done" --> AI((ai_drafted)):::ai
    AI -- "edit_answer(人工修正)<br/>:212" --> C((confirmed)):::state
    C -- "confirm_and_sync :228" --> SYNC["① MinIO 上传 faq/{doc_id}.md<br/>② 建 Document(doc_type=证据补全FAQ)+Chunk<br/>③ vectorize_document 写 Milvus<br/>④ cache 双写(confidence=high)"]:::sync
    SYNC --> S((synced)):::sync

    CRON["定时 deep_cron_loop<br/>main.py:175<br/>周期 EVIDENCE_GAP_DEEP_INTERVAL=180s<br/>批量 EVIDENCE_GAP_DEEP_BATCH=5<br/>operator=auto-deep-sync ✅自动"]:::trig
    CRON -. "batch_deep_and_sync<br/>串行防LLM限流" .-> AI

flowchart LR
    classDef code fill:#e3f2fd,stroke:#1976d2
    classDef redis fill:#ffebee,stroke:#c62828
    classDef mem fill:#fff8e1,stroke:#f9a825
    classDef inject fill:#fce4ec,stroke:#c62828

    ADMIN([admin 改 prompt]):::redis
    ADMIN --> UP["update_prompt_config<br/>config_service.py:88<br/>cache_set_json_persistent<br/>(无TTL永久存) + 刷新 _RUNTIME"]:::redis

    START([lifespan 启动]):::code
    START --> LD["load_runtime :16<br/>从 Redis 载 config:prompt<br/>→ 填 _RUNTIME 内存"]:::mem

    RT["rt_system_prompt :97<br/>sync getter 热路径<br/>零 Redis 往返"]:::mem
    LD --> RT
    UP --> RT

    RT --> GSP{"get_system_prompt<br/>prompt_templates.py:15"}:::code
    GSP -- "rt 非空" --> USE_RT([用运行时覆盖]):::redis
    GSP -- "rt 空" --> USE_CODE([回落 SYSTEM_PROMPT<br/>7条规则 :3]):::code

    USE_RT --> BUILD["build_messages_with_history :38<br/>system + history + 参考资料 + 图谱 + 问题"]:::code
    USE_CODE --> BUILD

    BUILD --> INJ{"confidence?"}:::inject
    INJ -- medium --> INJ1["追加规则8: '标注不确定'"]:::inject
    INJ -- refused --> INJ2["追加: '优先回答无法确认'"]:::inject
    INJ1 --> LLM([→ LLM 生成]):::code
    INJ2 --> LLM

sequenceDiagram
    autonumber
    participant FE as 前端
    participant RT as /qa/answer/stream
    participant SA as stream_answer
    participant Cache as 三级缓存
    participant LLM as LLM provider

    FE->>RT: POST + JWT(限流 30/min)
    RT->>SA: StreamingResponse(SSE)

    alt 单轮缓存命中
        SA->>Cache: 查 L1/L2/L1.5
        Cache-->>SA: 命中
        SA-->>FE: meta(整答案 sources)
        SA-->>FE: token(整段)
        SA-->>FE: done(cached=true)
    else miss
        SA->>SA: guard + 路由 + mixed_search + CRAG + GraphRAG + build_messages
        SA-->>FE: meta(sources + conversationId)
        SA->>LLM: stream(messages, temp=rt_temperature)
        loop 逐 token(原生 delta 不切块)
            LLM-->>SA: chunk.delta.content
            SA-->>FE: token(打字机片段)
        end
        SA->>SA: 拼完整答案 + auto_cite 角标补全
        SA->>SA: save_message(user+assistant) + Write-Through 双写缓存
        SA-->>FE: data: [DONE]
    end

    Note over FE: done 后异步拉 /qa/faithfulness 真值覆盖幻觉率展示

flowchart TD
    classDef in fill:#e3f2fd,stroke:#1976d2
    classDef multi fill:#fff8e1,stroke:#f9a825
    classDef cache fill:#fff3e0,stroke:#ef6c00
    classDef llm fill:#ede7f6,stroke:#6a1b9a

    Q([追问 query + conversationId]):::in
    Q --> IS{"is_single = not conv_id?<br/>qa_service.py:211"}:::multi
    IS -- 单轮 --> CACHE([走完整三级缓存读+写]):::cache
    IS -- 多轮 --> HIST["get_messages 最近6条(3轮)<br/>_HISTORY_LIMIT=6"]:::multi

    HIST --> STD["_search_query_for_retrieve<br/>qa_service.py:182"]:::multi
    STD --> SR["rewrite_standalone<br/>消解代词'它'→具体设备<br/>仅用于检索,不改原问题"]:::multi
    SR --> CMP{"search_q == nq?"}:::cache
    CMP -- 是(原query完整) --> READ["只读 Redis 热点<br/>不写缓存"]:::cache
    CMP -- 否(已改写) --> NO([不读不写缓存]):::cache

    READ --> RET([→ 检索用 search_q]):::multi
    NO --> RET
    RET --> PROMPT["build_messages_with_history<br/>用 原问题nq + history 喂 LLM<br/>(不是 search_q)"]:::llm

flowchart LR
    classDef trig fill:#e3f2fd,stroke:#1976d2
    classDef judge fill:#ede7f6,stroke:#6a1b9a,stroke-width:2px
    classDef score fill:#fff8e1,stroke:#f9a825
    classDef store fill:#e8f5e9,stroke:#2e7d32

    DONE([stream done<br/>qa_service.py:449,829]):::trig
    DONE --> SMP{"should_sample?<br/>_SAMPLE_RATE=1.0<br/>(生产建议0.1)"}:::trig
    SMP -- 命中 --> ASYNC["asyncio.ensure_future<br/>eval_quality(异步不阻塞)"]:::trig

    ASYNC --> J1["judge_hallucination :10<br/>声明拆解→逐条核验<br/>faithfulness = 1-未支撑/总<br/>(不信模型自报)"]:::judge
    ASYNC --> J2["judge_context_relevance :61<br/>per-chunk relevant/partial/irrelevant<br/>relevance_score 0-1"]:::judge
    ASYNC --> J3["judge_answerability :117<br/>answerable + confidence<br/>+ missing_info"]:::judge
    ASYNC --> J4["_judge_completeness :103<br/>1=完全/0.7主要/0.4部分/0无关"]:::judge

    J1 --> SC
    J2 --> SC
    J4 --> SC
    SC["综合分 overall<br/>online_eval_service.py:73<br/>= relevance×0.3<br/>+ faithfulness×0.4<br/>+ completeness×0.3"]:::score
    SC --> LOG["落 operation_logs<br/>operate_type=online_eval"]:::store
    LOG --> TREND["get_quality_trends<br/>质量趋势面板"]:::store

    DONE -. 前端异步 .-> API["POST /qa/faithfulness<br/>qa.py:220<br/>覆盖粗糙启发式展示"]:::judge

flowchart LR
    classDef heavy fill:#ffebee,stroke:#c62828
    classDef write fill:#fff3e0,stroke:#ef6c00
    classDef normal fill:#e3f2fd,stroke:#1976d2
    classDef light fill:#e8f5e9,stroke:#2e7d32

    REQ([请求]):::normal
    REQ --> LIM["slowapi Limiter<br/>key=get_remote_address<br/>core/limiter.py:8"]:::normal
    LIM --> CHK{"@limiter.limit"}:::normal
    CHK -- "检索调参 /system/retrieval/tune" --> H1["1/min 最严<br/>(参数扫描极重)"]:::heavy
    CHK -- "BM25重建 /bm25/rebuild" --> H2["3/min"]:::heavy
    CHK -- "图谱抽取 /kg/extract" --> H3["5/min"]:::heavy
    CHK -- "多Agent辩论 /diagnose-debate" --> H4["4/min"]:::heavy
    CHK -- "诊断Agent /diagnose-agent" --> H5["6/min"]:::heavy
    CHK -- "文档 上传/解析/向量化" --> W1["10/min"]:::write
    CHK -- "问答 /qa/answer(stream)" --> N1["30/min"]:::normal
    CHK -- "反馈 /qa/feedback" --> L1["60/min 最高<br/>(轻量)"]:::light

flowchart LR
    classDef hook fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    classDef plugin fill:#ede7f6,stroke:#6a1b9a
    classDef main fill:#e3f2fd,stroke:#1976d2

    IN([body.query]):::main
    IN --> H1["hook: query_preprocess<br/>qa.py:45"]:::hook
    H1 --> P1["length_guard<br/>plugin_registry.py:84<br/>len>500 截断"]:::plugin
    P1 --> CORE(["qa_service.answer / 双RAG<br/>检索+增强+生成"]):::main
    CORE --> H2["hook: retrieval_filter<br/>(预留扩展点)"]:::hook
    H2 --> H3["hook: answer_postprocess<br/>qa.py:62"]:::hook
    H3 --> P3["safety_banner :74<br/>含'停电/接地/倒闸/带电/放电'等<br/>→ 追加⚠安全提示<br/>(已有则不重复)"]:::plugin
    P3 --> OUT([返回答案]):::main

    H1 -. "插件异常" .-> DEG["degraded('plugin_*')<br/>不中断主链路"]:::plugin
    H3 -. "插件异常" .-> DEG

flowchart TD
    classDef in fill:#e3f2fd,stroke:#1976d2
    classDef main fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef sec fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef warn fill:#ffebee,stroke:#c62828

    REQ([POST /qa/answer]):::in
    REQ --> SW{"DUAL_RAG_ENABLE?<br/>(opt-in 默认关<br/>不在 config,getattr)"}:::in
    SW -- 否 --> DIRECT["直接 qa_service.answer"]:::main
    SW -- 是 --> AR["answer_redundant<br/>rag_router.py:35"]:::main

    AR --> TRY{"TRY 主路<br/>qa_service.answer"}:::main
    TRY -- 成功 --> OK([返回主路结果]):::main

    TRY -- "任意异常<br/>(Milvus挂/embed失败)" --> EXC["EXCEPT<br/>degraded('rag_failover_to_secondary')"]:::warn
    EXC --> SEC["_secondary_bm25_llm<br/>rag_router.py:47<br/>① bm25 ensure_built+search topk=8<br/>② build_messages + llm.chat<br/>(只依赖 MySQL)"]:::sec
    SEC --> SECO([返回 failover=True<br/>framework=secondary_bm25_llm]):::sec

    HEALTH["GET /system/rag/health<br/>system.py:979<br/>探 milvus num_entities<br/>n≥0 = available"]:::in
    HEALTH -. "运维查看" .-> TRY

flowchart LR
    classDef src fill:#ffebee,stroke:#c62828
    classDef cluster fill:#fff8e1,stroke:#f9a825
    classDef blind fill:#fff3e0,stroke:#ef6c00
    classDef ai fill:#ede7f6,stroke:#6a1b9a
    classDef review fill:#e3f2fd,stroke:#1976d2
    classDef sync fill:#e8f5e9,stroke:#2e7d32

    SRC["数据源: dislike 反馈<br/>+ EvidenceGap medium/refused"]:::src
    SRC --> CL["cluster<br/>knowledge_evolution_service.py:46<br/>零依赖贪心近邻聚类<br/>threshold=0.82, min_size=3<br/>选最接近centroid的query当代表"]:::cluster
    CL --> EM["embed 代表 query"]:::cluster
    EM --> BL["Milvus 盲区识别<br/>top1 &lt; BLIND_TOP1_THRESHOLD=0.55<br/>→ 判为知识盲区"]:::blind
    BL -- 是盲区 --> GEN["_generate_draft :131<br/>LLM + 最近规程上下文<br/>生成 FAQ 草稿"]:::ai
    GEN --> D((draft)):::review

    D -- review_draft approve --> A((approved)):::review
    A --> RF["reflow_to_kb :300<br/>① 检查每周配额 ≤20<br/>② 写 Milvus doc_type=ai_evolution<br/>③ quality_score=0.6 降权"]:::sync
    RF --> I((indexed)):::sync
    D -- reject --> REJ((rejected)):::review
    I -- withdraw_draft --> WD["按 Milvus pk 删单条向量<br/>(AI草稿共享doc_id<br/>不能用delete_by_doc)"]:::sync
    WD --> WD2((withdrawn)):::review

    CRON["evolution_cron_loop<br/>main.py:168<br/>KNOWLEDGE_EVOLUTION_CRON_HOURS=24"]:::src
    CRON -. "enqueue_evolution_scan<br/>idempotency_key 5min" .-> CL

flowchart TD
    classDef persona fill:#fff8e1,stroke:#f9a825
    classDef engine fill:#ede7f6,stroke:#6a1b9a,stroke-width:2px
    classDef tool fill:#e3f2fd,stroke:#1976d2
    classDef out fill:#e8f5e9,stroke:#2e7d32

    subgraph PERSONAS["Persona(agent_personas.py)"]
        P1["DIAGNOSE_PERSONA<br/>max_iter=6<br/>诊断工具子集"]:::persona
        P2["QA_PERSONA<br/>问答工具子集"]:::persona
        P3["ALERT_PERSONA<br/>告警处置工具子集"]:::persona
    end

    P1 & P2 & P3 --> RA["run_agent<br/>agent_runtime.py:179<br/>ReAct 循环: LLM决策→调工具→观察→再决策"]:::engine

    RA --> TR["ToolRegistry.run :62<br/>① per-tool 异常隔离(不中断)<br/>② 权限校验<br/>③ 审计留痕"]:::tool
    TR --> TOOLS["DEFAULT_REGISTRY<br/>agent_tools.py<br/>检索/图谱/案例/两票工具"]:::tool

    RA -->|"超 max_iter / 异常"| FB["_fallback :277<br/>调 persona.fallback<br/>degraded(...) 全记指标"]:::out
    TR --> RES["AgentResult<br/>(结构化输出)"]:::out

    DA["diagnose_agent_service.py:11<br/>适配层<br/>run_agent(DIAGNOSE_PERSONA)"]:::persona
    DA -. 映射既有schema .-> RA

flowchart LR
    classDef src fill:#ffebee,stroke:#c62828
    classDef metric fill:#fff8e1,stroke:#f9a825
    classDef panel fill:#e3f2fd,stroke:#1976d2
    classDef health fill:#e8f5e9,stroke:#2e7d32

    subgraph SRC["埋点源 ~30 指标(metrics.py)"]
        DEG["DEGRADED{tag} :63<br/>(rerank/neo4j/cache挂)"]:::src
        CH["COMPONENT_HEALTH{component} :69<br/>1=up/0=down"]:::src
        CRAG["CRAG_GRADE/ACTION/CONFIDENCE :65"]:::src
        CACHE["CACHE_HIT/FAIL :89-92"]:::src
        AGENT["AGENT_TOOL_CALLS :83"]:::src
        RT["ROUTING_DECISION :98"]:::src
    end

    SRC --> OBS["obs.degraded(tag, exc) :18<br/>193处统一入口<br/>except→计数+warning"]:::metric
    SRC --> MTRACE["metrics_loop 30s<br/>main.py:123"]:::metric
    OBS -.-> CH
    CH --> PROBE["_refresh_component_health_loop 30s<br/>main.py:294<br/>后台探活 DB/MinIO/Milvus/Redis<br/>→ 同步 Gauge"]:::health
    PROBE --> ENDPOINT["/metrics(Prometheus 抓取)<br/>/health(配置态快照) :308"]:::health
    ENDPOINT2["/health/providers :198<br/>admin 主动 ping LLM+embed<br/>(消耗少量token 抓欠费/配额)"]:::health

    ENDPOINT --> PROM["Prometheus :9090"]:::panel
    PROM --> GRAFANA["Grafana :3000<br/>22面板 + cache-monitor + agent-monitor"]:::panel

flowchart LR
    classDef trig fill:#fff8e1,stroke:#f9a825
    classDef dump fill:#e3f2fd,stroke:#1976d2
    classDef safe fill:#ffebee,stroke:#c62828
    classDef out fill:#e8f5e9,stroke:#2e7d32

    T1([手动 /backup<br/>system.py:829 admin]):::trig
    T2([backup_all_loop<br/>main.py:150 每3h]):::trig

    T1 & T2 --> BA["backup_all :262<br/>三合一 + manifest"]:::dump
    BA --> BM["backup_mysql :56<br/>SHOW CREATE TABLE<br/>+ INSERT _sql_val转义<br/>(NULL/bytes/int/str)"]:::dump
    BA --> BR["backup_redis :108"]:::dump
    BA --> BMI["backup_milvus :190"]:::dump
    BM & BR & BMI --> FILE["data/backups/{ts}.sql/.json<br/>_safe_filename :41<br/>拒 ../  防穿越"]:::safe

    FILE -- restore_all :284 --> RS["按顺序 Milvus→MySQL→Redis<br/>(drop重建最重先做)"]:::out

flowchart LR
    classDef loop fill:#fff8e1,stroke:#f9a825
    classDef export fill:#e3f2fd,stroke:#1976d2
    classDef del fill:#ffebee,stroke:#c62828

    LOOP["archive_loop 每24h<br/>main.py:143<br/>LOG_ARCHIVE_DAYS=90"]:::loop
    LOOP --> AO["archive_old_logs :70"]:::export
    AO --> Q1["① 查 operate_time &lt; cutoff"]:::export
    Q1 --> Q2["② 写 data/log_archive/logs_{ts}.jsonl<br/>(id/user/type/content/time)"]:::export
    Q2 --> Q3["③ 按主键 IN 批量 DELETE<br/>(删除前文件已落盘)"]:::del
    Q3 --> PERS["落 backend 持久卷 /app/data<br/>容器重建不丢"]:::export

    AO -. 失败 .-> DEG["degraded('log_archive')<br/>不中断"]:::del
    STATS["archive_stats :46<br/>pendingArchive 超期待归档数<br/>手动触发 /logs/archive"]:::loop

flowchart LR
    classDef src fill:#fff8e1,stroke:#f9a825
    classDef calc fill:#e3f2fd,stroke:#1976d2
    classDef out fill:#e8f5e9,stroke:#2e7d32

    SRC["operation_logs<br/>operate_type=告警"]:::src
    SRC --> PAR["_parse_alert :27<br/>_ALERT_RE 正则<br/>抽 [critical] 标题：..."]:::src
    PAR --> AGG["按标题聚合频次<br/>近7天 vs 上7天判趋势"]:::calc
    AGG --> SC["predict :56<br/>score = count × severity_weight<br/>+ (上升?2:0)"]:::calc
    SC --> JOIN["join tickets 总数<br/>+ feedbacks dislike 数<br/>(风险语境上下文)"]:::calc
    JOIN --> LV["_risk_level :41<br/>高/中/低"]:::out
    LV --> OUT["按风险降序 Top20<br/>+ _suggestion 处置建议<br/>GET /fault-prediction"]:::out

flowchart TD
    classDef admin fill:#fff8e1,stroke:#f9a825
    classDef guard fill:#ffebee,stroke:#c62828,stroke-width:2px
    classDef self fill:#e3f2fd,stroke:#1976d2
    classDef ok fill:#e8f5e9,stroke:#2e7d32

    OP([admin 操作]):::admin
    OP --> G1{"user_id == actor_id?<br/>(不能操作自己)"}:::guard
    G1 -- 是 --> BLK((403 拒绝)):::guard
    G1 -- 否 --> G2{"是 admin 且<br/>active数 ≤1?<br/>_count_active_admins :87"}:::guard
    G2 -- 是 --> BLK2((拒绝<br/>不能动最后admin)):::guard
    G2 -- 否 --> OK([允许]):::ok

    OP2([用户自助]):::self
    OP2 --> CP["change_password :157<br/>verify_password 校验旧密码"]:::self
    OP2 --> UP["update_profile :146<br/>只能改 dept(影响ACL)<br/>角色/租户由admin管"]:::self

    ADMINR["update_user_role :71<br/>role in VALID_ROLES<br/>4角色外拒绝"]:::admin

flowchart LR
    classDef mysql fill:#fff8e1,stroke:#f9a825
    classDef milvus fill:#ede7f6,stroke:#6a1b9a
    classDef neo4j fill:#fce4ec,stroke:#c62828
    classDef redis fill:#ffebee,stroke:#e91e63
    classDef minio fill:#e3f2fd,stroke:#1976d2

    MYSQL[("MySQL 8 :3307<br/>结构化元数据<br/>user/document/chunks(父子)<br/>conversation/feedback/kg_triple<br/>★qa_cache L2冷备<br/>operation_logs/evidence_gap<br/>knowledge_evolution_draft")]:::mysql

    MILVUS[("Milvus 2.4 :19530<br/>双 collection 向量<br/>grid_chunks(云1024d)<br/>grid_chunks_bge(bge512d)<br/>HNSW M=16/efC=200/COSINE")]:::milvus

    NEO4J[("Neo4j 5 :7687<br/>知识图谱<br/>:Entity{name,type}<br/>-[:REL{type,doc_id}]-><br/>设备-故障-处置多跳")]:::neo4j

    REDIS[("Redis 7 :6379<br/>★三级缓存 L1<br/>热点问答(TTL3天 maxmem300mb)<br/>+ L1.5 Semantic 索引<br/>+ query向量缓存<br/>+ 运行时配置(config:prompt<br/>无TTL永久)")]:::redis

    MINIO[("MinIO :9000<br/>原文对象存储<br/>上传源文档<br/>+ faq/ AI补全FAQ")]:::minio

    BE([FastAPI backend])
    BE --> MYSQL & MILVUS & NEO4J & REDIS & MINIO

cp .env.example .env          # 填三家 API Key
docker compose up -d          # 全栈(首次拉镜像+构建)

# 基础设施
docker compose up -d mysql minio redis milvus neo4j

# 后端
python -m venv venv && source venv/Scripts/activate   # Windows Git Bash
pip install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
uvicorn app.main:app --reload --host 127.0.0.1 --port 8001 --app-dir backend

# 前端
npm --prefix frontend install --registry https://registry.npmmirror.com
npm --prefix frontend run dev

cp .env.example .env && docker compose up -d --build   # 11 服务

bash scripts/pack_release.sh          # 本地打包(含数据+bge缓存)
# 接收方:
tar -xzf grid-qa-release-*.tar.gz && cd grid-qa-release-*
cp .env.template .env && vim .env     # 填 API Key
./install.sh up                       # 一键(含 grid_qa.sql 自动导入)

gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8001 --app-dir backend