World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A namesake tie goes to review, not to candidate order (#329)
Ben Younesc22b4e5df747
diff --git a/crates/utopia-server/src/extraction.rs b/crates/utopia-server/src/extraction.rsindex d921ca45..63697f6d 100644--- a/crates/utopia-server/src/extraction.rs+++ b/crates/utopia-server/src/extraction.rs@@ -348,7 +348,8 @@ async fn resolve_uncached() -> anyhow::Result<Uuid> {let r =utopia_store::resolution::resolve_mention(pool, kb_id, type_id, name, ctx, exclude).await?;- // 疑似重复对(同名灰区 / 类型漂移)入审核队列,攒批裁决任务收尾统一触发+ // 疑似重复对(画像灰区 / 类型漂移 / 同名并列)入审核队列。多数走批量裁决器,+ // 同名并列(`ReviewStage::Human`)分不出谁是谁,只能等人裁——它自己带着 stage。for review in &r.reviews {utopia_store::resolution::create_review(pool,@@ -357,10 +358,13 @@ async fn resolve_uncached(review.other_id,review.score,&review.reason,- utopia_store::resolution::ReviewStage::Adjudicating,+ review.stage,).await?;- *needs_adjudication = true;+ // 只有批量可裁的才触发裁决任务;纯人工审核对不该唤醒裁决器+ if review.stage == utopia_store::resolution::ReviewStage::Adjudicating {+ *needs_adjudication = true;+ }}Ok(r.entity_id)}@@ -2445,4 +2449,105 @@ mod tests {.await;run}++ /// #270:跨文档的裸 mention 同名并列——不靠 handle,靠画像相似度。库里已有两个+ /// 「张伟」,画像质心一模一样(同一 chunk 播的种)。新 mention 对两人打出同一个分。+ /// 旧路径在最高分 ≥ SIM_ATTACH 时静默 attach 到先遇到的那个;修好之后 `resolve`+ /// 走的这条路要:新建第三个实体、两条**人工**审核对、且绝不唤醒 LLM 裁决器+ /// (否则两条几乎相同的画像会被自动并掉,正是要防的)。+ #[tokio::test]+ async fn a_profile_tie_across_documents_files_human_reviews_not_an_attach() -> anyhow::Result<()>+ {+ let Some(url) = utopia_store::test_db::url() else {+ return Ok(());+ };+ let pool = sqlx::PgPool::connect(&url).await?;+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'profile-tie-test')")+ .bind(org)+ .execute(&pool)+ .await?;+ sqlx::query(+ "INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'profile-tie-test')",+ )+ .bind(ws)+ .bind(org)+ .execute(&pool)+ .await?;+ sqlx::query(+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'profile-tie-test')",+ )+ .bind(kb)+ .bind(ws)+ .execute(&pool)+ .await?;+ let person = Uuid::now_v7();+ sqlx::query(+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'person', 'Person')",+ )+ .bind(person)+ .bind(kb)+ .execute(&pool)+ .await?;++ let run = async {+ // 两个同名的人,画像向量完全相同+ let (a, b) = (Uuid::now_v7(), Uuid::now_v7());+ for id in [a, b] {+ sqlx::query(+ "INSERT INTO entities+ (id, kb_id, type_id, canonical_name, profile_embedding, profile_n)+ VALUES ($1, $2, $3, 'Zhang Wei', '[1,0,0]'::vector, 1)",+ )+ .bind(id)+ .bind(kb)+ .bind(person)+ .execute(&pool)+ .await?;+ }++ // 与两人画像都一致的上下文:打出的余弦相同 → 分不开+ let ctx: Vec<f32> = vec![1.0, 0.0, 0.0];+ let mut doc_cache = HashMap::new();+ let mut needs_adjudication = false;+ let c = super::resolve(+ &pool,+ kb,+ Some(person),+ "Zhang Wei",+ Some(&ctx),+ &mut doc_cache,+ &mut needs_adjudication,+ )+ .await?;++ assert_ne!(c, a, "画像并列不该 attach 到 A——那是候选顺序掷出的硬币");+ assert_ne!(c, b, "画像并列不该 attach 到 B——那是候选顺序掷出的硬币");+ assert!(+ !needs_adjudication,+ "同名并列只能等人裁,绝不该唤醒 LLM 裁决器"+ );++ let reviews = utopia_store::resolution::list_reviews(&pool, kb, 10, 0).await?;+ assert_eq!(reviews.len(), 2, "对 A、对 B 各一条审核对");+ assert!(+ reviews.iter().all(|review| review.stage == "human"),+ "同名并列的审核对必须是人工阶段"+ );+ assert!(+ utopia_store::resolution::pending_adjudications(&pool, kb, 10)+ .await?+ .is_empty(),+ "人工审核对绝不能落进批量裁决队列,否则又会被自动并掉"+ );+ Ok::<_, anyhow::Error>(())+ }+ .await;++ let _ = sqlx::query("DELETE FROM organizations WHERE id = $1")+ .bind(org)+ .execute(&pool)+ .await;+ run+ }}diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rsindex 2149b06f..2ae4972c 100644--- a/crates/utopia-store/src/resolution.rs+++ b/crates/utopia-store/src/resolution.rs@@ -21,6 +21,12 @@ use uuid::Uuid;pub const SIM_ATTACH: f32 = 0.55;pub const SIM_NEW: f32 = 0.35;+/// 同名并列的判定边界:两个**同名**候选的画像分数相差不超过这个值,就算「分不开」。+/// 画像分不出谁是谁时,attach 到分高的那个只是候选顺序掷出的硬币(#270)——+/// 与其掷硬币,不如两个都不并、都入人工审核。取值偏紧:真正拉得开的同名人(不同+/// chunk、不同事实积累)分差远大于此,只有质心几乎重合(如同一 chunk 播种)才触发。+pub const SIM_TIE_MARGIN: f32 = 0.02;+/// 名称规范化:全角 ASCII → 半角、全角空格 → 半角、空白折叠。/// 返回展示形态(保留大小写);匹配一律再套 SQL lower()。pub fn normalize_name(raw: &str) -> String {@@ -175,6 +181,7 @@ fn cosine(a: &[f32], b: &[f32]) -> Option<f32> {#[derive(Debug, sqlx::FromRow)]struct Candidate {id: Uuid,+ canonical_name: String,profile_embedding: Option<Vector>,profile_n: i32,degree: i64,@@ -195,6 +202,9 @@ pub struct ReviewRequest {pub other_id: Uuid,pub score: f32,pub reason: String,+ /// 交给谁裁:画像灰区走 [`ReviewStage::Adjudicating`](批量裁决器),+ /// 同名并列只有人分得开,走 [`ReviewStage::Human`]。+ pub stage: ReviewStage,}/// 审核项由谁消费。普通画像灰区先交给批量裁决器;抽取器在同一回复里明确拆出的@@ -232,7 +242,7 @@ pub async fn resolve_mention(// 只扩召回,归并与否仍由下方画像相似度分层定夺。let keys = recall_keys(&name);let candidates: Vec<Candidate> = sqlx::query_as(- "SELECT e.id, e.profile_embedding, e.profile_n,+ "SELECT e.id, e.canonical_name, e.profile_embedding, e.profile_n,(SELECT count(*) FROM facts fWHERE (f.subject_id = e.id OR f.object_id = e.id)AND f.invalidated_at IS NULL) AS degree@@ -271,7 +281,7 @@ pub async fn resolve_mention(};// 有画像的候选算相似度;无画像(历史数据/无 embedding 期创建)单独归类- let mut best_scored: Option<(&Candidate, f32)> = None;+ let mut scored: Vec<(&Candidate, f32)> = Vec::new();let mut unprofiled: Option<&Candidate> = None;for c in &candidates {match c@@ -279,11 +289,7 @@ pub async fn resolve_mention(.as_ref().and_then(|p| cosine(p.as_slice(), ctx)){- Some(sim) => {- if best_scored.map(|(_, s)| sim > s).unwrap_or(true) {- best_scored = Some((c, sim));- }- }+ Some(sim) => scored.push((c, sim)),None => {if unprofiled.map(|u| c.degree > u.degree).unwrap_or(true) {unprofiled = Some(c);@@ -291,9 +297,47 @@ pub async fn resolve_mention(}}}+ // 最高分候选:并列时保留先遇到的那个(与旧的 `sim > s` 严格大于一致)+ let best_scored = scored+ .iter()+ .copied()+ .reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc });if let Some((best, sim)) = best_scored {if sim >= SIM_ATTACH {+ // 同名并列的灰区:另有一个**同名**候选的分数贴着最高分(差 ≤ SIM_TIE_MARGIN),+ // 画像分不出谁是谁——attach 到分高的那个只是候选顺序掷出的硬币(#270)。+ // 宁分勿合:不 attach,新建实体,对并列的两个候选各入一条**人工**审核对。+ // 分数无论多高都拦:高分并列正是静默错并的危险区,不能因为「够像」就放行。+ if let Some((runner, r_sim)) = scored+ .iter()+ .copied()+ .filter(|(c, s)| {+ // 同名比较要与召回一致地忽略大小写:召回用 SQL `lower()`,+ // 「Zhang Wei」与「zhang wei」本就是一对同名候选,不能漏。+ c.id != best.id+ && c.canonical_name.to_lowercase() == best.canonical_name.to_lowercase()+ && sim - *s <= SIM_TIE_MARGIN+ })+ .reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc })+ {+ let id = create_entity(pool, kb_id, type_id, &name, context).await?;+ refresh_disambiguators(pool, kb_id, &name).await?;+ let reviews = [(best, sim), (runner, r_sim)]+ .into_iter()+ .map(|(c, s)| ReviewRequest {+ other_id: c.id,+ score: s,+ reason: format!("namesake_tie|{s:.2}"),+ stage: ReviewStage::Human,+ })+ .collect();+ return Ok(Resolution {+ entity_id: id,+ created: true,+ reviews,+ });+ }update_profile(pool, best.id, best.profile_n, ctx).await?;return Ok(Resolution {entity_id: best.id,@@ -322,6 +366,7 @@ pub async fn resolve_mention(other_id: c.id,score: sim,reason: format!("ambiguous_name|{sim:.2}"),+ stage: ReviewStage::Adjudicating,}]}).unwrap_or_default();@@ -467,6 +512,7 @@ async fn containment_reviews(other_id: id,score,reason: format!("contains|{other_name}"),+ stage: ReviewStage::Adjudicating,}}).collect())@@ -588,6 +634,7 @@ fn confusable_reviews(other_id: c.id,score: sim.unwrap_or(0.0),reason: drift_reason(mention_key, c.type_key.as_deref(), sim),+ stage: ReviewStage::Adjudicating,}}).collect()@@ -725,6 +772,7 @@ async fn resolve_type_drift(other_id: c.id,score: sim.unwrap_or(0.0),reason: drift_reason(mention_key.as_deref(), c.type_key.as_deref(), sim),+ stage: ReviewStage::Adjudicating,}),}}diff --git a/crates/utopia-store/tests/a_namesake_tie_goes_to_review_not_a_coin_flip.rs b/crates/utopia-store/tests/a_namesake_tie_goes_to_review_not_a_coin_flip.rsnew file mode 100644index 00000000..e39d3771--- /dev/null+++ b/crates/utopia-store/tests/a_namesake_tie_goes_to_review_not_a_coin_flip.rs@@ -0,0 +1,204 @@+//! 同名并列的灰区不该靠候选顺序掷硬币(#270,续 #221/#296)。+//!+//! 一个库里已有两个「张伟」,画像向量一模一样(都从同一个 chunk 里长出来,+//! #221 之后这是常态)。后来一条没有任何 handle 的「张伟」mention 进来,对两个+//! 候选打出同一个分数。旧的 `resolve_mention` 在最高分 ≥ `SIM_ATTACH` 时直接归并到+//! **先遇到的那个**,且不入任何审核对——落到谁头上全看候选从库里回来的顺序。+//!+//! 分不开就别硬分:新建实体,对并列的两个候选各入一条**人工**审核对,绝不静默归并。+//! 连库才测得到——「先遇到的那个」是一条 `ORDER BY` 缺省下的物理顺序,`cargo check`+//! 一个字看不见。没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败,自建自拆,绝不碰已有的库。++use sqlx::PgPool;+use utopia_store::resolution::ReviewStage;+use uuid::Uuid;++struct Fx {+ org: Uuid,+ kb: Uuid,+ person: Uuid,+ zhang_a: Uuid,+ zhang_b: Uuid,+}++/// 两个同名的「张伟」,画像向量完全相同;雇主不同,但那条线索此刻没人用得上。+async fn seed(pool: &PgPool) -> anyhow::Result<Fx> {+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());+ let (person, organization) = (Uuid::now_v7(), Uuid::now_v7());+ let works_for = Uuid::now_v7();+ let (platform, finance) = (Uuid::now_v7(), Uuid::now_v7());+ let (zhang_a, zhang_b) = (Uuid::now_v7(), Uuid::now_v7());++ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'namesake-tie-test')")+ .bind(org)+ .execute(pool)+ .await?;+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'namesake-tie-test')")+ .bind(ws)+ .bind(org)+ .execute(pool)+ .await?;+ sqlx::query(+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'namesake-tie-test')",+ )+ .bind(kb)+ .bind(ws)+ .execute(pool)+ .await?;+ for (id, key, label) in [+ (person, "person", "Person"),+ (organization, "organization", "Organization"),+ ] {+ sqlx::query("INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, $3, $4)")+ .bind(id)+ .bind(kb)+ .bind(key)+ .bind(label)+ .execute(pool)+ .await?;+ }+ sqlx::query(+ "INSERT INTO relation_types (id, kb_id, key, label, temporal)+ VALUES ($1, $2, 'works_for', 'works for', 'state')",+ )+ .bind(works_for)+ .bind(kb)+ .execute(pool)+ .await?;++ // 两个雇主,两个同名的人。故意一个大写一个小写:召回用 SQL `lower()`,+ // 「Zhang Wei」和「zhang wei」本就是一对同名候选,并列判定也必须忽略大小写。+ for (id, type_id, name) in [+ (platform, organization, "Platform Engineering"),+ (finance, organization, "Finance"),+ (zhang_a, person, "Zhang Wei"),+ (zhang_b, person, "zhang wei"),+ ] {+ sqlx::query(+ "INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES ($1, $2, $3, $4)",+ )+ .bind(id)+ .bind(kb)+ .bind(type_id)+ .bind(name)+ .execute(pool)+ .await?;+ }+ // 画像向量一模一样:两人都是同一个 chunk 里播下的种子,质心相同+ for id in [zhang_a, zhang_b] {+ sqlx::query("UPDATE entities SET profile_embedding = '[1,0,0]'::vector, profile_n = 1 WHERE id = $1")+ .bind(id)+ .execute(pool)+ .await?;+ }+ // 区分他们的事实就摆在这里——department/雇主——只是画像比对看不见它+ for (subject, object) in [(zhang_a, platform), (zhang_b, finance)] {+ sqlx::query(+ "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id, confidence)+ VALUES ($1, $2, $3, $4, $5, 0.9)",+ )+ .bind(Uuid::now_v7())+ .bind(kb)+ .bind(subject)+ .bind(works_for)+ .bind(object)+ .execute(pool)+ .await?;+ }++ Ok(Fx {+ org,+ kb,+ person,+ zhang_a,+ zhang_b,+ })+}++#[tokio::test]+async fn a_namesake_tie_creates_an_entity_and_two_reviews() -> anyhow::Result<()> {+ let Some(url) = utopia_store::test_db::url() else {+ return Ok(());+ };+ let pool = PgPool::connect(&url).await?;+ let f = seed(&pool).await?;++ let run = async {+ // 与两个候选画像都一致的上下文:对 A、对 B 打出的余弦相同+ let ctx: Vec<f32> = vec![1.0, 0.0, 0.0];+ let r = utopia_store::resolution::resolve_mention(+ &pool,+ f.kb,+ Some(f.person),+ "Zhang Wei",+ Some(&ctx),+ &[],+ )+ .await?;++ // 分不开就不归并:新建了第三个实体,没有 attach 到 A 或 B+ assert!(+ r.created,+ "同名并列不该静默归并到先遇到的那个——该新建实体(#270)"+ );+ assert_ne!(r.entity_id, f.zhang_a, "attach 到了 A:候选顺序掷出的硬币");+ assert_ne!(r.entity_id, f.zhang_b, "attach 到了 B:候选顺序掷出的硬币");++ // 对并列的两个候选各入一条审核对+ let mut reviewed: Vec<Uuid> = r.reviews.iter().map(|rv| rv.other_id).collect();+ reviewed.sort();+ let mut want = vec![f.zhang_a, f.zhang_b];+ want.sort();+ assert_eq!(reviewed, want, "两个同名候选都该进审核,一个都不能少");++ // 同名并列只有人分得开,绝不能让批量裁决器把两条几乎相同的画像自动并掉+ assert!(+ r.reviews.iter().all(|rv| rv.stage == ReviewStage::Human),+ "同名并列的审核对必须是人工阶段(Human)"+ );++ // 落库后确实是两条待裁的人工审核对,都挂在新建的实体上+ for rv in &r.reviews {+ utopia_store::resolution::create_review(+ &pool,+ f.kb,+ r.entity_id,+ rv.other_id,+ rv.score,+ &rv.reason,+ rv.stage,+ )+ .await?;+ }+ let pending: Vec<(Uuid, String)> = sqlx::query_as(+ "SELECT CASE WHEN left_id = $2 THEN right_id ELSE left_id END, stage+ FROM resolution_reviews+ WHERE kb_id = $1 AND status = 'pending' AND (left_id = $2 OR right_id = $2)",+ )+ .bind(f.kb)+ .bind(r.entity_id)+ .fetch_all(&pool)+ .await?;+ assert_eq!(pending.len(), 2, "库里该有两条待裁的审核对");+ assert!(+ pending.iter().all(|(_, stage)| stage == "human"),+ "落库的审核对都该是 human 阶段"+ );+ let mut others: Vec<Uuid> = pending.iter().map(|(id, _)| *id).collect();+ others.sort();+ assert_eq!(others, want, "两条审核对分别指向 A 和 B");++ Ok::<_, anyhow::Error>(())+ }+ .await;++ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")+ .bind(f.kb)+ .execute(&pool)+ .await?;+ sqlx::query("DELETE FROM organizations WHERE id = $1")+ .bind(f.org)+ .execute(&pool)+ .await?;+ run+}diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.tsindex b2c37820..ff0d8723 100644--- a/web/src/i18n/en.ts+++ b/web/src/i18n/en.ts@@ -1406,6 +1406,8 @@ export const en = {escalate_entity_changed: "The entity changed while being adjudicated",escalate_unsure: "The adjudicator was not confident enough",namesake: "Two entities with this name in one document",+ /* 画像分不开时的并列:分数是真的,所以百分比照常显示(与 namesake 的哨兵值不同) */+ namesake_tie: "Same name, and the profiles cannot tell them apart",/* 名字互相包含:等值召回看不见,简称会静默变成第二个实体 */contains: "One name contains the other",ambiguous_name: "Same name, context did not settle it",diff --git a/web/src/i18n/zh.ts b/web/src/i18n/zh.tsindex 6c8f211b..190b0988 100644--- a/web/src/i18n/zh.ts+++ b/web/src/i18n/zh.ts@@ -1244,6 +1244,7 @@ export const zh: Strings = {escalate_entity_changed: "裁决过程中实体发生了变化",escalate_unsure: "裁决的把握不够",namesake: "同一篇文档里有两个同名实体",+ namesake_tie: "同名,画像分不出谁是谁",contains: "一个名字包含另一个",ambiguous_name: "同名,但上下文没能定夺",type_drift: "同名,但类型不同",