Skip to content

World's first open-source enterprise world model.

Embed the question once per chat turn, not on every graph lookup (#971)

Maya Kid21d2de2cae30
diff --git a/crates/utopia-server/src/api/chat_embed_once_tests.rs b/crates/utopia-server/src/api/chat_embed_once_tests.rs
new file mode 100644
index 00000000..c8972dd7
--- /dev/null
+++ b/crates/utopia-server/src/api/chat_embed_once_tests.rs
@@ -0,0 +1,242 @@
+//! 同一轮里,同一句话只嵌一次。
+//!
+//! 同名实体的候选按问题排(`rank_by_question`):问题嵌成向量,与候选的上下文画像比。
+//! 一轮里每按名字查一次实体都走到那里,句子是同一句;从前每次都重新嵌一遍,读一次模型
+//! 设置、调一次嵌入服务。谓词对不上时的对齐(`aligned_predicates`)也是这样。
+//!
+//! 假嵌入服务记下每次请求的文字,每条都回同一个方向。两个都叫 Acme 的实体,画像近的
+//! 那个事实少:不按问题排(MCP 没有问题),按事实数排在前面的是远的那个。
+//!
+//! - 工具层(同一个 sink 就是同一轮):find_entities、按名字的 entity_facts 与
+//! neighbors 都挑中近的那个,问题只嵌一次;同一个对不上的谓词问两次,那个词只嵌
+//! 一次;换一个 sink(下一轮),问题再嵌一次
+//! - 整条对话:模型先 find_entities,再按名字 entity_facts,嵌入服务只收到一次请求
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
+use super::*;
+use crate::api::tools::{dispatch, ToolCtx, ToolSink};
+
+const QUESTION: &str = "Where is the Acme lab?";
+
+/// 假嵌入服务:记下每次请求的输入,每条都回 (1, 0, 0)
+#[derive(Clone, Default)]
+struct Embedder {
+ inputs: Arc<Mutex<Vec<Vec<String>>>>,
+}
+
+async fn embeddings(
+ State(e): State<Embedder>,
+ Json(body): Json<serde_json::Value>,
+) -> Json<serde_json::Value> {
+ let texts: Vec<String> = body["input"]
+ .as_array()
+ .into_iter()
+ .flatten()
+ .filter_map(|t| t.as_str().map(str::to_string))
+ .collect();
+ let data: Vec<serde_json::Value> = (0..texts.len())
+ .map(|i| json!({"index": i, "embedding": [1.0, 0.0, 0.0]}))
+ .collect();
+ e.inputs.lock().unwrap().push(texts);
+ Json(json!({"data": data}))
+}
+
+impl Embedder {
+ /// 每次请求一行,行里是那次嵌的文字
+ fn requests(&self) -> Vec<Vec<String>> {
+ self.inputs.lock().unwrap().clone()
+ }
+}
+
+struct Acme {
+ near: Uuid,
+ far: Uuid,
+}
+
+/// 起假嵌入服务,把这个库所在工作区的嵌入模型指过去;种两个 Acme:
+/// 近的那个画像与假向量同向、一条事实,远的那个画像正交、两条事实
+async fn seed(f: &Fx) -> anyhow::Result<(Embedder, tokio::task::JoinHandle<()>, Acme)> {
+ let embedder = Embedder::default();
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
+ let base = format!("http://{}", listener.local_addr()?);
+ let app = axum::Router::new()
+ .route("/embeddings", axum::routing::post(embeddings))
+ .with_state(embedder.clone());
+ let server = tokio::spawn(async move {
+ let _ = axum::serve(listener, app).await;
+ });
+ sqlx::query(
+ "UPDATE llm_settings SET embed_base_url = $1, embed_model = 'fake-embedding'
+ WHERE workspace_id = (SELECT workspace_id FROM knowledge_bases WHERE id = $2)",
+ )
+ .bind(&base)
+ .bind(f.kb)
+ .execute(&f.pool)
+ .await?;
+
+ let id = Uuid::now_v7;
+ let (org, place, located_in) = (id(), id(), id());
+ let (near, far, harbor, port) = (id(), id(), id(), id());
+ // 插进去的只有本地生成的 UUID
+ sqlx::raw_sql(&format!(
+ r#"
+ INSERT INTO entity_types(id,kb_id,key,label) VALUES
+ ('{org}','{kb}','organization','Organization'), ('{place}','{kb}','place','Place');
+ INSERT INTO relation_types(id,kb_id,key,label,temporal) VALUES
+ ('{located_in}','{kb}','located_in','located in','state');
+ INSERT INTO entities(id,kb_id,type_id,canonical_name,profile_embedding) VALUES
+ ('{near}','{kb}','{org}','Acme','[1,0,0]'),
+ ('{far}','{kb}','{org}','Acme','[0,1,0]'),
+ ('{harbor}','{kb}','{place}','Harbor',NULL),
+ ('{port}','{kb}','{place}','Port',NULL);
+ INSERT INTO facts(id,kb_id,subject_id,predicate_id,object_id,confidence) VALUES
+ ('{f1}','{kb}','{near}','{located_in}','{harbor}',0.9),
+ ('{f2}','{kb}','{far}','{located_in}','{harbor}',0.9),
+ ('{f3}','{kb}','{far}','{located_in}','{port}',0.9);
+ "#,
+ kb = f.kb,
+ f1 = id(),
+ f2 = id(),
+ f3 = id(),
+ ))
+ .execute(&f.pool)
+ .await?;
+ Ok((embedder, server, Acme { near, far }))
+}
+
+/// 一轮对话的工具上下文;`question` 为 None 就是 MCP 那样没有问题的调用。
+/// `embed` 按工作区读模型设置,所以用这个库真正所在的工作区
+async fn ctx<'f>(f: &'f Fx, question: Option<&'f str>) -> anyhow::Result<ToolCtx<'f>> {
+ let workspace_id: Uuid =
+ sqlx::query_scalar("SELECT workspace_id FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .fetch_one(&f.pool)
+ .await?;
+ Ok(ToolCtx {
+ state: &f.state,
+ kb_id: f.kb,
+ workspace_id,
+ mounted_sources: &[],
+ can_write: false,
+ actor: Some(f.user.id),
+ via_token: None,
+ question,
+ })
+}
+
+#[tokio::test]
+async fn a_turn_embeds_its_question_and_each_word_once() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![])).await? else {
+ return Ok(());
+ };
+ let (embedder, server, acme) = seed(&f).await?;
+ let run = async {
+ // 没有问题(MCP 那样):不嵌,按事实数挑,排在前面的是远的那个
+ let plain = dispatch(
+ &ctx(&f, None).await?,
+ &mut ToolSink::default(),
+ "find_entities",
+ &json!({"name": "Acme"}),
+ )
+ .await;
+ assert!(
+ plain
+ .text
+ .lines()
+ .nth(1)
+ .is_some_and(|l| l.starts_with(&acme.far.to_string())),
+ "{}",
+ plain.text
+ );
+ assert!(embedder.requests().is_empty());
+
+ let ctx = ctx(&f, Some(QUESTION)).await?;
+ let mut turn = ToolSink::default();
+
+ // 三次按名字查 Acme:都挑中画像近的那个,问题只嵌一次
+ let found = dispatch(&ctx, &mut turn, "find_entities", &json!({"name": "Acme"})).await;
+ assert!(
+ found
+ .text
+ .starts_with(&format!("Best match: {} |", acme.near)),
+ "{}",
+ found.text
+ );
+ let facts = dispatch(
+ &ctx,
+ &mut turn,
+ "entity_facts",
+ &json!({"entity_id": "Acme"}),
+ )
+ .await;
+ assert!(
+ facts.text.contains("closest to the question") && !facts.text.contains("Port"),
+ "the near Acme (one fact, Harbor): {}",
+ facts.text
+ );
+ let near = dispatch(&ctx, &mut turn, "neighbors", &json!({"entity": "Acme"})).await;
+ assert!(
+ near.text.contains("closest to the question") && !near.text.contains("Port"),
+ "{}",
+ near.text
+ );
+ assert_eq!(embedder.requests(), vec![vec![QUESTION.to_string()]]);
+
+ // 对不上的谓词问两次:那个词只嵌一次,问题仍不重嵌
+ for _ in 0..2 {
+ dispatch(
+ &ctx,
+ &mut turn,
+ "entity_facts",
+ &json!({"entity_id": "Acme", "predicate": "headquarters"}),
+ )
+ .await;
+ }
+ assert_eq!(
+ embedder.requests(),
+ vec![vec![QUESTION.to_string()], vec!["headquarters".to_string()]]
+ );
+
+ // 下一轮是另一个 sink:问题再嵌一次,挑的还是近的那个
+ let mut next = ToolSink::default();
+ let again = dispatch(&ctx, &mut next, "find_entities", &json!({"name": "Acme"})).await;
+ assert!(
+ again
+ .text
+ .starts_with(&format!("Best match: {} |", acme.near)),
+ "{}",
+ again.text
+ );
+ assert_eq!(embedder.requests().len(), 3);
+ anyhow::Ok(())
+ }
+ .await;
+ server.abort();
+ f.cleanup().await?;
+ run
+}
+
+#[tokio::test]
+async fn a_chat_turn_embeds_its_question_once() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![
+ Reply::Tool("find_entities", r#"{"name":"Acme"}"#),
+ Reply::Tool("entity_facts", r#"{"entity_id":"Acme"}"#),
+ Reply::Text("The Acme lab is in Harbor."),
+ ]))
+ .await?
+ else {
+ return Ok(());
+ };
+ let (embedder, server, _) = seed(&f).await?;
+ let run = async {
+ let sse = f.ask(QUESTION).await?;
+ assert!(sse.contains("event: done"), "{sse}");
+ assert_eq!(sse.matches("event: step").count(), 2, "{sse}");
+ assert_eq!(embedder.requests(), vec![vec![QUESTION.to_string()]]);
+ anyhow::Ok(())
+ }
+ .await;
+ server.abort();
+ f.cleanup().await?;
+ run
+}
diff --git a/crates/utopia-server/src/api/chat_empty_reply_tests.rs b/crates/utopia-server/src/api/chat_empty_reply_tests.rs
index a4e0e317..88ec03e2 100644
--- a/crates/utopia-server/src/api/chat_empty_reply_tests.rs
+++ b/crates/utopia-server/src/api/chat_empty_reply_tests.rs
@@ -371,6 +371,8 @@ async fn a_reply_that_stays_empty_is_an_error_after_one_retry() -> anyhow::Resul
f.cleanup().await
}
+#[path = "chat_embed_once_tests.rs"]
+mod embed_once_tests;
#[path = "chat_error_code_tests.rs"]
mod error_code_tests;
#[path = "chat_fallback_tests.rs"]
diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rs
index 144a8328..bc13424d 100644
--- a/crates/utopia-server/src/api/tools.rs
+++ b/crates/utopia-server/src/api/tools.rs
@@ -73,6 +73,16 @@ impl ToolCtx<'_> {
}
}
}
+
+ /// [`Self::embed`],同一轮里同样的文字只嵌一次(见 [`ToolSink::embeddings`])
+ pub async fn embed_once(&self, sink: &mut ToolSink, text: &str) -> Option<Vec<f32>> {
+ if let Some(vec) = sink.embeddings.get(text) {
+ return Some(vec.clone());
+ }
+ let vec = self.embed(text).await?;
+ sink.embeddings.insert(text.to_string(), vec.clone());
+ Some(vec)
+ }
}
/// 工具执行过程中往外攒的东西。
@@ -87,6 +97,10 @@ pub struct ToolSink {
pub sources: Vec<serde_json::Value>,
/// 这一轮认下的实体,落进会话供下一轮回放
pub resolved: Vec<serde_json::Value>,
+ /// 这一轮嵌过的文字与它的向量,不落库。同名实体每按名字查一次,都拿同一句问题去比
+ /// 画像;谓词对不上时,同一个词也会再嵌。一轮之内文字与模型都不变,嵌一次就够:
+ /// 对话一轮一个 sink,MCP 一次调用一个。只记成功的,失败了下次照样再试
+ pub embeddings: std::collections::HashMap<String, Vec<f32>>,
}
/// 界面上的一步(#942)。
diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rs
index 80906902..08c16b00 100644
--- a/crates/utopia-server/src/api/tools_graph.rs
+++ b/crates/utopia-server/src/api/tools_graph.rs
@@ -129,7 +129,7 @@ async fn resolve(
tracing::warn!(error = %e, "Entity lookup failed");
ResolveError::ReadFailed
})?;
- let (ranked, by_question) = rank_by_question(ctx, rank(hits, raw), raw).await;
+ let (ranked, by_question) = rank_by_question(ctx, sink, rank(hits, raw), raw).await;
let Some(first) = ranked.first() else {
return Err(ResolveError::Unresolved(format!(
"no entity named \"{raw}\" in this base"
@@ -266,7 +266,7 @@ pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
}
};
let read = hits.len();
- let (ranked, by_question) = rank_by_question(ctx, rank(hits, &name), &name).await;
+ let (ranked, by_question) = rank_by_question(ctx, sink, rank(hits, &name), &name).await;
let clear = by_question || dominant(&ranked, &name);
let mut text = if ranked.is_empty() {
"No matching entities.".to_string()
@@ -473,11 +473,13 @@ pub(super) fn word_score(name: &str, words: &[&str]) -> usize {
.count()
}
-/// 同名候选按问题排:用户的问题嵌一次,与候选的上下文画像比,近的在前。
+/// 同名候选按问题排:用户的问题嵌成向量,与候选的上下文画像比,近的在前。问题一轮
+/// 只嵌一次(`embed_once`):这一轮里每按名字查一次实体都会走到这里,句子却是同一句。
/// 精确命中仍在前(问 OpenAI 就先给叫 OpenAI 的),画像只在同一档里排序。
/// 没有问题(MCP)、没有嵌入模型、只有一个候选:原样返回,第二个值说明有没有用上
async fn rank_by_question(
ctx: &ToolCtx<'_>,
+ sink: &mut ToolSink,
ranked: Vec<GraphNode>,
query: &str,
) -> (Vec<GraphNode>, bool) {
@@ -487,7 +489,7 @@ async fn rank_by_question(
let Some(question) = ctx.question else {
return (ranked, false);
};
- let Some(vec) = ctx.embed(question).await else {
+ let Some(vec) = ctx.embed_once(sink, question).await else {
return (ranked, false);
};
let ids: Vec<Uuid> = ranked.iter().map(|n| n.id).collect();
@@ -527,8 +529,8 @@ pub(super) fn reorder_by_distance(
const PREDICATE_DISTANCE: f32 = 0.45;
const PREDICATE_CANDIDATES: i64 = 5;
-async fn aligned_predicates(ctx: &ToolCtx<'_>, word: &str) -> Vec<String> {
- let Some(vec) = ctx.embed(word).await else {
+async fn aligned_predicates(ctx: &ToolCtx<'_>, sink: &mut ToolSink, word: &str) -> Vec<String> {
+ let Some(vec) = ctx.embed_once(sink, word).await else {
return Vec::new();
};
let near = utopia_store::ontology::nearest_relation_types(
@@ -552,6 +554,7 @@ async fn aligned_predicates(ctx: &ToolCtx<'_>, word: &str) -> Vec<String> {
/// 过滤;谓词按子串对不上时向量对齐一次,回一句说明给结果开头
async fn filtered<'f>(
ctx: &ToolCtx<'_>,
+ sink: &mut ToolSink,
facts: &'f [EntityFact],
filter: &FactFilter<'_>,
) -> (Vec<&'f EntityFact>, Option<String>) {
@@ -562,7 +565,10 @@ async fn filtered<'f>(
if !kept.is_empty() || facts.is_empty() {
return (kept, None);
}
- let keys: HashSet<String> = aligned_predicates(ctx, word).await.into_iter().collect();
+ let keys: HashSet<String> = aligned_predicates(ctx, sink, word)
+ .await
+ .into_iter()
+ .collect();
if keys.is_empty() {
return (kept, None);
}
@@ -727,7 +733,7 @@ pub async fn entity_facts(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
tracing::warn!(error = %e, "Entity names lookup failed");
Vec::new()
});
- let (kept, aligned) = filtered(ctx, &facts, &filter).await;
+ let (kept, aligned) = filtered(ctx, sink, &facts, &filter).await;
let shown: Vec<&EntityFact> = kept.iter().copied().take(limit).collect();
let mut lines: Vec<String> = Vec::new();
if let Some(note) = &who.note {
@@ -900,7 +906,7 @@ pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) ->
};
remember(sink, &node);
// 邻居是对端**实体**;属性值不算邻居,entity_facts 里有
- let (matched, aligned) = filtered(ctx, &facts, &filter).await;
+ let (matched, aligned) = filtered(ctx, sink, &facts, &filter).await;
let linked: Vec<&EntityFact> = matched
.into_iter()
.filter(|f| f.other_id.is_some())
@@ -1038,7 +1044,7 @@ pub async fn timeline(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> T
remember(sink, &node);
// 只要**说出了世界时间**的事实。没日期的那些起点是摄取时刻,排进时间线只会
// 把一篇文章的日期当成事件的日期
- let (matched, aligned) = filtered(ctx, &facts, &filter).await;
+ let (matched, aligned) = filtered(ctx, sink, &facts, &filter).await;
let mut dated: Vec<&EntityFact> = matched
.into_iter()
.filter(|f| f.valid_from.is_some())