altair823-org/kebab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

chore(ingest): PR #204 회차1 리뷰 반영 — 버전 라벨 v0.26.0 → v0.27.0

Browse Source 
신규 진행로깅 표면(asset_phase / ocr_ms / caption_ms + progress.rs heartbeat·
slowest 주석)이 v0.26.0 으로 잘못 표기돼 있던 것을 v0.27.0(실제 추가 버전)으로
정정. wire schema 의 "추가 버전" 정확성(외부 통합 참조). 로직 변경 없음(주석/doc).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
altair823
2026-06-03 10:57:17 +00:00
parent aeaa18a564
commit 4918983d9c
5 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
crates/kebab-app/src/ingest_progress.rs
View File

@@ -96,7 +96,7 @@ pub enum IngestEvent {
/// `idx/total` while its per-chunk phases churn. `chunks` is the chunk /// `idx/total` while its per-chunk phases churn. `chunks` is the chunk
/// count for asset `idx`. /// count for asset `idx`.
AssetChunked { idx: u32, total: u32, chunks: u32 }, AssetChunked { idx: u32, total: u32, chunks: u32 },
/// v0.26.0 (additive): emitted when an asset enters a *slow* internal /// v0.27.0 (additive): emitted when an asset enters a *slow* internal
/// phase, so the interactive progress bar can show **which** phase /// phase, so the interactive progress bar can show **which** phase
/// (and which model) is currently running instead of looking frozen. /// (and which model) is currently running instead of looking frozen.
/// `phase` ∈ {`"ocr"`, `"caption"`, `"embed"`}; short phases /// `phase` ∈ {`"ocr"`, `"caption"`, `"embed"`}; short phases
@@ -121,8 +121,8 @@ pub enum IngestEvent {
/// them so the slowest-asset summary attributes vision-model time /// them so the slowest-asset summary attributes vision-model time
/// correctly. `expansion_ms` is retained for wire compatibility but is /// correctly. `expansion_ms` is retained for wire compatibility but is
/// always 0 since doc-side expansion was removed (HOTFIXES 2026-06-03). /// always 0 since doc-side expansion was removed (HOTFIXES 2026-06-03).
/// `ocr_ms` / `caption_ms` (v0.26.0) are additive with serde default 0 /// `ocr_ms` / `caption_ms` (v0.27.0) are additive with serde default 0
/// so pre-v0.26.0 consumers deserialize cleanly. /// so pre-v0.27.0 consumers deserialize cleanly.
AssetTimings { AssetTimings {
idx: u32, idx: u32,
total: u32, total: u32,
@@ -312,7 +312,7 @@ mod tests {
#[test] #[test]
fn asset_timings_ocr_caption_default_to_zero_for_legacy_wire() { fn asset_timings_ocr_caption_default_to_zero_for_legacy_wire() {
// v0.26.0 additive: a pre-v0.26.0 wire payload omits ocr_ms / // v0.27.0 additive: a pre-v0.27.0 wire payload omits ocr_ms /
// caption_ms; serde `default` must fill 0 so old producers stay // caption_ms; serde `default` must fill 0 so old producers stay
// compatible. // compatible.
let legacy = serde_json::json!({ let legacy = serde_json::json!({
@@ -339,7 +339,7 @@ mod tests {
#[test] #[test]
fn asset_phase_serializes_with_discriminator() { fn asset_phase_serializes_with_discriminator() {
// v0.26.0 additive variant — `kind` must be snake_case // v0.27.0 additive variant — `kind` must be snake_case
// `asset_phase`, `phase` is the slow-phase label, `model` the // `asset_phase`, `phase` is the slow-phase label, `model` the
// model id (nullable). // model id (nullable).
let ev = IngestEvent::AssetPhase { let ev = IngestEvent::AssetPhase {

8
crates/kebab-app/src/lib.rs
View File

@@ -1350,7 +1350,7 @@ fn ingest_one_asset(
let store_ms = u64::try_from(t_store.elapsed().as_millis()).unwrap_or(u64::MAX); let store_ms = u64::try_from(t_store.elapsed().as_millis()).unwrap_or(u64::MAX);
// Embed + vector upsert (only when both sides are configured). // Embed + vector upsert (only when both sides are configured).
// v0.26.0: surface the embed phase + model so a long embed run reads as // v0.27.0: surface the embed phase + model so a long embed run reads as
// "embedding(<model>)…" rather than a frozen bar (markdown path too). // "embedding(<model>)…" rather than a frozen bar (markdown path too).
crate::ingest_progress::emit( crate::ingest_progress::emit(
progress, progress,
@@ -1578,7 +1578,7 @@ fn ingest_one_image_asset(
let lang_hint = lang_hint_from_doc(&canonical); let lang_hint = lang_hint_from_doc(&canonical);
let now = time::OffsetDateTime::now_utc(); let now = time::OffsetDateTime::now_utc();
let mut warning_notes: Vec<String> = Vec::new(); let mut warning_notes: Vec<String> = Vec::new();
// v0.26.0: vision phases (OCR / caption) are the usual bottleneck on an // v0.27.0: vision phases (OCR / caption) are the usual bottleneck on an
// image-heavy vault and emitted no progress before — so the bar looked // image-heavy vault and emitted no progress before — so the bar looked
// frozen. Surface each as an `AssetPhase` and measure its wall-clock for // frozen. Surface each as an `AssetPhase` and measure its wall-clock for
// the slowest-asset summary. // the slowest-asset summary.
@@ -1771,7 +1771,7 @@ fn ingest_one_image_asset(
} }
let embed_ms = u64::try_from(t_embed.elapsed().as_millis()).unwrap_or(u64::MAX); let embed_ms = u64::try_from(t_embed.elapsed().as_millis()).unwrap_or(u64::MAX);
// v0.26.0: per-phase timing for the image path — ocr_ms / caption_ms // v0.27.0: per-phase timing for the image path — ocr_ms / caption_ms
// carry the vision-model cost so the slowest-asset summary attributes // carry the vision-model cost so the slowest-asset summary attributes
// an image-heavy run's bottleneck correctly. // an image-heavy run's bottleneck correctly.
crate::ingest_progress::emit( crate::ingest_progress::emit(
@@ -2360,7 +2360,7 @@ fn ingest_one_pdf_asset(
} }
let embed_ms = u64::try_from(t_embed.elapsed().as_millis()).unwrap_or(u64::MAX); let embed_ms = u64::try_from(t_embed.elapsed().as_millis()).unwrap_or(u64::MAX);
// v0.26.0: per-phase timing for the PDF path. `ocr_ms` reuses the // v0.27.0: per-phase timing for the PDF path. `ocr_ms` reuses the
// page-OCR total already computed above so a scanned-PDF run's OCR cost // page-OCR total already computed above so a scanned-PDF run's OCR cost
// shows up in the slowest-asset summary; caption is markdown/image-only. // shows up in the slowest-asset summary; caption is markdown/image-only.
crate::ingest_progress::emit( crate::ingest_progress::emit(

32
crates/kebab-cli/src/progress.rs
View File

@@ -32,7 +32,7 @@ use time::format_description::well_known::Rfc3339;
use crate::wire; use crate::wire;
/// v0.26.0: number of slowest assets surfaced in the end-of-run summary. /// v0.27.0: number of slowest assets surfaced in the end-of-run summary.
/// Constant for now (spec defers the config knob). /// Constant for now (spec defers the config knob).
const SLOWEST_TOP_N: usize = 5; const SLOWEST_TOP_N: usize = 5;
@@ -72,19 +72,19 @@ impl ProgressMode {
pub struct ProgressDisplay { pub struct ProgressDisplay {
mode: ProgressMode, mode: ProgressMode,
bar: Option<ProgressBar>, bar: Option<ProgressBar>,
/// v0.26.0 heartbeat: start `Instant` of the asset currently in /// v0.27.0 heartbeat: start `Instant` of the asset currently in
/// flight, shared with the bar's steady-tick custom template key so /// flight, shared with the bar's steady-tick custom template key so
/// the `(Ns)` elapsed counter advances *between* events (the drain /// the `(Ns)` elapsed counter advances *between* events (the drain
/// loop blocks on `recv()`, so without the ticker the counter would /// loop blocks on `recv()`, so without the ticker the counter would
/// freeze). `None` while scanning / between assets / after completion. /// freeze). `None` while scanning / between assets / after completion.
asset_start: Arc<Mutex<Option<Instant>>>, asset_start: Arc<Mutex<Option<Instant>>>,
/// v0.26.0: workspace path of the asset currently in flight — set on /// v0.27.0: workspace path of the asset currently in flight — set on
/// `AssetStarted`, reused by `AssetPhase` to render `{path} · {phase}…`. /// `AssetStarted`, reused by `AssetPhase` to render `{path} · {phase}…`.
current_path: Option<String>, current_path: Option<String>,
/// v0.26.0 slowest summary: idx → path, captured from `AssetStarted` /// v0.27.0 slowest summary: idx → path, captured from `AssetStarted`
/// so `AssetTimings` (which only carries `idx`) can name the asset. /// so `AssetTimings` (which only carries `idx`) can name the asset.
asset_paths: HashMap<u32, String>, asset_paths: HashMap<u32, String>,
/// v0.26.0 slowest summary: (path, total_ms) per asset that reported /// v0.27.0 slowest summary: (path, total_ms) per asset that reported
/// `AssetTimings`. Sorted + truncated to top-N on `Completed`. /// `AssetTimings`. Sorted + truncated to top-N on `Completed`.
timings: Vec<(String, u64)>, timings: Vec<(String, u64)>,
} }
@@ -151,7 +151,7 @@ impl ProgressDisplay {
if let Some(bar) = self.bar.as_mut() { if let Some(bar) = self.bar.as_mut() {
bar.set_length(u64::from(*total)); bar.set_length(u64::from(*total));
bar.set_position(0); bar.set_position(0);
// v0.26.0: a custom `{asset_elapsed}` key reads the shared // v0.27.0: a custom `{asset_elapsed}` key reads the shared
// per-asset start `Instant` and appends ` (Ns)`. Combined // per-asset start `Instant` and appends ` (Ns)`. Combined
// with the steady tick below, the elapsed counter advances // with the steady tick below, the elapsed counter advances
// even while the drain loop is blocked on `recv()` waiting // even while the drain loop is blocked on `recv()` waiting
@@ -198,18 +198,18 @@ impl ProgressDisplay {
path, path,
media, media,
} => { } => {
// v0.26.0: remember the path so AssetPhase can render it and // v0.27.0: remember the path so AssetPhase can render it and
// the slowest summary (keyed by idx in AssetTimings) can name // the slowest summary (keyed by idx in AssetTimings) can name
// the asset. // the asset.
self.current_path = Some(path.clone()); self.current_path = Some(path.clone());
self.asset_paths.insert(*idx, path.clone()); self.asset_paths.insert(*idx, path.clone());
// v0.26.0: (re)start the per-asset heartbeat clock. // v0.27.0: (re)start the per-asset heartbeat clock.
if let Ok(mut guard) = self.asset_start.lock() { if let Ok(mut guard) = self.asset_start.lock() {
*guard = Some(Instant::now()); *guard = Some(Instant::now());
} }
if let Some(bar) = self.bar.as_ref() { if let Some(bar) = self.bar.as_ref() {
bar.set_position(u64::from(idx.saturating_sub(1))); bar.set_position(u64::from(idx.saturating_sub(1)));
// v0.26.0: show the current filename on the bar (TTY). // v0.27.0: show the current filename on the bar (TTY).
// Previously position-only — the interactive user couldn't // Previously position-only — the interactive user couldn't
// tell which file was in flight. The steady tick redraws // tell which file was in flight. The steady tick redraws
// in place, so this no longer pollutes scrollback. // in place, so this no longer pollutes scrollback.
@@ -222,7 +222,7 @@ impl ProgressDisplay {
} }
IngestEvent::AssetFinished { .. } => { IngestEvent::AssetFinished { .. } => {
// Position is advanced in AssetStarted; bar.finish_and_clear() // Position is advanced in AssetStarted; bar.finish_and_clear()
// in Completed handles the final state. v0.26.0: stop the // in Completed handles the final state. v0.27.0: stop the
// heartbeat clock so the bar doesn't show a stale `(Ns)` in the // heartbeat clock so the bar doesn't show a stale `(Ns)` in the
// gap before the next AssetStarted. // gap before the next AssetStarted.
if let Ok(mut guard) = self.asset_start.lock() { if let Ok(mut guard) = self.asset_start.lock() {
@@ -230,7 +230,7 @@ impl ProgressDisplay {
} }
self.current_path = None; self.current_path = None;
} }
// v0.26.0: an asset entered a slow internal phase (ocr / caption / // v0.27.0: an asset entered a slow internal phase (ocr / caption /
// embed). Surface which phase + model is running so a multi-second // embed). Surface which phase + model is running so a multi-second
// vision-model call no longer looks frozen. // vision-model call no longer looks frozen.
IngestEvent::AssetPhase { IngestEvent::AssetPhase {
@@ -276,7 +276,7 @@ impl ProgressDisplay {
caption_ms, caption_ms,
.. ..
} => { } => {
// v0.26.0: accumulate (path, total_ms) for the slowest summary. // v0.27.0: accumulate (path, total_ms) for the slowest summary.
// total = every measured phase (expansion_ms is always 0). // total = every measured phase (expansion_ms is always 0).
let total_ms = parse_ms + chunk_ms + embed_ms + store_ms + ocr_ms + caption_ms; let total_ms = parse_ms + chunk_ms + embed_ms + store_ms + ocr_ms + caption_ms;
if let Some(path) = self.asset_paths.get(idx) { if let Some(path) = self.asset_paths.get(idx) {
@@ -287,7 +287,7 @@ impl ProgressDisplay {
} }
if !quiet { if !quiet {
let mut err = std::io::stderr().lock(); let mut err = std::io::stderr().lock();
// v0.26.0: only print ocr / caption when they actually ran // v0.27.0: only print ocr / caption when they actually ran
// (markdown leaves them 0) so the text path stays uncluttered. // (markdown leaves them 0) so the text path stays uncluttered.
let mut parts = vec![ let mut parts = vec![
format!("parse {}", fmt_ms(*parse_ms)), format!("parse {}", fmt_ms(*parse_ms)),
@@ -320,7 +320,7 @@ impl ProgressDisplay {
"ingest: complete (scanned={} new={} updated={} skipped={} errors={})", "ingest: complete (scanned={} new={} updated={} skipped={} errors={})",
counts.scanned, counts.new, counts.updated, counts.skipped, counts.errors, counts.scanned, counts.new, counts.updated, counts.skipped, counts.errors,
); );
// v0.26.0: slowest-asset summary. Useful in both TTY and // v0.27.0: slowest-asset summary. Useful in both TTY and
// non-TTY (it pinpoints the bottleneck file), so it prints // non-TTY (it pinpoints the bottleneck file), so it prints
// unless --quiet. --json mode never reaches here (emit_json). // unless --quiet. --json mode never reaches here (emit_json).
let _ = write_slowest_summary(&mut err, &self.timings, SLOWEST_TOP_N); let _ = write_slowest_summary(&mut err, &self.timings, SLOWEST_TOP_N);
@@ -404,7 +404,7 @@ fn fmt_ms(ms: u64) -> String {
} }
} }
/// v0.26.0: shorten an over-long workspace path for the progress-bar /// v0.27.0: shorten an over-long workspace path for the progress-bar
/// message so the live `(Ns)` heartbeat suffix stays visible on a narrow /// message so the live `(Ns)` heartbeat suffix stays visible on a narrow
/// terminal. Keeps the tail (filename + a couple of parents) — that's the /// terminal. Keeps the tail (filename + a couple of parents) — that's the
/// distinguishing part — and prefixes `…` when truncated. Paths up to the /// distinguishing part — and prefixes `…` when truncated. Paths up to the
@@ -423,7 +423,7 @@ fn abbreviate_path(path: &str) -> String {
format!("…{tail}") format!("…{tail}")
} }
/// v0.26.0: render the end-of-run "slowest assets" summary. Sorts /// v0.27.0: render the end-of-run "slowest assets" summary. Sorts
/// `(path, total_ms)` descending by time, takes the top `n`, and writes a /// `(path, total_ms)` descending by time, takes the top `n`, and writes a
/// compact table to `w`. No-op (writes nothing) when `timings` is empty so /// compact table to `w`. No-op (writes nothing) when `timings` is empty so
/// a run with no per-asset timing (e.g. all-skipped) prints no stray header. /// a run with no per-asset timing (e.g. all-skipped) prints no stray header.

2
crates/kebab-tui/src/ingest_progress.rs
View File

@@ -161,7 +161,7 @@ fn apply_event(state: &mut IngestState, event: IngestEvent) {
// no-ops here (the CLI / --json surfaces render them). // no-ops here (the CLI / --json surfaces render them).
| IngestEvent::AssetChunked { .. } | IngestEvent::AssetChunked { .. }
| IngestEvent::AssetTimings { .. } | IngestEvent::AssetTimings { .. }
// v0.26.0 slow-phase hint (ocr / caption / embed): the CLI bar uses // v0.27.0 slow-phase hint (ocr / caption / embed): the CLI bar uses
// it for a live phase message; the TUI status-bar reducer tracks only // it for a live phase message; the TUI status-bar reducer tracks only
// per-asset counters, so it's a no-op here. // per-asset counters, so it's a no-op here.
| IngestEvent::AssetPhase { .. } => {} | IngestEvent::AssetPhase { .. } => {}

8
docs/wire-schema/v1/ingest_progress.schema.json
View File

@@ -37,15 +37,15 @@
"description": "asset_finished: per-asset outcome (mirrors `ingest_report.v1.items[].kind`)." "description": "asset_finished: per-asset outcome (mirrors `ingest_report.v1.items[].kind`)."
}, },
"chunks": { "type": "integer", "minimum": 0, "description": "asset_finished / asset_chunked (v0.24.0): chunk count produced for this asset." }, "chunks": { "type": "integer", "minimum": 0, "description": "asset_finished / asset_chunked (v0.24.0): chunk count produced for this asset." },
"phase": { "type": "string", "enum": ["ocr", "caption", "embed"], "description": "asset_phase (v0.26.0): the slow internal phase the asset just entered. Short phases (parse/chunk/store) are not emitted." }, "phase": { "type": "string", "enum": ["ocr", "caption", "embed"], "description": "asset_phase (v0.27.0): the slow internal phase the asset just entered. Short phases (parse/chunk/store) are not emitted." },
"model": { "type": ["string", "null"], "description": "asset_phase (v0.26.0): model performing the phase — vision LLM id for ocr/caption, embedder model_id for embed. null when the phase runs without a configured model." }, "model": { "type": ["string", "null"], "description": "asset_phase (v0.27.0): model performing the phase — vision LLM id for ocr/caption, embedder model_id for embed. null when the phase runs without a configured model." },
"parse_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): parse phase wall-clock (ms). Emitted by markdown / image / PDF paths." }, "parse_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): parse phase wall-clock (ms). Emitted by markdown / image / PDF paths." },
"chunk_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): chunk phase wall-clock (ms). Emitted by markdown / image / PDF paths." }, "chunk_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): chunk phase wall-clock (ms). Emitted by markdown / image / PDF paths." },
"expansion_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): retained for wire compatibility but always 0 — doc-side expansion was removed (HOTFIXES 2026-06-03)." }, "expansion_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): retained for wire compatibility but always 0 — doc-side expansion was removed (HOTFIXES 2026-06-03)." },
"embed_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): embed + vector phase wall-clock (ms) — embedding, vector upsert, and stale-vector purge." }, "embed_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): embed + vector phase wall-clock (ms) — embedding, vector upsert, and stale-vector purge." },
"store_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): SQLite persist phase wall-clock (ms) — put_asset/document/blocks/chunks only." }, "store_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.24.0, additive): SQLite persist phase wall-clock (ms) — put_asset/document/blocks/chunks only." },
"ocr_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.26.0, additive, default 0): image/PDF OCR phase wall-clock (ms). 0 on the markdown path (no OCR)." }, "ocr_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.27.0, additive, default 0): image/PDF OCR phase wall-clock (ms). 0 on the markdown path (no OCR)." },
"caption_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.26.0, additive, default 0): image caption phase wall-clock (ms). 0 on markdown / PDF paths." }, "caption_ms": { "type": "integer", "minimum": 0, "description": "asset_timings (v0.27.0, additive, default 0): image caption phase wall-clock (ms). 0 on markdown / PDF paths." },
"n_chunks": { "type": "integer", "minimum": 0, "description": "embed_batch_started / embed_batch_finished: chunks in this embedding batch." }, "n_chunks": { "type": "integer", "minimum": 0, "description": "embed_batch_started / embed_batch_finished: chunks in this embedding batch." },
"ms": { "type": "integer", "minimum": 0, "description": "embed_batch_finished / pdf_ocr_finished: wall-clock duration (ms). pdf_ocr_finished skip path 의 의미는 mixed (DCTDecode 부재 시 0, engine 실패 시 latency-before-bail)." }, "ms": { "type": "integer", "minimum": 0, "description": "embed_batch_finished / pdf_ocr_finished: wall-clock duration (ms). pdf_ocr_finished skip path 의 의미는 mixed (DCTDecode 부재 시 0, engine 실패 시 latency-before-bail)." },
"chars": { "type": "integer", "minimum": 0, "description": "pdf_ocr_finished: char count of OCR result. Skip 시 0." }, "chars": { "type": "integer", "minimum": 0, "description": "pdf_ocr_finished: char count of OCR result. Skip 시 0." },