3分钟阅读

Graphify 数据写入 API

🔌 前往 Graphify →](/zh-CN/graphify)

Graphify 将知识库(tKB)条目可视化为 3D 知识图谱。本文说明如何 通过 API 添加数据,以及如何调用才能让 信息显示得更好。

数据流程分两步: ① 写入条目(giipKb) → ② 重建图谱(giipGraphifyRebuild)。必须调用重建,新条目才会出现在图谱中。

快速开始 (3步)

# 1) 写入条目 — giipKb POST (主机: giipfaw.azurewebsites.net)
curl -X POST "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47,"title":"OAuth 回调 500","content":"## 原因\ntoken 交换超时","tags":"auth,oauth,timeout","refType":"ISSUE","extRefId":"ISSUE-1001"}'

# 2) 重建图谱 — giipGraphifyRebuild POST
curl -X POST "https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47}'

# 3) 验证 — 浏览器打开 https://<host>/zh-CN/graphify?csn=47

认证密钥(x-api-key)使用登录用户的 AK 或项目范围的 SK。密钥只能在其自身 csn 范围内添加/重建数据。

⭐ 如何让信息显示得更好 (关键)

Graphify 是 标签二部(bipartite)图谱: 文档通过"共享标签"相互连接(标签是一级节点)。因此 打标签的方式决定图谱质量。

好标签 (能产生连接)

使用 2〜50 个条目共享的有意义标签,例如 auth、billing、timeout、payment、login。
同主题条目会围绕共享标签节点形成聚类。

应避免的标签

不良模式	原因	结果
每个条目独有的标签(如文件名 `report_2026_01.md`)	无条目共享(DF=1)	无法连接 → 孤立节点
几乎每个条目都有的通用标签(如 `doc`、`sync`、`general`)	文档频率(DF)过高	被自动过滤出边(防止毛球)

经验法则: 既不太常见也不太独有的标签才能产生好连接。默认在一个 csn 内,只有 DF(文档频率)在 2〜50 之间的标签才会成为标签节点。

其他显示技巧

title 会成为图谱的 节点标签 — 简短清晰。
content 在点击节点时作为 详情弹窗正文以 Markdown 渲染。
extRefId 是外部系统的条目 ID — 重新同步时 更新而不重复(幂等)。
必须重建: 只添加条目而不重建,图谱不会变化。批量写入后调用一次 giipGraphifyRebuild。

详情 · API 参考

1) 写入 — `giipKb`

POST https://giipfaw.azurewebsites.net/api/giipKb · 头 x-api-key: <ak/sk>

字段	类型	必填	说明
`csn`	int	✅	项目编号;须与密钥范围一致(示例: 47)
`title`	string(200)	✅	节点标签
`content`	string		节点详情正文(允许 Markdown)
`tags`	string(500)		逗号分隔标签。连接的核心(见"好标签")
`refType`	string(50)	✅	条目类型,例如 `ISSUE`、`GENERAL`、`GUIDE`
`extRefId`	string(100)		外部条目 ID(幂等 upsert 键);存在则重新同步时更新

响应

{ "success": true, "kbSn": 844, "message": "KB entry created successfully" }

用相同 extRefId 再次发送:

{ "success": true, "kbSn": 844, "message": "KB entry updated (idempotent)" }

PowerShell 示例

$headers = @{ "x-api-key"="<ak/sk>"; "Content-Type"="application/json; charset=utf-8" }
$body = @{ csn=47; title="支付延迟"; content="## 现象`n审批延迟5秒"; tags="payment,timeout"; refType="ISSUE"; extRefId="ISSUE-1002" } | ConvertTo-Json
Invoke-RestMethod -Uri "https://giipfaw.azurewebsites.net/api/giipKb" -Method POST -Headers $headers -Body ([Text.Encoding]::UTF8.GetBytes($body))

2) 重建 — `giipGraphifyRebuild`

POST https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild · 头 x-api-key: <ak/sk>

从 tKB 重建指定 csn 的图谱(DOC 节点 + 有辨识度的 TAG 节点 + doc→tag 边)。

字段	类型	必填	说明
`csn`	int	✅	要重建的项目编号
`maxTagDF`	int		通用标签阈值(文档频率上限,默认 50);比此更常见的标签被排除
`maxNodes`	int		DOC 节点安全上限(默认 20000)

响应

{ "success": true, "nodes": 838, "edges": 11, "docNodes": 835, "tagNodes": 3, "message": "Graph rebuilt (tag-bipartite)" }

故障排查

现象	原因	解决
图谱看起来为空	未调用重建 / csn 错误	调用 `giipGraphifyRebuild`,检查 `?csn=`
节点很多但几乎没有边	标签独有(DF=1)或通用(过于频繁)	用 2〜50 个共享的有意义标签重新写入后重建
同一条目重复创建	未使用 `extRefId`	加入 `extRefId` 实现幂等写入
401/403	无密钥 / 不同 csn	使用有效的 `x-api-key` 和自己的 `csn`

元数据

源文件: giipv3/public/help/api-graphify.zh-CN.md
raw 原文路径: /help/api-graphify.zh-CN.md
相关 API: giipfaw/giipKb, giipfaw/giipGraphifyRebuild
相关页面: /[locale]/graphify