World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A search does not hold a runtime worker, and its two channels run side by side (#535)
WaylandYangcb996aa060df
diff --git a/crates/utopia-search/src/lib.rs b/crates/utopia-search/src/lib.rsindex 9a30bf0a..a905506a 100644--- a/crates/utopia-search/src/lib.rs+++ b/crates/utopia-search/src/lib.rs@@ -183,3 +183,41 @@ pub fn rrf_fuse(lists: &[Vec<String>], limit: usize) -> Vec<String> {ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));ranked.into_iter().take(limit).map(|(id, _)| id).collect()}++#[cfg(test)]+mod rrf_tests {+ use super::rrf_fuse;++ fn ids(list: &[&str]) -> Vec<String> {+ list.iter().map(|s| s.to_string()).collect()+ }++ /// 一路召回就是那一路的顺序,融合不许重排+ #[test]+ fn one_list_comes_back_in_its_own_order() {+ let lists = vec![ids(&["a", "b", "c"])];+ assert_eq!(rrf_fuse(&lists, 10), ids(&["a", "b", "c"]));+ }++ /// 两路都点名的排最前;只在一路里的按各自名次的倒数相加比大小:+ /// a = 1/61 + 1/62,c = 1/63 + 1/61,b = 1/62+ #[test]+ fn two_lists_follow_the_reciprocal_rank_arithmetic() {+ let lists = vec![ids(&["a", "b", "c"]), ids(&["c", "a"])];+ assert_eq!(rrf_fuse(&lists, 10), ids(&["a", "c", "b"]));+ }++ /// 空的那一路不是失败的那一路:它什么分都不加,也不影响别人+ #[test]+ fn an_empty_list_contributes_nothing() {+ let lists = vec![ids(&["a", "b"]), Vec::new()];+ assert_eq!(rrf_fuse(&lists, 10), ids(&["a", "b"]));+ }++ /// 上限在融合之后裁,不是每路各裁+ #[test]+ fn the_limit_cuts_after_fusion() {+ let lists = vec![ids(&["a", "b"]), ids(&["b", "c"])];+ assert_eq!(rrf_fuse(&lists, 1), ids(&["b"]));+ }+}diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rsindex 3a65c2ad..1ebedf86 100644--- a/crates/utopia-server/src/api/tools.rs+++ b/crates/utopia-server/src/api/tools.rs@@ -238,7 +238,16 @@ pub async fn search_docs(// 必填参数由 `chat::check_call` 在派发之前挡下,所以这里不再回落到// 用户那句原话——回落产出的是一个看起来没问题的错误答案let q = args["query"].as_str().unwrap_or_default().to_string();- let hits = ctx.state.docs.search(&q, 4).unwrap_or_default();+ // Tantivy 是同步的,放到阻塞线程池上,别占 runtime 线程(#515,与 retrieval.rs 同理)+ let hits = {+ let docs = ctx.state.docs.clone();+ let q = q.clone();+ tokio::task::spawn_blocking(move || docs.search(&q, 4))+ .await+ .ok()+ .and_then(Result::ok)+ .unwrap_or_default()+ };let mut lines = Vec::new();for h in &hits {let key = format!("charter:{}#{}", h.slug, h.anchor);diff --git a/crates/utopia-server/src/retrieval.rs b/crates/utopia-server/src/retrieval.rsindex f53c8d0f..b5d53ba5 100644--- a/crates/utopia-server/src/retrieval.rs+++ b/crates/utopia-server/src/retrieval.rs@@ -6,6 +6,13 @@//! 带时刻检索时,BM25 找回来的东西**是对的**(随后按当时的活性过滤),但它//! 找不回当时有、如今已被顶掉的那些块——召回缺一角,命中不会出错。//! 要补那一角得给全文索引也建版本,那是另一件事,不在这一刀里。+//!+//! **两路并行,BM25 在阻塞线程池上跑**(#515)。`SearchIndex::search` 是同步的:+//! 切词、走 mmap 段、逐条取文档,跑多久就占一条 runtime 线程多久;仓库里另外六处+//! Tantivy 调用都包了 `spawn_blocking`,这里是每次提问都走的最热一处,从前没包,+//! 两核机器上两个人同时提问就把 SSE、健康检查一起卡住。两路从前还串着:BM25 跑完+//! 才去调嵌入端点,嵌入回来才查向量,而嵌入是一次网络往返、整个函数最贵的一项,+//! 跟 BM25 毫无依赖。并起来之后延迟是两路取大,不是相加。use crate::llm_util;use crate::state::AppState;@@ -23,36 +30,90 @@ pub async fn hybrid(top_k: usize,as_of: Option<chrono::DateTime<chrono::Utc>>,) -> AppResult<Vec<ChunkView>> {- let mut lists: Vec<Vec<String>> = Vec::new();-- // BM25- let bm25 = state- .search- .search(&kb_id.to_string(), query, RECALL_PER_CHANNEL)+ let bm25 = {+ let search = state.search.clone();+ let kb = kb_id.to_string();+ let query = query.to_string();+ tokio::task::spawn_blocking(move || search.search(&kb, &query, RECALL_PER_CHANNEL))+ };+ // `join!` 不是 `try_join!`:向量那一路失败是降级不是错误(见 vector_channel),+ // `try_join!` 会把模型故障变成检索报错+ let (bm25, vector) = tokio::join!(+ bm25,+ vector_channel(state, kb_id, workspace_id, query, as_of)+ );+ let bm25 = bm25+ .map_err(|e| utopia_core::AppError::Other(anyhow::anyhow!("BM25 检索线程退出:{e}")))?.map_err(utopia_core::AppError::Other)?;- lists.push(bm25.into_iter().map(|h| h.chunk_id).collect());+ let lists = channel_lists(bm25.into_iter().map(|h| h.chunk_id).collect(), vector?);++ let fused = utopia_search::rrf_fuse(&lists, top_k);+ let ids: Vec<Uuid> = fused.iter().filter_map(|s| s.parse().ok()).collect();+ utopia_store::documents::chunks_by_ids(&state.pool, kb_id, &ids, as_of).await+}- // 向量(可选通道)+/// 向量那一路。没配嵌入模型、嵌入请求失败、回了空,都是 `Ok(None)`:检索照常,+/// 只剩 BM25——这就是模块头说的静默降级。向量查询本身失败仍是 `Err`:那是库的事,+/// 不是模型的事,吞掉会把坏库伪装成没配模型。+async fn vector_channel(+ state: &AppState,+ kb_id: Uuid,+ workspace_id: Uuid,+ query: &str,+ as_of: Option<chrono::DateTime<chrono::Utc>>,+) -> AppResult<Option<Vec<String>>> {let settings = utopia_store::settings::get(&state.pool, workspace_id).await?;- if let Some(client) = settings.as_ref().and_then(llm_util::embed_client) {- match client.embed(&[query.to_string()]).await {- Ok(mut embeddings) if !embeddings.is_empty() => {- let ids = utopia_store::documents::vector_search(- &state.pool,- kb_id,- &embeddings.remove(0),- RECALL_PER_CHANNEL as i64,- as_of,- )- .await?;- lists.push(ids.into_iter().map(|id| id.to_string()).collect());- }- Ok(_) => {}- Err(e) => tracing::warn!(error = %e, "查询 embedding 失败,降级为纯 BM25"),+ let Some(client) = settings.as_ref().and_then(llm_util::embed_client) else {+ return Ok(None);+ };+ let mut embeddings = match client.embed(&[query.to_string()]).await {+ Ok(v) => v,+ Err(e) => {+ tracing::warn!(error = %e, "查询 embedding 失败,降级为纯 BM25");+ return Ok(None);}+ };+ if embeddings.is_empty() {+ return Ok(None);}+ let ids = utopia_store::documents::vector_search(+ &state.pool,+ kb_id,+ &embeddings.remove(0),+ RECALL_PER_CHANNEL as i64,+ as_of,+ )+ .await?;+ Ok(Some(ids.into_iter().map(|id| id.to_string()).collect()))+}- let fused = utopia_search::rrf_fuse(&lists, top_k);- let ids: Vec<Uuid> = fused.iter().filter_map(|s| s.parse().ok()).collect();- utopia_store::documents::chunks_by_ids(&state.pool, kb_id, &ids, as_of).await+/// 送进 RRF 的列表:BM25 恒在第一位,向量有就在第二位。顺序钉死、不看谁先回来——+/// 今天的 RRF 不看顺序,将来若给通道加权就看了,不能让它取决于哪路网络快。+fn channel_lists(bm25: Vec<String>, vector: Option<Vec<String>>) -> Vec<Vec<String>> {+ let mut lists = vec![bm25];+ if let Some(vector) = vector {+ lists.push(vector);+ }+ lists+}++#[cfg(test)]+mod tests {+ use super::channel_lists;++ #[test]+ fn the_channels_keep_their_places_whichever_answered_first() {+ let lists = channel_lists(vec!["b".into()], Some(vec!["v".into()]));+ assert_eq!(lists, vec![vec!["b".to_string()], vec!["v".to_string()]]);+ }++ #[test]+ fn a_missing_vector_channel_leaves_bm25_alone() {+ let lists = channel_lists(vec!["b".into()], None);+ assert_eq!(lists, vec![vec!["b".to_string()]]);+ }}++#[cfg(test)]+#[path = "retrieval_tests.rs"]+mod retrieval_tests;diff --git a/crates/utopia-server/src/retrieval_tests.rs b/crates/utopia-server/src/retrieval_tests.rsnew file mode 100644index 00000000..1c413fef--- /dev/null+++ b/crates/utopia-server/src/retrieval_tests.rs@@ -0,0 +1,188 @@+//! #515:混合检索的两路各走各的,丢一路是降级不是失败。+//!+//! 夹具:一个库、一篇文档、两个分块。A 的正文能被 BM25 命中,B 不能;+//! 两块各有一个 4 维向量,嵌入端点用 wiremock 假扮,想回什么向量就回什么。+//! 三件事:+//! 1. **没配嵌入模型也能答**:只剩 BM25 那一路,A 回来,B 不回来。+//! 2. **嵌入请求失败退化成 BM25**:端点回 500,结果与上一条一样,不是报错。+//! 3. **两路都在时按 BM25 在前融合**:端点回的向量离 A 最近,A 同时在两路里,排第一;+//! B 只在向量那一路,排第二。++use std::sync::Arc;+use uuid::Uuid;+use wiremock::{matchers::method, matchers::path, Mock, MockServer, ResponseTemplate};++struct Fixture {+ pool: sqlx::PgPool,+ state: crate::state::AppState,+ org: Uuid,+ ws: Uuid,+ kb: Uuid,+ a: Uuid,+ b: Uuid,+ dir: std::path::PathBuf,+}++async fn fixture() -> anyhow::Result<Option<Fixture>> {+ let Some(url) = utopia_store::test_db::url() else {+ return Ok(None);+ };+ let pool = sqlx::PgPool::connect(&url).await?;+ let (org, ws, kb, doc, a, b) = (+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ );+ sqlx::query("INSERT INTO organizations(id,name) VALUES($1,'retrieval-test')")+ .bind(org)+ .execute(&pool)+ .await?;+ sqlx::query("INSERT INTO workspaces(id,org_id,name) VALUES($1,$2,'retrieval-test')")+ .bind(ws)+ .bind(org)+ .execute(&pool)+ .await?;+ sqlx::query("INSERT INTO knowledge_bases(id,workspace_id,name) VALUES($1,$2,'retrieval-test')")+ .bind(kb)+ .bind(ws)+ .execute(&pool)+ .await?;+ sqlx::query(+ "INSERT INTO documents(id,kb_id,filename,sha256) VALUES($1,$2,'orchard.md',repeat('0',64))",+ )+ .bind(doc)+ .bind(kb)+ .execute(&pool)+ .await?;+ sqlx::query(+ "INSERT INTO chunks(id,kb_id,document_id,seq,text,embedding) VALUES+ ($1,$3,$4,0,'apple orchard harvest report','[1,0,0,0]'::vector),+ ($2,$3,$4,1,'bridge concrete inspection','[0,1,0,0]'::vector)",+ )+ .bind(a)+ .bind(b)+ .bind(kb)+ .bind(doc)+ .execute(&pool)+ .await?;++ let dir = std::env::temp_dir().join(format!("utopia-retrieval-{kb}"));+ let cfg = utopia_core::config::AppConfig {+ data_dir: dir.to_string_lossy().into_owned(),+ ..Default::default()+ };+ let search = Arc::new(utopia_search::SearchIndex::open(&dir.join("search"))?);+ search.reindex_document(+ &kb.to_string(),+ &doc.to_string(),+ &[+ (a.to_string(), "apple orchard harvest report".into()),+ (b.to_string(), "bridge concrete inspection".into()),+ ],+ )?;+ let state = crate::state::AppState::new(pool.clone(), &cfg, search, "test-only".into());+ Ok(Some(Fixture {+ pool,+ state,+ org,+ ws,+ kb,+ a,+ b,+ dir,+ }))+}++impl Fixture {+ async fn point_embeddings_at(&self, server: &MockServer) -> anyhow::Result<()> {+ utopia_store::settings::upsert(+ &self.pool,+ self.ws,+ None,+ None,+ None,+ Some(&server.uri()),+ None,+ Some("fake-embed"),+ None,+ )+ .await?;+ Ok(())+ }++ async fn search(&self, query: &str) -> anyhow::Result<Vec<Uuid>> {+ let chunks = super::hybrid(&self.state, self.kb, self.ws, query, 8, None).await?;+ Ok(chunks.into_iter().map(|c| c.id).collect())+ }++ async fn cleanup(self) -> anyhow::Result<()> {+ sqlx::query("DELETE FROM organizations WHERE id=$1")+ .bind(self.org)+ .execute(&self.pool)+ .await?;+ let _ = std::fs::remove_dir_all(&self.dir);+ Ok(())+ }+}++#[tokio::test]+async fn a_search_without_an_embedding_model_still_answers() -> anyhow::Result<()> {+ let Some(f) = fixture().await? else {+ return Ok(());+ };+ let ids = f.search("apple harvest").await?;+ assert_eq!(+ ids,+ vec![f.a],+ "BM25 alone finds the orchard chunk and nothing else"+ );+ f.cleanup().await+}++#[tokio::test]+async fn a_failed_query_embedding_degrades_to_bm25() -> anyhow::Result<()> {+ let Some(f) = fixture().await? else {+ return Ok(());+ };+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/embeddings"))+ .respond_with(ResponseTemplate::new(500).set_body_string("model is down"))+ .mount(&server)+ .await;+ f.point_embeddings_at(&server).await?;+ let ids = f.search("apple harvest").await?;+ assert_eq!(+ ids,+ vec![f.a],+ "a dead embedding endpoint costs the vector channel, not the answer"+ );+ f.cleanup().await+}++#[tokio::test]+async fn both_channels_fuse_with_bm25_first() -> anyhow::Result<()> {+ let Some(f) = fixture().await? else {+ return Ok(());+ };+ let server = MockServer::start().await;+ // 回的向量就是 A 的向量:向量那一路按距离排出 [A, B],BM25 那一路只有 [A]+ Mock::given(method("POST"))+ .and(path("/embeddings"))+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({+ "data": [{ "embedding": [1.0, 0.0, 0.0, 0.0] }]+ })))+ .mount(&server)+ .await;+ f.point_embeddings_at(&server).await?;+ let ids = f.search("apple harvest").await?;+ assert_eq!(+ ids,+ vec![f.a, f.b],+ "the chunk both channels found ranks first; the vector-only chunk still comes back"+ );+ f.cleanup().await+}