World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A scan is read by a layout service (#720)
WaylandYangabab6cffa54f
diff --git a/Cargo.toml b/Cargo.tomlindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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 ®ions {+ 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsindex 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: &strOk(())}-/// 等着 `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 chunksWHERE 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.rsindex 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_settingsWHERE ($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.rsindex 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.mdindex 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 andimages 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 Doclingbehind 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 sldescription — and skipped below a size floor. A per-document call budget reports what it skippedinstead 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 itThe 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 part1. **The ledger shape.** `origin`, `origin_model`, `anchor`, the packer rule, the ceiling, the readcontract. 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.mdindex 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.sqlnew file mode 100644index 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.tsindex 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 {