5分钟阅读

Graphify 数据写入 API

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

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

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

📦 数据存储与流程 — tKB 才是"真正的存储"

⚠️ 最常见的误解: "登记了 issue 但图谱里没有出现",几乎都是因为 还没有写入 tKB。tBlogGraphNodes/tBlogGraphEdges(图谱表)本身并不持有数据,而是 每次调用重建时从 tKB 重新生成的派生结果。没有办法直接写入图谱表,必须始终走 tKB → 重建这条路径。

[issue / 知识来源]
   │ ① 写入: POST /api/giipKb (x-api-key: ak/sk)
   │   → 向 tKB 表写入 1 行 (csn, refType, title, content, tags, extRefId)
   │   → refType='ISSUE'(外部/自有 issue) 或 'k-layer-daily'(K-Layer 每日同步,见下文)
   │   → 通过 extRefId 幂等 upsert(重新发送相同 extRefId 时是 UPDATE 已有行,而非新建)
   ▼
  tKB  (图谱的"真正数据存储" — 图谱表本身只是派生结果)
   │ ② 重建: POST /api/giipGraphifyRebuild {csn} (x-api-key)
   │   → SP pApiGraphifyRebuildbyAk 会先整体 DELETE 该 csn 的 tBlogGraphNodes/tBlogGraphEdges,
   │     再从 tKB 重新生成(只写入而不重建,图谱不会变化)
   │   → DOC 节点(tKB 每行对应一个文档) + TAG 节点(仅限 2 个以上文档共享的标签,为防止
   │     "毛球"效应,过于常见的标签会被自动排除) + doc→tag 边
   │   → (新增)按该 csn 设置的语言(tCorp.cLang)自动翻译节点标签后再保存
   ▼
 tBlogGraphNodes / tBlogGraphEdges  (csn 范围,页面实际读取的表)
   │ ③ 查询: GET /api/giipGraphifyTenant?csn= (严格隔离,ak 授权) 或页面 /graphify?csn=
   ▼
 3D 知识图谱可视化

仅完成①写入,图谱中不会出现任何内容。 必须继续调用②重建才会反映。
重建每次都是全量重新生成。 不是在旧图谱基础上增量构建,而是根据当前 tKB 的全部内容重新绘制。因此从 tKB 中删除条目(或按 refType 批量删除)后,下次重建会自然从图谱中消失。
隔离: 每一步都以 csn(项目边界)和 x-api-key(ak/sk 授权)为范围。无法访问其他 csn 的 tKB 或图谱。

K-Layer 自动写入(已在运行,`refType='k-layer-daily'`)

giip 会话积累的 工程经验(K-Layer) 目前已经每天自动写入 tKB(并非新功能,而是既有的生产功能)。

调度器: giipdb/mgmt/run_klayer_daily_wiki.ps1 每天 00:15 UTC 通过 Windows 任务计划程序作业 GIIP_Daily_KLayerWiki 执行。
执行内容: 对所有有 giip issue 的 csn,汇总前一天的 issue 与评论,用 MiniMax 生成摘要,再通过 giipKb INSERT 写入 tKB。
字段取值: refType='k-layer-daily'、tags='k-layer-wiki,daily'、title='K-Layer Wiki {csn} - {yyyy-MM-dd}'。
脱敏: 敏感信息在存储前会经过 giipdb/mgmt/lib/Mask-SensitiveInfo.ps1 双重脱敏处理。
在图谱中的呈现: 这些 tKB 行与其他条目一样,会在下次重建时作为 DOC 节点被纳入。共享标签 k-layer-wiki、daily 会成为 TAG 节点,使按日期累积的 K-Layer 文档自然聚合成一个聚类。
可按 refType='k-layer-daily' 筛选或批量删除(参见§1表中的 refType)。

基于 csn 语言的自动翻译(新增)

调用 giipGraphifyRebuild 时,会按 该 csn 项目的语言设置(tCorp.cLang,例如 ko-KR、en-US — 项目管理界面中已可设置的既有值) 自动翻译节点标签后再保存。

执行时机: tKB 中的原始数据(title/content)始终按原样保存,与语言无关;在重建执行时 读取该 csn 的 cLang 值,用于翻译节点标签。
面向用户的要点: 在项目管理界面 更改 csn 的语言设置(cLang)后,从下一次调用 giipGraphifyRebuild 起,图谱中显示的文本语言就会改变。 无需修改原始 tKB 数据。
同一份 tKB 数据,在 cLang 设置不同的多个 csn 中,图谱节点可能显示为不同语言。
翻译在每次重建时都会重新执行(不缓存、不累积) — 原始 title/content 始终是最新来源。

快速开始 (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