지식 베이스 구축 (Ingest · Caption figures)
이 장에서 다루는 것
Knowledge 탭의 Source Ingest 는 변환된 Markdown을 읽어 지식 베이스(온톨로지 페이지)를 만듭니다. 이 장은 Source Ingest를 실행하는 법, 실행 중과 완료 후의 화면을 읽는 법, 만들어진 페이지를 확인하는 법, 그리고 문서에서 추출된 그림에 캡션을 붙이는 법을 다룹니다.
- 대상 독자: 입력 문서의 Markdown 변환을 마친 사용자
- 선행 조건: 앞 장에서 만든
Wiki/raw/<문서>/<문서>.md
Ingest와 Caption figures는 Claude를 호출하며 과금됩니다. Ingest는 AI 연결 여부를 확인하지 않고 실행되므로, 연결 없이 실행하면 모델 호출이 실패해
not connected가 포함된 경고가 남습니다. 실행 전에 헤더의 AI 상태가 초록 점인지 확인하세요.
Source Ingest 실행
- ① Knowledge 탭을 누릅니다. 왼쪽 레일에 아이콘 4 개(Knowledge, Ingest, Index, Graph)가 있고, 두 번째 Ingest 아이콘이 Source Ingest 화면입니다.
- 화면 아래 Input Documents 표에서 변환된
.md파일의 Status 가 Ready 인지 확인합니다. Ready 는 지원되는 형식이고 아직 인제스트되지 않았다는 뜻입니다(Ingested = 이미 인제스트됨, Skipped = 변환 로그 같은 메타데이터 파일, Unsupported = 지원하지 않는 확장자). - ② 오른쪽 위의 두 드롭다운에서 모델과 effort를 고릅니다. 기본값은 Default · sonnet 과 Default · high 이고, 모델은 opus / sonnet / haiku, effort는 low / medium / high 중에서 바꿀 수 있습니다.
- ③ Run Ingest 를 누릅니다. 실행 중에는 버튼이 Ingesting 으로 바뀝니다.
① Knowledge 탭의 Source Ingest 화면입니다. ② 모델(Default · sonnet)과 effort(Default · high) 드롭다운, ③ Run Ingest 버튼. 아래 Input Documents 표에서 변환된 .md 는 Ready, _conversion.log 는 Skipped 입니다. Source coverage 는 아직 측정 전이라 Not measured yet 입니다.
실행 중 화면
실행이 시작되면 화면 위쪽에 Knowledge ingest 진행 배너가 나타납니다. 진행 문구는 ingest 0/1 · extracting <파일> 처럼 페이즈·개수·현재 파일을 보여 주고, 그 아래에 선택한 모델·effort가 표시됩니다. 배너의 버튼은 다음과 같습니다.
- Pause — 진행 중인 Claude 호출이 끝난 뒤 다음 경계에서 멈춥니다. 이미 과금된 작업은 잃지 않습니다.
- Stop — 실행을 중단합니다.
진행 배너입니다. Knowledge ingest 작업이 ingest 0/1 · extracting Wiki/raw/…/Battery Pack Functional Requirements and KPIs.md 단계에 있고, 아래 줄에 sonnet · medium 이 보입니다(이 예시는 effort를 medium으로 바꿔 실행했습니다). 오른쪽의 Open / Pause / Stop 으로 작업을 다룹니다.
인제스트가 멈춘 채 앱을 종료해도 진행 상황은 디스크에 남습니다. 앱을 다시 열면 Unfinished ingest found 배너에 완료된 창 수(
N/M discovered window(s) done)와 Resume 버튼이 나타나고, 이미 끝난 부분은 다시 과금되지 않습니다.
완료 화면 읽기
- 실행이 끝나면 ① Ingest complete 패널이 나타나고 Preserved progress: N/N discovered window(s). Completed work is kept on disk. 가 표시됩니다. 그 아래 한 줄이 결과 요약입니다(예: Ingested 128 page(s), 4 warning(s).).
- ② 경고 목록은 실패가 아니라 참고 사항입니다. 자주 보이는 네 가지는 다음과 같습니다.
| 경고(앞부분) | 뜻 |
|---|---|
format profile … | 그 파일에서 요구사항 표기 규칙·표 형식을 추론하지 못했습니다. 파일은 구조가 덜 잡힌 채로 인제스트됩니다. |
LLM call #N failed transiently (retry i/N) | 호출 하나가 실패해 재시도했습니다. 실행이 끝났다면 무해합니다. |
block delimiter glued mid-line … | 모델이 페이지 구분자 앞의 줄바꿈을 빠뜨려, 그 페이지가 앞 페이지에 합쳐졌습니다. |
source_ref gate: injected N [INFO-INSUFFICIENT: source_ref missing] mark(s) … | 근거 없이 쓰인 문단에 표시를 넣었습니다. 페이지는 삭제되지 않고 유지됩니다. |
① Ingest complete 패널 — Preserved progress: 6/6 discovered window(s). Completed work is kept on disk. 와 그 아래의 요약 Ingested 128 page(s), 4 warning(s). ② 경고 네 건은 위 표의 네 종류가 하나씩 나온 것입니다. Input Documents 의 .md 상태는 Ingested 로 바뀌었고, Source coverage 의 예상 문구는 이제 against 128 wiki page(s) 로 끝납니다.
만들어진 페이지 확인
- 왼쪽 레일의 첫 번째 ① Knowledge 아이콘을 누릅니다. 왼쪽에 페이지 목록(타입별: CONCEPT, REQUIREMENT …), 가운데에 RELATIONSHIP GRAPH, 오른쪽에 선택한 페이지의 내용이 보입니다.
- 페이지 본문의 문단 끝에는 ②
(source_ref: <파일> <위치>)칩이 붙어 있습니다. 이 칩이 그 문단의 근거가 된 입력 문서와 위치입니다. 근거 없이 쓰인 문단에는[INFO-INSUFFICIENT: …]표시가 대신 붙습니다.
① 레일의 Knowledge 아이콘을 누르면 세 열 화면이 됩니다. 왼쪽 목록은 CONCEPT, REQUIREMENT 같은 타입별로 묶여 있고, 가운데 RELATIONSHIP GRAPH 는 페이지 사이의 관계입니다. 오른쪽 페이지(타입 드롭다운이 CONCEPT)의 문단마다 ② (source_ref: Battery Pack Functional Requirements and KPIs.md doc) 칩이 붙어 있어 어느 문서에서 왔는지 알 수 있습니다. TYPE 행의 Edit / Delete 로 페이지를 직접 고치거나 지울 수 있습니다.
그림 캡션 생성 (Caption figures)
문서 변환 때 Wiki/raw/<문서>/images/ 에 추출된 그림에는 아직 설명이 없습니다. Caption figures 는 Claude vision으로 그림마다 설명을 만들어 Wiki/figures/<문서>.md 에 추가합니다.
- Source Ingest 화면(레일의 Ingest 아이콘)에서 Caption figures (vision — billed per image) 버튼을 누릅니다.
완료 패널 아래쪽에 있는 Caption figures (vision — billed per image) 버튼입니다. 옆의 설명대로 추출된 그림을 Claude vision으로 설명해 Wiki/figures/ 에 넣으며, 이미 캡션이 있는 그림은 다시 과금하지 않습니다.
- 실행 중에는 버튼이 Captioning figures… 로 바뀌고 비활성화됩니다. 끝나면 버튼 아래에 Last run: 으로 시작하는 결과 줄이 나타나 적용된 수, 판독 가능·정보 부족 수, 장식용으로 건너뛴 수, 과금된 호출 수를 보여 줍니다.
실행 중에는 버튼이 Captioning figures… 로 바뀝니다. 끝날 때까지 다시 누를 수 없습니다.
이미지마다 과금됩니다. 다만 같은 그림을 두 번 과금하지는 않습니다 — 처리 장부에 기록된 그림은 호출 전에 건너뛰고, 장부가 없어도
Wiki/figures/파일 안의 표식을 보고 다시 붙이지 않습니다. 중간에 멈춰도 다시 누르면 남은 그림만 처리합니다.
다음 단계
지식 베이스가 준비되었습니다. 워크플로 실행에서 Workflow 탭의 Run 으로 A-SPICE 산출물 생성을 시작합니다.