Graphify 지식 그래프 가이드

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

🚀 Graphify 페이지로 이동 →

📋 개요

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

🔍 주요 요소 설명

1. 상단 헤더

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

2. 노드 검색

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

3. 3D 그래프 캔버스

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

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

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

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

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

5. 문서 본문 팝업

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

🛠️ 활용 팁

더 보기: 그래프는 성능을 위해 중요도 상위 50개 노드만 먼저 표시합니다. 하단 중앙의 [Load N more] 버튼으로 다음 50개를 추가로 불러올 수 있습니다.
동기화: 헤더 우측의 [Sync] 버튼을 누르면 그래프 데이터를 다시 불러옵니다.

💡 유의 사항

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

🔌 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 레퍼런스 개요 를 참조하세요.

문제 해결

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

버전: 1.0 최종 업데이트: 2026-07-22 소스 파일: giipv3/public/help/graphify.ko.md

← PreviousNetwork Topology Next →Process List