kg_agent/visualization/knowledge_search_traverse

Knowledge Search Traverse 可视化工具

概述

这是 knowledge_search_traverse.py (v6.1.2.125) 的配套可视化工具。基于 v6.1.2.121 的 React Flow 可视化引擎，通过数据转换层将语义分段跨域组词的执行数据转换为图结构，实现美观的交互式可视化。

🆕 新增功能：多模态图片提取展示

支持展示帖子图片的文字提取和AI语义描述，提供更丰富的内容分析能力。

🎯 核心特性

1. 智能数据转换

• 自动检测数据格式（v6.1.2.5 或 v6.1.2.8）
• 将轮次数据（rounds）转换为节点-边图结构
• 保留完整的轮次信息和来源追踪

2. 多类型节点支持

节点类型	颜色	说明
root	紫色 (#6b21a8)	原始问题根节点
seg	绿色 (#10b981)	初始分词结果
q	蓝色 (#3b82f6)	查询节点
search	深紫 (#8b5cf6)	搜索操作节点
note	粉色 (#ec4899)	帖子结果节点

3. 来源标识

清楚展示每个Query的来源：

• seg - 来自分词
• add - 加词生成
• sug - 建议词生成

4. 交互功能

继承 v6.1.2.5 的所有交互功能：

• ✅ 节点拖拽和缩放
• ✅ 按层级筛选
• ✅ 节点搜索
• ✅ 路径高亮
• ✅ 目录树导航（左侧面板）
• ✅ 节点折叠/展开
• ✅ 聚焦功能
• ✅ 目录卡片交错布局 - 卡片左右错开，避免垂直叠加
• ✅ 目录卡片拖动 - 支持垂直方向拖动调整位置

📁 文件结构

visualization/sug_v6_1_2_8/
├── index.js                  # 主可视化脚本（支持格式检测）
├── convert_v8_to_graph.js   # 数据转换层
├── package.json             # 依赖配置
├── node_modules/            # 依赖包（React Flow, esbuild等）
└── README.md               # 本文档

🚀 使用方式

方式1：通过主脚本自动生成（推荐）

# 运行脚本并自动生成可视化
python3 knowledge_search_traverse.py --visualize

可视化HTML会自动生成在输出目录中。

方式2：手动生成可视化

# 从 run_context.json 生成可视化
node visualization/knowledge_search_traverse/index.js \
  path/to/run_context.json \
  path/to/output.html \
  [--simplified]

参数说明：

• path/to/run_context.json：运行上下文文件路径（必需）
• path/to/output.html：输出HTML文件路径（可选，默认为 query_graph_output.html）
• --simplified：使用简化视图（可选）

📦 数据来源

可视化工具会读取以下文件：

1. run_context.json（必需）：主要的运行上下文数据
2. search_results.json（可选）：搜索结果详情
3. search_extract.json（可选）：🆕 图片提取结果

🖼️ 多模态图片提取展示

如果存在 search_extract.json 文件，可视化会展示：

• 提取文字：图片中的所有可见文字内容
• 图片描述：AI生成的图片详细描述
• 原图展示：点击可查看原始图片

search_extract.json 格式

{
  "note_id_xxx": {
    "note_id": "xxx",
    "note_url": "https://...",
    "title": "帖子标题",
    "body_text": "帖子正文",
    "type": "normal",
    "extraction_time": "2025-01-11T15:00:00",
    "images": [
      {
        "image_index": 0,
        "original_url": "https://...",
        "description": "图片的详细语义描述...",
        "extract_text": "图片中提取的文字内容..."
      }
    ]
  }
}

扩展图片提取展示

如需自定义图片提取结果的展示方式，可以修改 index.js 中的React组件，添加图片展示的UI和交互逻辑。

示例位置：

// 读取提取结果
const extractPath = path.join(path.dirname(inputFile), 'search_extract.json');
let extractData = {};
if (fs.existsSync(extractPath)) {
    extractData = JSON.parse(fs.readFileSync(extractPath, 'utf-8'));
}

📊 数据转换说明

输入格式（v6.1.2.8）

{
  "o": "快速进行图片背景移除和替换",
  "rounds": [
    {
      "round_num": 0,
      "type": "initialization",
      "seg_list": [
        {"text": "快速", "score": 0.1},
        {"text": "图片", "score": 0.1}
      ],
      "q_list_1": [...]
    },
    {
      "round_num": 1,
      "input_q_list": [...],
      "output_q_list": [
        {"text": "快速图片", "score": 0.2, "from": "add"}
      ],
      "search_count": 3
    }
  ]
}

转换后格式（图结构）

{
  "nodes": {
    "root_o": {
      "type": "root",
      "query": "快速进行图片背景移除和替换",
      "level": 0
    },
    "seg_快速_0": {
      "type": "seg",
      "query": "快速",
      "level": 1
    },
    "q_快速图片_r2_0": {
      "type": "q",
      "query": "快速图片",
      "level": 2,
      "from_source": "add"
    }
  },
  "edges": [
    {
      "from": "root_o",
      "to": "seg_快速_0",
      "edge_type": "root_to_seg"
    },
    {
      "from": "seg_快速_0",
      "to": "q_快速_r1",
      "edge_type": "seg_to_q"
    }
  ]
}

🎨 可视化效果

图布局

• 水平布局：从左到右按轮次展开
• 层次化：相同轮次的节点纵向排列
• 自动布局：使用 dagre 算法自动计算最佳位置

节点样式

• 边框颜色：根据节点类型区分
• 标签内容：显示 Query 文本、分数、策略
• 特殊标识：
  • 未选中的节点：红色 "未选中" 标签
  • Search 节点：显示搜索次数和帖子数

边样式

• 虚线：表示不同类型的关系
• 颜色：根据策略类型着色
• 箭头：指示数据流向

📦 依赖

所有依赖已包含在 package.json 中：

• react + react-dom - UI 框架
• @xyflow/react - 流程图库
• dagre - 图布局算法
• esbuild - 打包工具
• zustand - 状态管理
• react-draggable - 拖拽功能库

安装依赖：

cd visualization/sug_v6_1_2_121
npm install

总大小：约 34MB

🔧 技术实现

转换层（convert_v8_to_graph.js）

• 解析 rounds 数据
• 创建图节点和边
• 维护轮次信息（iterations）

可视化层（index.js）

• 格式检测和自动转换
• React Flow 渲染
• 交互功能实现

优势

• ✅ 复用成熟的可视化引擎
• ✅ 保持视觉一致性
• ✅ 完整的交互功能
• ✅ 易于维护和扩展

📝 更新日志

v1.2.0 (knowledge_search_traverse - 2025-01-11)

• 🆕 集成多模态图片提取功能
• 📦 添加 search_extract.json 数据支持
• 📝 更新文档说明多模态展示方式
• 🔧 修改脚本路径为 knowledge_search_traverse

v1.1.0 (2025-11-11)

• ✨ 新增目录树卡片交错布局（之字形排列）
• ✨ 新增目录树卡片拖动功能（支持垂直拖动）
• 🔧 增加卡片间距从 8px 到 20px
• 📦 添加 react-draggable 依赖

v1.0.0 (2025-10-31)

• 基于 v6.1.2.121 可视化引擎
• 实现轮次数据到图结构的转换
• 支持新的节点类型（root, segment, domain_comb, search）
• 自动格式检测和转换
• 完整的交互功能

🤝 兼容性

版本	支持	说明
v6.1.2.121	✅	直接渲染（语义分段跨域组词版）
v6.1.2.125	✅	完全兼容 + 多模态图片提取
knowledge_search_traverse	✅	当前版本，完整支持

📧 问题反馈

如有问题或建议，请查看主项目 README 或提交 Issue。