altair823
f9714aa5cb
마지막 commit. 모든 .md 안의 `kb` 단어 일괄 갱신. - 19 개 crate 이름 (`kb-core`, `kb-app`, …) → `kebab-*` (Rust 모듈 path 표기 `kb_*` → `kebab_*` 포함). - 미래 component (`kb-tui`, `kb-desktop`, `kb-asr-whisper`, `kb-ocr`, `kb-mcp`, `kb-vlm`, `kb-rerank`, `kb-vision-ocr`, `kb-index`, `kb-smoke`, `kb-architecture`) → `kebab-*` (P6+ 가 시작될 때 같은 prefix 사용). - CLI 명령 예제: `kb ingest` / `kb search` / `kb ask` / `kb init` / `kb doctor` / `kb inspect` / `kb list` / `kb eval` → `kebab <verb>`. fenced code block + 인라인 backtick 모두. - XDG paths + env vars + binary 경로 (`target/release/kb` → `target/release/kebab`) 동기화. - design doc / 최초 보고서 / SMOKE / HOTFIXES / phase epic / task spec 모든 reference 통일. - task-decomposition.md 의 `git -c user.name=kb` 는 과거 git history 기록용 author 정보라 그대로 유지 (실제 git history 의 author 는 변경 불가). - `tasks/phase-5-evaluation.md` 의 `status: planned` → `completed` 도 같이 (P5-1 + P5-2 PR 머지 후 미반영분). ## 검증 - `grep -rEn "\bkb-[a-z]|\bkb_[a-z]|\.config/kb\b|kb\.sqlite|\bKB_[A-Z]" --include="*.md"` 0 hits (task-decomposition.md 의 git author 제외). - 모든 file path reference 살아있음 (renamed file 들 모두 새 path 로 update). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
---
|
|
phase: P6
|
|
title: "이미지 ingestion (OCR + caption)"
|
|
status: planned
|
|
depends_on: [P5]
|
|
source: kebab_local_rust_report.md §9.1, §17 Phase 6
|
|
---
|
|
|
|
# P6 — 이미지 ingestion
|
|
|
|
## 목표
|
|
|
|
이미지 파일을 `CanonicalDocument` 로 변환. 동일 검색/RAG 파이프라인에 합류. citation 은 파일 + region.
|
|
|
|
## 산출 crate
|
|
|
|
- `kebab-parse-image` — `Extractor` 구현. 이미지 → CanonicalDocument.
|
|
- (선택) `kebab-ocr` / `kebab-vlm` 어댑터 (외부 모델 분리 시).
|
|
|
|
## 추출 정보 3종 (§9.1)
|
|
|
|
| 종류 | provenance.kind | 신뢰도 |
|
|
|------|-----------------|--------|
|
|
| 파일 metadata (경로, EXIF, 크기, mtime) | `metadata` | 높음 (관찰값) |
|
|
| OCR text + bounding box | `observed_text` | 높음 (관찰값) |
|
|
| AI caption / VLM 설명 | `model_caption` | 낮음 (생성값) |
|
|
| visual embedding | `visual_embedding` | 검색용 (의미값) |
|
|
|
|
핵심 규칙: **OCR 과 caption 을 같은 신뢰도로 취급 금지**. provenance 분리.
|
|
|
|
## CanonicalDocument 매핑
|
|
|
|
이미지 1장 → 1 document. blocks:
|
|
|
|
```rust
|
|
Block::ImageRef(ImageRefBlock {
|
|
asset_id,
|
|
caption: Option<String>, // model 생성, 신뢰도 낮음 표시
|
|
ocr_text: Option<OcrText>, // 관찰값
|
|
exif: Option<ExifMetadata>,
|
|
})
|
|
|
|
pub struct OcrText {
|
|
pub regions: Vec<OcrRegion>, // bounding box + text + confidence
|
|
pub joined: String, // 검색용 단일 문자열
|
|
pub engine: String, // "apple-vision" | "tesseract" | ...
|
|
pub engine_version: String,
|
|
}
|
|
```
|
|
|
|
## OCR 엔진 선택
|
|
|
|
- macOS 1차: Apple Vision text recognition (sidecar Swift 또는 Tauri command 통해 호출).
|
|
- cross-platform fallback: tesseract binding 또는 PaddleOCR sidecar.
|
|
- 1차 구현: 1개 엔진만. abstract trait `OcrEngine` 으로 교체 가능하게.
|
|
|
|
## VLM caption (선택, 후순위)
|
|
|
|
- local VLM (예: llava, qwen-vl) 통해 caption.
|
|
- caption 은 chunk text 에 포함하되 prefix 표시 (`[caption(model=...): ...]`).
|
|
- 검색 시 caption-only hit 는 별도 `retrieval_method = "vlm-caption"` 로 표기.
|
|
|
|
## Visual embedding (선택)
|
|
|
|
- CLIP 계열 image encoder.
|
|
- text embedding 과 차원/모델 다름 → 별도 LanceDB table (`image_embeddings`).
|
|
- text query → image 검색 = CLIP joint space 필요. 1차 구현은 OCR/caption text embedding 으로 충분.
|
|
|
|
## Chunking
|
|
|
|
- region-aware: OCR region 1개 또는 인접 region 묶음 = 1 chunk.
|
|
- caption 1개 = 별도 chunk (provenance 표시).
|
|
- chunker version: `image-region-v1`.
|
|
|
|
## Citation 형식
|
|
|
|
```text
|
|
photos/diagram-2026.png
|
|
photos/diagram-2026.png#region=120,40,520,180 # x,y,w,h
|
|
photos/diagram-2026.png#caption # caption chunk
|
|
```
|
|
|
|
## CLI
|
|
|
|
```text
|
|
kebab ingest ./assets/diagram.png
|
|
kebab ingest ./assets/ # 폴더 안 이미지 자동 인식
|
|
kebab search "이미지 안의 OCR 텍스트"
|
|
kebab inspect doc <image_doc_id> # OCR/caption/EXIF 모두 표시
|
|
```
|
|
|
|
## 테스트
|
|
|
|
- fixture: 한글 텍스트 이미지 + 영문 텍스트 이미지 + 텍스트 없는 사진.
|
|
- OCR region → CanonicalDocument round-trip.
|
|
- caption 이 chunk text 에 prefix 와 함께 들어가는지.
|
|
- 검색 결과에서 OCR hit 와 caption hit 구분 표기.
|
|
- 동일 이미지 재수집 시 idempotent (asset_id = blake3 동일).
|
|
|
|
## 의존성 경계
|
|
|
|
- `kebab-parse-image` 는 `kebab-core` + 이미지 디코딩 (`image` crate) + OCR adapter 만.
|
|
- LLM/embedding 호출 금지 (caption 은 별도 adapter 통해).
|
|
- VLM caption 은 background job. ingest blocking 금지.
|
|
|
|
## 완료 조건
|
|
|
|
- [ ] `kebab ingest <image>` 동작
|
|
- [ ] OCR text 검색 가능
|
|
- [ ] OCR region citation 출력
|
|
- [ ] caption 과 observed text provenance 분리
|
|
- [ ] EXIF 보존
|
|
- [ ] 같은 이미지 재수집 idempotent
|
|
|
|
## 리스크 / 주의
|
|
|
|
- OCR confidence 낮은 region 을 chunk 로 색인하면 noise. threshold 적용.
|
|
- caption hallucination = noise + 잘못된 RAG 인용 위험. citation 표기에서 caption 임을 항상 노출.
|
|
- Apple Vision sidecar 는 macOS 종속. linux 빌드는 다른 OCR 로 fallback.
|
|
- 대량 이미지 폴더 ingest 시 메모리/디스크 사용량 monitoring.
|