giip

Graphify 데이터 추가 API

🔌 Graphify 페이지로 이동 →](/ko/graphify)

Graphify는 지식베이스(tKB) 항목을 3D 지식 그래프로 시각화합니다. 이 문서는 API로 데이터를 추가하고, 정보가 잘 보이도록 호출하는 방법을 설명합니다.

데이터 흐름은 2단계입니다: ① 항목 적재(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>/ko/graphify?csn=47

인증 키(x-api-key)는 로그인 사용자의 AK 또는 프로젝트 스코프 SK를 사용합니다. 키는 자신의 csn 범위로만 데이터를 추가/재빌드할 수 있습니다.

⭐ 정보가 잘 보이게 하는 법 (핵심)

Graphify는 태그 이분(bipartite) 그래프입니다. 즉 문서는 "공유 태그"를 통해 서로 연결됩니다(태그가 1급 노드). 따라서 태그를 어떻게 붙이느냐가 그래프 품질을 좌우합니다.

좋은 태그 (연결이 잘 생김)

  • 2~50개 항목이 공유하는 의미 있는 태그를 사용하세요. 예: auth, billing, timeout, payment, login.
  • 같은 주제의 항목들이 공유 태그 노드를 중심으로 클러스터를 이룹니다.

피해야 할 태그

나쁜 패턴왜 안 좋은가결과
항목마다 유일한 태그 (예: 파일명 report_2026_01.md)공유하는 항목이 없음(DF=1)아무것도 연결 안 됨 → 고립 노드
거의 모든 항목에 붙는 제네릭 태그 (예: doc, sync, general)문서빈도(DF)가 너무 높음자동 필터링되어 엣지에서 제외(헤어볼 방지)

규칙 요약: 너무 흔하지도, 너무 유일하지도 않은 태그가 좋은 연결을 만듭니다. 기본적으로 한 csn 안에서 DF(문서빈도)가 2~50인 태그만 태그 노드가 됩니다.

그 외 표시 팁

  • title: 그래프의 노드 라벨이 됩니다. 짧고 명확하게.
  • content: 노드를 클릭하면 상세 팝업 본문으로 마크다운 렌더됩니다.
  • extRefId: 외부 시스템의 항목 ID. 재동기화 시 **중복 생성 없이 갱신(멱등)**됩니다.
  • 재빌드 필수: 항목만 추가하고 재빌드를 안 하면 그래프는 그대로입니다. 배치 적재 후 giipGraphifyRebuild를 한 번 호출하세요.

상세 기능 · API 참조

1) 항목 적재 — giipKb

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

필드타입필수설명
csnint✅프로젝트 번호. 키 권한 범위와 일치해야 함(기본 예시: 47)
titlestring(200)✅노드 라벨
contentstring노드 상세 본문(마크다운 허용)
tagsstring(500)콤마 구분 태그. 연결의 핵심(위 "좋은 태그" 참조)
refTypestring(50)✅항목 종류. 예: ISSUE, GENERAL, GUIDE
extRefIdstring(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>

해당 csn의 그래프를 tKB로부터 재생성합니다(DOC 노드 + 변별력 태그 노드 + doc→tag 엣지).

필드타입필수설명
csnint✅재빌드할 프로젝트 번호
maxTagDFint제네릭 태그 컷(문서빈도 상한, 기본 50). 이보다 흔한 태그는 제외
maxNodesintDOC 노드 안전상한(기본 20000)

응답

{ "success": true, "nodes": 838, "edges": 11, "docNodes": 835, "tagNodes": 3, "message": "Graph rebuilt (tag-bipartite)" }
  • docNodes: 문서 노드 수, tagNodes: 태그 노드 수, edges: doc→tag 연결 수.

문제 해결

증상원인해결
그래프가 비어 보임재빌드 미호출 / 잘못된 csngiipGraphifyRebuild 호출, ?csn= 확인
노드는 많은데 연결이 거의 없음태그가 유일(DF=1)하거나 제네릭(DF 과다)2~50개가 공유하는 의미 태그로 재적재 후 재빌드
같은 항목이 중복 생성extRefId 미사용extRefId를 넣어 멱등 적재
401/403키 없음 / 다른 csn올바른 x-api-key와 자기 csn 사용

메타데이터

  • 소스 파일: giipv3/public/help/api-graphify.ko.md
  • raw 원문 경로: /help/api-graphify.ko.md
  • 관련 API: giipfaw/giipKb, giipfaw/giipGraphifyRebuild
  • 관련 페이지: /[locale]/graphify
← Previous시스템 관리 APINext →KVS(키-값 저장소) API