Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
213 lines (170 loc) · 7.28 KB

ARCHITECTURE.md

File metadata and controls

213 lines (170 loc) · 7.28 KB

系统架构说明

1. 分层架构

flowchart TB
    subgraph 表现层 Presentation
        WEB[web/ React + Vite]
        GR[app.py Gradio]
    end
    subgraph 网关层 Gateway
        API[server/ FastAPI]
    end
    subgraph 领域层 Domain
        QA[qa_engine/]
        KB[KBQA/ 遗留]
        GRAG[graphrag/ 遗留]
    end
    subgraph 数据层 Data
        NEO[(Neo4j)]
        DICT[dict/]
        JSON[data/]
    end
    subgraph 基础设施 Infra
        LLM[LLM Provider]
        LS[LangSmith 可选]
    end
    WEB --> API
    GR --> QA
    API --> QA
    API --> KB
    QA --> NEO
    QA --> GRAG
    QA --> LLM
    QA --> DICT
    QA -.-> LS
    KB --> NEO
Loading
层 目录 职责
表现层 web/, app.py 用户交互、流式展示、图谱可视化
网关层 server/ REST/SSE、CORS、静态资源挂载
领域层 qa_engine/ 问答编排、路由、降级、流式事件
数据层 Neo4j + dict/ + data/ 图谱存储与离线实体表
基础设施 settings.py, .env 配置、LLM、追踪

2. 数据全链路

flowchart LR
    S1[data_spider/ 采集<br/>（已固化数据）] --> S2[JSON 结构化]
    S2 --> S3[knowledge_graph/main.py]
    S3 --> S4[(Neo4j 4.4万节点<br/>约30万关系)]
    S4 --> S5[qa_engine 查询/子图检索]
    S5 --> S6[LLM 生成或模板格式化]
    S6 --> S7[FastAPI SSE]
    S7 --> S8[React 答案+调试+图谱]
Loading

离线词典 dict/*.txt 供 Level 3 降级与实体模糊匹配使用。

3. qa_engine LangGraph 工作流

3.1 状态 QAState（qa_engine/state.py）

字段 用途
question 用户原始问题
intent, entities, normalized_entities 模板路径语义与实体
cypher, raw_results, answer Cypher 生成与执行结果
analysis_level 降级等级 1/2/3
route template / graphrag / template_to_graphrag / llm_fallback / graphrag_to_llm / template_to_graphrag_to_llm（前端 Badge 展示流转路径）
rag_entities, subgraph, context, rag_answer GraphRAG 路径
error, no_results 错误与空结果标记
template_no_result 模板路径查询无结果时触发 GraphRAG 回退
graph_data 前端可视化图谱数据，{nodes, edges}
chat_history 多轮对话历史，[{role, content}, ...]

3.2 节点一览

节点 ID 模块 功能
1. 分析问题 nodes/analysis.py 三级降级：LLM 全分析 → 部分 LLM → 词典 NER
2. 路由判断 nodes/route.py 写入 route，供条件边选择
T1–T4 nodes/normalize.py, template_path.py 归一化 → Cypher → 查询 → 格式化（T1/T2 失败自动设 template_no_result 回退 G）
G1–G5 nodes/graphrag_path.py 实体抽取 → 归一化 → 子图 → 上下文 → LLM 回答（G5 成功时写 route）
X. 错误处理 nodes/error_handler.py 三级兜底：错误分类提示 → LLM 直接回答 → 静态提示文本

3.3 条件边

条件函数 step_outcome / select_route_or_error / select_query_outcome 返回 success | error | template | graphrag | template_fallback（不再使用 True/False，避免导出图误解）。

完整分支图见 docs/assets/workflow.png（源码：qa_engine/workflow_diagram.py）。

step_outcome：存在 state.error 或 no_results → error，否则 → success。
select_route_or_error：route 为 template / graphrag，否则 → error。
select_query_outcome（T3 之后）：template_no_result == True → template_fallback（跳转到 G1 GraphRAG 路径），error / no_results → error，否则 → success。

错误处理节点的三级兜底策略（handle_error）：

优先级 条件 行为
1 系统级硬错误（LLM/Cypher/Neo4j） 返回分类错误提示
2 可恢复错误 / 无结果 / template_no_result 调用 LLM 直接回答，根据来源写 route（共4种流转标签）
3 LLM 不可用 返回静态兜底文本

前端路由标签（UnifiedChatPanel.tsx MODE_LABELS 6 种模式）：

route 值 Badge 文字 颜色
template 模板检索 绿
graphrag GraphRAG 蓝
template_to_graphrag 模板检索 → GraphRAG 蓝
llm_fallback AI 智能回答 靛蓝
graphrag_to_llm GraphRAG → AI 回答 靛蓝
template_to_graphrag_to_llm 模板检索 → GraphRAG → AI 回答 靛蓝

3.4 流式事件（qa_engine/stream.py）

event 载荷 前端处理
delta { chunk } 追加到助手气泡
done { answer, debug, graph_data, mode } 最终答案 + 侧栏
error { message } onError

4. API 端点（server/app.py）

方法 路径 说明
POST /api/chat 同步问答（消费 stream_qa 的 done，含 graph_data）
POST /api/chat/stream 推荐 SSE 流式，统一引擎；请求体可带 session_id
POST /api/graphrag/chat 同步（兼容，逻辑同 chat）
POST /api/graphrag/chat/stream 流式（兼容，同 chat/stream）
GET /api/graph/neighbors/{name} 节点邻居，供图谱点击展开
GET /api/health Neo4j / LLM / qa_engine 健康检查

SSE 流式响应示例（done）

{
  "answer": "...",
  "debug": { "analysis_level": 2, "route": "template", "intents": [...], ... },
  "graph_data": { "nodes": [...], "edges": [...] },
  "mode": "template",
  "session_id": "web-session"
}

LangGraph 工作流示意图

工作流

5. 前端组件树（web/src/）

App.tsx
├── UnifiedChatPanel.tsx      # 统一聊天 + streamChat
│   └── onResponse → debug / graphData / responseMode
└── Tabs
    ├── DebugPanel.tsx        # mode !== graphrag
    ├── GraphRAGDebugPanel.tsx # mode === graphrag
    └── GraphPanel.tsx        # react-force-graph-2d + fetchNeighbors

关键模块

文件 职责
api/client.ts streamChat、SSE 解析、fetchNeighbors
utils/debugNormalize.ts normalizeDebug：analysis_level → level
types/index.ts StreamDoneData、UnifiedMessage

前端技术栈与依赖（web/package.json）

依赖 版本 用途
React ^19.2 UI 框架
TypeScript ~5.9 类型检查
Vite ^8.0 构建工具
Tailwind CSS ^4.2 原子化 CSS
shadcn/ui ^4.1 UI 组件库（Badge/Card/Button/Input/Tabs/ScrollArea）
@base-ui/react ^1.3 shadcn/ui 底层 headless 组件
react-force-graph-2d ^1.29 力导向知识图谱可视化
lucide-react ^1.7 图标库
class-variance-authority ^0.7 组件变体管理
clsx + tailwind-merge ^2.1 / ^3.5 类名合并工具

6. 兼容入口关系

basic_qa.py  ──re-export──►  qa_engine/
server/app.py ──import──►    basic_qa.stream_qa / build_workflow
app.py        ──import──►    basic_qa.build_workflow

相关文档