# ibm/dualtkb architecture

> Architecture diagram of the GitHub repository ibm/dualtkb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/dualtkb
- Repository: https://github.com/ibm/dualtkb

## Overview

下面针对当前项目“DualTKB”——一个旨在在文本（Text）与知识库（Knowledge Base，KB）之间建立双向学习桥梁的研究型机器学习系统，给出如何绘制最准确、最清晰的系统设计图的详细指导。我们将分步骤说明，并结合项目的特殊性（仅含 README 文档，无实际代码目录）给出可落地的可视化建议。

##### 确定项目类型与目的
- 类型：研究性质的深度学习/双向迁移模型，重点在于“文本↔知识图谱路径”的无监督/弱监督双向转换。
- 目的：
1）从句子生成 KB 路径（Text → KB）
2）从 KB 路径生成句子（KB → Text）
3）通过自编码、互译、自循环翻译（back-translation）实现无监督训练

##### 从文件结构与 README 中提取关键信息
- 文件结构：仅有LICENSE和README.md，说明本仓库主要提供文档和模型概念，不含实际代码实现。
- README 内容：
- 模型整体架构为 Encoder–Decoder 形式
- 两种输入域（Domain A：文本；Domain B：图路径）
- 四种转换：同域自编码（A→A、B→B）、跨域互译（A→B、B→A）
- 训练分两阶段：翻译阶段（重建损失 L_REC + 有监督损失 L_SUP）和回译阶段（back-translation L_BT）
- 支持三种底层实现：GRU–GRU、BERT–GRU、Transformer–Transformer

##### 确定系统设计图的核心组件
a. 数据输入层
- 文本语料库（OMCS 原始句子）
- 知识库路径集合（ConceptNet 边）
b. 编码器（Encoder）
- 文本编码器（可选：GRU / BERT / Transformer）
- 路径编码器（可选：GRU / Transformer）
c. 公共潜在表示（Latent Space）
d. 解码器（Decoder）
- 文本解码器 Decoder A
- 路径解码器 Decoder B
e. 损失模块
- 重建损失 L_REC
- 有监督互译损失 L_SUP
- 回译损失 L_BT
f. 数据集与弱监督匹配流程（ConceptNet ↔ OMCS 模糊匹配）

##### 组件间关系与交互
- 文本输入 x_A → 文本编码器 → 潜在表示 z → Decoder A 重建为 x_AA (自编码)
- 文本输入 x_A → 文本编码器 → z → Decoder B 转换为路径 x_AB → 路径编码器 → z' → Decoder A 回译为 x_ABA (回译)
- 同理，路径输入 x_B 流向路径编码器、潜在表示、Decoder B/B→A/A→B，不断循环
- 在有监督数据对 (x_A, x_B) 情况下，直接计算 A→B、B→A 的有监督损失

##### 绘制图示的建议
1）布局
- 左侧放置“Domain A：文本域”，右侧放置“Domain B：图路径域”，中间为“共享潜空间”
2）符号与颜色
- 输入数据用文档图标（文本）和图谱节点-边图标（路径）
- 编码器/解码器用矩形框，不同颜色区分文本 vs. 路径 vs. 公共表示
- 损失函数用菱形或带标签的箭头标注（L_REC, L_SUP, L_BT）
3）箭头与标签
- 单向箭头表示数据流向；双向线可表示循环回译
- 每条关键转换箭头上方标注 T_AB、T_BA、T_AA、T_BB、T_ABA、T_BAB 等转换函数或损失名
- 说明颜色、形状对应关系
- 简要注释各阶段：1. 翻译阶段（L_REC + L_SUP） 2. 回译阶段（L_BT）

##### 针对该研究型模型的专属细节
- 在“共享潜空间”处可突出“高维向量表示 Embedding”
- 三种不同实现策略（GRU–GRU / BERT–GRU / Transformer–Transformer）可在编码器/解码器模块旁用标注或子图强调可插拔性
- 数据集预处理与弱匹配流程可在图外沿底部用流程箭头简述

##### 最终图示应包含
- 各组件清晰标签：Encoder A、Encoder B、Latent Space、Decoder A、Decoder B
- 箭头显示数据流与损失计算流向
- 颜色或形状区分三类：文本域组件 / 图路径域组件 / 公共组件
- 图例与分阶段注释，确保阅读者一目了然

总结：通过上述分层次、模块化的绘制思路，可将 DualTKB 的双向迁移、互译与回译三大核心流程，以及训练时的三类损失结构，一并直观地呈现在一张系统设计图中，充分捕捉项目的主要架构要素与交互关系。

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% 文档部分
    subgraph "文档"
        Read["README.md 文档"]:::doc
        Lic["LICENSE"]:::doc
    end

    %% 域与编码器/解码器
    subgraph "Domain A: 文本域" 
        TextIn["文本输入 x_A"]:::textdomain
        EncA["文本编码器 Encoder A\n(GRU/BERT/Transformer)"]:::textdomain
        DecA["文本解码器 Decoder A"]:::textdomain
    end

    subgraph "共享潜空间" 
        Latent["潜在表示 z\n(高维向量 Embedding)"]:::common
    end

    subgraph "Domain B: 图路径域" 
        PathIn["路径输入 x_B"]:::pathdomain
        EncB["路径编码器 Encoder B\n(GRU/Transformer)"]:::pathdomain
        DecB["路径解码器 Decoder B"]:::pathdomain
    end

    %% 预处理流程
    Preprocess["数据预处理 & 弱匹配流程\n(ConceptNet ↔ OMCS)"]:::preprocess

    %% 损失模块
    Lrec["L_REC\n重建损失"]:::loss
    Lsup["L_SUP\n有监督互译损失"]:::loss
    Lbt["L_BT\n回译损失"]:::loss

    %% 流程箭头
    TextIn -->|T_AA 自编码| EncA
    EncA -->|z| Latent
    Latent -->|T_AA| DecA
    DecA -->|重建 x_AA| Lrec

    TextIn -->|T_AB 跨域翻译| EncA
    EncA -->|z| Latent
    Latent -->|T_AB| DecB
    DecB -->|生成 x_AB| EncB
    EncB -->|z'| Latent
    Latent -->|T_BA 回译| DecA
    DecA -->|回译 x_ABA| Lbt

    PathIn -->|T_BB 自编码| EncB
    EncB -->|z| Latent
    Latent -->|T_BB| DecB
    DecB -->|重建 x_BB| Lrec

    PathIn -->|T_BA 跨域翻译| EncB
    EncB -->|z| Latent
    Latent -->|T_BA| DecA
    DecA -->|生成 x_BA| EncA
    EncA -->|z'| Latent
    Latent -->|T_AB 回译| DecB
    DecB -->|回译 x_BBA| Lbt

    %% 有监督损失
    TextIn -->|配对 x_B| Lsup
    PathIn -->|配对 x_A| Lsup

    %% 预处理流程连接
    Preprocess --> TextIn
    Preprocess --> PathIn

    %% 图例
    subgraph "Legend" 
        A["文本域组件"]:::textdomain
        B["图路径域组件"]:::pathdomain
        C["公共组件"]:::common
        D["损失模块"]:::loss
        E["预处理流程"]:::preprocess
    end

    %% Click Events
    click Read "https://github.com/ibm/dualtkb/blob/main/README.md"
    click Lic "https://github.com/ibm/dualtkb/tree/main/LICENSE"

    %% 样式定义
    classDef doc fill:#F9F,stroke:#333,stroke-width:1px
    classDef textdomain fill:#B3E5FC,stroke:#0277BD,stroke-width:1px
    classDef pathdomain fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef common fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px
    classDef loss fill:#FFCDD2,stroke:#C62828,stroke-width:1px,stroke-dasharray: 5 5
    classDef preprocess fill:#E1BEE7,stroke:#6A1B9A,stroke-width:1px
    classDef legend fill:#FFF9C4,stroke:#F9A825,stroke-width:1px
```
