4분 읽기

Graphify 데이터 추가 API

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

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

데이터 흐름은 2단계입니다: ① 항목 적재(giipKb) → ② 그래프 재빌드(giipGraphifyRebuild). 재빌드를 호출해야 새 항목이 그래프에 반영됩니다.

📦 데이터 저장 및 흐름 — tKB가 "진짜 저장소"다

⚠️ 가장 흔한 오해: "이슈를 등록했는데 그래프에 안 보인다"는 대부분 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가 그 csn의 tBlogGraphNodes/tBlogGraphEdges를
   │     통째로 DELETE 후 tKB로부터 재생성(적재만 하고 재빌드 안 하면 그래프는 그대로 안 바뀜)
   │   → DOC 노드(tKB 각 행=문서 하나) + TAG 노드(2개 이상 문서가 공유하는 태그만, 헤어볼 방지로
   │     너무 흔한 태그는 자동 제외) + doc→tag 엣지
   │   → (신규) 이 csn에 설정된 언어(tCorp.cLang)로 노드 라벨을 자동 번역해서 저장
   ▼
 tBlogGraphNodes / tBlogGraphEdges  (csn 스코프, 화면이 실제로 읽는 테이블)
   │ ③ 조회: GET /api/giipGraphifyTenant?csn= (엄격 격리, ak 인가) 또는 화면 /graphify?csn=
   ▼
 3D 지식 그래프 시각화

1단계(인제스트)만으로는 그래프에 아무것도 나타나지 않습니다. 반드시 2단계(재빌드)까지 호출해야 반영됩니다.
재빌드는 매번 전량 재생성입니다. 이전 그래프 상태를 이어받는 것이 아니라, 그 시점의 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 이슈가 있는 모든 csn에 대해 전날 하루치 이슈+코멘트를 모아 MiniMax로 요약한 뒤 giipKb를 통해 tKB에 INSERT합니다.
필드 값: 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 데이터라도 csn마다 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>/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>

필드	타입	필수	설명
`csn`	int	✅	프로젝트 번호. 키 권한 범위와 일치해야 함(기본 예시: 47)
`title`	string(200)	✅	노드 라벨
`content`	string		노드 상세 본문(마크다운 허용)
`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>

해당 csn의 그래프를 tKB로부터 재생성합니다(DOC 노드 + 변별력 태그 노드 + 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)" }

docNodes: 문서 노드 수, tagNodes: 태그 노드 수, edges: doc→tag 연결 수.

문제 해결

증상	원인	해결
그래프가 비어 보임	재빌드 미호출 / 잘못된 csn	`giipGraphifyRebuild` 호출, `?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