# wangle1218/kbqa-for-diagnosis architecture

> Architecture diagram of the GitHub repository wangle1218/kbqa-for-diagnosis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wangle1218/kbqa-for-diagnosis
- Repository: https://github.com/wangle1218/kbqa-for-diagnosis

## Overview

##### Project Type and Purpose
- This project is a full-stack NLP/Q&A system focused on medical diagnosis. It integrates multiple NLP components (intent recognition, slot filling, entity normalization, knowledge extraction) with a knowledge graph (Neo4j) to answer diagnosis-related questions. The WeChat demo is implemented using itchat to offer a conversational interface.

##### File Structure for Architectural Clues
- Top-level directories show distinct responsibilities:
- “build_kg”: Scripts/utilities to construct or update the knowledge graph.
- “entity_normalization”: Handles entity disambiguation and BM25-based retrieval.
- “faiss_index”: Contains scripts that use FAISS (and BERT-based models) to compute vector similarities (likely for entity/semantic matching).
- “knowledge_extraction”: Includes several approaches (CasRel, bilstm_crf, and bert-deploy) meant for relation extraction and possibly general knowledge extraction from text.
- “nlu”: Contains two separate modules:
▪ “bert_intent_recognition” – Uses BERT for intent recognition.
▪ “sklearn_Classification” – Uses classical ML techniques for classification.
Also present is “slotgate_slu” which is responsible for slot filling.
- “itchat_app.py”: The entry point that integrates with WeChat via itchat to receive user messages.
- “config.py”, “modules.py”, “doc”, etc., which support configuration, documentation, and extra functionalities.
- You also see several bat scripts (e.g., run_intent_recog_service.bat, run_ner_service.bat) which spin up individual NLP sub-services.

##### README for Additional Insights
- The README highlights that the demonstration leverages wechat (via itchat) for Q&A.
- Neo4j is explicitly mentioned as the graph DB to be started for the knowledge graph backend.
- There’s an explanation for setting up the intent recognition and slot filling services.

a. Main Components to Represent:
- User Interface Layer: The WeChat-based interface accessed via itchat (through itchat_app.py).
- NLP / NLU Components:
▪ Intent Recognition: Both BERT-based (in nlu/bert_intent_recognition) and sklearn-based pipelines (in nlu/sklearn_Classification).
▪ Slot Filling/SLU: Located in nlu/slotgate_slu.
- Entity & Knowledge Processing:
▪ Entity Normalization: (entity_normalization folder, which includes BM25 and other helper scripts).
▪ Knowledge Extraction: Multiple approaches available (CasRel, bilstm_crf, and components under knowledge_extraction/bert-deploy).
▪ Faiss-based Semantic Indexing: (faiss_index folder, with components that manage similarity-based search using BERT).
- Knowledge Graph Backend:
▪ Neo4j Database: The central graph DB that houses the medical diagnosis knowledge graph.
- Knowledge Graph Building Utility:
▪ build_kg: Scripts that may be used to construct or refresh the knowledge graph using external data.
- Supporting Components:
▪ Utility scripts and configuration files that allow orchestration of the individual services.

b. Relationships and Interactions:
- User inputs a query via WeChat. The itchat_app.py receives and forwards the query.
- The query goes through the NLP chain:
▪ The request is processed by the Intent Recognition service (BERT-based and/or the sklearn classifier) to determine the user's intent.
▪ Meanwhile, the slot filling module (slotgate_slu) extracts relevant slots (like disease names, symptoms).
▪ The normalized entities are further processed by the entity_normalization module using methods like BM25 retrieval.
▪ If needed, the question can also be passed through one of the knowledge extraction pipelines (CasRel, bilstm_crf, or the BERT deploy module) to extract relations and answer the question.
▪ The FAISS-based module may assist in searching for additional semantically similar information.
- After processing, the system queries the Neo4j graph (which was constructed by build_kg and updated based on inputs) to retrieve medical diagnosis information.
- Finally, the system compiles an answer and sends the response back via the itchat interface.

c. Architectural Patterns and Design Principles:
- Modular design: Each functionality is encapsulated in its module or sub-service.
- Pipeline pattern: The query flows from front-end to NLP (intent recognition and slot filling) to entity normalization and finally to the knowledge graph query, before returning an answer.
- Loose coupling: Scripts and services are independently started (e.g., via bat files) and communicate through clearly defined APIs or file-based interactions (like JSON read/writes).

d. Relevant Technologies & Frameworks in Context:
- Python and its ecosystem (TensorFlow, Keras, bert4keras, scikit-learn, etc.) for model implementations.
- itchat (for WeChat integration).
- Neo4j (graph database) for storing and querying the knowledge graph.
- FAISS (for efficient vector similarity search).
- Flask is referenced in some subcomponents, potentially used for exposing lightweight HTTP services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User"]:::frontend
    W["WeChat Interface (Itchat)"]:::frontend

    subgraph "Intent Recognition Services"
        BERT["Intent Recognition (BERT-based)"]:::nlp
        SKL["Intent Recognition (Sklearn-based)"]:::nlp
    end

    SLOT["Slot Filling Module"]:::nlp
    ENTITY["Entity Normalization (BM25 Retrieval)"]:::nlp

    subgraph "Knowledge Extraction"
        CASREL["Knowledge Extraction (CasRel)"]:::extraction
        EXBERT["Knowledge Extraction (BERT Deploy)"]:::extraction
        BLSTM["Knowledge Extraction (BiLSTM-CRF)"]:::extraction
    end

    FAISS["FAISS Semantic Indexing"]:::nlp
    KG["Knowledge Graph (Neo4j)"]:::db
    Builder["Knowledge Graph Builder"]:::utility

    U --> W
    W --> BERT
    W --> SKL
    BERT --> SLOT
    SKL --> SLOT
    SLOT --> ENTITY
    ENTITY --> CASREL
    ENTITY --> EXBERT
    ENTITY --> BLSTM
    ENTITY --> FAISS
    CASREL --> KG
    EXBERT --> KG
    BLSTM --> KG
    FAISS --> KG
    KG --> W
    W --> U
    Builder --> KG

    click W "https://github.com/wangle1218/kbqa-for-diagnosis/blob/main/itchat_app.py"
    click BERT "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/nlu/bert_intent_recognition"
    click SKL "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/nlu/sklearn_Classification"
    click SLOT "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/nlu/slotgate_slu"
    click ENTITY "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/entity_normalization"
    click CASREL "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/knowledge_extraction/CasRel"
    click EXBERT "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/knowledge_extraction/bert-deploy"
    click BLSTM "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/knowledge_extraction/bilstm_crf"
    click FAISS "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/faiss_index"
    click Builder "https://github.com/wangle1218/kbqa-for-diagnosis/tree/main/build_kg"

    classDef frontend fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef nlp fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef extraction fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef db fill:#FFAB91,stroke:#333,stroke-width:2px;
    classDef utility fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
