智航云 开发者平台

Appearance

知识图谱开发指南 ​

概述 ​

知识图谱 (Knowledge Graph) 用于存储和查询业务实体间的关系网络。与知识库的非结构化文本不同，知识图谱以节点和边的形式存储结构化的实体关系，适合回答"A和B之间是什么关系""哪些设备在这个区域"等关联性问题。

核心概念：

  • 节点 (Node) -- 业务实体，如设备、建筑、员工、技能
  • 边 (Edge) -- 实体间的关系，如 LOCATED_IN、REPORTS_TO、HAS_SKILL
  • 图谱 (Graph) -- 以 appId 为单位隔离的一组节点和边

底层使用 MongoDB 的 graph_nodes 和 graph_edges 集合存储。

添加节点 ​

bash
curl -X POST https://api.invoratec.cn/v1/graph/my-graph/nodes \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Device",
    "name": "冷水机-01",
    "externalId": "CW-001",
    "properties": {
      "floor": "B1",
      "power": "500kW",
      "brand": "开利",
      "install_date": "2022-06-01"
    }
  }'
python
node = claw.graph.add_node("my-graph",
    type="Device",
    name="冷水机-01",
    externalId="CW-001",
    properties={"floor": "B1", "power": "500kW"}
)
javascript
const node = await claw.graph.addNode('my-graph', {
  type: 'Device',
  name: '冷水机-01',
  externalId: 'CW-001',
  properties: { floor: 'B1', power: '500kW' }
})

节点字段说明：

字段类型必填说明
typestring是节点类型 (如 Device, Room, Employee)
namestring是节点名称
externalIdstring否外部系统ID，用于数据同步去重
propertiesobject否自定义属性键值对

节点使用 upsert 逻辑：如果同一图谱下已存在相同 externalId 的节点，会更新而非重复创建。

添加关系 ​

bash
curl -X POST https://api.invoratec.cn/v1/graph/my-graph/edges \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "冷水机-01",
    "to": "机房-B1",
    "relation": "LOCATED_IN",
    "properties": {
      "since": "2022-06-01",
      "position": "北侧"
    }
  }'
python
edge = claw.graph.add_edge("my-graph",
    from_node="冷水机-01",
    to_node="机房-B1",
    relation="LOCATED_IN",
    properties={"since": "2022-06-01"}
)
javascript
const edge = await claw.graph.addEdge('my-graph', {
  from: '冷水机-01',
  to: '机房-B1',
  relation: 'LOCATED_IN',
  properties: { since: '2022-06-01' }
})

常用关系类型示例：

关系说明场景
LOCATED_IN位于设备 -> 房间
CONTAINS包含楼栋 -> 楼层
REPORTS_TO汇报给员工 -> 经理
HAS_SKILL拥有技能员工 -> 技能
SUPPLIES供给冷水机 -> 空调系统
DEPENDS_ON依赖服务A -> 服务B

查询节点 ​

按类型和名称模式查询节点：

bash
curl "https://api.invoratec.cn/v1/graph/my-graph/nodes?object_type=Device&name=%E5%86%B7%E6%B0%B4%E6%9C%BA&limit=50" \
  -H "X-API-Key: claw_xxxx"
python
nodes = claw.graph.find_nodes("my-graph", object_type="Device", name="冷水机", limit=50)
for node in nodes:
    print(f"{node['name']} ({node['properties']['power']})")
javascript
const { nodes } = await claw.graph.getNodes('my-graph', {
  objectType: 'Device',
  name: '冷水机',
  limit: 50
})

查询参数：

参数类型说明
object_typestring按节点类型过滤
namestring按名称模糊匹配
limitinteger返回上限，默认 100

关系遍历 ​

从指定节点出发，沿关系路径发现关联实体：

bash
curl -X POST https://api.invoratec.cn/v1/graph/my-graph/traverse \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "startNode": "冷水机-01",
    "relation": "LOCATED_IN",
    "depth": 2,
    "direction": "both"
  }'
python
result = claw.graph.traverse("my-graph",
    start_node="冷水机-01",
    relation="LOCATED_IN",
    depth=2,
    direction="both"
)
# 返回与冷水机-01相关联的所有实体（2层深度）
javascript
const result = await claw.graph.traverse('my-graph', {
  startNode: '冷水机-01',
  relation: 'LOCATED_IN',
  depth: 2,
  direction: 'both'
})

遍历参数：

参数类型必填说明
startNodestring是起始节点名称
relationstring否限定关系类型，不填则遍历所有关系
depthinteger否遍历深度，默认 1，最大 3
directionstring否遍历方向：outgoing/incoming/both，默认 both

全文搜索 ​

在图谱中搜索节点，可同时返回相邻节点：

bash
curl -X POST https://api.invoratec.cn/v1/graph/my-graph/search \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "冷水机",
    "object_type": "Device",
    "limit": 20,
    "includeNeighbors": true
  }'
python
result = claw.graph.search("my-graph",
    query="冷水机",
    object_type="Device",
    limit=20,
    include_neighbors=True
)
javascript
const result = await claw.graph.search('my-graph', {
  query: '冷水机',
  objectType: 'Device',
  limit: 20,
  includeNeighbors: true
})

批量同步 ​

从外部系统批量导入节点和关系，适合初始化或定期数据同步：

bash
curl -X POST https://api.invoratec.cn/v1/graph/my-graph/sync \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      { "type": "Building", "name": "A栋", "properties": { "floors": 20 } },
      { "type": "Floor", "name": "A栋-B1", "properties": { "area": "2000m2" } },
      { "type": "Room", "name": "机房-B1", "properties": { "area": "200m2" } },
      { "type": "Device", "name": "冷水机-01", "externalId": "CW-001", "properties": { "power": "500kW" } },
      { "type": "Device", "name": "冷水机-02", "externalId": "CW-002", "properties": { "power": "300kW" } }
    ],
    "edges": [
      { "from": "A栋-B1", "to": "A栋", "relation": "PART_OF" },
      { "from": "机房-B1", "to": "A栋-B1", "relation": "PART_OF" },
      { "from": "冷水机-01", "to": "机房-B1", "relation": "LOCATED_IN" },
      { "from": "冷水机-02", "to": "机房-B1", "relation": "LOCATED_IN" },
      { "from": "冷水机-01", "to": "冷水机-02", "relation": "BACKUP_FOR" }
    ]
  }'
python
result = claw.graph.sync("my-graph",
    nodes=[
        {"type": "Building", "name": "A栋", "properties": {"floors": 20}},
        {"type": "Floor", "name": "A栋-B1"},
        {"type": "Room", "name": "机房-B1"},
        {"type": "Device", "name": "冷水机-01", "externalId": "CW-001"},
        {"type": "Device", "name": "冷水机-02", "externalId": "CW-002"},
    ],
    edges=[
        {"from": "A栋-B1", "to": "A栋", "relation": "PART_OF"},
        {"from": "机房-B1", "to": "A栋-B1", "relation": "PART_OF"},
        {"from": "冷水机-01", "to": "机房-B1", "relation": "LOCATED_IN"},
        {"from": "冷水机-02", "to": "机房-B1", "relation": "LOCATED_IN"},
    ]
)
print(f"写入: {result['nodesWritten']} 节点, {result['edgesWritten']} 关系")
javascript
const result = await claw.graph.sync('my-graph', {
  nodes: [
    { type: 'Building', name: 'A栋', properties: { floors: 20 } },
    { type: 'Device', name: '冷水机-01', externalId: 'CW-001' }
  ],
  edges: [
    { from: '冷水机-01', to: '机房-B1', relation: 'LOCATED_IN' }
  ]
})
console.log(`写入: ${result.nodesWritten} 节点, ${result.edgesWritten} 关系`)

sync 使用 upsert 逻辑，可以安全地重复执行。

查看图谱统计 ​

bash
# 所有图谱的统计
curl https://api.invoratec.cn/v1/graph \
  -H "X-API-Key: claw_xxxx"

# 指定图谱
curl https://api.invoratec.cn/v1/graph/my-graph/stats \
  -H "X-API-Key: claw_xxxx"

实战示例：智慧园区设备拓扑 ​

python
# 构建园区设备拓扑图谱
claw.graph.sync("smart-campus", nodes=[
    # 建筑层级
    {"type": "Campus", "name": "智慧园区"},
    {"type": "Building", "name": "1号楼", "properties": {"floors": 15}},
    {"type": "Building", "name": "2号楼", "properties": {"floors": 12}},
    {"type": "Floor", "name": "1号楼-1F"},
    {"type": "Floor", "name": "1号楼-B1"},

    # 系统
    {"type": "System", "name": "暖通系统"},
    {"type": "System", "name": "照明系统"},
    {"type": "System", "name": "电梯系统"},

    # 设备
    {"type": "Device", "name": "冷水机-01", "externalId": "CW-001",
     "properties": {"power": "500kW", "status": "running"}},
    {"type": "Device", "name": "AHU-01", "externalId": "AHU-001",
     "properties": {"power": "50kW", "status": "running"}},
], edges=[
    {"from": "1号楼", "to": "智慧园区", "relation": "PART_OF"},
    {"from": "2号楼", "to": "智慧园区", "relation": "PART_OF"},
    {"from": "1号楼-1F", "to": "1号楼", "relation": "PART_OF"},
    {"from": "1号楼-B1", "to": "1号楼", "relation": "PART_OF"},
    {"from": "冷水机-01", "to": "1号楼-B1", "relation": "LOCATED_IN"},
    {"from": "冷水机-01", "to": "暖通系统", "relation": "BELONGS_TO"},
    {"from": "AHU-01", "to": "1号楼-1F", "relation": "LOCATED_IN"},
    {"from": "AHU-01", "to": "暖通系统", "relation": "BELONGS_TO"},
    {"from": "AHU-01", "to": "冷水机-01", "relation": "DEPENDS_ON"},
])

# 查询：冷水机-01 关联了哪些设备？
result = claw.graph.traverse("smart-campus", start_node="冷水机-01", depth=2)

下一步 ​

智航云 AI 中台 — 开发者平台

© 2026 Invoratec. All rights reserved.