# iGraph 技术文档

iGraph 是图数据智能体：从用户问题出发，用图组织实体关系，通过查询、图算法与图学习获取证据，组织后续分析和结果解释。

## 认识 iGraph

iGraph 是图数据智能体。它把数据中的对象和联系表示为节点和边，围绕你的问题查找对象、追踪关系、识别结构，或训练适用的图学习模型。智能体调用工具完成计算，再依据实际结果给出解释；你可以在同一会话中继续追问。

智能体负责判断当前问题需要什么证据、已有结果是否足够，以及下一步应查询哪些对象。Graph Engine 管理图数据与版本，执行图查询、算法、训练和推理，并返回结构化结果。前端呈现对话、运行进度、图视图和报告；运行服务保存会话、工具调用与执行状态。用户可以围绕同一份图继续追问，已有图状态和已完成结果为后续步骤提供上下文。

技能（Skill）组织分析流程，例如先核对图状态与边权含义，再选择路径或中心性工具，最后解释结果范围。自进化构图提供图模式准备与优化能力：当任务需要从关系数据建立图，或现有图模式不适合既定查询时，它保留源语义、比较候选结构并积累策略经验。已有可用图可以直接加载分析，无需每次重新构图。

当前版本采用单用户工作区：打开即可使用，无需登录、注册或切换账号。项目、会话、模型连接、记忆和技能统一保存在默认工作区；分析过程仍核对项目、数据集与会话范围。

## 从这里开始

- [快速开始](/zh/quickstart/): 启动系统，确认会话与图状态，开始第一次分析。
- [实验结果](/zh/experiments/): 查看图分析任务成功率，以及构图智能体相对 PK/FK 规则构图的成本改善。
- [工作台操作指南](/zh/workspace/): 从上传、预览和构图，到图分析、训练与报告，按界面入口完成一次分析。
- [图分析工具](/zh/graph-tools/): 按分析目标查看查询、图算法、学习与报告工具的参数和输出。
- [图模式准备与优化](/zh/construction/): 了解自进化构图如何为分析保留关系语义、验收候选图模式和复用经验。
- [API 参考](/zh/api/): 请求参数、响应结构和可复制的调用示例。

## 为什么用图分析数据

许多数据问题涉及多个对象之间的连接，而不止是单列数值。把客户、订单、供应商、设备等对象表示为节点，把引用、交易、依赖或连接表示为边，可以明确一次分析沿哪些关系展开、采用什么方向、使用哪个版本。节点与边的业务含义必须先由数据确认；图模型本身不会替用户决定一条连接是否代表控制、影响或因果关系。

| 分析问题 | 图上的操作 | 获得的证据及含义 |
| --- | --- | --- |
| 对象之间如何关联？ | 实体定位、邻域与路径查询 | 真实节点标识、连接序列与可达范围；按已确认的关系方向解释关联。 |
| 哪些对象位于重要结构位置？ | 度数、中心性、连通性 | 相应指标定义下的排名或结构属性；高分不自动等于业务价值或风险。 |
| 数据中有哪些群体或局部模式？ | 社区发现、子图提取与可视化 | 结构分组、局部连接和展示范围；社区标签需要结合业务信息解释。 |
| 能否从图特征学习预测规则？ | 节点分类、链接预测、图分类或预训练 | 模型输出、评估指标与嵌入向量；结论受特征、标签、划分和任务实现限制。 |

同一分析可以组合这些操作，但需要保持输入语义一致。例如先用社区发现提出待检查的群体，再用真实节点标识查询跨群体连接；或者先比较中心性，再查看高分节点的邻域。后一步由前一步结果和用户目标决定。查询、排名、可视化和预测提供不同类型的证据，不能互相替代。

## 一次分析如何推进

![图驱动的数据分析流程](/diagrams/analysis-zh.svg)

分析围绕“问题—图上证据—解释—下一步”反复推进。图中展示模块之间的分析流程，不表示每个请求都必须构图、训练或生成报告。一次明确的路径问题可能只需要状态核验、节点定位和路径计算；综合分析则可能经历多个模型回合与工具分支。

- 明确问题与范围：确定用户要比较或解释的对象，核对附件所属数据集、项目范围以及已有会话状态。
- 确认图模式：用 get_graph_info 核验活动图；需要时加载已保存的构图结果，或引导到适用的数据准备入口。核对实体类型、关系方向、边权和 graph_version。
- 选择证据操作：依据问题调用检索、路径、中心性、社区等工具。只有任务定义和数据条件充分时，才进入相应图学习流程。
- 执行并读取结果：已知参数的独立操作可以同轮提交；依赖搜索结果中的节点 ID 或训练生成的 model_id 时，先等待真实结果，再组织后续调用。
- 检查证据范围：核对 success、任务终态、方向和版本，留意截断、有限范围查询、未匹配对象及模型评估协议。证据不足时补查或说明缺口。
- 形成解释并继续分析：将可支持的观察与推断分别说明，需要时展示子图或生成报告；新的问题继续使用已确认的状态和结果。

工具调度解决资源读写冲突和执行顺序，不负责替智能体补造未知参数。工具成功说明对应操作完成，也不自动证明自然语言解释正确。结构关联、预测分数和业务原因应分别讨论；当前流程没有通用的因果推断保证。

## 工具证据示例：追踪两个实体的连接

假设用户问：“当前供应关系图中，供应商 A 与工厂 B 之间是否有连接路径？经过哪些对象？”以下仅为说明性调用示例，不是实际运行记录，也不预设路径存在。前提是已经加载一张方向含义明确的供应关系图；供应关系不自动表示货物流向、交易金额或因果影响。

先确认活动图。下列 name / arguments 对象表示工具调用及其参数；读取并核验 get_graph_info 的实际返回后，再进行对象搜索。

```json
{
  "name": "get_graph_info",
  "arguments": {}
}
```

> **语义搜索需要额外配置**
> search_node 的语义检索需要可用的向量模型和索引。检索是否启用语义评分，应查看返回的 semantic_enabled 及服务配置；精确名称或结构筛选不等于语义检索。若搜索不可用，可从“数据”页或节点详情复制真实节点 ID，再调用 get_node_info、get_neighbors 或路径工具。

图状态核验完成后，检索两个名称。两次搜索参数互不依赖，可一起提交。search_node 返回候选后，应检查是否歧义，并使用已确认的真实节点名。

```json
[
  {
    "name": "search_node",
    "arguments": {
      "query": "Supplier A",
      "top_k": 5
    }
  },
  {
    "name": "search_node",
    "arguments": {
      "query": "Factory B",
      "top_k": 5
    }
  }
]
```

确认两个节点后，再调用 shortest_path。这里按最少跳数分析，显式设置 use_weight=false；占位符必须替换为搜索结果中的节点名。该工具只读取活动图，调用前还需确认当前方向正是问题所需的遍历方向。

```json
{
  "name": "shortest_path",
  "arguments": {
    "source": "SUPPLIER_NODE_FROM_SEARCH",
    "target": "FACTORY_NODE_FROM_SEARCH",
    "use_weight": false,
    "algorithm": "default"
  }
}
```

| 已取得的证据 | 下一步如何使用 |
| --- | --- |
| get_graph_info | 确认加载状态、图版本、规模与语义；这些信息限定本次结果属于哪份图。 |
| search_node | 核对候选的真实名称、类型与歧义标记；找不到对象时补充信息，不生成一个看似合理的 ID。 |
| shortest_path | 根据真实 found、path、hop_count 等字段解释连接；远端有界查询还需检查结果范围，未找到不总是全图不可达。 |
| visualize_subgraph | 如找到路径，把返回的节点序列传入 highlights.paths[].node_sequence。展示该路径的结构证据，并说明视图是否截断。 |
| create_analysis_report | 用户需要综合报告时，把已完成工具的原始返回按真实工具名放入 source_results。报告负责组织证据，不补造缺失的路径或业务结论。 |

最终说明应对应实际结果：找到路径时，解释它连接了哪些对象以及关系方向；没有找到时，说明检索范围和可能需要补充的数据。任何关于交付风险、供应商控制力或业务成因的判断，都需要额外业务依据，不能仅凭一条路径推出。

## 技能与自进化构图如何支撑分析

技能提供可复用的分析步骤，构图能力提供这些步骤所需的图模式。两者围绕用户的分析目标协同：已有图适合当前问题时直接分析；需要保留关系源数据或针对固定查询优化图模式时，再进入构图与验收流程。表格构图中的独立 SQL 验证针对图模式转换，不会自动验证主智能体的所有分析答案。

关系构图先从 SQL、CSV、表格或逐行 TXT 建立属性图，保留记录、已声明的主外键和字段类型，再用独立 SQL 参考执行器核对固定评测查询的结果。普通 TXT 也支持由模型抽取实体和关系，但这条路径只检查输出结构和文本出处，不进行关系表的 SQL 对照验证。

自进化体现在两条相互独立的路径中：用户批准的技能可以在后续任务中复用操作流程；构图策略库则积累变换成功、没有收益或不安全的证据，用于调整相似任务的候选顺序。经验提供决策依据，当前数据仍须重新验证。一次构图没有找到查询更高效的图模式，也可以保留有效基线并形成可复用的负反馈。

## 能力边界

| 能力 | 当前实现 |
| --- | --- |
| 智能体协作 | Agno AgentOS 会话、Run、审批、学习与可恢复事件流。 |
| 图计算 | 图可视化、算法、GNN 训练与推理，重任务在 Graph Engine 执行。 |
| 表格构图 | CSV、分隔表格 TXT 与 SQLite 兼容 SQL；先保留源记录和关系语义，再验收候选图。 |
| 自然语言文本抽取 | 普通 TXT 可确定性逐行构图，也可显式选择 entities，由构图 LLM 分块抽取实体和关系。 |
| 源数据预览 | 构图前后查看 SQL 表记录、CSV 表头与样例、TXT 原文片段；字段说明区分源注释、键关系、名称推断和未知。 |

TXT 数据集入口提供三种明确模式：auto 只自动识别严格制表符表格，否则逐行记录；lines 强制逐行记录；entities 必须与 llm 联用，把全文分块发送到已配置的构图模型。auto 和 lines 不做自然语言实体抽取，与 rules 联用可保持完整离线。entities 不要求 PK/FK，只校验边端点落在来源分块且图符合契约；实体归并、关系名称、方向和事实含义仍需人工复核。

当前能力通过具体工具和数据入口提供，并非所有上传文件都会自动转为可分析图。文本抽取、关系表构图、已有图加载和多图分类数据集采用不同的数据结构与验证条件。图驱动分析要求先确定可用图模式和任务前提，再决定调用哪些能力。

## 典型任务如何完成

| 任务 | 执行过程 | 如何确认结果 |
| --- | --- | --- |
| 关系数据分析 | 围绕用户问题确认数据与关系含义 → 加载可用图，必要时准备图模式 → 查询路径、社区或关键节点 → 检查证据并解释。 | 检查数据集 revision、会话 graph_version、真实节点标识和查询范围。 |
| 面向分析的图模式优化 | 固定业务查询 → 测量当前图 → 在副本上变换 → 核对答案与成本 → 保留有效图模式及策略经验。 | 查询通过率与源数据完整性同时满足；收益由运行报告中的实测耗时解释。 |
| 图机器学习 | 确认特征、标签和数据划分 → 提交训练 → 等待后台作业完成 → 用模型 ID 执行推理。 | 核对任务、模型、指标与输入图；说明当前划分协议和模型使用的特征。 |

分析时应先明确“节点和边代表什么”，再选择算法。相同的边权可以表示距离、成本、联系强度或容量，解释不同会改变适用算法。例如，最短路径把权重当作要最小化的成本，最大流把权重当作可累加的容量；中心性排名与社区分组也回答不同的问题。图算法指南给出这些选择的数学含义、实现参数和示例。

- [智能体运行机制](/zh/agent-runtime/): 技能加载、工具调用顺序、审批、取消与状态恢复。
- [图算法与结果解读](/zh/graph-algorithms/): 按分析问题选择算法，理解公式、边权和输出范围。
- [图机器学习](/zh/graph-ml/): 输入张量、损失函数、训练作业和推理示例。