Skip to content

World's first open-source enterprise world 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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
+}