World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 同一轮里,同一句话只嵌一次。
//!
//! 同名实体的候选按问题排(`rank_by_question`):问题嵌成向量,与候选的上下文画像比。
//! 一轮里每按名字查一次实体都走到那里,句子是同一句;从前每次都重新嵌一遍,读一次模型
//! 设置、调一次嵌入服务。谓词对不上时的对齐(`aligned_predicates`)也是这样。
//!
//! 假嵌入服务记下每次请求的文字,每条都回同一个方向。两个都叫 Acme 的实体,画像近的
//! 那个事实少:不按问题排(MCP 没有问题),按事实数排在前面的是远的那个。
//!
//! - 工具层(同一个 sink 就是同一轮):find_entities、按名字的 entity_facts 与
//! neighbors 都挑中近的那个,问题只嵌一次;同一个对不上的谓词问两次,那个词只嵌
//! 一次;换一个 sink(下一轮),问题再嵌一次
//! - 整条对话:模型先 search_chunks(检索词就是那句问题),再 find_entities、按名字
//! entity_facts,嵌入服务只收到一次请求
//! - 挑口径(`mapping_index::relevant`)、检索分块(`retrieval::hybrid`)和按名字查实体
//! 共用这一轮的缓存:问题只嵌一次;没有缓存的调用方各嵌各的(#971 的后续)
//!
//! 没有 `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("search_chunks", r#"{"query":"Where is the Acme lab?"}"#),
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(), 3, "{sse}");
assert_eq!(embedder.requests(), vec![vec![QUESTION.to_string()]]);
anyhow::Ok(())
}
.await;
server.abort();
f.cleanup().await?;
run
}
/// 挑口径、检索分块、按名字查实体三处拿的是同一个向量;换一句检索词才再嵌一次;
/// 没有缓存的调用方(HTTP 检索、口径页)各嵌各的
#[tokio::test]
async fn mappings_search_and_the_graph_tools_share_one_embedding() -> anyhow::Result<()> {
let Some(f) = fixture(Scripted::new(vec![])).await? else {
return Ok(());
};
let (embedder, server, acme) = seed(&f).await?;
let run = async {
let ws: Uuid = sqlx::query_scalar("SELECT workspace_id FROM knowledge_bases WHERE id = $1")
.bind(f.kb)
.fetch_one(&f.pool)
.await?;
let mut cache = crate::llm_util::EmbedCache::default();
// 这个库一条确认口径都没有:挑口径两路都空,但问题已经嵌了一次
let mappings =
crate::mapping_index::relevant(&f.state, f.kb, ws, QUESTION, 8, Some(&mut cache))
.await?;
assert!(mappings.is_empty());
assert_eq!(embedder.requests(), vec![vec![QUESTION.to_string()]]);
assert!(cache.contains_key(QUESTION));
// 检索分块拿同一个向量:索引里没有块,向量那一路照样跑,只是不再嵌
let chunks =
crate::retrieval::hybrid(&f.state, f.kb, ws, QUESTION, 8, None, Some(&mut cache))
.await?;
assert!(chunks.is_empty());
assert_eq!(embedder.requests().len(), 1, "search reuses the vector");
// 按名字查实体:还是它,挑中画像近的那个
let ctx = ctx(&f, Some(QUESTION)).await?;
let mut turn = ToolSink {
embeddings: cache,
..ToolSink::default()
};
let found = dispatch(&ctx, &mut turn, "find_entities", &json!({"name": "Acme"})).await;
assert!(
found
.text
.starts_with(&format!("Best match: {} |", acme.near)),
"{}",
found.text
);
assert_eq!(
embedder.requests().len(),
1,
"the graph lookup reuses it too"
);
// 模型把检索词改了:另一句话,嵌一次,记进同一个缓存
let _ = crate::retrieval::hybrid(
&f.state,
f.kb,
ws,
"Acme lab address",
8,
None,
Some(&mut turn.embeddings),
)
.await?;
assert_eq!(
embedder.requests().last(),
Some(&vec!["Acme lab address".to_string()])
);
assert!(turn.embeddings.contains_key("Acme lab address"));
// 没有这一轮的调用方各嵌各的
let _ = crate::retrieval::hybrid(&f.state, f.kb, ws, QUESTION, 8, None, None).await?;
let _ = crate::mapping_index::relevant(&f.state, f.kb, ws, QUESTION, 8, None).await?;
assert_eq!(embedder.requests().len(), 4);
anyhow::Ok(())
}
.await;
server.abort();
f.cleanup().await?;
run
}