Graphify 지식 그래프 가이드

프로젝트의 문서·소스·태그를 3D 지식 그래프로 시각화하고 노드 간 연결을 탐색하는 방법을 안내합니다.

🚀 Graphify 페이지로 이동 →

📋 개요

Graphify는 선택된 프로젝트(csn)에 속한 문서, 소스 코드, 태그를 노드와 연결선으로 이루어진 3D 지식 그래프로 보여주는 화면입니다. 노드는 유형별로 색이 다르며, 연결의 중요도(가중 연결 수)를 기준으로 정렬되어 표시됩니다.

⚠️ 중요: Graphify는 tKB(지식베이스) 항목만 그래프로 보여줍니다 — giip 이슈, 서버 정보 등 다른 데이터는 자동으로 포함되지 않습니다. 프로젝트에 이슈나 다른 데이터가 있어도 tKB에 아직 아무것도 등록되지 않았다면 그래프는 비어 있습니다. tKB에 항목을 넣으려면 아래 API로 그래프 관리하기 섹션을 참고하세요.

🔍 주요 요소 설명

1. 상단 헤더

현재 렌더링된 노드 수와 전체 노드 수, 그리고 연결선 수를 표시 / 전체 nodes · N links 형식으로 보여줍니다.

2. 노드 검색

헤더의 검색창에 라벨 또는 경로(path)의 일부를 입력하면 전체 노드 집합에서 일치하는 노드를 찾아 좌측에 결과 목록으로 표시합니다. 결과를 클릭하면 해당 노드가 그래프에 나타나며 선택됩니다.

3. 3D 그래프 캔버스

노드는 유형에 따라 색으로 구분됩니다. 좌측 하단 범례에 표시된 대로 Doc / Spec(황색), Code / Source(하늘색), Tag(녹색)입니다. 노드를 클릭하면 해당 노드를 선택하여 인스펙터를 열고, 배경을 클릭하면 선택이 해제됩니다.

4. 노드 인스펙터 (우측 패널)

선택한 노드의 유형 배지, 연결 수, 경로를 보여주며 두 가지 관계 목록을 제공합니다.

• Backlinks: 이 노드를 가리키는(들어오는) 노드 목록
• Outgoing links: 이 노드가 가리키는(나가는) 노드 목록

목록의 항목을 클릭하면 그 노드로 이동(드릴다운)하며, 이전 노드로 돌아가려면 패널 좌상단의 뒤로 가기 버튼을 사용합니다.

5. 문서 본문 팝업

인스펙터의 노드 제목을 클릭하면 레이어 팝업이 열립니다. 노드가 KB 문서(경로가 kb/<번호>)인 경우 문서 본문 전체를 마크다운으로 보여줍니다. 그 외 노드에는 표시할 본문이 없다는 안내가 나타납니다. Esc 키로 팝업을 닫을 수 있습니다.

6. Refresh / Rebuild 버튼

헤더의 [Refresh] 버튼은 그래프 데이터를 다시 불러옵니다(재빌드와는 다름). [Rebuild] 버튼은 이 프로젝트(csn)의 tKB 항목들로부터 그래프(노드·엣지)를 다시 생성합니다. 로그인한 사용자만 Rebuild를 사용할 수 있으며, 완료되면 자동으로 그래프가 새로고침됩니다. Rebuild는 프로젝트 규모에 따라 수 초~수십 초가 걸릴 수 있습니다(로딩 표시로 확인 가능). tKB에 새 항목을 추가/수정/삭제한 뒤에는 반드시 Rebuild를 눌러야 그래프에 반영됩니다.

🛠️ 활용 팁

• 더 보기: 그래프는 성능을 위해 중요도 상위 50개 노드만 먼저 표시합니다. 하단 중앙의 [Load N more] 버튼으로 다음 50개를 추가로 불러올 수 있습니다.
• 새로고침: 헤더 우측의 [Refresh] 버튼을 누르면 그래프 데이터를 다시 불러옵니다(Rebuild와는 다름 — Rebuild는 옆의 [Rebuild] 버튼을 사용하세요).

💡 유의 사항

• 프로젝트가 선택되지 않으면 "No Project Selected" 화면이 표시됩니다. 상단 내비게이션에서 프로젝트를 선택하세요.
• 그래프 조회는 로그인 없이도 가능하지만, KB 문서의 본문은 로그인(인증 토큰)이 있어야 열람할 수 있습니다.

🔌 API로 그래프 관리하기 (추가·수정·삭제·재빌드)

💡 일반적인 사용에는 화면의 [재빌드] 버튼(위 "주요 요소 설명" 참고)을 쓰면 충분합니다. 아래 API 방법은 버튼을 쓸 수 없는 경우(스크립트/자동화, 대량 등록 등)를 위한 것입니다.

Graphify 그래프는 KB 항목(tKB)에서 파생됩니다. 항목을 API로 추가·수정·삭제한 뒤 재빌드를 호출하면 그래프에 반영됩니다. 연결(엣지)은 사람이 직접 긋는 것이 아니라 재빌드가 항목들로부터 자동 생성합니다.

• 호스트: https://giipfaw.azurewebsites.net
• 인증: 모든 쓰기 API는 헤더 x-api-key에 로그인 사용자의 AK 또는 프로젝트 스코프 SK가 필요합니다. 키는 자신의 csn 범위 안에서만 추가·수정·삭제·재빌드할 수 있습니다.
• 작업 흐름: 추가/수정/삭제(giipKb) → 재빌드(giipGraphifyRebuild) → 확인(giipGraphify)

1) 노드 추가 — giipKb POST

curl -X POST "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <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"}'

• title이 그래프의 노드 라벨, content는 노드 클릭 시 열리는 본문 팝업(마크다운)입니다.
• extRefId를 지정하면 멱등 upsert — 같은 값으로 다시 보내면 새로 만들지 않고 갱신합니다.
• 응답: { "success": true, "kbSn": 844, "message": "..." }

2) 노드 수정 — giipKb PUT

curl -X PUT "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"kbSn":844,"title":"OAuth 콜백 500 (해결)","content":"## 조치\n타임아웃 30s→90s","tags":"auth,oauth,resolved"}'

• kbSn으로 수정할 항목을 지정합니다.

3) 노드 삭제 — giipKb DELETE

curl -X DELETE "https://giipfaw.azurewebsites.net/api/giipKb?kbSn=844" \
  -H "x-api-key: <AK_OR_SK>"

4) 재빌드 (연결 생성) — giipGraphifyRebuild POST

항목을 추가/수정/삭제한 뒤 반드시 호출해야 그래프에 반영됩니다. 해당 csn의 노드·엣지를 KB 항목들로부터 다시 생성합니다.

curl -X POST "https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild" \
  -H "x-api-key: <AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47}'

• 응답: { "success": true, "csn": 47, "nodes": 838, "edges": 11, "message": "Graph rebuilt" }
• 선택 파라미터(대용량 프로젝트 성능 튜닝):
  • maxNodes: 그래프화할 최신 항목 상한 (기본 400)
  • scanLen: 연결 탐색 시 본문 앞부분 스캔 길이 (기본 1500)

  -d '{"csn":47,"maxNodes":800,"scanLen":2000}'

5) 그래프 조회 — giipGraphify GET

페이지가 내부적으로 사용하는 읽기 API입니다(인증 없이 조회 가능). 직접 확인할 때:

curl "https://giipfaw.azurewebsites.net/api/giipGraphify?csn=47"

• 응답: { "nodes": [...], "links": [...] }

필드 전체 사양은 📘 API 레퍼런스 개요 를 참조하세요.

📦 데이터는 어디에 저장되나요? (요약)

API로 추가한 항목은 tKB 테이블에 저장되며, 그래프 테이블(tBlogGraphNodes/tBlogGraphEdges)은 재빌드를 호출할 때마다 tKB로부터 새로 만들어지는 파생 결과입니다. tKB에 없는 데이터는 아무리 재빌드해도 그래프에 나타나지 않습니다 — "이슈는 있는데 그래프에 안 보인다"의 대부분 원인이 여기 있습니다.

(이미 운영 중) giip 세션이 축적한 엔지니어링 노하우(K-Layer)는 매일 자동으로 refType='k-layer-daily'(태그 k-layer-wiki,daily)로 tKB에 적재됩니다 — 이 문서들도 다음 Rebuild 때 DOC 노드로 흡수되어 날짜별 클러스터로 보입니다. (신규) 재빌드 시 그 csn의 프로젝트 언어 설정(cLang)에 맞춰 그래프 텍스트를 자동 번역하는 기능도 추가되었습니다. csn의 언어 설정을 바꾸면 다음 Rebuild부터 그래프 표시 언어가 바뀝니다. 상세 데이터 흐름과 필드 설명은 📘 API 레퍼런스 개요 의 "데이터 저장 및 흐름" 섹션을 참고하세요.

문제 해결

증상	원인	해결
"No Project Selected"만 표시됨	프로젝트(csn)가 지정되지 않음	상단에서 프로젝트를 선택합니다.
문서 본문 팝업에 "로그인이 필요합니다" 표시	KB 본문 조회에 인증 토큰이 없음	로그인 후 다시 노드 제목을 클릭합니다.
노드에 본문이 없다고 표시됨	해당 노드가 KB 문서(kb/…)가 아님	본문은 KB 문서 노드에만 제공됩니다. 정상 동작입니다.
일부 노드가 그래프에 보이지 않음	중요도 상위 50개만 우선 표시됨	하단 [Load N more]로 추가 노드를 불러오거나 검색으로 해당 노드를 찾습니다.
API Error 또는 로딩 실패	세션 만료 또는 서버 응답 오류	오류 배너의 [Retry]를 누르거나 다시 로그인합니다.
이슈/데이터가 있는데 그래프가 비어있음	tKB에 아직 반영 안 됨	재빌드 버튼을 누르기 전에 먼저 giipKb API로 내용을 tKB에 추가해야 합니다(위 API 섹션 참조).

---

버전: 1.1 최종 업데이트: 2026-09-06 소스 파일: giipv3/public/help/graphify.ko.md