Skip to content

World's first open-source enterprise world 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.rs
index 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.rs
index 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 f
WHERE (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.rs
new file mode 100644
index 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.ts
index 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.ts
index 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: "同名,但类型不同",