Skip to content

World's first open-source enterprise world model.

A scan is read by a layout service (#720)

WaylandYangabab6cffa54f
diff --git a/Cargo.toml b/Cargo.toml
index 2db6a439..b0e96793 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -72,7 +72,7 @@ pgvector = { version = "0.4", features = ["sqlx"] }
# 21 字节而信息量只有 4 字节,一次响应 1.33 MB。实测同一条链路上不压缩 62 秒、
# gzip 21 秒(429 KB)——服务端算完只用 1 秒,其余全在传。
# `default-features = false` 把它一并关掉了,这里补回来。
-reqwest = { version = "0.13", default-features = false, features = ["json", "form", "stream", "http2", "rustls", "webpki-roots", "charset", "system-proxy", "gzip"] }
+reqwest = { version = "0.13", default-features = false, features = ["json", "form", "multipart", "stream", "http2", "rustls", "webpki-roots", "charset", "system-proxy", "gzip"] }
feed-rs = "2"
cron = "0.12"
diff --git a/crates/utopia-core/src/models.rs b/crates/utopia-core/src/models.rs
index 54c44cec..3a2ef67a 100644
--- a/crates/utopia-core/src/models.rs
+++ b/crates/utopia-core/src/models.rs
@@ -435,6 +435,11 @@ pub struct LlmSettings {
pub embed_model: Option<String>,
pub embed_dim: Option<i32>,
pub updated_at: DateTime<Utc>,
+ /// 读扫描件、图片的版面识别服务(MinerU,0040);空 = 没配,那类文件降级
+ pub ocr_base_url: Option<String>,
+ #[serde(skip_serializing)]
+ pub ocr_api_key: Option<String>,
+ pub ocr_backend: Option<String>,
}
impl LlmSettings {
@@ -444,6 +449,9 @@ impl LlmSettings {
pub fn embed_ready(&self) -> bool {
self.embed_base_url.is_some() && self.embed_model.is_some()
}
+ pub fn ocr_ready(&self) -> bool {
+ self.ocr_base_url.is_some()
+ }
}
#[derive(Debug, Clone, Serialize, sqlx::FromRow)]
@@ -1023,6 +1031,10 @@ pub struct ChunkFull {
pub id: Uuid,
pub seq: i32,
pub text: String,
+ /// 这块文字从哪来(0040):查看器按它标出认出来的字,按锚点翻到那一页
+ pub origin: String,
+ pub origin_model: Option<String>,
+ pub anchor: Option<serde_json::Value>,
}
#[derive(Debug, Clone, Serialize, sqlx::FromRow)]
diff --git a/crates/utopia-ingest/src/lib.rs b/crates/utopia-ingest/src/lib.rs
index b162cc61..77db6f68 100644
--- a/crates/utopia-ingest/src/lib.rs
+++ b/crates/utopia-ingest/src/lib.rs
@@ -164,6 +164,7 @@ mod reader_tests {
mod blocks;
mod chunker;
pub mod html;
+pub mod mineru;
pub mod ontology_rdf;
mod parsers;
pub mod provenance;
diff --git a/crates/utopia-ingest/src/mineru.rs b/crates/utopia-ingest/src/mineru.rs
new file mode 100644
index 00000000..19145cc4
--- /dev/null
+++ b/crates/utopia-ingest/src/mineru.rs
@@ -0,0 +1,299 @@
+//! MinerU 读出来的版面(`content_list`)→ 一份正文 + 按页的出处段(0040 第二刀)。
+//!
+//! MinerU 先认版面、再逐区域认字,交回一串按阅读顺序排好的区域:正文、标题、表、公式、
+//! 图注,每个带 `page_idx` 和 `bbox`(映射到 0–1000)。这里把它们拼成分块器认得的
+//! Markdown——标题还是标题,表还是表,于是扫描件的块跟原生文档按同一套规矩切:表头
+//! 跟着续块走、标题贴着下一段。
+//!
+//! **段按页分,不按区域分。**一块只装一种出处(决定 2),而每个区域的框都不一样;按区域
+//! 分段,一段话一块,块就碎到抽取看不见上下文。页是人核对时翻到的那个单位,所以一页一
+//! 段,块切好之后再把它盖住的那几个区域的框并成一个,写进锚点。
+//!
+//! 页码从 1 数(`page_idx` + 1):锚点是给人翻页用的,查看器的 `#page=` 也从 1 数。
+
+use crate::chunker::{chunk_segments, ChunkPiece};
+use crate::provenance::{Origin, Provenance, Segment};
+use serde_json::{json, Value};
+use std::ops::Range;
+
+/// 版面上的辅助区域:页眉、页脚、页码。每页重复一遍,进了正文只会让每块都多一行噪声。
+/// 页脚注和旁注不在这里——合同的脚注里写着条款
+const CHROME: &[&str] = &["header", "footer", "page_number"];
+
+/// 拼好的正文,连同每页的出处和每个区域的位置
+#[derive(Debug, Clone)]
+pub struct Reading {
+ pub text: String,
+ pub segments: Vec<Segment>,
+ /// 每个区域在正文里的字节区间、所在页、框
+ regions: Vec<Region>,
+}
+
+#[derive(Debug, Clone)]
+struct Region {
+ range: Range<usize>,
+ page: u64,
+ bbox: Option<[f64; 4]>,
+}
+
+impl Reading {
+ /// 按页分段切块,再给每块的锚点补上它盖住的区域的外框
+ pub fn chunk(&self, budget: usize) -> Vec<ChunkPiece> {
+ let mut pieces = chunk_segments(&self.text, &self.segments, budget);
+ for p in &mut pieces {
+ let span = p.char_start as usize..p.char_end as usize;
+ let Some(anchor) = p.provenance.anchor.as_mut() else {
+ continue;
+ };
+ let page = anchor["page"].as_u64();
+ let covered = self
+ .regions
+ .iter()
+ .filter(|r| {
+ Some(r.page) == page && r.range.start < span.end && span.start < r.range.end
+ })
+ .filter_map(|r| r.bbox);
+ if let Some(b) = covered.reduce(|a, b| {
+ [
+ a[0].min(b[0]),
+ a[1].min(b[1]),
+ a[2].max(b[2]),
+ a[3].max(b[3]),
+ ]
+ }) {
+ anchor["bbox"] = json!(b);
+ }
+ }
+ pieces
+ }
+}
+
+/// 读 `content_list`。`model` 记在出处上:哪个版本、哪个后端读的
+pub fn reading(content_list: &Value, model: &str) -> Reading {
+ let mut text = String::new();
+ let mut regions: Vec<Region> = Vec::new();
+ for item in content_list.as_array().map(Vec::as_slice).unwrap_or(&[]) {
+ let kind = item["type"].as_str().unwrap_or("text");
+ if CHROME.contains(&kind) {
+ continue;
+ }
+ let Some(body) = render(kind, item) else {
+ continue;
+ };
+ let body = without_nul(&body);
+ let body = body.trim();
+ if body.is_empty() {
+ continue;
+ }
+ if !text.is_empty() {
+ text.push_str("\n\n");
+ }
+ let start = text.len();
+ text.push_str(body);
+ regions.push(Region {
+ range: start..text.len(),
+ page: item["page_idx"].as_u64().unwrap_or(0) + 1,
+ bbox: bbox(&item["bbox"]),
+ });
+ }
+
+ // 一页一段,段首尾相接盖满整份正文:段从这一页第一个区域开始,到下一页第一个区域为止
+ let mut segments: Vec<Segment> = Vec::new();
+ for r in &regions {
+ if segments.last().is_some_and(|s| {
+ s.provenance.anchor.as_ref().map(|a| &a["page"]) == Some(&json!(r.page))
+ }) {
+ continue;
+ }
+ if let Some(prev) = segments.last_mut() {
+ prev.range.end = r.range.start;
+ }
+ segments.push(Segment {
+ range: r.range.start..text.len(),
+ provenance: Provenance {
+ origin: Origin::Ocr,
+ model: Some(model.to_string()),
+ anchor: Some(json!({ "page": r.page })),
+ },
+ });
+ }
+ if let Some(first) = segments.first_mut() {
+ first.range.start = 0;
+ }
+ Reading {
+ text,
+ segments,
+ regions,
+ }
+}
+
+/// 一个区域写成 Markdown。认不出的类型有字就照字收,没字就跳过
+fn render(kind: &str, item: &Value) -> Option<String> {
+ let s = |key: &str| item[key].as_str().map(str::trim).filter(|t| !t.is_empty());
+ let lines = |key: &str| -> Vec<String> {
+ item[key]
+ .as_array()
+ .map(|a| {
+ a.iter()
+ .filter_map(|v| v.as_str().map(str::trim).filter(|t| !t.is_empty()))
+ .map(String::from)
+ .collect()
+ })
+ .unwrap_or_default()
+ };
+ let with_notes = |caption: &str, body: Option<String>, footnote: &str| -> Option<String> {
+ let parts: Vec<String> = lines(caption)
+ .into_iter()
+ .chain(body)
+ .chain(lines(footnote))
+ .collect();
+ (!parts.is_empty()).then(|| parts.join("\n\n"))
+ };
+ match kind {
+ "text" => {
+ let t = s("text")?;
+ match item["text_level"].as_u64().unwrap_or(0) {
+ 0 => Some(t.to_string()),
+ // 标题要单独一行才认得出;认字认出来的换行并成空格
+ n => Some(format!(
+ "{} {}",
+ "#".repeat(n.min(6) as usize),
+ t.split_whitespace().collect::<Vec<_>>().join(" ")
+ )),
+ }
+ }
+ "table" => {
+ let body = s("table_body").map(|html| {
+ crate::html::fragment_to_markdown(html)
+ .map(|md| md.trim().to_string())
+ .unwrap_or_else(|_| html.to_string())
+ });
+ with_notes("table_caption", body, "table_footnote")
+ }
+ "image" | "chart" => with_notes("image_caption", None, "image_footnote"),
+ "code" => with_notes(
+ "code_caption",
+ s("code_body").map(|c| format!("```\n{c}\n```")),
+ "code_footnote",
+ ),
+ "list" => {
+ let items = lines("list_items");
+ (!items.is_empty()).then(|| items.join("\n"))
+ }
+ _ => s("text").map(String::from),
+ }
+}
+
+fn bbox(v: &Value) -> Option<[f64; 4]> {
+ let a = v.as_array()?;
+ if a.len() != 4 {
+ return None;
+ }
+ let mut out = [0.0; 4];
+ for (o, x) in out.iter_mut().zip(a) {
+ *o = x.as_f64()?;
+ }
+ Some(out)
+}
+
+/// 认字认出来的 NUL 跟 PDF 文本层里的一样要剥(#611)
+fn without_nul(s: &str) -> String {
+ s.replace('\0', "")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn scan() -> Value {
+ json!([
+ { "type": "header", "text": "ACME CONFIDENTIAL", "page_idx": 0, "bbox": [0, 0, 1000, 30] },
+ { "type": "text", "text": "Lease Agreement", "text_level": 1, "page_idx": 0, "bbox": [100, 50, 900, 90] },
+ { "type": "text", "text": "The tenant is Beta Robotics.", "page_idx": 0, "bbox": [100, 100, 900, 140] },
+ { "type": "text", "text": "Rent is paid monthly.", "page_idx": 0, "bbox": [100, 150, 800, 190] },
+ { "type": "page_number", "text": "1", "page_idx": 0, "bbox": [480, 970, 520, 990] },
+ { "type": "table", "table_caption": ["Schedule of rent"],
+ "table_body": "<table><tr><td>Year</td><td>Rent</td></tr><tr><td>2026</td><td>1,000</td></tr></table>",
+ "table_footnote": [], "page_idx": 1, "bbox": [100, 60, 900, 300] },
+ { "type": "image", "img_path": "images/stamp.png", "image_caption": [], "page_idx": 1, "bbox": [600, 800, 900, 950] },
+ { "type": "text", "text": "Signed by both parties.", "page_idx": 1, "bbox": [100, 320, 900, 360] }
+ ])
+ }
+
+ #[test]
+ fn a_scan_reads_as_markdown_without_page_chrome() {
+ let r = reading(&scan(), "mineru 2.5.4 vlm");
+ assert!(r
+ .text
+ .starts_with("# Lease Agreement\n\nThe tenant is Beta Robotics."));
+ assert!(
+ !r.text.contains("ACME CONFIDENTIAL"),
+ "the header repeats on every page"
+ );
+ assert!(!r.text.contains("\n\n1\n\n"), "the page number is not text");
+ assert!(
+ r.text.contains("Schedule of rent\n\n| Year | Rent |"),
+ "{}",
+ r.text
+ );
+ assert!(r.text.contains("| 2026 | 1,000 |"));
+ assert!(
+ !r.text.contains("stamp.png"),
+ "an image without a caption says nothing yet"
+ );
+ }
+
+ #[test]
+ fn pages_are_segments_that_cover_the_text() {
+ let r = reading(&scan(), "mineru 2.5.4 vlm");
+ assert_eq!(r.segments.len(), 2);
+ assert_eq!(r.segments[0].range.start, 0);
+ assert_eq!(r.segments[0].range.end, r.segments[1].range.start);
+ assert_eq!(r.segments[1].range.end, r.text.len());
+ assert!(r.text[r.segments[1].range.clone()].starts_with("Schedule of rent"));
+ assert_eq!(r.segments[1].provenance.anchor, Some(json!({ "page": 2 })));
+ }
+
+ #[test]
+ fn a_chunk_stays_on_its_page_and_boxes_what_it_covers() {
+ let r = reading(&scan(), "mineru 2.5.4 vlm");
+ let pieces = r.chunk(300);
+ assert_eq!(pieces.len(), 2, "{pieces:#?}");
+ let first = &pieces[0];
+ assert_eq!(first.provenance.origin, Origin::Ocr);
+ assert_eq!(first.provenance.model.as_deref(), Some("mineru 2.5.4 vlm"));
+ assert_eq!(
+ first.provenance.anchor,
+ Some(json!({ "page": 1, "bbox": [100.0, 50.0, 900.0, 190.0] }))
+ );
+ assert!(first.text.contains("Rent is paid monthly."));
+ let second = &pieces[1];
+ assert_eq!(second.provenance.anchor.as_ref().unwrap()["page"], json!(2));
+ assert!(second.text.contains("Signed by both parties."));
+ assert_eq!(
+ second.heading.as_deref(),
+ Some("Lease Agreement"),
+ "the breadcrumb crosses the page"
+ );
+ for p in &pieces {
+ assert!(p
+ .text
+ .ends_with(&r.text[p.char_start as usize..p.char_end as usize]));
+ }
+ }
+
+ #[test]
+ fn an_empty_or_odd_list_reads_as_nothing() {
+ assert!(reading(&json!([]), "m").text.is_empty());
+ assert!(reading(&json!({"not": "a list"}), "m").segments.is_empty());
+ let r = reading(
+ &json!([{ "type": "equation", "text": "$$E = mc^2$$", "page_idx": 3 }]),
+ "m",
+ );
+ assert_eq!(r.text, "$$E = mc^2$$");
+ assert_eq!(
+ r.chunk(300)[0].provenance.anchor,
+ Some(json!({ "page": 4 }))
+ );
+ }
+}
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index 44899a3e..00bbf6e9 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -30,7 +30,7 @@ mod workspaces;
use axum::extract::DefaultBodyLimit;
use axum::http::{header, HeaderValue, Method};
-use axum::routing::{any, get, patch, post};
+use axum::routing::{any, get, patch, post, put};
use axum::{Json, Router};
use serde_json::json;
use tower_http::cors::CorsLayer;
@@ -139,6 +139,10 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
"/workspaces/{id}/settings",
get(settings_routes::get).put(settings_routes::put),
)
+ .route(
+ "/workspaces/{id}/settings/ocr",
+ put(settings_routes::put_ocr),
+ )
.route(
"/workspaces/{id}/settings/test",
post(settings_routes::test),
diff --git a/crates/utopia-server/src/api/settings_routes.rs b/crates/utopia-server/src/api/settings_routes.rs
index 8afafcec..fc6d9e09 100644
--- a/crates/utopia-server/src/api/settings_routes.rs
+++ b/crates/utopia-server/src/api/settings_routes.rs
@@ -29,6 +29,9 @@ pub async fn get(
"embed_model": s.embed_model,
"embed_dim": s.embed_dim,
"has_embed_key": s.embed_api_key.as_deref().is_some_and(|k| !k.is_empty()),
+ "ocr_base_url": s.ocr_base_url,
+ "ocr_backend": s.ocr_backend,
+ "has_ocr_key": s.ocr_api_key.as_deref().is_some_and(|k| !k.is_empty()),
}),
}))
}
@@ -92,7 +95,56 @@ pub async fn put(
Ok(Json(json!({ "ok": true })))
}
-/// 连通性测试:对话发一条最小消息;embedding 试算一条并返回维度。
+#[derive(Deserialize)]
+pub struct PutOcrReq {
+ /// 空 = 关掉:扫描件、图片照第一刀降级
+ pub base_url: Option<String>,
+ /// None 或空串 = 保留旧密钥
+ pub api_key: Option<String>,
+ pub backend: Option<String>,
+}
+
+/// 版面识别服务(0040 第二刀)。单独一个接口:管理页上它是自己的一张卡片,存它不该把
+/// 对话、嵌入那几列按表单里的空值抹掉。
+///
+/// 配上的这一刻,这个工作区里因为没有它而停在 failed 的扫描件、图片重新排进处理队列——
+/// 告警里说的「配上会自己重新处理」就是这里
+pub async fn put_ocr(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path(workspace_id): Path<Uuid>,
+ Json(req): Json<PutOcrReq>,
+) -> ApiResult<Json<serde_json::Value>> {
+ utopia_store::workspaces::require_role(&state.pool, user.id, workspace_id, Role::Admin).await?;
+ let nonempty = |v: &Option<String>| -> Option<String> {
+ v.as_deref()
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+ .map(String::from)
+ };
+ let base_url = nonempty(&req.base_url);
+ utopia_store::settings::upsert_ocr(
+ &state.pool,
+ workspace_id,
+ base_url.as_deref(),
+ nonempty(&req.api_key).as_deref(),
+ nonempty(&req.backend).as_deref(),
+ )
+ .await?;
+ let mut requeued = 0usize;
+ if base_url.is_some() {
+ let docs =
+ utopia_store::documents::requeue_waiting_for_reader(&state.pool, workspace_id, "ocr")
+ .await?;
+ requeued = docs.len();
+ for (document_id, kb_id) in docs {
+ state.emit_document(kb_id, document_id);
+ }
+ }
+ Ok(Json(json!({ "ok": true, "requeued": requeued })))
+}
+
+/// 连通性测试:对话发一条最小消息;embedding 试算一条并返回维度;版面识别服务问一声健康。
pub async fn test(
State(state): State<AppState>,
AuthUser(user): AuthUser,
@@ -102,7 +154,8 @@ pub async fn test(
let Some(s) = utopia_store::settings::get(&state.pool, workspace_id).await? else {
return Ok(Json(
json!({ "chat": { "ok": false, "error": "Not configured" },
- "embed": { "ok": false, "error": "Not configured" } }),
+ "embed": { "ok": false, "error": "Not configured" },
+ "ocr": { "ok": false, "error": "Not configured" } }),
));
};
@@ -131,5 +184,15 @@ pub async fn test(
},
};
- Ok(Json(json!({ "chat": chat_result, "embed": embed_result })))
+ let ocr_result = match crate::readers::Ocr::from_settings(&s) {
+ None => json!({ "ok": false, "error": "Not configured" }),
+ Some(ocr) => match ocr.health().await {
+ Ok(h) => json!({ "ok": true, "version": h["version"] }),
+ Err(e) => json!({ "ok": false, "error": format!("{e:#}") }),
+ },
+ };
+
+ Ok(Json(
+ json!({ "chat": chat_result, "embed": embed_result, "ocr": ocr_result }),
+ ))
}
diff --git a/crates/utopia-server/src/main.rs b/crates/utopia-server/src/main.rs
index 53bdc730..b1ea1bb2 100644
--- a/crates/utopia-server/src/main.rs
+++ b/crates/utopia-server/src/main.rs
@@ -27,6 +27,7 @@ mod pipeline;
mod predicate_match;
mod query_engine;
mod rdf;
+mod readers;
mod retrieval;
mod rss_full_content;
mod state;
diff --git a/crates/utopia-server/src/pipeline.rs b/crates/utopia-server/src/pipeline.rs
index 0a4f9ee4..40d0af64 100644
--- a/crates/utopia-server/src/pipeline.rs
+++ b/crates/utopia-server/src/pipeline.rs
@@ -36,6 +36,8 @@ const EMBED_JOBS: usize = 4;
pub async fn process_document(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
match run(state, document_id).await {
Ok(()) => Ok(()),
+ // 在等读字的服务读完:文档照旧是 parsing,任务过一会儿再来问
+ Err(e) if utopia_core::is_deferred(&e).is_some() => Err(e),
Err(e) => {
let doc = utopia_store::documents::get(&state.pool, document_id)
.await
@@ -91,16 +93,45 @@ async fn run(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
state.emit_document(doc.kb_id, document_id);
let bytes = state.blob.get(&doc.sha256).await?;
let filename = doc.filename.clone();
- let parsed =
- tokio::task::spawn_blocking(move || utopia_ingest::parse(&filename, &bytes)).await??;
- // 解析出来的正文可能夹着 NUL(PDF 文本层常见),入库之前剥掉(#611)——与记忆
- // 那条路共用 `utopia_core::without_nul`(#665)。剥必须在算长度、分块之前:之后的
- // text_len、分块偏移、全文索引、嵌入读的都是这一份,彼此才对得上
- let text = utopia_core::without_nul(&parsed.text);
- let text_len = text.chars().count() as i32;
+ let (parsed, bytes) =
+ tokio::task::spawn_blocking(move || (utopia_ingest::parse(&filename, &bytes), bytes))
+ .await?;
+ let kb_row = utopia_store::kbs::get(&state.pool, doc.kb_id).await?;
+ let settings = utopia_store::settings::get(&state.pool, kb_row.workspace_id).await?;
// 2. 分块 + 入库
- let pieces = utopia_ingest::chunk_with_budget(&text, state.chunk_tokens);
+ let (text, pieces) = match parsed {
+ Ok(parsed) => {
+ // 解析出来的正文可能夹着 NUL(PDF 文本层常见),入库之前剥掉(#611)——与记忆
+ // 那条路共用 `utopia_core::without_nul`(#665)。剥必须在算长度、分块之前:之后的
+ // text_len、分块偏移、全文索引、嵌入读的都是这一份,彼此才对得上
+ let text = utopia_core::without_nul(&parsed.text).into_owned();
+ let pieces = utopia_ingest::chunk_with_budget(&text, state.chunk_tokens);
+ (text, pieces)
+ }
+ // 没有文本层的扫描件、图片:工作区配了版面识别服务就交给它读(0040 第二刀),
+ // 按页分段切块,每块记着页码和框。没配的照旧往上抛,由外面降级
+ Err(e) => match (
+ e.downcast_ref::<utopia_ingest::NeedsReader>(),
+ settings
+ .as_ref()
+ .and_then(crate::readers::Ocr::from_settings),
+ ) {
+ (Some(needs), Some(ocr)) if needs.reader == utopia_ingest::Reader::Ocr => {
+ let reading = ocr.read(state, &doc, bytes).await?;
+ if reading.text.trim().is_empty() {
+ return Err(utopia_ingest::Unreadable(
+ "The OCR service found no text in this file".into(),
+ )
+ .into());
+ }
+ let pieces = reading.chunk(state.chunk_tokens);
+ (reading.text, pieces)
+ }
+ _ => return Err(e),
+ },
+ };
+ let text_len = text.chars().count() as i32;
let chunk_pairs =
utopia_store::documents::replace_chunks(&state.pool, doc.kb_id, document_id, &pieces)
.await?;
@@ -115,8 +146,6 @@ async fn run(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
tokio::task::spawn_blocking(move || search.reindex_document(&kb, &did, &chunk_pairs)).await??;
// 4. embedding(工作区配置了 embedding 模型才做;没配也算 ready,先享受 BM25 搜索)
- let kb_row = utopia_store::kbs::get(&state.pool, doc.kb_id).await?;
- let settings = utopia_store::settings::get(&state.pool, kb_row.workspace_id).await?;
if let Some((settings, client)) = embedder(settings.as_ref()) {
utopia_store::documents::set_status(&state.pool, document_id, "embedding").await?;
state.emit_document(doc.kb_id, document_id);
diff --git a/crates/utopia-server/src/pipeline_tests.rs b/crates/utopia-server/src/pipeline_tests.rs
index ed728ff0..6723d685 100644
--- a/crates/utopia-server/src/pipeline_tests.rs
+++ b/crates/utopia-server/src/pipeline_tests.rs
@@ -16,6 +16,8 @@
//! 7. **正文夹 NUL 不毁整篇**(#611):Postgres 的 TEXT 不收 0x00,从前一个字节就让整篇
//! 落在 failed。现在走完整的 process_document 到 ready,库里没有一个分块带 NUL。
//!
+//! 8. **扫描件等版面识别服务读**(0040 第二刀):配上服务重新排队,交一次、挂回去问、按页切块。
+//!
//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
use std::sync::{Arc, Mutex};
@@ -418,6 +420,224 @@ async fn a_file_that_needs_a_reader_waits_and_says_so() -> anyhow::Result<()> {
f.cleanup().await
}
+/// 假的 `mineru-api`:交一次拿到 `t-n`;问状态前 `processing_polls` 次说还在读,之后说读完;
+/// `fail` 时说读失败。记下交了几次、每次带了什么
+#[derive(Clone, Default)]
+struct FakeMineru {
+ submissions: Arc<Mutex<Vec<String>>>,
+ polls: Arc<Mutex<usize>>,
+ processing_polls: usize,
+ fail: bool,
+}
+
+impl Respond for FakeMineru {
+ fn respond(&self, request: &Request) -> ResponseTemplate {
+ if request.method.as_str() == "POST" {
+ let mut subs = self.submissions.lock().expect("lock");
+ let auth = request
+ .headers
+ .get("authorization")
+ .and_then(|v| v.to_str().ok())
+ .unwrap_or_default()
+ .to_string();
+ subs.push(format!(
+ "{auth}\n{}",
+ String::from_utf8_lossy(&request.body)
+ ));
+ return ResponseTemplate::new(202).set_body_json(
+ serde_json::json!({ "task_id": format!("t-{}", subs.len()), "status": "pending" }),
+ );
+ }
+ if request.url.path().ends_with("/result") {
+ let list = serde_json::json!([
+ { "type": "header", "text": "ACME", "page_idx": 0, "bbox": [0, 0, 1000, 20] },
+ { "type": "text", "text": "Lease Agreement", "text_level": 1, "page_idx": 0, "bbox": [100, 40, 900, 80] },
+ { "type": "text", "text": "Beta Robotics pays Alpha 1,000 per month.", "page_idx": 0, "bbox": [100, 100, 900, 140] },
+ { "type": "text", "text": "Signed on 12 February 2025.", "page_idx": 1, "bbox": [100, 60, 700, 90] }
+ ]);
+ return ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "status": "completed", "backend": "vlm-auto-engine", "version": "2.5.4",
+ "results": { "contract-scan": { "content_list": list.to_string() } }
+ }));
+ }
+ let mut polls = self.polls.lock().expect("lock");
+ *polls += 1;
+ let status = if self.fail {
+ serde_json::json!({ "status": "failed", "error": "CUDA out of memory" })
+ } else if *polls <= self.processing_polls {
+ serde_json::json!({ "status": "processing" })
+ } else {
+ serde_json::json!({ "status": "completed" })
+ };
+ ResponseTemplate::new(200).set_body_json(status)
+ }
+}
+
+async fn with_mineru(f: &Fx, fake: &FakeMineru) -> anyhow::Result<()> {
+ Mock::given(wiremock::matchers::path_regex("^/ocr/tasks.*"))
+ .respond_with(fake.clone())
+ .mount(&f.server)
+ .await;
+ utopia_store::settings::upsert_ocr(
+ &f.pool,
+ f.ws,
+ Some(&format!("{}/ocr/", f.server.uri())),
+ Some("ocr-secret"),
+ Some("vlm-auto-engine"),
+ )
+ .await?;
+ Ok(())
+}
+
+async fn reader_task(f: &Fx, doc: Uuid) -> anyhow::Result<Option<serde_json::Value>> {
+ Ok(utopia_store::documents::reader_task(&f.pool, doc).await?)
+}
+
+/// 0040 第二刀:没配服务时停下的扫描件,配上服务就重新排队;交一次、问到读完、按页切块,
+/// 每块记着读它的服务版本、页码和框。等的时候不烧重试预算,也不重交
+#[tokio::test]
+async fn a_scan_waits_for_the_layout_service_and_keeps_its_page() -> anyhow::Result<()> {
+ let Some(f) = fixture(FakeEmbed::new(Duration::from_millis(5))).await? else {
+ return Ok(());
+ };
+ let png = [
+ 0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0x0D, b'I', b'H',
+ ];
+ let doc = f.document_with_bytes("contract-scan.png", &png).await?;
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("no OCR yet");
+ assert!(utopia_core::is_terminal(&err));
+
+ let fake = FakeMineru {
+ processing_polls: 1,
+ ..Default::default()
+ };
+ with_mineru(&f, &fake).await?;
+ let requeued =
+ utopia_store::documents::requeue_waiting_for_reader(&f.pool, f.ws, "ocr").await?;
+ assert_eq!(
+ requeued,
+ vec![(doc, f.kb)],
+ "saving the service queues the scan again"
+ );
+ let row = utopia_store::documents::get(&f.pool, doc).await?;
+ assert_eq!((row.status.as_str(), row.reader_needed), ("pending", None));
+ let queued: i64 = sqlx::query_scalar(
+ "SELECT count(*) FROM jobs WHERE kind = 'process_document' AND status = 'queued'
+ AND payload->>'document_id' = $1",
+ )
+ .bind(doc.to_string())
+ .fetch_one(&f.pool)
+ .await?;
+ assert!(queued >= 1);
+
+ // 交上去:挂回队列等,文档还在 parsing
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("submitted");
+ assert!(utopia_core::is_deferred(&err).is_some(), "{err:#}");
+ assert!(!utopia_core::is_terminal(&err));
+ assert_eq!(
+ utopia_store::documents::get(&f.pool, doc).await?.status,
+ "parsing"
+ );
+ let task = reader_task(&f, doc).await?.expect("the task is remembered");
+ assert_eq!(task["task_id"], "t-1");
+
+ // 问一次:还在读
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("processing");
+ assert!(utopia_core::is_deferred(&err).is_some());
+
+ // 再问:读完了
+ super::process_document(&f.state, doc).await?;
+ let row = utopia_store::documents::get(&f.pool, doc).await?;
+ assert_eq!(row.status, "ready", "{:?}", row.error);
+ assert_eq!(
+ reader_task(&f, doc).await?,
+ None,
+ "a finished read forgets its task"
+ );
+ let subs = fake.submissions.lock().expect("lock").clone();
+ assert_eq!(subs.len(), 1, "waiting never submits twice");
+ assert!(subs[0].starts_with("Bearer ocr-secret\n"));
+ assert!(subs[0].contains("name=\"backend\""));
+ assert!(subs[0].contains("vlm-auto-engine"));
+
+ type Stored = (String, String, Option<String>, Option<serde_json::Value>);
+ let chunks: Vec<Stored> = sqlx::query_as(
+ "SELECT text, origin, origin_model, anchor FROM chunks
+ WHERE document_id = $1 AND superseded_at IS NULL ORDER BY seq",
+ )
+ .bind(doc)
+ .fetch_all(&f.pool)
+ .await?;
+ assert_eq!(chunks.len(), 2, "one chunk per page: {chunks:#?}");
+ assert!(chunks.iter().all(|c| c.1 == "ocr"));
+ assert_eq!(chunks[0].2.as_deref(), Some("mineru 2.5.4 vlm-auto-engine"));
+ assert!(chunks[0].0.contains("1,000 per month"));
+ assert!(!chunks[0].0.contains("ACME"), "the page header is not text");
+ assert_eq!(
+ chunks[0].3,
+ Some(serde_json::json!({ "page": 1, "bbox": [100.0, 40.0, 900.0, 140.0] }))
+ );
+ assert_eq!(
+ chunks[1].3.as_ref().map(|a| a["page"].clone()),
+ Some(serde_json::json!(2))
+ );
+ assert!(
+ f.stored(doc).await?.iter().all(|(_, v)| v.is_some()),
+ "embedded like any text"
+ );
+ f.cleanup().await
+}
+
+/// 服务说读失败:文档带着服务给的原因落在 failed,任务号清掉,这次失败走普通重试(下一次重交)
+#[tokio::test]
+async fn a_failed_read_is_retried_from_a_fresh_submission() -> anyhow::Result<()> {
+ let Some(f) = fixture(FakeEmbed::new(Duration::from_millis(5))).await? else {
+ return Ok(());
+ };
+ let fake = FakeMineru {
+ fail: true,
+ ..Default::default()
+ };
+ with_mineru(&f, &fake).await?;
+ let doc = f
+ .document_with_bytes(
+ "contract-scan.png",
+ &[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A],
+ )
+ .await?;
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("submitted");
+ assert!(utopia_core::is_deferred(&err).is_some());
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("failed");
+ assert!(utopia_core::is_deferred(&err).is_none());
+ assert!(
+ !utopia_core::is_terminal(&err),
+ "the next attempt may succeed"
+ );
+ let row = utopia_store::documents::get(&f.pool, doc).await?;
+ assert_eq!(row.status, "failed");
+ assert!(row
+ .error
+ .as_deref()
+ .is_some_and(|e| e.contains("CUDA out of memory")));
+ assert_eq!(reader_task(&f, doc).await?, None);
+ let err = super::process_document(&f.state, doc)
+ .await
+ .expect_err("submitted again");
+ assert!(utopia_core::is_deferred(&err).is_some());
+ assert_eq!(fake.submissions.lock().expect("lock").len(), 2);
+ f.cleanup().await
+}
+
/// 读不了的格式(老式 .doc、压缩包):一次失败、不重试,也不进库成乱码;它不缺模型,不报那条告警
#[tokio::test]
async fn a_binary_file_fails_once_instead_of_becoming_text() -> anyhow::Result<()> {
diff --git a/crates/utopia-server/src/readers.rs b/crates/utopia-server/src/readers.rs
new file mode 100644
index 00000000..6af63ccf
--- /dev/null
+++ b/crates/utopia-server/src/readers.rs
@@ -0,0 +1,223 @@
+//! 读字的服务(0040):扫描件和图片交给版面识别服务 MinerU(`mineru-api`)。
+//!
+//! 识别一份几百页的扫描件要几分钟到几十分钟。处理任务不在这里干等:第一次来交文件、把
+//! 远端任务号记在文档上(`documents.reader_task`),挂 `Deferred` 回队列;之后每次来问
+//! 一声,没好再挂回去,好了取回版面交给分块。`Deferred` 不烧重试预算,进程重启也从记下
+//! 的任务号接着问,不重交。
+//!
+//! 接口:`POST /tasks`(multipart,`files` + 选项)交任务,`GET /tasks/{id}` 问状态
+//! (pending / processing / completed / failed),`GET /tasks/{id}/result` 取结果——
+//! `results` 按文件名去掉扩展名为键,`content_list` 是一段 JSON **字符串**。`mineru-api`
+//! 本身不认证;部署在它前面挂了反向代理的,密钥按 Bearer 带上。
+
+use std::time::Duration;
+
+use anyhow::{anyhow, Context};
+use serde_json::{json, Value};
+use utopia_core::models::{Document, LlmSettings};
+use utopia_core::{Deferred, Terminal};
+use utopia_ingest::mineru::Reading;
+
+use crate::state::AppState;
+
+/// 多久问一次。一页扫描件在 GPU 上一两秒,十秒问一次,几十页的文件问几次就好
+const POLL: Duration = Duration::from_secs(10);
+
+/// 交上去的任务最多等多久。服务把任务吞了、却一直报 processing 的时候,文档不能永远停在
+/// parsing:六小时够一份上千页的扫描件在 CPU 上读完
+const PATIENCE_HOURS: i64 = 6;
+
+/// 传文件、取结果的超时。共用客户端的 20 秒是给探针和小请求的,一份几十兆的扫描件传不完
+const TRANSFER_TIMEOUT: Duration = Duration::from_secs(600);
+
+/// 工作区配的版面识别服务
+pub struct Ocr<'a> {
+ base: &'a str,
+ key: Option<&'a str>,
+ backend: Option<&'a str>,
+}
+
+impl<'a> Ocr<'a> {
+ pub fn from_settings(s: &'a LlmSettings) -> Option<Self> {
+ Some(Ocr {
+ base: s.ocr_base_url.as_deref()?.trim_end_matches('/'),
+ key: s.ocr_api_key.as_deref().filter(|k| !k.is_empty()),
+ backend: s.ocr_backend.as_deref().filter(|b| !b.is_empty()),
+ })
+ }
+
+ fn request(
+ &self,
+ client: &reqwest::Client,
+ method: reqwest::Method,
+ path: &str,
+ ) -> reqwest::RequestBuilder {
+ let req = client.request(method, format!("{}/{path}", self.base));
+ match self.key {
+ Some(key) => req.bearer_auth(key),
+ None => req,
+ }
+ }
+
+ /// 连通性测试:服务活着就回它报的版本
+ pub async fn health(&self) -> anyhow::Result<Value> {
+ let client = crate::query_engine::http()?;
+ let resp = self
+ .request(&client, reqwest::Method::GET, "health")
+ .send()
+ .await
+ .context("the OCR service is unreachable")?;
+ let status = resp.status();
+ if !status.is_success() {
+ return Err(anyhow!("the OCR service answered {status}"));
+ }
+ Ok(resp.json().await.unwrap_or(Value::Null))
+ }
+
+ /// 读这份文件。没读完返回挂着 `Deferred` 的错误,调用方原样往上抛
+ pub async fn read(
+ &self,
+ state: &AppState,
+ doc: &Document,
+ bytes: Vec<u8>,
+ ) -> anyhow::Result<Reading> {
+ let pool = &state.pool;
+ let stored = utopia_store::documents::reader_task(pool, doc.id).await?;
+ let current = stored.as_ref().filter(|t| {
+ t["reader"] == "ocr" && t["sha256"] == doc.sha256.as_str() && t["service"] == self.base
+ });
+ let Some(task) = current else {
+ // 没交过;或者交的是旧版本的文件、交给的是换掉之前的服务——作废重交
+ if stored.is_some() {
+ utopia_store::documents::clear_reader_task(pool, doc.id).await?;
+ }
+ let task_id = self.submit(&doc.filename, bytes).await?;
+ let task = json!({
+ "reader": "ocr",
+ "service": self.base,
+ "task_id": task_id,
+ "sha256": doc.sha256,
+ "submitted_at": chrono::Utc::now(),
+ });
+ if !utopia_store::documents::claim_reader_task(pool, doc.id, &task).await? {
+ tracing::info!(document = %doc.id, "another run submitted this file first");
+ }
+ return Err(anyhow!("waiting for the OCR service").context(Deferred::new(POLL)));
+ };
+
+ let task_id = task["task_id"].as_str().unwrap_or_default();
+ let client = crate::query_engine::http()?;
+ let resp = self
+ .request(&client, reqwest::Method::GET, &format!("tasks/{task_id}"))
+ .send()
+ .await
+ .context("the OCR service is unreachable")?;
+ if resp.status() == reqwest::StatusCode::NOT_FOUND {
+ // 服务重启过、或者结果过了保留期:任务没了,下一轮重交
+ utopia_store::documents::clear_reader_task(pool, doc.id).await?;
+ return Err(anyhow!("the OCR service no longer knows the task")
+ .context(Deferred::new(Duration::from_secs(1))));
+ }
+ let status: Value = resp
+ .error_for_status()
+ .context("the OCR service could not report the task")?
+ .json()
+ .await?;
+ match status["status"].as_str() {
+ Some("completed") => {}
+ Some("failed") => {
+ // 清掉任务号,普通重试会重交一次:显存不够、服务过载这类失败,下一次未必还失败
+ utopia_store::documents::clear_reader_task(pool, doc.id).await?;
+ return Err(anyhow!(
+ "The OCR service could not read this file: {}",
+ status["error"].as_str().unwrap_or("no reason given")
+ ));
+ }
+ _ => {
+ let submitted = task["submitted_at"]
+ .as_str()
+ .and_then(|t| chrono::DateTime::parse_from_rfc3339(t).ok());
+ if submitted.is_some_and(|t| {
+ chrono::Utc::now().signed_duration_since(t)
+ > chrono::Duration::hours(PATIENCE_HOURS)
+ }) {
+ utopia_store::documents::clear_reader_task(pool, doc.id).await?;
+ return Err(anyhow!(
+ "The OCR service did not finish reading this file within {PATIENCE_HOURS} hours"
+ )
+ .context(Terminal));
+ }
+ return Err(anyhow!("waiting for the OCR service").context(Deferred::new(POLL)));
+ }
+ }
+
+ let result: Value = self
+ .request(
+ &client,
+ reqwest::Method::GET,
+ &format!("tasks/{task_id}/result"),
+ )
+ .timeout(TRANSFER_TIMEOUT)
+ .send()
+ .await
+ .context("the OCR service is unreachable")?
+ .error_for_status()
+ .context("the OCR service could not return the result")?
+ .json()
+ .await?;
+ // 一次只交一份文件,结果里就一项;键是服务规整过的文件名,不去猜它的规则
+ let entry = result["results"]
+ .as_object()
+ .and_then(|m| m.values().next())
+ .ok_or_else(|| anyhow!("The OCR service returned no result for this file"))?;
+ let list = match &entry["content_list"] {
+ Value::String(s) => serde_json::from_str(s)
+ .context("The OCR service returned a content list that is not JSON")?,
+ other => other.clone(),
+ };
+ let model = ["mineru", jstr(&result["version"]), jstr(&result["backend"])]
+ .into_iter()
+ .filter(|s| !s.is_empty())
+ .collect::<Vec<_>>()
+ .join(" ");
+ Ok(utopia_ingest::mineru::reading(&list, &model))
+ }
+
+ async fn submit(&self, filename: &str, bytes: Vec<u8>) -> anyhow::Result<String> {
+ let client = crate::query_engine::http()?;
+ let part = reqwest::multipart::Part::bytes(bytes)
+ .file_name(filename.to_string())
+ .mime_str("application/octet-stream")?;
+ let mut form = reqwest::multipart::Form::new()
+ .part("files", part)
+ .text("return_content_list", "true")
+ .text("return_md", "false");
+ if let Some(backend) = self.backend {
+ form = form.text("backend", backend.to_string());
+ }
+ let resp = self
+ .request(&client, reqwest::Method::POST, "tasks")
+ .multipart(form)
+ .timeout(TRANSFER_TIMEOUT)
+ .send()
+ .await
+ .context("the OCR service is unreachable")?;
+ let status = resp.status();
+ if !status.is_success() {
+ let body = resp.text().await.unwrap_or_default();
+ return Err(anyhow!(
+ "The OCR service refused this file ({status}): {}",
+ body.chars().take(300).collect::<String>()
+ ));
+ }
+ let v: Value = resp.json().await?;
+ v["task_id"]
+ .as_str()
+ .map(String::from)
+ .ok_or_else(|| anyhow!("The OCR service accepted the file but returned no task id"))
+ }
+}
+
+fn jstr(v: &Value) -> &str {
+ v.as_str().unwrap_or_default()
+}
diff --git a/crates/utopia-store/src/documents.rs b/crates/utopia-store/src/documents.rs
index f5fb30a0..fa2f4328 100644
--- a/crates/utopia-store/src/documents.rs
+++ b/crates/utopia-store/src/documents.rs
@@ -763,7 +763,8 @@ pub async fn set_status(pool: &PgPool, id: Uuid, status: &str) -> AppResult<()>
pub async fn set_failed(pool: &PgPool, id: Uuid, error: &str) -> AppResult<()> {
sqlx::query(
- "UPDATE documents SET status = 'failed', error = $2, updated_at = now() WHERE id = $1",
+ "UPDATE documents SET status = 'failed', error = $2, reader_task = NULL, updated_at = now()
+ WHERE id = $1",
)
.bind(id)
.bind(error)
@@ -776,7 +777,8 @@ pub async fn set_failed(pool: &PgPool, id: Uuid, error: &str) -> AppResult<()> {
/// 记下缺的是哪一种,配上之后按它重新排队
pub async fn set_needs_reader(pool: &PgPool, id: Uuid, reader: &str, error: &str) -> AppResult<()> {
sqlx::query(
- "UPDATE documents SET status = 'failed', error = $3, reader_needed = $2, updated_at = now()
+ "UPDATE documents SET status = 'failed', error = $3, reader_needed = $2, reader_task = NULL,
+ updated_at = now()
WHERE id = $1",
)
.bind(id)
@@ -787,20 +789,81 @@ pub async fn set_needs_reader(pool: &PgPool, id: Uuid, reader: &str, error: &str
Ok(())
}
-/// 等着 `reader` 那一种模型的文档(活着的),配上模型之后重新排进处理队列用
-pub async fn waiting_for_reader(pool: &PgPool, reader: &str) -> AppResult<Vec<(Uuid, Uuid)>> {
- Ok(sqlx::query_as(
- "SELECT id, kb_id FROM documents
- WHERE reader_needed = $1 AND deleted_at IS NULL ORDER BY created_at, id",
- )
+/// 配上了 `reader` 那一种模型:这个工作区里等着它的文档(活着的)重新排进处理队列。
+///
+/// 一个事务里改状态、排任务,于是不会有「状态改回 pending、任务却没排上」的半截。
+/// 返回 (文档, 库),给调用方逐个推送列表更新
+pub async fn requeue_waiting_for_reader(
+ pool: &PgPool,
+ workspace_id: Uuid,
+ reader: &str,
+) -> AppResult<Vec<(Uuid, Uuid)>> {
+ let mut tx = pool.begin().await?;
+ let rows: Vec<(Uuid, Uuid)> = sqlx::query_as(
+ "UPDATE documents d SET status = 'pending', error = NULL, reader_needed = NULL,
+ reader_task = NULL, updated_at = now()
+ FROM knowledge_bases k
+ WHERE k.id = d.kb_id AND k.workspace_id = $1
+ AND d.reader_needed = $2 AND d.deleted_at IS NULL
+ RETURNING d.id, d.kb_id",
+ )
+ .bind(workspace_id)
.bind(reader)
- .fetch_all(pool)
- .await?)
+ .fetch_all(&mut *tx)
+ .await?;
+ for (id, _) in &rows {
+ crate::jobs::enqueue_with_max_attempts_tx(
+ &mut tx,
+ "process_document",
+ serde_json::json!({ "document_id": id }),
+ 3,
+ )
+ .await?;
+ }
+ tx.commit().await?;
+ Ok(rows)
+}
+
+/// 正在读这份文件的远端任务(0040 第二刀,形状见迁移 0059)
+pub async fn reader_task(pool: &PgPool, id: Uuid) -> AppResult<Option<serde_json::Value>> {
+ Ok(
+ sqlx::query_scalar("SELECT reader_task FROM documents WHERE id = $1")
+ .bind(id)
+ .fetch_optional(pool)
+ .await?
+ .flatten(),
+ )
+}
+
+/// 记下刚提交的远端任务。**只在没有任务时记得上**:同一份文档被重复排队、两个处理任务
+/// 同时交了一份,只有先记上的那个算数,另一个挂回去问它——返回 false
+pub async fn claim_reader_task(
+ pool: &PgPool,
+ id: Uuid,
+ task: &serde_json::Value,
+) -> AppResult<bool> {
+ let done =
+ sqlx::query("UPDATE documents SET reader_task = $2 WHERE id = $1 AND reader_task IS NULL")
+ .bind(id)
+ .bind(task)
+ .execute(pool)
+ .await?;
+ Ok(done.rows_affected() == 1)
+}
+
+/// 作废远端任务(读完、换了文件、服务把它忘了)
+pub async fn clear_reader_task(pool: &PgPool, id: Uuid) -> AppResult<()> {
+ sqlx::query("UPDATE documents SET reader_task = NULL WHERE id = $1")
+ .bind(id)
+ .execute(pool)
+ .await?;
+ Ok(())
}
pub async fn set_ready(pool: &PgPool, id: Uuid, text_len: i32, chunk_count: i32) -> AppResult<()> {
sqlx::query(
- "UPDATE documents SET status = 'ready', error = NULL, reader_needed = NULL, text_len = $2,
+ "UPDATE documents SET status = 'ready', error = NULL, reader_needed = NULL, reader_task = NULL,
+ text_len = $2,
chunk_count = $3, updated_at = now() WHERE id = $1",
)
.bind(id)
@@ -1358,7 +1421,7 @@ pub async fn chunks_full(
document_id: Uuid,
) -> AppResult<Vec<utopia_core::models::ChunkFull>> {
let rows = sqlx::query_as(
- "SELECT id, seq, text FROM chunks
+ "SELECT id, seq, text, origin, origin_model, anchor FROM chunks
WHERE document_id = $1 AND superseded_at IS NULL ORDER BY seq",
)
.bind(document_id)
diff --git a/crates/utopia-store/src/sealing.rs b/crates/utopia-store/src/sealing.rs
index 38bcb643..36876971 100644
--- a/crates/utopia-store/src/sealing.rs
+++ b/crates/utopia-store/src/sealing.rs
@@ -1,7 +1,7 @@
//! 凭据补封:升级前落库的明文凭据,在钥匙装好之后的第一次启动补成密文。
//!
//! 幂等,每次启动都跑:判据是「值没有 `enc:v1:` 前缀」,已封的不动。四处凭据
-//! (`llm_settings` 两把 key、`data_sources.conn_string`、`sources.config` 的凭据键、
+//! (`llm_settings` 三把 key、`data_sources.conn_string`、`sources.config` 的凭据键、
//! `sources.ingest_token`)在这里各扫一遍——加了新的存放处要同时加到这里,否则那一处
//! 会一直是明文而没有任何地方报警。
@@ -22,23 +22,27 @@ pub async fn backfill(pool: &PgPool) -> AppResult<usize> {
/// `only` = 只补这一个工作区(测试用;启动时传 None 扫全部)
pub async fn seal_llm_settings(pool: &PgPool, only: Option<Uuid>) -> AppResult<usize> {
- let rows: Vec<(Uuid, Option<String>, Option<String>)> = sqlx::query_as(
- "SELECT workspace_id, chat_api_key, embed_api_key FROM llm_settings
+ type Keys = (Uuid, Option<String>, Option<String>, Option<String>);
+ let rows: Vec<Keys> = sqlx::query_as(
+ "SELECT workspace_id, chat_api_key, embed_api_key, ocr_api_key FROM llm_settings
WHERE ($1::uuid IS NULL OR workspace_id = $1)
AND ((chat_api_key IS NOT NULL AND chat_api_key NOT LIKE 'enc:v1:%')
- OR (embed_api_key IS NOT NULL AND embed_api_key NOT LIKE 'enc:v1:%'))",
+ OR (embed_api_key IS NOT NULL AND embed_api_key NOT LIKE 'enc:v1:%')
+ OR (ocr_api_key IS NOT NULL AND ocr_api_key NOT LIKE 'enc:v1:%'))",
)
.bind(only)
.fetch_all(pool)
.await?;
let n = rows.len();
- for (ws, chat, embed) in rows {
+ for (ws, chat, embed, ocr) in rows {
sqlx::query(
- "UPDATE llm_settings SET chat_api_key = $2, embed_api_key = $3 WHERE workspace_id = $1",
+ "UPDATE llm_settings SET chat_api_key = $2, embed_api_key = $3, ocr_api_key = $4
+ WHERE workspace_id = $1",
)
.bind(ws)
.bind(secrets::seal_opt(chat.as_deref()))
.bind(secrets::seal_opt(embed.as_deref()))
+ .bind(secrets::seal_opt(ocr.as_deref()))
.execute(pool)
.await?;
}
diff --git a/crates/utopia-store/src/settings.rs b/crates/utopia-store/src/settings.rs
index 13a268a2..25e8a9d5 100644
--- a/crates/utopia-store/src/settings.rs
+++ b/crates/utopia-store/src/settings.rs
@@ -3,11 +3,12 @@ use utopia_core::models::LlmSettings;
use utopia_core::{secrets, AppError, AppResult};
use uuid::Uuid;
-/// 出库即开封:两把 API key 在库里是封印的(`utopia_core::secrets`)。
+/// 出库即开封:三把 API key 在库里是封印的(`utopia_core::secrets`)。
/// 任何返回 `LlmSettings` 的查询都从这里过
fn opened(mut s: LlmSettings) -> AppResult<LlmSettings> {
s.chat_api_key = secrets::open_opt(s.chat_api_key.as_deref()).map_err(AppError::Other)?;
s.embed_api_key = secrets::open_opt(s.embed_api_key.as_deref()).map_err(AppError::Other)?;
+ s.ocr_api_key = secrets::open_opt(s.ocr_api_key.as_deref()).map_err(AppError::Other)?;
Ok(s)
}
@@ -77,3 +78,32 @@ pub async fn upsert(
.await?;
opened(row)
}
+
+/// 版面识别服务的设置,单独存:它在管理页上是自己的一张卡片,存它不该碰对话和嵌入那几列
+/// (反过来也一样——`upsert` 不写这三列)。`api_key` 传 None 保留旧值;地址传 None = 关掉
+pub async fn upsert_ocr(
+ pool: &PgPool,
+ workspace_id: Uuid,
+ base_url: Option<&str>,
+ api_key: Option<&str>,
+ backend: Option<&str>,
+) -> AppResult<LlmSettings> {
+ let api_key = secrets::seal_opt(api_key);
+ let row: LlmSettings = sqlx::query_as(
+ "INSERT INTO llm_settings (workspace_id, ocr_base_url, ocr_api_key, ocr_backend, updated_at)
+ VALUES ($1, $2, $3, $4, now())
+ ON CONFLICT (workspace_id) DO UPDATE SET
+ ocr_base_url = EXCLUDED.ocr_base_url,
+ ocr_api_key = COALESCE(EXCLUDED.ocr_api_key, llm_settings.ocr_api_key),
+ ocr_backend = EXCLUDED.ocr_backend,
+ updated_at = now()
+ RETURNING *",
+ )
+ .bind(workspace_id)
+ .bind(base_url)
+ .bind(api_key)
+ .bind(backend)
+ .fetch_one(pool)
+ .await?;
+ opened(row)
+}
diff --git a/docs/decisions/0040-a-chunk-says-where-its-words-came-from.md b/docs/decisions/0040-a-chunk-says-where-its-words-came-from.md
index 60cd8e42..f29119d2 100644
--- a/docs/decisions/0040-a-chunk-says-where-its-words-came-from.md
+++ b/docs/decisions/0040-a-chunk-says-where-its-words-came-from.md
@@ -8,7 +8,11 @@
PDF with an empty text layer is a scan, and without the model the document fails once with
`documents.reader_needed` and a `document.needs_reader` alert · revised 2026-09-15: scans and
images are read by a MinerU service instead of a Docling sidecar, and a transcript must label
- speakers · readers are cuts 2 and 3
+ speakers · cut 2 implemented (2026-09-15): scans and images are read by a workspace's MinerU
+ service (`llm_settings.ocr_*`, migration 0059), one segment per page with the covered regions'
+ box in the anchor; the processing job waits on the service with `Deferred` and remembers the
+ remote task on the document; saving the service queues the waiting documents again · the
+ settings card is its own interface cut · recordings are cut 3
- **Written**: 2026-09-13 (conventions in the [README](README.md))
- **Related**: [0039](0039-a-chunk-is-what-extraction-sees.md) (#633, not merged yet) puts Docling
behind the block model as its cut 2 and leaves "evidence that points at a table cell or an image
@@ -172,6 +176,23 @@ document are deduplicated by content hash across the base — a logo on fifty sl
description — and skipped below a size floor. A per-document call budget reports what it skipped
instead of dropping it quietly.
+*Cut 2, as built (2026-09-15).* The job that waits is `process_document` itself rather than a
+new job kind. It submits the file to `POST /tasks`, records the remote task on the document
+(`documents.reader_task`: reader, service, task id, the file's `sha256`, when it was submitted),
+and returns `Deferred`, which puts the job back in the queue without spending an attempt. Each
+later run asks `GET /tasks/{id}` and either waits again or fetches the content list. A restart
+resumes from the recorded task; a new file version or a different service discards it. A task
+the service no longer knows is submitted again; a task it reports failed is cleared and takes an
+ordinary retry; a task still unfinished after six hours fails the document for good. MinerU
+returns the whole file at once, so "resumable from the last block written" is resuming from the
+remote task: nothing is read twice unless the service lost it.
+
+Segments are per page, not per region. Every region has its own box, and a segment per region
+would make every paragraph its own chunk. After packing, a chunk's anchor carries the union of
+the boxes of the regions it covers on its page. Page headers, footers and page numbers are
+dropped; tables become Markdown tables, so a long scanned table repeats its header across
+chunks like any other.
+
### 7. The read contract says it
The evidence API, the MCP tool results (`quote`, `document_id` and `filename` today) and the RDF
@@ -186,7 +207,7 @@ the recording at `start_ms` — is a separate cut after the capability, not part
1. **The ledger shape.** `origin`, `origin_model`, `anchor`, the packer rule, the ceiling, the read
contract. No media reader yet; everything that exists is stated, and says so.
-2. **Scans and document images through Docling** (0039's cut 2): `ocr`. The highest value —
+2. **Scans and document images through MinerU** (revised from Docling): `ocr`. The highest value —
scanned contracts, stamped approvals, invoices, all of which fail today with no text layer —
and the modality that keeps the verbatim contract.
3. **Recordings**: `transcribed`, segment times required, speakers where the endpoint labels them.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index bb2ff4ff..df304110 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -63,7 +63,7 @@ The test for writing one: if someone (including us) looks at a piece of code in
| 0037 | [A relation carries its own attributes](0037-a-relation-carries-its-own-attributes.md) | Written · cut 1 in progress: qualifier tables (0049), declaration, extraction, panel, export · entity-valued qualifier reserved, conflict-as-two-rows and the canvas label next |
| 0038 | [The interface has a light side](0038-the-interface-has-a-light-side.md) | Implemented (#599) · `data-theme` on `<html>`, chosen by the reader and stored in the browser, `system` resolved to one of the two before first paint · a second token block in `styles.css` and not one rule rewritten: alpha stays, the triplet swaps · the canvas reads its colours from the tokens through one reader file and rebuilds on a switch; edges are flattened over the ground on light because the WebGL shader can only brighten · a `raw-colour` guard rule over `.ts` and `.tsx` · the entity palette is the same in both themes; a paper-tuned set is open |
| 0039 | [A chunk is what extraction sees](0039-a-chunk-is-what-extraction-sees.md) | Implemented, cut 1 · the parser's Markdown is read into blocks and packed by a token budget (1000, cl100k) · a table travels with its caption and header and a continuation repeats both · headings become a breadcrumb and fill `chunks.heading` · a page-break rule is not a boundary and a table it split is joined back · not measured on its own: the budget · cut 2: an external parser behind the block model, evidence that names a cell or a region |
-| 0040 | [A chunk says where its words came from](0040-a-chunk-says-where-its-words-came-from.md) | Cut 1 implemented (the ledger shape, and a file that needs a reader degrades with an alert instead of becoming garbage text) · scans and images through a MinerU service, recordings only with speaker labels (revised 2026-09-15) · a chunk carries an **origin** (`stated`, `ocr`, `transcribed`, `described`) and the model that produced it, and an **anchor** back into the original bytes (a page and region, a time range, an image inside the file) — decided before any media reader, because a transcript stored without its times can never be tied to the recording again · the packer never mixes origins in a chunk · facts from a description enter below `AUTO_CLOSE_MIN_CONFIDENCE`, so a misread chart opens a conflict instead of closing a correct fact · per-modality model settings, media reading as a resumable job, origin and anchor in the API, MCP and RDF · cuts: ledger shape, scans via Docling, recordings, descriptions, video |
+| 0040 | [A chunk says where its words came from](0040-a-chunk-says-where-its-words-came-from.md) | Cuts 1–2 implemented (the ledger shape, and a file that needs a reader degrades with an alert instead of becoming garbage text; scans and images read by a workspace's MinerU service, one segment per page, waiting on the service without spending retries) · scans and images through a MinerU service, recordings only with speaker labels (revised 2026-09-15) · a chunk carries an **origin** (`stated`, `ocr`, `transcribed`, `described`) and the model that produced it, and an **anchor** back into the original bytes (a page and region, a time range, an image inside the file) — decided before any media reader, because a transcript stored without its times can never be tied to the recording again · the packer never mixes origins in a chunk · facts from a description enter below `AUTO_CLOSE_MIN_CONFIDENCE`, so a misread chart opens a conflict instead of closing a correct fact · per-modality model settings, media reading as a resumable job, origin and anchor in the API, MCP and RDF · cuts: ledger shape, scans via MinerU, recordings, descriptions, video |
| 0041 | [A name is a claim about an entity](0041-a-name-is-a-claim-about-an-entity.md) | Cut 0 built (identity bench) · cut 1 implemented (#670): names are value facts on `known_as`, the extractor reports other names, a shared name goes to the adjudicator; forward/reverse F1 0.43/0.54 → 0.68/0.68 · cuts 2–4 (name vectors and neighbours, evidence decides, re-evaluation) not started |
| 0042 | [The chat loop is a runner with hooks](0042-the-chat-loop-is-a-runner-with-hooks.md) | Implemented (#548) · the loop is rig's runner and every policy is a hook with a typed result · the wire stays `LlmClient` behind `RigModel` · a turn cannot end before a tool has run, `no_evidence_needed` is the exit for questions not about the base · RAG fallback only on a 400/422 to the first request with tools · an empty reply is asked again once · the skip rate is the model's (DeepSeek-V3 1–3 of 12, Qwen2.5-72B 0) and recorded, not prevented |
diff --git a/migrations/0059_a_scan_is_read_by_a_layout_service.sql b/migrations/0059_a_scan_is_read_by_a_layout_service.sql
new file mode 100644
index 00000000..14e5fc22
--- /dev/null
+++ b/migrations/0059_a_scan_is_read_by_a_layout_service.sql
@@ -0,0 +1,20 @@
+-- 扫描件和图片交给版面识别服务读(0040 第二刀)。
+--
+-- 读字的服务按工作区配,跟对话、嵌入分开:一份扫描的合同比一段文字敏感,部署会合理地把
+-- 识别留在本地、对话交给托管模型。服务是 MinerU(`mineru-api`):先认版面再逐区域认字,
+-- 交回每个区域的页码和框,正是 `chunks.anchor` 的 `{"page", "bbox"}`。地址为空 = 关掉,
+-- 需要它的文件照第一刀降级。密钥跟另外两把一样入库即封印。
+ALTER TABLE llm_settings
+ ADD COLUMN ocr_base_url TEXT,
+ ADD COLUMN ocr_api_key TEXT,
+ -- 服务端的后端(pipeline、vlm-auto-engine……);空 = 用服务自己的默认
+ ADD COLUMN ocr_backend TEXT;
+
+-- 正在读这份文件的远端任务。
+--
+-- 识别一份几百页的扫描件要几分钟到几十分钟,不能占着一个任务槽等:提交之后把任务号记在
+-- 这里,处理任务挂回队列过一会儿再来问。进程重启、任务重排都从这里接着问,不重新提交。
+-- 形状:{"reader", "service", "task_id", "sha256", "submitted_at"}——`sha256` 对不上
+-- (文件换了版本)或 `service` 对不上(换了服务)就作废重交。读完、失败都清空
+ALTER TABLE documents
+ ADD COLUMN reader_task JSONB;
diff --git a/web/src/api.ts b/web/src/api.ts
index 77fc32f7..a69ce2e3 100644
--- a/web/src/api.ts
+++ b/web/src/api.ts
@@ -1007,6 +1007,11 @@ export interface ChunkFull {
id: string;
seq: number;
text: string;
+ /** 这块文字从哪来(0040) */
+ origin: "stated" | "ocr" | "transcribed" | "described";
+ origin_model: string | null;
+ /** ocr: {page, bbox?};transcribed: {start_ms, end_ms, speaker} */
+ anchor: Record<string, unknown> | null;
}
export interface EntityTypeView {