World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 实体消解 v2:同名≠同人(流程图与三次实测修洞见 `docs/pipeline.md` 第二节)。
//!
//! 漏斗:名字候选召回(免费,含泛用后缀词干互推)→ 画像向量相似度分层(毫秒,复用摄入阶段的 chunk embedding)
//! → 灰区新建实体 + 疑似重复审核项(宁分勿合),LLM 攒批裁决在独立后台任务里跑,
//! 人工终审兜底。LLM 永远不在抽取写入的关键路径上。
//!
//! 类型漂移:同名在同类型下无候选时再查其它类型(同一团队被抽成 organization/
//! project/concept 是常态),按类型对的互斥强度分流——concept 兜底型当召回候选走
//! 画像分层,易混具体类型照建实体但入队审核对,硬互斥(person vs organization)完全分开。
use chrono::{DateTime, Utc};
use pgvector::Vector;
use sqlx::PgPool;
use std::collections::{HashMap, HashSet};
use utopia_core::models::{MergeLogView, ReviewBatchOutcome, ReviewItem, ReviewSide};
use utopia_core::{AppError, AppResult};
use uuid::Uuid;
/// 上下文相似度阈值(bge-m3 类模型余弦相似度经验值,后续可调)。
/// ≥ ATTACH 归并到既有实体;< NEW 判为不同实体;中间灰区宁分勿合 + 审核项。
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;
/// 旁证宾语的最短长度。低于它的("IT"、"A 组")在任何一篇文档里都可能出现,
/// 命中不含信息量。**宁可漏掉一条旁证**:漏了就是今天的行为,错了会并错人。
const MIN_CORROBORATION_CHARS: usize = 2;
/// 每个候选取几个消歧宾语参与旁证。取多个是因为文档提到的未必是排序最靠前的
/// 那一个(他的部门写在这句、职位写在下一句),但也不能全取——候选的事实越多,
/// 撞上一个泛泛的宾语的机会越大。
const CORROBORATION_OBJECTS: i64 = 3;
/// 名称规范化:全角 ASCII → 半角、全角空格 → 半角、空白折叠。
/// 返回展示形态(保留大小写);匹配一律再套 SQL lower()。
pub fn normalize_name(raw: &str) -> String {
let mapped: String = raw
.chars()
.map(|c| match c {
'\u{3000}' => ' ',
'\u{FF01}'..='\u{FF5E}' => char::from_u32(c as u32 - 0xFEE0).unwrap_or(c),
_ => c,
})
.collect();
mapped.split_whitespace().collect::<Vec<_>>().join(" ")
}
/// Fold unambiguous Markdown formatting in names; evidence keeps the original text.
/// Input should already have passed through [`normalize_name`]. Only whole-name
/// `**...**` / `__...__` emphasis is removed; empty, nested, mismatched or
/// whitespace-padded markup is kept.
/// `__identifier__` stays literal (Unicode letters/digits and underscores count).
/// Single backticks are removed only around a slash path or a dotted filename
/// containing a letter: only letters, digits, `/`, `.`, `_` and `-` are allowed,
/// with at least one alphanumeric character and no trailing dot. This deliberately
/// leaves code, bare identifiers, numeric versions and paths with spaces alone.
pub fn fold_markdown_markers(name: &str) -> &str {
for marker in ["**", "__", "`"] {
let Some(inner) = name
.strip_prefix(marker)
.and_then(|s| s.strip_suffix(marker))
else {
continue;
};
if inner.is_empty()
|| inner.trim() != inner
|| inner.contains(['*', '`'])
|| (marker != "`"
&& (inner.starts_with('_') || inner.ends_with('_') || inner.contains("__")))
{
return name;
}
let fold = match marker {
"__" => !inner.chars().all(|c| c.is_alphanumeric() || c == '_'),
"`" => {
(inner.contains('/')
|| (inner.contains('.') && inner.chars().any(char::is_alphabetic)))
&& inner.chars().any(char::is_alphanumeric)
&& !inner.ends_with('.')
&& inner
.chars()
.all(|c| c.is_alphanumeric() || matches!(c, '/' | '.' | '_' | '-'))
}
_ => true,
};
return if fold { inner } else { name };
}
name
}
/// Shared identity key for recall and document-level name claims.
pub fn name_key(raw: &str) -> String {
fold_markdown_markers(&normalize_name(raw)).to_lowercase()
}
/// 泛用后缀词表:中文直接拼在词干后;英文按独立词算、首尾两种语序都认
/// ("Phoenix Project" / "Project Phoenix")。只影响召回,判定仍走画像相似度。
const GENERIC_SUFFIXES_CJK: &[&str] = &["项目", "公司", "集团", "部门", "团队"];
const GENERIC_WORDS_EN: &[&str] = &["project", "corp", "inc", "team"];
/// 词干:剥去一个泛用后缀后的 lower 形态。未命中、剥空、或词干本身就是
/// 泛用词("项目团队")时返回 None。输入应已过 normalize_name。
pub fn name_stem(name: &str) -> Option<String> {
let lower = name.to_lowercase();
let strip_punct = |w: &str| w.trim_end_matches(['.', ',']).to_string();
let generic = |s: &str| {
GENERIC_SUFFIXES_CJK.contains(&s) || GENERIC_WORDS_EN.contains(&strip_punct(s).as_str())
};
for suf in GENERIC_SUFFIXES_CJK {
if let Some(stem) = lower.strip_suffix(suf) {
let stem = stem.trim_end();
if !stem.is_empty() && !generic(stem) {
return Some(stem.to_string());
}
}
}
let words: Vec<&str> = lower.split(' ').collect();
if words.len() >= 2 {
if generic(words[words.len() - 1]) {
let stem = words[..words.len() - 1].join(" ");
if !generic(&stem) {
return Some(stem);
}
}
if generic(words[0]) {
let stem = words[1..].join(" ");
if !generic(&stem) {
return Some(stem);
}
}
}
None
}
/// 输入应已过 [`normalize_name`]。
/// mention 的召回键集合(全 lower):本名 + 词干 + 词干的泛用后缀增广。
/// 增广覆盖反方向(库内是"星尘项目"、mention 只说"星尘");词干含 CJK 拼中文
/// 尾缀,否则拼英文词(两种语序)。键数 ≤11,走 (kb,type,lower(name)) 索引多点查。
pub fn recall_keys(normalized: &str) -> Vec<String> {
let name = fold_markdown_markers(normalized);
let lower = name.to_lowercase();
let base = name_stem(name).unwrap_or_else(|| lower.clone());
let mut keys = vec![lower];
fn add(keys: &mut Vec<String>, k: String) {
if !keys.contains(&k) {
keys.push(k);
}
}
// Keep exact recall of names already stored with formatting as well.
add(&mut keys, normalized.to_lowercase());
add(&mut keys, base.clone());
if base.chars().any(|c| ('\u{4E00}'..='\u{9FFF}').contains(&c)) {
for suf in GENERIC_SUFFIXES_CJK {
add(&mut keys, format!("{base}{suf}"));
}
} else {
for w in GENERIC_WORDS_EN {
add(&mut keys, format!("{base} {w}"));
add(&mut keys, format!("{w} {base}"));
}
}
keys
}
// ---------------------------------------------------------------------------
// 类型漂移:同名实体被抽成了不同类型("Orion platform team" ↔ organization/project)
// ---------------------------------------------------------------------------
/// 易混具体类型:抽取常在这几类间摇摆(一个团队算组织还是项目?平台算项目还是产品?)。
/// 同名跨这组类型 → 照建实体(宁分勿合),但入队审核对交 LLM/人工裁决。
///
/// **本体说了算,这张表只是没声明时的退路。** 判两个类能不能指同一个东西,先看
/// `owl:disjointWith`(`entity_type_disjoint`,含继承:Person ⟂ Organization 就让
/// Corporation ⟂ Person)——声明了互斥的一律分开,哪怕它们在类层级上是一家;
/// 没声明的再看类层级(同一支系当易混,#226),最后才是这三个硬 key。
/// 没装包也没声明的库里这三个 key 不存在,于是所有跨类型同名判 `Disjoint`——
/// 变严不变松,不会错合(0016 B3)
pub const CONFUSABLE_TYPE_KEYS: &[&str] = &["organization", "project", "product"];
/// 单次消解最多入队的漂移审核对(防同名大组刷爆审核队列)。
const MAX_DRIFT_REVIEWS: usize = 4;
/// 跨类型同名的处置分类。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TypeDrift {
/// 一侧是兜底类型:当召回候选,走画像相似度分层(可 ATTACH)
Recall,
/// 两个易混具体类型:新建 + 审核对
Review,
/// 硬互斥(person vs organization 等,含未知自定义类型):完全分开
Disjoint,
}
fn classify_type_drift(a: Option<&str>, b: Option<&str>) -> TypeDrift {
// **同一个类型当然可能是同一个东西。**
//
// 这一档原本不存在,因为这个函数生来只服务"类型漂移"——同名被抽成两种
// 类型——那里两边相同根本不会发生。后来 containment_reviews 借它当相容性
// 判据,而那里**两边相同才是最常见的情形**,于是 person 对 person 落进了
// 最后那行 Disjoint,被读成"永不可能是同一个东西"。
//
// 代价是全文最明显的同指关系一对都进不了队列:福尔摩斯前六篇里
// Sherlock Holmes 与 Holmes 是两个实体,488 个实体只合并掉 14 个。
// 原有的 12 个单元测试全在测跨类型,一个都没测相同类型。
if a == b {
return TypeDrift::Recall;
}
// **一侧还没判出来** → 当召回候选,走画像相似度分层。
// 从前比的是 `== FALLBACK_TYPE_KEY`,那个 key 已经没有了:
// 「还没判出来」现在由 `None` 表达(0009)。两边都是 None
// 已经被上面 `a == b` 那行接住
let (Some(a), Some(b)) = (a, b) else {
return TypeDrift::Recall;
};
if CONFUSABLE_TYPE_KEYS.contains(&a) && CONFUSABLE_TYPE_KEYS.contains(&b) {
return TypeDrift::Review;
}
TypeDrift::Disjoint
}
fn cosine(a: &[f32], b: &[f32]) -> Option<f32> {
if a.len() != b.len() || a.is_empty() {
return None;
}
let (mut dot, mut na, mut nb) = (0f32, 0f32, 0f32);
for (x, y) in a.iter().zip(b) {
dot += x * y;
na += x * x;
nb += y * y;
}
if na == 0.0 || nb == 0.0 {
return None;
}
Some(dot / (na.sqrt() * nb.sqrt()))
}
#[derive(Debug, sqlx::FromRow)]
struct Candidate {
id: Uuid,
canonical_name: String,
profile_embedding: Option<Vector>,
profile_n: i32,
}
/// 这些实体各自的度数(不数名字事实),与 `ids` 同序;没有事实的是 0。
async fn degrees(pool: &PgPool, kb_id: Uuid, ids: &[Uuid]) -> AppResult<Vec<i64>> {
let rows: HashMap<Uuid, i64> = sqlx::query_as(&format!(
"SELECT n.id, count(*)
FROM unnest($2::uuid[]) AS n(id)
JOIN facts f ON f.kb_id = $1 AND (f.subject_id = n.id OR f.object_id = n.id)
AND f.invalidated_at IS NULL AND {not_name}
GROUP BY n.id",
not_name = crate::names::not_a_name("f"),
))
.bind(kb_id)
.bind(ids)
.fetch_all(pool)
.await?
.into_iter()
.collect();
Ok(ids
.iter()
.map(|id| rows.get(id).copied().unwrap_or(0))
.collect())
}
/// 消解结果:mention 落到了哪个实体;附带需要入队的疑似重复审核对
/// (同名灰区 / 类型漂移),由调用方写入审核队列并触发裁决任务。
#[derive(Debug)]
pub struct Resolution {
pub entity_id: Uuid,
pub created: bool,
pub reviews: Vec<ReviewRequest>,
}
/// 待入队的审核对:`Resolution::entity_id` vs `other_id`。
#[derive(Debug)]
pub struct ReviewRequest {
pub other_id: Uuid,
pub score: f32,
pub reason: String,
/// 交给谁裁:画像灰区走 [`ReviewStage::Adjudicating`](批量裁决器),
/// 同名并列只有人分得开,走 [`ReviewStage::Human`]。
pub stage: ReviewStage,
}
/// 审核项由谁消费。普通画像灰区先交给批量裁决器;抽取器在同一回复里明确拆出的
/// 同名实体只有人能判断,不能让几乎相同的画像触发自动合并。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReviewStage {
Adjudicating,
Human,
}
impl ReviewStage {
fn as_str(self) -> &'static str {
match self {
Self::Adjudicating => "adjudicating",
Self::Human => "human",
}
}
}
/// 消解一个 mention。召回走两条通道(0041 决定 3):名字字面相等(通道 1,
/// `resolve_by_name` 里的那条 SQL)和名字向量最近邻(通道 2,给了 `name_vector` 才走)。
///
/// **通道 2 只提议,不决定。** 它召回到的实体这一刀不参与归并——决定该由证据来做,
/// 那是 0041 的第 3 刀,还没建——只给裁决器排一对(`name_vector|<余弦>`),让它拿两份
/// 画像和先例去判是不是一个。于是这一刀加的是「多问一句」,不是「多合一次」:错合
/// 是静默的、要人回头拆,多问只是贵一点。
///
/// 同一个字面名字不走通道 2:那是通道 1 的地盘,它已经按画像判过了,再排一对等于
/// 让裁决器复议一个刚做过的决定。大类对不上的也不提议(海探1 是设备,不会是一个人)。
#[allow(clippy::too_many_arguments)]
pub async fn resolve_mention(
pool: &PgPool,
kb_id: Uuid,
type_id: Option<Uuid>,
raw_name: &str,
context: Option<&[f32]>,
// mention 名字本身的向量(不是块的)。None = 没配嵌入模型,或这次没算
name_vector: Option<&[f32]>,
text: Option<&str>,
exclude: &[Uuid],
) -> AppResult<Resolution> {
let mut r = resolve_by_name(pool, kb_id, type_id, raw_name, context, text, exclude).await?;
if let Some(query) = name_vector {
propose_by_name_vector(pool, kb_id, type_id, raw_name, query, exclude, &mut r).await?;
}
// 判过「不是一个」的对不再排。新建的实体没有过去,没东西要排的也不用问
if !r.created && !r.reviews.is_empty() {
let kept = kept_apart_from(pool, kb_id, r.entity_id).await?;
r.reviews.retain(|v| !kept.contains(&v.other_id));
}
Ok(r)
}
/// 跟这个实体判过「不是一个」的那些实体。
///
/// **每次提到都会走到召回**:名字向量通道不分新建还是归并,同名易混类型那条路也是
/// 归并之后照常入队。而审核表的唯一索引只管 pending 的行——判完的一对下次被提到,
/// 就又是一条新的 pending。一个有六万实体的库上,`migration 395` 每出现在一篇新文档里,
/// 它跟 `migration 394` 等八个近邻就重新排一遍队,裁决器(或人)分开过多少次都一样
/// (#1104)。分开这个决定要记得住,[`crate::names::pair_shared_name`] 早就是这么做的。
///
/// 人仍然可以在审核页把分开过的一对合并:这里拦的是自动重提,不是合并本身。
async fn kept_apart_from(pool: &PgPool, kb_id: Uuid, entity_id: Uuid) -> AppResult<HashSet<Uuid>> {
let rows: Vec<(Uuid,)> = sqlx::query_as(
"SELECT CASE WHEN left_id = $2 THEN right_id ELSE left_id END
FROM resolution_reviews
WHERE kb_id = $1 AND status = 'kept' AND (left_id = $2 OR right_id = $2)",
)
.bind(kb_id)
.bind(entity_id)
.fetch_all(pool)
.await?;
Ok(rows.into_iter().map(|(id,)| id).collect())
}
/// 通道 2:mention 名字向量的近邻,各排一对(规矩见 [`resolve_mention`])
async fn propose_by_name_vector(
pool: &PgPool,
kb_id: Uuid,
type_id: Option<Uuid>,
raw_name: &str,
query: &[f32],
exclude: &[Uuid],
r: &mut Resolution,
) -> AppResult<()> {
let mention_name = name_key(raw_name);
let mention_family = match type_id {
Some(t) => type_label(pool, t)
.await?
.as_deref()
.and_then(crate::governance::type_family),
None => None,
};
let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
let mut seen: HashSet<Uuid> = r.reviews.iter().map(|v| v.other_id).collect();
seen.insert(r.entity_id);
seen.extend(exclude.iter().copied());
for near in crate::name_vectors::nearest(pool, kb_id, query, crate::name_vectors::TOP_K).await?
{
if near.similarity < crate::name_vectors::SIM_FLOOR {
break; // 降序:后面的更远
}
if near.name.to_lowercase() == mention_name || !seen.insert(near.entity_id) {
continue;
}
// 只差一个数的名字向量上几乎重合,却几乎从不是同一个(见 `numbers_differ`)
if crate::names::numbers_differ(raw_name, &near.name) {
continue;
}
let near_family = near
.type_label
.as_deref()
.and_then(crate::governance::type_family);
if let (Some(a), Some(b)) = (mention_family, near_family) {
if a != b {
continue;
}
}
// 大类认不出的类(Spec、Test……)靠本体声明分开,与 containment、类型漂移同一张表
if near.type_id.is_some_and(|t| disjoint.contains(&t)) {
continue;
}
r.reviews.push(ReviewRequest {
other_id: near.entity_id,
score: near.similarity,
reason: format!(
"{}{:.2}",
utopia_core::review_reasons::NAME_VECTOR,
near.similarity
),
stage: ReviewStage::Adjudicating,
});
}
Ok(())
}
async fn type_label(pool: &PgPool, type_id: Uuid) -> AppResult<Option<String>> {
Ok(
sqlx::query_scalar("SELECT label FROM entity_types WHERE id = $1")
.bind(type_id)
.fetch_optional(pool)
.await?,
)
}
/// 通道 1:名字字面相等的候选,按画像分层归并或新建(原 `resolve_mention` 的全部)。
/// `context` 为 mention 所在分块的向量(无 embedding 模型时为 None,退化为 v1 行为:
/// 同名归并到事实最多的候选)。
#[allow(clippy::too_many_arguments)]
async fn resolve_by_name(
pool: &PgPool,
kb_id: Uuid,
// None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
type_id: Option<Uuid>,
raw_name: &str,
context: Option<&[f32]>,
// 这次提及所在的**块原文**。画像分不出谁是谁时拿它做事实旁证(#331)——
// 传整篇文档会让每个部门都命中,所以这里要的是句子或块,不是文档。
text: Option<&str>,
// Candidates already claimed by a different response-local handle. They remain stored
// and recallable on later calls, but this mention cannot attach to them.
exclude: &[Uuid],
) -> AppResult<Resolution> {
let normalized = normalize_name(raw_name);
// 召回键 = 本名 + 泛用后缀词干及其增广("星尘"↔"星尘项目"互为候选)。
// 只扩召回,归并与否仍由下方画像相似度分层定夺。
let keys = recall_keys(&normalized);
// Store the same spelling whichever form is mentioned first.
let name = fold_markdown_markers(&normalized);
// 名字召回读名字事实(0041 决定 1):本名、简称、曾用名都是 `known_as` 上的一条。
// 度数不数名字事实——名字不是一条「关于它的事」,数进去每个实体都凭空多一
// 度数要等真有几个候选得比时才数:每个候选一条计数子查询,大库上很贵(#1296)
let candidates: Vec<Candidate> = sqlx::query_as(&format!(
"SELECT e.id, e.canonical_name, e.profile_embedding, e.profile_n
FROM entities e
-- IS NOT DISTINCT FROM 而不是 =(0009 的那个陷阱):开放图谱里的实体都没有类
-- (类由对齐来定),`type_id = NULL` 永远不成立,同名的它就永远撞不上——
-- 实测一个库里 Securities and Exchange Commission 与它的全大写写法成了两个实体
WHERE e.kb_id = $1 AND e.type_id IS NOT DISTINCT FROM $2 AND e.merged_into IS NULL
-- 被描述的东西没有名字(0044):它的 canonical_name 只是显示用的描述,
-- 不是召回的桥——两篇文档里描述得一样的两个东西不能因此接到一起
AND e.description IS NULL
AND (lower(e.canonical_name) = ANY($3) OR {named})",
named = crate::names::has_name_in("e", 1, 3),
))
.bind(kb_id)
.bind(type_id)
.bind(&keys)
.fetch_all(pool)
.await?
.into_iter()
.filter(|candidate: &Candidate| !exclude.contains(&candidate.id))
.collect();
if candidates.is_empty() {
// 同类型无候选 ≠ 新名字:类型标签会漂(同一团队被抽成 organization/project/
// concept),先查其它类型下的同名实体,按类型对的互斥强度分流。
return resolve_type_drift(pool, kb_id, type_id, name, &keys, context, exclude).await;
}
let Some(ctx) = context else {
// 无向量可比:v1 兼容 —— 归并到事实最多的同名候选
let best = match candidates.as_slice() {
[only] => only,
_ => {
let ids: Vec<Uuid> = candidates.iter().map(|c| c.id).collect();
let degree = degrees(pool, kb_id, &ids).await?;
candidates
.iter()
.zip(degree)
.max_by_key(|(_, d)| *d)
.map(|(c, _)| c)
.expect("non-empty")
}
};
touch_entity(pool, best.id).await?;
return Ok(Resolution {
entity_id: best.id,
created: false,
reviews: Vec::new(),
});
};
// 这一次调用**绝不能归上去**的全部:调用方点名排除的(`exclude`),加上这一轮
// 看过、并且会被判「不是同一个」的同名候选。下面无论走哪条分支决定新建,都要把
// 这份名单递给 `create_entity`——锁里那条回捞按名字捞,不给名单就会把它们捞回来
let weighed: Vec<Uuid> = exclude
.iter()
.copied()
.chain(candidates.iter().map(|c| c.id))
.collect();
// 有画像的候选算相似度;无画像(历史数据/无 embedding 期创建)单独归类
let mut scored: Vec<(&Candidate, f32)> = Vec::new();
let mut unprofiled: Vec<&Candidate> = Vec::new();
for c in &candidates {
match c
.profile_embedding
.as_ref()
.and_then(|p| cosine(p.as_slice(), ctx))
{
Some(sim) => scored.push((c, sim)),
None => unprofiled.push(c),
}
}
// 最高分候选:并列时保留先遇到的那个(与旧的 `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 })
{
// 画像掷硬币之前,先问事实(#331):这句话里提到了其中一个人的
// 部门或职位吗?提到了就不是硬币,是线索
if let Some(t) = text {
if let Some(c) =
corroborating_candidate(pool, kb_id, &[best, runner], t).await?
{
update_profile(pool, c.id, c.profile_n, ctx).await?;
return Ok(Resolution {
entity_id: c.id,
created: false,
reviews: Vec::new(),
});
}
}
let (id, created) =
create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
if !created {
// 并行的另一份文档刚建好它:用它的,审核对也是它排的
return Ok(Resolution {
entity_id: id,
created: false,
reviews: Vec::new(),
});
}
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,
created: false,
reviews: Vec::new(),
});
}
}
let unprofiled = match unprofiled.as_slice() {
[] => None,
[only] => Some(*only),
many => {
let ids: Vec<Uuid> = many.iter().map(|c| c.id).collect();
let degree = degrees(pool, kb_id, &ids).await?;
many.iter()
.copied()
.zip(degree)
.reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc })
.map(|(c, _)| c)
}
};
if let Some(c) = unprofiled {
// 无画像候选无从判别:v1 兼容归并,并用本次上下文初始化画像
update_profile(pool, c.id, c.profile_n, ctx).await?;
return Ok(Resolution {
entity_id: c.id,
created: false,
reviews: Vec::new(),
});
}
// 走到这里:所有候选都有画像且最高分 < ATTACH → 新建实体(同名不同人)。
//
// 但先问一次事实(#331)。灰区的意思是"向量说不好",不是"一定是新人"——
// 这句话里若正好写着某一个候选的部门或职位,那比余弦值可靠。
// **只认灰区**(≥ SIM_NEW):分数低于它的候选连审核对都不配入队,
// 拿一条旁证把它拉成同一人,等于绕过阈值而不是补充它。
if let Some(t) = text {
let in_grey: Vec<&Candidate> = scored
.iter()
.filter(|(_, s)| *s >= SIM_NEW)
.map(|(c, _)| *c)
.collect();
if let Some(c) = corroborating_candidate(pool, kb_id, &in_grey, t).await? {
update_profile(pool, c.id, c.profile_n, ctx).await?;
return Ok(Resolution {
entity_id: c.id,
created: false,
reviews: Vec::new(),
});
}
}
let (id, created) = create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
if !created {
// 并行的另一份文档刚建好它:用它的,审核对也是它排的
return Ok(Resolution {
entity_id: id,
created: false,
reviews: Vec::new(),
});
}
refresh_disambiguators(pool, kb_id, name).await?;
let mut reviews = best_scored
.filter(|(_, sim)| *sim >= SIM_NEW)
.map(|(c, sim)| {
vec![ReviewRequest {
other_id: c.id,
score: sim,
reason: format!("ambiguous_name|{sim:.2}"),
stage: ReviewStage::Adjudicating,
}]
})
.unwrap_or_default();
// 名字互相包含的既有实体:等值召回看不见它们(前缀枚举不完),
// 于是简称会静默变成第二个实体。只入队,不合并
reviews.extend(containment_reviews(pool, kb_id, type_id, name, id, context).await?);
Ok(Resolution {
entity_id: id,
created: true,
reviews,
})
}
/// **事实旁证**:这次提及的原文里,出现了某个候选的消歧宾语吗(#331)。
///
/// 画像向量分不出谁是谁时,能分开的线索往往就在事实里——一个张伟 `works_for`
/// 平台工程部,另一个 `works_for` 财务部,而这句话里写着"财务"。人在审核卡上
/// 看的正是这些事实(`top_facts`),这一步是把人做的事交回给代码。
///
/// **证据只往一个方向走。** 一致是"同一人"的弱证据;不一致**什么都不是**——
/// 在 Acme 上班又在 Zenith 兼职的人有两个 `works_for` 值,他仍是一个人。所以
/// 这个函数只回答"哪个候选被原文提到了",永远不回答"哪个候选被排除了"。
///
/// **恰好一个候选命中才算数。** 两个都命中说明这条线索在他们之间也分不开,
/// 与其挑一个不如维持原样。
///
/// 宾语的挑法与 `refresh_disambiguators` 同源(#299 之后从本体的 range 声明选,
/// 不是词表),并且**排除同名同伴也指着的那些**:两个张伟都在同一家公司时,
/// 公司名对分辨他们毫无帮助,却最容易在文档里撞上。
async fn corroborating_candidate<'a>(
pool: &PgPool,
kb_id: Uuid,
candidates: &[&'a Candidate],
text: &str,
) -> AppResult<Option<&'a Candidate>> {
// 单个候选也算数:「其他候选都没命中」在只有一个候选时天然成立
if candidates.is_empty() || text.trim().is_empty() {
return Ok(None);
}
let ids: Vec<Uuid> = candidates.iter().map(|c| c.id).collect();
// 一次查完所有候选:每个候选取若干个「同伴不指向」的宾语名字。
//
// **LEFT JOIN relation_types**(0044):开放陈述没有谓词、只有照抄的短语,
// 它指着的宾语一样是这个候选的画像——「收购了 Beta」不因为本体没接住
// 「收购了」就不算佐证。排序里关系的三个布尔位对开放行是 NULL,COALESCE
// 成 false 排在类型化行之后:类型化行之间的次序一字不变
let rows: Vec<(Uuid, String)> = sqlx::query_as(
"SELECT s.subject_id, s.name FROM (
SELECT f.subject_id, o.canonical_name AS name,
row_number() OVER (
PARTITION BY f.subject_id
ORDER BY EXISTS (SELECT 1 FROM relation_type_ranges rr
WHERE rr.relation_type_id = r.id) DESC,
COALESCE(r.temporal = 'state', FALSE) DESC,
COALESCE(r.functional, FALSE) DESC,
f.confidence DESC, f.recorded_at DESC
) AS rn
FROM facts f
LEFT JOIN relation_types r ON r.id = f.predicate_id
JOIN entities o ON o.id = f.object_id
WHERE f.kb_id = $1 AND f.subject_id = ANY($2)
AND f.invalidated_at IS NULL AND f.object_id IS NOT NULL
-- 同名同伴也指着的宾语没有分辨力,排除
AND NOT EXISTS (SELECT 1 FROM facts g
WHERE g.kb_id = $1 AND g.subject_id = ANY($2)
AND g.subject_id <> f.subject_id
AND g.object_id = f.object_id
AND g.invalidated_at IS NULL)
) s WHERE s.rn <= $3",
)
.bind(kb_id)
.bind(&ids)
.bind(CORROBORATION_OBJECTS)
.fetch_all(pool)
.await?;
let haystack = text.to_lowercase();
let mut hit: Option<&'a Candidate> = None;
for (subject_id, object_name) in &rows {
let needle = object_name.trim().to_lowercase();
if needle.chars().count() < MIN_CORROBORATION_CHARS || !haystack.contains(&needle) {
continue;
}
let Some(c) = candidates.iter().find(|c| c.id == *subject_id) else {
continue;
};
match hit {
// 同一个候选的第二条宾语也命中:仍是同一个候选,不算分歧
Some(prev) if prev.id == c.id => {}
// 命中了第二个候选:这条线索分不开他们
Some(_) => return Ok(None),
None => hit = Some(c),
}
}
Ok(hit)
}
/// 包含关系候选的最短边:两个名字里**较短的那个**至少这么长才算数。
/// 低于它的多是「研究院」「中心」这类通名,配对没有信息量,只会刷爆队列。
const MIN_CONTAIN_CHARS: i32 = 4;
/// 单次最多产出的包含关系审阅对。与 `MAX_DRIFT_REVIEWS` 同理:
/// 一个通名可能包含在几十个实体里,全放进去就把队列淹了。
const MAX_CONTAIN_REVIEWS: usize = 4;
/// SQL 侧多取几行:类型硬互斥的在 Rust 侧才筛得掉,
/// 只取 4 行的话可能 4 行全是互斥类型,真正那一对反而被 LIMIT 切掉。
const CONTAIN_SCAN_LIMIT: i64 = 16;
/// 名字当 LIKE 的字面子串用:不转义的话名字里的 `_` 会匹配任意一个字(#1293)
fn like_escaped(name: &str) -> String {
name.replace('\\', "\\\\")
.replace('%', "\\%")
.replace('_', "\\_")
}
/// 新建实体之后,找出**名字互相包含**的既有实体,作为审阅候选。
///
/// 中文商业文本在一篇之内就会全称转简称(「星云科技上海研究院」→「上海研究院」),
/// 而 [`recall_keys`] 是等值查:它靠枚举泛用后缀命中反向,可前缀是任意组织名,
/// **枚举不完**。于是这三类全部漏网,静默变成第二个实体:
///
/// ```text
/// 上海研究院 ⊂ 星云科技上海研究院 后缀被限定
/// 启明 X7 加速卡 ~ 启明 X7 推理加速卡 中间插词(靠 LIKE 覆盖不到,见下)
/// 沧海 ⊂ 沧海分布式推理平台 2.0 前缀被扩展
/// ```
///
/// **只出候选,永不自动合并。** 同名候选那条路在相似度 ≥ [`SIM_ATTACH`] 时直接归并,
/// 包含关系绝不能走它:`华瑞集团技术中心` 与 `星云科技技术中心` 都含「技术中心」,
/// 同一篇文档里上下文相似度很容易过线,而它们是两个部门。宁分勿合。
///
/// **别的名字一并参与**:合并会把名字事实搬到存活者身上,只查 `canonical_name` 的话,
/// 每成功合并一次就少一条召回的桥——`Holmes` 并入 `Sherlock Holmes` 之后,
/// 后来的 `Mr. Holmes` 就再也搭不上了(它跟 `Sherlock Holmes` 谁也不含谁)。
/// 合并越成功、漏得越多,是个会自我加剧的洞。
///
/// **已知不覆盖**:两个名字既不互相包含、又没有共同别名做桥的情形
///(`启明 X7 加速卡` 与 `启明 X7 推理加速卡`)。那要三元组相似度,而
/// `CREATE EXTENSION pg_trgm` 需要超级权限——本仓库是受限角色连库(见 `migrations/0010_least_privilege_role.sql`),
/// 装扩展会在部署上失败。留给需要时再说。
///
/// **性能**:反向那半(新名字包含旧名字)用不上任何索引,别名那半同样,
/// 所以这里靠 `kb_id` 收窄行集并设上限,且只在**新建实体时**跑一次,
/// 不是每条 mention。大库上如果不够,正解是建一张「后缀键」表走等值查,
/// 而不是加模糊索引。
/// 包含扫描的一行:(id, 本名, 类型 key, 类型 id, 画像)。类型 id 用来比本体声明的互斥
type ContainRow = (Uuid, String, Option<String>, Option<Uuid>, Option<Vector>);
async fn containment_reviews(
pool: &PgPool,
kb_id: Uuid,
// None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
type_id: Option<Uuid>,
name: &str,
new_id: Uuid,
ctx: Option<&[f32]>,
) -> AppResult<Vec<ReviewRequest>> {
let lower = name.to_lowercase();
if lower.chars().count() < MIN_CONTAIN_CHARS as usize {
return Ok(Vec::new());
}
// 实体可能还没判出类型(0009),那时没有 key 可查
let mention_key: Option<String> = match type_id {
Some(t) => sqlx::query_as::<_, (String,)>("SELECT key FROM entity_types WHERE id = $1")
.bind(t)
.fetch_optional(pool)
.await?
.map(|(k,)| k),
None => None,
};
// **不按类型过滤**:简称经常掉进 concept 兜底,而全称是具体类型
//(实测 上海研究院→concept vs 星云科技上海研究院→organization,
// 启明 X7 加速卡→concept vs 启明 X7 推理加速卡→product),
// 按类型相等去查,这两对一个都捞不到。相容性交给下面的 classify_type_drift。
// 多取一些行,因为硬互斥的会在 Rust 侧被筛掉
// 本体声明了跟这个类互斥的那些类(含继承),一次取出,逐行比 id
let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
// 第三列可空:未分类实体也要参与包含关系扫描(0009)
let rows: Vec<ContainRow> = sqlx::query_as(
"SELECT e.id, e.canonical_name, t.key, e.type_id, e.profile_embedding
FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.merged_into IS NULL
AND e.id <> $2
AND lower(e.canonical_name) <> $3
AND (
(char_length(e.canonical_name) >= $4
AND (lower(e.canonical_name) LIKE '%' || $6 || '%'
OR $3 LIKE '%' || replace(replace(replace(lower(e.canonical_name), '\\', '\\\\'), '%', '\\%'), '_', '\\_') || '%'))
-- **别的名字也要参与召回,否则每合并一次就少一条桥。**
--
-- 合并把名字事实搬到存活者身上:Holmes 并入 Sherlock Holmes 之后,
-- Holmes 那一行 merged_into 非空、被上面第一个条件滤掉了。可十分钟后
-- 出现的 Mr. Holmes 跟 Sherlock Holmes 谁也不含谁——本来正是靠
-- Holmes 才桥得上。实测就是这么漏的:同类型那个 bug 修好、Holmes
-- 正确合并之后,Mr. Holmes 反而永远进不了队列。
--
-- 合并越成功,桥拆得越多。这个洞会自我加剧。
OR EXISTS (
SELECT 1 FROM facts nf
JOIN relation_types nr ON nr.id = nf.predicate_id
WHERE nf.subject_id = e.id AND nf.kb_id = $1
AND nr.builtin AND nr.key = 'known_as'
AND nf.invalidated_at IS NULL
AND char_length(nf.object_value->>'value') >= $4
AND (lower(nf.object_value->>'value') LIKE '%' || $6 || '%'
OR $3 LIKE '%' || replace(replace(replace(lower(nf.object_value->>'value'), '\\', '\\\\'), '%', '\\%'), '_', '\\_') || '%'))
)
ORDER BY char_length(e.canonical_name)
LIMIT $5",
)
.bind(kb_id)
.bind(new_id)
.bind(&lower)
.bind(MIN_CONTAIN_CHARS)
.bind(CONTAIN_SCAN_LIMIT)
.bind(like_escaped(&lower))
.fetch_all(pool)
.await?;
Ok(rows
.into_iter()
// 哪些类型对可能指同一个东西,既有规则已经想清楚了,别另发明一套:
// 本体声明互斥的永不合并,person vs organization 永不合并,
// concept 兜底与谁都可能是一个
.filter(|(_, other_name, type_key, other_type, _)| {
!other_type.is_some_and(|t| disjoint.contains(&t))
&& classify_type_drift(mention_key.as_deref(), type_key.as_deref())
!= TypeDrift::Disjoint
// `migration 39` 是 `migration 395` 的子串,但不是它的简称(见 `numbers_differ`)。
// 筛在 take 之前:带别的数的兄弟不该占掉真候选的名额
&& !crate::names::numbers_differ(name, other_name)
})
.take(MAX_CONTAIN_REVIEWS)
.map(|(id, other_name, _, _, emb)| {
// 分数只是给队列排序用的参考,**不参与是否合并的判断**——
// 那个判断本来就不在这条路上
let score = ctx
.and_then(|x| emb.as_ref().and_then(|p| cosine(p.as_slice(), x)))
.unwrap_or(0.0);
ReviewRequest {
other_id: id,
score,
reason: format!("contains|{other_name}"),
stage: ReviewStage::Adjudicating,
}
})
.collect())
}
#[derive(Debug, sqlx::FromRow)]
struct CrossCandidate {
id: Uuid,
canonical_name: String,
// None = 这个候选还没判出类型(0009)
type_key: Option<String>,
// 同上;`types_are_kin` 要按 id 走类层级
type_id: Option<Uuid>,
// 抽取升格要看它:人说过「就是没有类型」时,那也是一个决定
type_source: String,
profile_embedding: Option<Vector>,
profile_n: i32,
}
/// `reason` 存 code,措辞归界面(docs/decisions/0004)——这一列不该一半 code
/// 一半英文句子,那样中文界面上就是一半能翻一半不能。
fn drift_reason(mention_key: Option<&str>, other_key: Option<&str>, sim: Option<f32>) -> String {
// 未分类的一侧写成 `(untyped)`。这一列存 code 供界面翻译,
// 留空会让 `a vs b` 变成 `a vs `,读起来像被截断而不像"没有"
let a = mention_key.unwrap_or("(untyped)");
let b = other_key.unwrap_or("(untyped)");
match sim {
Some(s) => format!("type_drift|{a} vs {b} {s:.2}"),
None => format!("type_drift|{a} vs {b}"),
}
}
/// 本体声明了跟这个类互斥的全部类(0016 B3)。
///
/// **互斥是继承的**:Person ⟂ Organization 一条声明,就让 Person 的每个子类跟
/// Organization 的每个子类都互斥。所以先沿父链往上收集这个类的祖先,取它们声明的
/// 互斥对象,再沿子链往下展开。表里两个方向各存一行,问一个方向就够。
///
/// 没判出类型(`None`)时没有类可问,回空集:那一侧本来就走召回候选那一档
async fn declared_disjoint_from(
pool: &PgPool,
kb_id: Uuid,
type_id: Option<Uuid>,
) -> AppResult<HashSet<Uuid>> {
let Some(type_id) = type_id else {
return Ok(HashSet::new());
};
let rows: Vec<(Uuid,)> = sqlx::query_as(
"WITH RECURSIVE up(id) AS (
SELECT $2::uuid
UNION
SELECT p.parent_id FROM entity_type_parents p JOIN up ON p.child_id = up.id
), hit(id) AS (
SELECT d.b_id FROM entity_type_disjoint d JOIN up ON d.a_id = up.id
WHERE d.kb_id = $1
), down(id) AS (
SELECT id FROM hit
UNION
SELECT p.child_id FROM entity_type_parents p JOIN down ON p.parent_id = down.id
)
SELECT id FROM down",
)
.bind(kb_id)
.bind(type_id)
.fetch_all(pool)
.await?;
Ok(rows.into_iter().map(|(id,)| id).collect())
}
/// 两个类是不是一家的:一方是另一方的祖先,或者两者共有一个**不是根**的祖先。
///
/// `CONFUSABLE_TYPE_KEYS` 那张三 key 的硬表是给没装包的库准备的;装了 schema.org
/// 之后同一家公司会被抽成 Organization / Corporation / OnlineBusiness 三种类型,
/// 全都在 Organization 之下,却一对都过不了硬表,于是三个同名实体并存、
/// 审阅队列里一条都没有,面板还指着 Review 说"去那里合并"(#226)。
///
/// 根不算共同祖先:schema.org 里万物皆 Thing,算上它 Person 与 Organization
/// 也成了一家。没有根的词汇表(W3C Org 的 Organization 自己就是顶)靠
/// 祖先/后代那一半接住
async fn types_are_kin(pool: &PgPool, a: Uuid, b: Uuid) -> AppResult<bool> {
let (kin,): (bool,) = sqlx::query_as(
"WITH RECURSIVE up_a(id) AS (
SELECT $1::uuid
UNION
SELECT p.parent_id FROM entity_type_parents p JOIN up_a ON p.child_id = up_a.id
), up_b(id) AS (
SELECT $2::uuid
UNION
SELECT p.parent_id FROM entity_type_parents p JOIN up_b ON p.child_id = up_b.id
)
SELECT EXISTS (SELECT 1 FROM up_a WHERE id = $2)
OR EXISTS (SELECT 1 FROM up_b WHERE id = $1)
OR EXISTS (SELECT 1 FROM up_a JOIN up_b USING (id)
WHERE EXISTS (SELECT 1 FROM entity_type_parents p
WHERE p.child_id = up_a.id))",
)
.bind(a)
.bind(b)
.fetch_one(pool)
.await?;
Ok(kin)
}
fn confusable_reviews(
// None = 这一侧还没判出类型(0009)
mention_key: Option<&str>,
cands: &[&CrossCandidate],
ctx: Option<&[f32]>,
) -> Vec<ReviewRequest> {
cands
.iter()
.map(|c| {
let sim = ctx.and_then(|x| {
c.profile_embedding
.as_ref()
.and_then(|p| cosine(p.as_slice(), x))
});
ReviewRequest {
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()
}
/// 同类型召回为空时的跨类型处置(类型漂移)。
/// concept 兜底型候选跑既有画像分层:高相似直接 ATTACH(漂移的召回修复,concept
/// 侧类型升格为具体类型),灰区/无从判别 → 宁分勿合新建 + 审核对;易混具体类型
/// 一律新建 + 审核对(同名 + 类型摇摆本身就是信号,不设相似度门槛);硬互斥忽略。
async fn resolve_type_drift(
pool: &PgPool,
kb_id: Uuid,
// None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
type_id: Option<Uuid>,
name: &str,
keys: &[String],
context: Option<&[f32]>,
exclude: &[Uuid],
) -> AppResult<Resolution> {
// 这一侧也可能还没判出类型(0009),那时没有 key 可查
let mention_key: Option<String> = match type_id {
Some(t) => sqlx::query_as::<_, (String,)>("SELECT key FROM entity_types WHERE id = $1")
.bind(t)
.fetch_optional(pool)
.await?
.map(|(k,)| k),
None => None,
};
let cross: Vec<CrossCandidate> = sqlx::query_as(&format!(
"SELECT e.id, e.canonical_name, t.key AS type_key, e.type_id, e.type_source,
e.profile_embedding, e.profile_n
FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
-- IS DISTINCT FROM 而不是 <>:后者遇 NULL 返回 NULL,被 WHERE 当假,
-- 未分类实体会被整个漏掉(0009)
WHERE e.kb_id = $1 AND e.type_id IS DISTINCT FROM $2 AND e.merged_into IS NULL
-- 被描述的东西不参与名字召回(0044),同上
AND e.description IS NULL
AND (lower(e.canonical_name) = ANY($3) OR {named})",
named = crate::names::has_name_in("e", 1, 3),
))
.bind(kb_id)
.bind(type_id)
.bind(keys)
.fetch_all(pool)
.await?
.into_iter()
.filter(|candidate: &CrossCandidate| !exclude.contains(&candidate.id))
.collect();
// 本体声明了互斥的类,一次取出(含继承)。声明优先于下面所有启发式
let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
let mut recall_cands: Vec<&CrossCandidate> = Vec::new();
let mut review_cands: Vec<&CrossCandidate> = Vec::new();
for c in &cross {
let mut drift = classify_type_drift(mention_key.as_deref(), c.type_key.as_deref());
if c.type_id.is_some_and(|t| disjoint.contains(&t)) {
// 本体说这两类互斥:哪怕硬表说易混、类层级说一家,也分开。
// 声明是人写下的判断,启发式只是没声明时的猜测
drift = TypeDrift::Disjoint;
} else if drift == TypeDrift::Disjoint {
// 硬表判不上的,再看类层级:同一支系下的同名当易混,进审阅队列
if let (Some(a), Some(b)) = (type_id, c.type_id) {
if types_are_kin(pool, a, b).await? {
drift = TypeDrift::Review;
}
}
}
match drift {
TypeDrift::Recall => recall_cands.push(c),
TypeDrift::Review => review_cands.push(c),
TypeDrift::Disjoint => {}
}
}
if let Some(ctx) = context {
let best = recall_cands
.iter()
.filter_map(|c| {
c.profile_embedding
.as_ref()
.and_then(|p| cosine(p.as_slice(), ctx))
.map(|sim| (*c, sim))
})
.max_by(|a, b| a.1.total_cmp(&b.1));
if let Some((best, sim)) = best {
if sim >= SIM_ATTACH {
update_profile(pool, best.id, best.profile_n, ctx).await?;
// 候选还没判出类型而这次抽取判出来了 → 升格。
// 不是合并(没有第二个实体),不入 entity_merges;本体页可手工改回
//
// **人说过的「没有类型」不算「还没判出来」。** 0009 之后两者都是
// NULL,只看 type_key.is_none() 分不出——于是一个人看过、认为
// 本体里没有合适类的实体,会在下一次抽取时被安上一个类型
if best.type_key.is_none() && best.type_source != "human" && type_id.is_some() {
sqlx::query(
"UPDATE entities
SET type_id = $2, type_source = 'extracted', updated_at = now()
WHERE id = $1",
)
.bind(best.id)
.bind(type_id)
.execute(pool)
.await?;
// 类型标签兜底的消歧后缀可能已过时
refresh_disambiguators(pool, kb_id, &best.canonical_name).await?;
}
// mention 已定居到召回实体;同名易混类型实体的疑点仍在 → 照常入队
let mut reviews =
confusable_reviews(mention_key.as_deref(), &review_cands, Some(ctx));
reviews.truncate(MAX_DRIFT_REVIEWS);
return Ok(Resolution {
entity_id: best.id,
created: false,
reviews,
});
}
}
}
// 同上:点名排除的,加上跨类型同名里掂量过的
let weighed: Vec<Uuid> = exclude
.iter()
.copied()
.chain(cross.iter().map(|c| c.id))
.collect();
let (id, created) = create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
if !created {
// 并行的另一份文档刚建好它:用它的,审核对也是它排的
return Ok(Resolution {
entity_id: id,
created: false,
reviews: Vec::new(),
});
}
if !cross.is_empty() {
// 跨类型同名并存:消歧后缀按名字分组(不分类型),需要刷新
refresh_disambiguators(pool, kb_id, name).await?;
}
let mut reviews = confusable_reviews(mention_key.as_deref(), &review_cands, context);
for c in &recall_cands {
let sim = context.and_then(|ctx| {
c.profile_embedding
.as_ref()
.and_then(|p| cosine(p.as_slice(), ctx))
});
match sim {
// 画像明确不像:完全分开,不打扰审核队列
Some(s) if s < SIM_NEW => {}
// 灰区或无从判别(无 embedding / 候选无画像):宁分勿合 + 审核对
_ => reviews.push(ReviewRequest {
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,
}),
}
}
reviews.truncate(MAX_DRIFT_REVIEWS);
// 漂移这条路一样会新建实体,包含关系照查
reviews.extend(containment_reviews(pool, kb_id, type_id, name, id, context).await?);
Ok(Resolution {
entity_id: id,
created: true,
reviews,
})
}
/// 新建一个实体。返回 `(id, 是否真的新建)`。
///
/// **同名同类的新建串行化。** 上面的查找不在事务里:两份文档并行抽取,同一个名字
/// 各自查一遍都没有、各自建一个——实测「澜图数据」在同一秒里建了两个,之后每一次
/// 提到它都撞上两个候选,再各建一个、各排一对审核,一篇语料跑完裂成四个。
/// 这里按(库,名字)拿事务级咨询锁,锁里再查一次:别人刚建好的,就用它的。
/// 不同类型的同名不在此列——那是消歧的事,不是竞态
async fn create_entity(
pool: &PgPool,
kb_id: Uuid,
// None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
type_id: Option<Uuid>,
name: &str,
context: Option<&[f32]>,
// 调用方**刚刚掂量过、并且决定不并**的那些同名实体。
//
// 锁里那条回捞不加这个就分不清两件事:一件是「并行的另一份文档一毫秒前
// 建好了同名的它」——该用它的;另一件是「这个名字本来就有人,而调用方看过
// 之后决定另建一个」——这时回捞只会捞回它刚拒绝的那个候选,等于让一把锁
// 替人把 mention 归到其中一个身上。同名并列那条路上这正是 #270 禁的事:
// 分不开就别硬分,谁也不归,两个都送审。
weighed: &[Uuid],
) -> AppResult<(Uuid, bool)> {
// 名字属性在锁外取:它自己有一次插入,放进锁里会让所有建实体的人排同一把队
let known_as = crate::names::ensure_known_as(pool, kb_id).await?;
let mut tx = pool.begin().await?;
sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))")
.bind(kb_id.to_string())
.bind(name)
.execute(&mut *tx)
.await?;
let existing: Option<(Uuid,)> = sqlx::query_as(
// 被描述的东西不算「同名的它」(0044):它的 canonical_name 只是显示用的描述
"SELECT id FROM entities
WHERE kb_id = $1 AND canonical_name = $2 AND type_id IS NOT DISTINCT FROM $3
AND merged_into IS NULL AND description IS NULL AND id <> ALL($4)
ORDER BY id LIMIT 1",
)
.bind(kb_id)
.bind(name)
.bind(type_id)
.bind(weighed)
.fetch_optional(&mut *tx)
.await?;
if let Some((id,)) = existing {
tx.commit().await?;
return Ok((id, false));
}
let id = Uuid::now_v7();
sqlx::query(
"INSERT INTO entities (id, kb_id, type_id, canonical_name, profile_embedding, profile_n)
VALUES ($1, $2, $3, $4, $5, $6)",
)
.bind(id)
.bind(kb_id)
.bind(type_id)
.bind(name)
.bind(context.map(|c| Vector::from(c.to_vec())))
.bind(i32::from(context.is_some()))
.execute(&mut *tx)
.await?;
// 与实体同一个事务:召回按名字事实找它,建出来却查不到名字的那一瞬间不能有。
// 出处(哪一块、哪句话)由抽取随后给这条事实补证据
sqlx::query(
"INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_value)
VALUES ($1, $2, $3, $4, jsonb_build_object('value', $5::text))",
)
.bind(Uuid::now_v7())
.bind(kb_id)
.bind(id)
.bind(known_as)
.bind(name)
.execute(&mut *tx)
.await?;
tx.commit().await?;
Ok((id, true))
}
/// 一个被描述、没有名字的东西(0044 第一刀,#729):"the buyer's parent company"、
/// 「那家上海的子公司」。它是一个实体——陈述要指着它——但它没有名字。
///
/// `canonical_name` 写成描述本身,**只为显示**;`description` 是它真正的身份。
/// **不写 `known_as`**:名字事实是召回的桥(0041),一段描述做桥会把两篇文档里
/// 碰巧描述得一样的两个东西接到一起。没有名字就没有桥,后来的提及找不到它——
/// 这是对的:一段描述指的是谁,要靠对齐(第二刀)而不是靠字面相同。
///
/// `kind_word` 是文档自己的类别词("company"、「子公司」),落在 `specific_type`
/// 上;`type_id` 留空,`type_source` 走缺省的 extracted。
///
/// 朴素插入:不加锁、不找候选、不去重——同一篇文档里同一段描述由调用方并成一个。
/// 两篇文档各描述一次,就是两个实体,等对齐来判它们是不是一个
pub async fn create_described(
pool: &PgPool,
kb_id: Uuid,
description: &str,
kind_word: Option<&str>,
) -> AppResult<Uuid> {
let description = description.trim();
if description.is_empty() {
return Err(AppError::invalid(
"description_missing",
"a described thing needs the document's description",
));
}
let id = Uuid::now_v7();
sqlx::query(
"INSERT INTO entities (id, kb_id, type_id, canonical_name, description, specific_type)
VALUES ($1, $2, NULL, $3, $3, left($4, 80))",
)
.bind(id)
.bind(kb_id)
.bind(description)
.bind(kind_word.map(str::trim).filter(|k| !k.is_empty()))
.execute(pool)
.await?;
Ok(id)
}
async fn touch_entity(pool: &PgPool, id: Uuid) -> AppResult<()> {
sqlx::query("UPDATE entities SET updated_at = now() WHERE id = $1")
.bind(id)
.execute(pool)
.await?;
Ok(())
}
/// 画像增量质心:profile ← (profile·n + ctx) / (n+1)。
/// 维度不匹配(换过 embedding 模型)时用新向量重置画像。
async fn update_profile(pool: &PgPool, id: Uuid, n: i32, ctx: &[f32]) -> AppResult<()> {
let existing: Option<(Option<Vector>,)> =
sqlx::query_as("SELECT profile_embedding FROM entities WHERE id = $1")
.bind(id)
.fetch_optional(pool)
.await?;
let old = existing.and_then(|(v,)| v);
let (new_vec, new_n) = match old {
Some(p) if p.as_slice().len() == ctx.len() && n > 0 => {
let nf = n as f32;
let merged: Vec<f32> = p
.as_slice()
.iter()
.zip(ctx)
.map(|(a, b)| (a * nf + b) / (nf + 1.0))
.collect();
(merged, n + 1)
}
_ => (ctx.to_vec(), 1),
};
let dims = new_vec.len();
sqlx::query(
"UPDATE entities SET profile_embedding = $2, profile_n = $3, updated_at = now()
WHERE id = $1",
)
.bind(id)
.bind(Vector::from(new_vec))
.bind(new_n)
.execute(pool)
.await?;
// 画像表也要索引(0035 / #514):类型消解按主语逐个扫它。在了的话这一句是一次查找
crate::vector_index::request(pool, crate::vector_index::Target::EntityProfiles, dims).await?;
Ok(())
}
/// 同名组展示消歧:组内 ≥2 个存活实体时,各自取最能把自己和同名者分开的那条
/// 事实的宾语名,否则退回类型标签;组内唯一则清空。
///
/// **不认谓词的名字**(#299)。原先这里写死 works_at / part_of / located_in / leads
/// 四个 key,而 schema.org 包建出来的库用的是 works_for / member_of / affiliation
/// ——于是两个明明分得清清楚楚的 John Smith(一个在 Acme Robotics,一个在
/// St Mary's Hospital)双双退回类型标签,并排显示成两个 "John Smith · Person"。
/// 一张手写的词表管不住别人的词汇表,这与 #193 那条「封闭动词表换个语料就漏」
/// 是同一个毛病。
///
/// 换成按**这条事实分不分得开**排序,理由都来自本体自己的声明:
///
/// 1. **宾语在同名组里独一份**——后缀存在的全部意义就是这个。两个人都在 Acme
/// 时它谁也分不开,那就退到下面几条按信息量取,而不是编一个假的区分
/// 2. **谓词声明过值域**(`relation_type_ranges`)——有人特意说过这条关系指向什么,
/// 比抽取顺手长出来的那些更可能是身份性的
/// 3. **状态而非事件**(`temporal`):「在哪儿工作」是身份,「某天开了个会」不是
/// 4. **单值关系**(`functional`):一个主语只能有一个值的关系,本身就是身份锚
///
/// 没有谓词的事实(`predicate_id IS NULL`,0010)不参与:原话留在证据里,
/// 不是本体承认的说法,不该被当成一个人的身份写进后缀。
/// 库里有没有叫这个名字的实体,**不问类型**、并掉的不算。
///
/// 抽取用它判断一个没声明的主宾是不是已知的东西(#559):模型偶尔漏报一个实体
/// 却在事实里用了它,那时库里多半已经有它;库里也没有的,就不是漏报,是一个
/// 描述("lawsuit against OpenAI"),不该成节点。同名多个时取事实最多的那个——
/// 这里只回答「有没有」,谁是谁交给消解
pub async fn existing_by_name(
pool: &PgPool,
kb_id: Uuid,
raw_name: &str,
) -> AppResult<Option<Uuid>> {
let name = normalize_name(raw_name);
let keys = recall_keys(&name);
let id: Option<Uuid> = sqlx::query_scalar(&format!(
"SELECT e.id FROM entities e
WHERE e.kb_id = $1 AND e.merged_into IS NULL
-- 被描述的东西不参与名字召回(0044):描述不是桥
AND e.description IS NULL
AND (lower(e.canonical_name) = ANY($2) OR {named})
ORDER BY (SELECT count(*) FROM facts f
WHERE f.kb_id = e.kb_id AND (f.subject_id = e.id OR f.object_id = e.id) AND f.invalidated_at IS NULL AND {not_name}) DESC,
e.created_at
LIMIT 1",
named = crate::names::has_name_in("e", 1, 2),
not_name = crate::names::not_a_name("f"),
))
.bind(kb_id)
.bind(&keys)
.fetch_optional(pool)
.await?;
Ok(id)
}
pub async fn refresh_disambiguators(pool: &PgPool, kb_id: Uuid, name: &str) -> AppResult<()> {
let group: Vec<(Uuid,)> = sqlx::query_as(
"SELECT id FROM entities
WHERE kb_id = $1 AND merged_into IS NULL AND lower(canonical_name) = lower($2)",
)
.bind(kb_id)
.bind(name)
.fetch_all(pool)
.await?;
if group.len() < 2 {
for (id,) in &group {
sqlx::query("UPDATE entities SET disambiguator = NULL WHERE id = $1")
.bind(id)
.execute(pool)
.await?;
}
return Ok(());
}
let peers: Vec<Uuid> = group.iter().map(|(id,)| *id).collect();
for (id,) in &group {
// LEFT JOIN(0044):开放陈述指着的宾语也能当消歧后缀——「张三 · 星云科技」
// 不因为「任职于」没进本体就写不出来。关系的布尔位对开放行 COALESCE 成 false,
// 类型化行之间的次序不变
let label: Option<(String,)> = sqlx::query_as(
"SELECT o.canonical_name FROM facts f
LEFT JOIN relation_types r ON r.id = f.predicate_id
JOIN entities o ON o.id = f.object_id
WHERE f.kb_id = $1 AND f.subject_id = $2
AND f.invalidated_at IS NULL AND f.object_id IS NOT NULL
ORDER BY
-- 同名的另一个也指着它,这条就分不开谁是谁
(NOT EXISTS (SELECT 1 FROM facts g
WHERE g.kb_id = $1 AND g.subject_id = ANY($3)
AND g.subject_id <> $2 AND g.object_id = f.object_id
AND g.invalidated_at IS NULL)) DESC,
EXISTS (SELECT 1 FROM relation_type_ranges rr
WHERE rr.relation_type_id = r.id) DESC,
COALESCE(r.temporal = 'state', FALSE) DESC,
COALESCE(r.functional, FALSE) DESC,
f.confidence DESC, f.recorded_at DESC
LIMIT 1",
)
.bind(kb_id)
.bind(id)
.bind(&peers)
.fetch_optional(pool)
.await?;
// 关联事实找不着就退到类型标签;**类型也可能没有**(0009),
// 那就没有可写的后缀——留 NULL,界面按同名并列显示,别编一个出来
let disambiguator: Option<String> = match label {
Some((l,)) => Some(l),
None => sqlx::query_as::<_, (String,)>(
"SELECT t.label FROM entities e JOIN entity_types t ON t.id = e.type_id
WHERE e.id = $1",
)
.bind(id)
.fetch_optional(pool)
.await?
.map(|(l,)| l),
};
sqlx::query("UPDATE entities SET disambiguator = $2 WHERE id = $1")
.bind(id)
.bind(disambiguator)
.execute(pool)
.await?;
}
Ok(())
}
// ---------------------------------------------------------------------------
// 审核队列
// ---------------------------------------------------------------------------
/// 灰区疑似重复对入队(同一 pending 对幂等)。
pub async fn create_review(
pool: &PgPool,
kb_id: Uuid,
left_id: Uuid,
right_id: Uuid,
score: f32,
reason: &str,
stage: ReviewStage,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO resolution_reviews AS existing
(id, kb_id, left_id, right_id, score, reason, stage)
VALUES ($1, $2, $3, $4, $5, $6, $7)
ON CONFLICT (kb_id, least(left_id, right_id), greatest(left_id, right_id))
WHERE status = 'pending'
DO UPDATE SET stage = 'human', reason = EXCLUDED.reason
WHERE EXCLUDED.stage = 'human' AND existing.stage = 'adjudicating'",
)
.bind(Uuid::now_v7())
.bind(kb_id)
.bind(left_id)
.bind(right_id)
.bind(score)
.bind(reason)
.bind(stage.as_str())
.execute(pool)
.await?;
Ok(())
}
#[derive(Debug, sqlx::FromRow)]
pub(crate) struct ReviewRow {
id: Uuid,
left_id: Uuid,
right_id: Uuid,
score: f32,
reason: Option<String>,
stage: String,
created_at: DateTime<Utc>,
}
async fn review_sides(
pool: &PgPool,
kb_id: Uuid,
entity_ids: &[Uuid],
) -> AppResult<HashMap<Uuid, ReviewSide>> {
#[derive(sqlx::FromRow)]
struct SideRow {
id: Uuid,
name: String,
type_label: Option<String>,
color: String,
disambiguator: Option<String>,
degree: i64,
}
let rows: Vec<SideRow> = sqlx::query_as(&format!(
"SELECT e.id, e.canonical_name AS name, t.label AS type_label,
coalesce(t.color, '#94a3b8') AS color, e.disambiguator,
(SELECT count(*) FROM facts f
WHERE f.kb_id = e.kb_id AND (f.subject_id = e.id OR f.object_id = e.id)
AND f.invalidated_at IS NULL AND {not_name}) AS degree
-- LEFT JOIN:没判出类型的实体照样要能进审核(0009)。
-- 内连接会让它整条审核项取不出来,而漂移审核恰恰最常发生在它们身上
FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.id = ANY($2)",
not_name = crate::names::not_a_name("f"),
))
.bind(kb_id)
.bind(entity_ids)
.fetch_all(pool)
.await?;
let mut lines = entity_fact_lines_many(pool, kb_id, entity_ids, 4).await?;
Ok(rows
.into_iter()
.map(|row| {
(
row.id,
ReviewSide {
id: row.id,
name: row.name,
type_label: row.type_label,
color: row.color,
disambiguator: row.disambiguator,
degree: row.degree,
top_facts: lines.remove(&row.id).unwrap_or_default(),
},
)
})
.collect())
}
/// 实体的事实摘要行:"works at → 星云科技 (2023-01 → now)",裁决 prompt 与审核 UI 共用。
pub async fn entity_fact_lines(
pool: &PgPool,
kb_id: Uuid,
entity_id: Uuid,
limit: i64,
) -> AppResult<Vec<String>> {
Ok(entity_fact_lines_many(pool, kb_id, &[entity_id], limit)
.await?
.remove(&entity_id)
.unwrap_or_default())
}
/// The lateral limit applies to each entity, not to the whole page. Keep this
/// path shared with the single-entity reader used by adjudication.
async fn entity_fact_lines_many(
pool: &PgPool,
kb_id: Uuid,
entity_ids: &[Uuid],
limit: i64,
) -> AppResult<HashMap<Uuid, Vec<String>>> {
if entity_ids.is_empty() {
return Ok(HashMap::new());
}
#[derive(sqlx::FromRow)]
struct Line {
entity_id: Uuid,
direction: String,
predicate_label: String,
other_name: Option<String>,
valid_from: Option<DateTime<Utc>>,
valid_to: Option<DateTime<Utc>>,
}
// 名字不算审阅卡上的一条事实(0041):两个同名实体各有一条「known as 张伟」,
// 摆出来像是一条共同证据,其实它什么也分不出来。
// 开放陈述(0044)按它照抄的短语读:`phrase` 在关系标签之后、证据众数之前——
// 类型化行的 phrase 是 NULL,它们的显示一字不变
let rows: Vec<Line> = sqlx::query_as(&format!(
"SELECT requested.id AS entity_id, line.*
FROM unnest($2::uuid[]) AS requested(id)
CROSS JOIN LATERAL (
SELECT CASE WHEN f.subject_id = requested.id THEN 'out' ELSE 'in' END AS direction,
COALESCE(r.label, f.phrase, fact_surface_predicate(f.id)) AS predicate_label,
-- 字面值的事实没有对端实体:值本身就是这一行要说的(职位、工号),不能读成「?」
COALESCE(o.canonical_name, left(f.object_value->>'value', 120)) AS other_name,
f.valid_from, f.valid_to, f.confidence, f.recorded_at
FROM facts f
LEFT JOIN relation_types r ON r.id = f.predicate_id
LEFT JOIN entities o
ON o.id = CASE WHEN f.subject_id = requested.id THEN f.object_id ELSE f.subject_id END
WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
AND (f.subject_id = requested.id OR f.object_id = requested.id)
AND COALESCE(r.label, f.phrase, fact_surface_predicate(f.id)) IS NOT NULL
AND {not_name}
ORDER BY f.confidence DESC, f.recorded_at DESC
LIMIT $3
) line
ORDER BY requested.id, line.confidence DESC, line.recorded_at DESC",
not_name = crate::names::not_a_name("f"),
))
.bind(kb_id)
.bind(entity_ids)
.bind(limit)
.fetch_all(pool)
.await?;
// 本名以外的名字单独打头一行(0041):「海洋探测器1号」对「海探1」,裁决器要看得见
// 前者也叫海探1,否则两边的事实各说各的,它只会判「不是同一个」。本名不列——
// 两个张伟各有一条「known as 张伟」,摆出来像共同证据,其实什么也分不出
let names = crate::names::other_names_many(pool, entity_ids).await?;
let mut lines: HashMap<Uuid, Vec<String>> = names
.into_iter()
.map(|(id, names)| (id, vec![format!("also known as: {}", names.join(", "))]))
.collect();
for l in rows {
let other = l.other_name.unwrap_or_else(|| "?".into());
let core = if l.direction == "out" {
format!("{} → {}", l.predicate_label, other)
} else {
format!("{} ← {}", l.predicate_label, other)
};
let text = match (l.valid_from, l.valid_to) {
(Some(f), Some(t)) => {
format!("{core} ({} → {})", f.format("%Y-%m"), t.format("%Y-%m"))
}
(Some(f), None) => format!("{core} ({} → now)", f.format("%Y-%m")),
_ => core,
};
lines.entry(l.entity_id).or_default().push(text);
}
Ok(lines)
}
pub(crate) async fn assemble_reviews(
pool: &PgPool,
kb_id: Uuid,
rows: Vec<ReviewRow>,
) -> AppResult<Vec<ReviewItem>> {
if rows.is_empty() {
return Ok(Vec::new());
}
// An entity can occur on either side of several pairs. Read it once for
// this page, then reuse its summary without changing the review order.
let mut entity_ids: Vec<Uuid> = rows.iter().flat_map(|r| [r.left_id, r.right_id]).collect();
entity_ids.sort_unstable();
entity_ids.dedup();
let sides = review_sides(pool, kb_id, &entity_ids).await?;
// 这一页上开着的建议(0025):一趟查完,按审核行挂上去
let ids: Vec<Uuid> = rows.iter().map(|r| r.id).collect();
let proposals: HashMap<Uuid, utopia_core::models::ReviewProposal> =
sqlx::query_as::<_, (Uuid, Uuid, String, f32, Option<String>)>(
"SELECT target_id, id, action, confidence, reason FROM agent_decisions
WHERE target_kind = 'review' AND target_id = ANY($1) AND status = 'proposed'",
)
.bind(&ids)
.fetch_all(pool)
.await?
.into_iter()
.map(|(target, id, action, confidence, reason)| {
(
target,
utopia_core::models::ReviewProposal {
id,
action,
confidence,
reason,
},
)
})
.collect();
let mut items = Vec::with_capacity(rows.len());
for r in rows {
let proposal = proposals.get(&r.id).cloned();
items.push(ReviewItem {
id: r.id,
score: r.score,
reason: r.reason,
stage: r.stage,
created_at: r.created_at,
left: sides.get(&r.left_id).cloned().ok_or(AppError::NotFound)?,
right: sides.get(&r.right_id).cloned().ok_or(AppError::NotFound)?,
proposal,
});
}
Ok(items)
}
/// 重复项按两边类型的关系分三档(#428)。**没类型的一侧哪档都不进**:不知道的
/// 既不能当成一样,也不能当成不一样。`clause()` 是 SQL 片段,别名固定 a / b
/// (左右两个实体),列表与 `review::counts` 共用,两处口径不会分叉。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TypeFilter {
Any,
/// 两边都有类型且相等——同名同类,人最先想批量合的那一档
Same,
/// 两边都有类型且不等——同名异义,合了就错
Conflict,
}
impl TypeFilter {
/// 查询串里的写法:缺省 any;认不出的当契约错误报出来
pub fn parse(s: Option<&str>) -> AppResult<Self> {
match s.unwrap_or("any") {
"any" => Ok(Self::Any),
"same" => Ok(Self::Same),
"conflict" => Ok(Self::Conflict),
other => Err(AppError::invalid(
"unknown_type_filter",
format!("types must be any, same or conflict, not {other}"),
)),
}
}
pub fn clause(self) -> &'static str {
match self {
Self::Any => "TRUE",
Self::Same => "a.type_id IS NOT NULL AND a.type_id = b.type_id",
Self::Conflict => {
"a.type_id IS NOT NULL AND b.type_id IS NOT NULL AND a.type_id <> b.type_id"
}
}
}
}
/// 全部待处理审核项(LLM 裁决中 + 等人工的都展示,人工可随时抢先定夺)。
pub async fn list_reviews(
pool: &PgPool,
kb_id: Uuid,
types: TypeFilter,
limit: i64,
offset: i64,
) -> AppResult<Vec<ReviewItem>> {
let sql = format!(
"SELECT rr.id, rr.left_id, rr.right_id, rr.score, rr.reason, rr.stage, rr.created_at
FROM resolution_reviews rr
JOIN entities a ON a.id = rr.left_id
JOIN entities b ON b.id = rr.right_id
WHERE rr.kb_id = $1 AND rr.status = 'pending' AND {}
ORDER BY rr.created_at DESC, rr.id DESC LIMIT $2 OFFSET $3",
types.clause()
);
let rows: Vec<ReviewRow> = sqlx::query_as(&sql)
.bind(kb_id)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await?;
assemble_reviews(pool, kb_id, rows).await
}
/// 批量裁决 = 逐条的人工裁决(#428):每一条走 `decide_review`,合并方向、状态、
/// decided_by 与单条一模一样。一条失败(不存在、已经裁过、并到一半出错)不拖累
/// 其余的,结果逐条带回;动作不认识整批拒绝——那不是某一条的问题。
pub async fn decide_reviews(
pool: &PgPool,
kb_id: Uuid,
ids: &[Uuid],
action: &str,
user_id: Uuid,
rationale: Option<&str>,
) -> AppResult<Vec<ReviewBatchOutcome>> {
if action != "merge" && action != "keep" {
return Err(AppError::Validation("action must be merge or keep".into()));
}
let mut out = Vec::with_capacity(ids.len());
for &id in ids {
let error = decide_review(pool, kb_id, id, action, user_id, rationale)
.await
.err()
.map(|e| e.to_string());
out.push(ReviewBatchOutcome { id, error });
}
Ok(out)
}
/// 等待 LLM 裁决的审核项(后台裁决任务消费)。
pub async fn pending_adjudications(
pool: &PgPool,
kb_id: Uuid,
limit: i64,
) -> AppResult<Vec<ReviewItem>> {
let rows: Vec<ReviewRow> = sqlx::query_as(
"SELECT id, left_id, right_id, score, reason, stage, created_at
FROM resolution_reviews
WHERE kb_id = $1 AND status = 'pending' AND stage = 'adjudicating'
ORDER BY created_at LIMIT $2",
)
.bind(kb_id)
.bind(limit)
.fetch_all(pool)
.await?;
assemble_reviews(pool, kb_id, rows).await
}
/// LLM 不确定 / 未配模型 → 转人工。
/// `reason` 存的是 **code**,可选地跟 `|detail`——不是给人看的句子。
///
/// 界面语言在客户端(见 docs/decisions/0004),服务端没有 locale 可用来措辞;
/// 写进这一列的英文散文会永久留在中文界面上。措辞归 i18n,这里只留稳定的 code。
pub async fn escalate_review(pool: &PgPool, review_id: Uuid, reason: &str) -> AppResult<()> {
sqlx::query(
"UPDATE resolution_reviews SET stage = 'human', reason = $2
WHERE id = $1 AND status = 'pending'",
)
.bind(review_id)
.bind(reason)
.execute(pool)
.await?;
Ok(())
}
/// 自动定夺(LLM 高置信):merged / kept。合并动作本身由调用方先执行。
/// 回关上了几行:0 = 这一对已经不是 pending(人裁了,或另一条路先到),调用方别再记一条一样的裁决
pub async fn close_review_auto(
pool: &PgPool,
review_id: Uuid,
status: &str,
reason: &str,
) -> AppResult<u64> {
let res = sqlx::query(
"UPDATE resolution_reviews SET status = $2, reason = $3, decided_at = now()
WHERE id = $1 AND status = 'pending'",
)
.bind(review_id)
.bind(status)
.bind(reason)
.execute(pool)
.await?;
Ok(res.rows_affected())
}
/// 人工定夺。merge 方向:度数高(事实多)的一方作为存活目标,平局取更早创建的。
/// `rationale`:人拍板时写的那一句(0026)。**空着是允许的**——问的是「什么让你
/// 这么定」,不是一张必填的表;但只要写了,它就跟着这一行和台账一起留下,
/// 下一次裁决器和 agent 读先例时读到的就不只是结果。
pub async fn decide_review(
pool: &PgPool,
kb_id: Uuid,
review_id: Uuid,
action: &str,
user_id: Uuid,
rationale: Option<&str>,
) -> AppResult<()> {
let rationale = rationale.map(str::trim).filter(|s| !s.is_empty());
let row: Option<ReviewRow> = sqlx::query_as(
"SELECT id, left_id, right_id, score, reason, stage, created_at
FROM resolution_reviews WHERE id = $1 AND kb_id = $2 AND status = 'pending'",
)
.bind(review_id)
.bind(kb_id)
.fetch_optional(pool)
.await?;
let row = row.ok_or(AppError::NotFound)?;
// agent 正在裁的一对(0025):等它的建议,或者关掉开关
if crate::governance::locked_by_agent(pool, kb_id, review_id).await? {
return Err(AppError::Conflict(
"The agent is deciding this pair right now; wait for its proposal or turn governance off."
.into(),
));
}
match action {
"merge" => {
// 同名连锁(A-B 合了,B-C 还等着):B 已并进 A,这一对实际上是 A-C。
// 跟着 merged_into 走到活着的那个再合;两边走到同一个,就只剩把审核行关上
let (l, r) = (
survivor(pool, kb_id, row.left_id).await?,
survivor(pool, kb_id, row.right_id).await?,
);
if l != r {
let (target, source) = merge_direction(pool, l, r).await?;
// 合并日志的 reason 也记这一句:Review › Merges 那一列读的是它
merge_entities(
pool,
kb_id,
source,
target,
Some(user_id),
rationale.unwrap_or("review decision"),
)
.await?;
}
sqlx::query(
"UPDATE resolution_reviews
SET status = 'merged', decided_at = now(), decided_by = $2, rationale = $3
WHERE id = $1",
)
.bind(review_id)
.bind(user_id)
.bind(rationale)
.execute(pool)
.await?;
}
"keep" => {
sqlx::query(
"UPDATE resolution_reviews
SET status = 'kept', decided_at = now(), decided_by = $2, rationale = $3
WHERE id = $1",
)
.bind(review_id)
.bind(user_id)
.bind(rationale)
.execute(pool)
.await?;
}
_ => return Err(AppError::Validation("action must be merge or keep".into())),
}
Ok(())
}
/// 跟着 `merged_into` 走到还活着的那个实体。同簇连锁合并之后,一对里的一侧可能已经
/// 并进了别人;合并要合的是活着的那个,不是那条已经空了的行
pub async fn survivor(pool: &PgPool, kb_id: Uuid, mut id: Uuid) -> AppResult<Uuid> {
for _ in 0..16 {
let next: Option<Option<Uuid>> =
sqlx::query_scalar("SELECT merged_into FROM entities WHERE id = $1 AND kb_id = $2")
.bind(id)
.bind(kb_id)
.fetch_optional(pool)
.await?;
match next {
Some(Some(n)) => id = n,
Some(None) => return Ok(id),
None => return Err(AppError::NotFound),
}
}
Err(AppError::Conflict("merge chain too long".into()))
}
/// 合并方向:返回 (target 存活, source 被并)。
pub async fn merge_direction(pool: &PgPool, a: Uuid, b: Uuid) -> AppResult<(Uuid, Uuid)> {
// 事实索引以 kb_id 开头;先用标量子查询取库,让 OR 两侧都能按复合索引定位。
// PG16 上直接 JOIN 可能只按 kb_id 扫描整个库,再过滤 subject/object。
let (deg_a,): (i64,) = sqlx::query_as(
"SELECT count(*) FROM facts
WHERE kb_id = (SELECT kb_id FROM entities WHERE id = $1)
AND (subject_id = $1 OR object_id = $1) AND invalidated_at IS NULL",
)
.bind(a)
.fetch_one(pool)
.await?;
let (deg_b,): (i64,) = sqlx::query_as(
"SELECT count(*) FROM facts
WHERE kb_id = (SELECT kb_id FROM entities WHERE id = $1)
AND (subject_id = $1 OR object_id = $1) AND invalidated_at IS NULL",
)
.bind(b)
.fetch_one(pool)
.await?;
// uuidv7 时间有序:度数平局时更早创建的一方存活
Ok(if deg_a > deg_b || (deg_a == deg_b && a < b) {
(a, b)
} else {
(b, a)
})
}
// ---------------------------------------------------------------------------
// 合并 / 回滚
// ---------------------------------------------------------------------------
#[derive(Debug, sqlx::FromRow)]
struct EntityFull {
// None = 还没判出来(0009)
type_id: Option<Uuid>,
canonical_name: String,
profile_embedding: Option<Vector>,
profile_n: i32,
merged_into: Option<Uuid>,
}
async fn entity_full(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<EntityFull> {
sqlx::query_as(
"SELECT type_id, canonical_name, profile_embedding, profile_n, merged_into
FROM entities WHERE kb_id = $1 AND id = $2",
)
.bind(kb_id)
.bind(id)
.fetch_optional(pool)
.await?
.ok_or(AppError::NotFound)
}
/// 合并 source → target:事实改挂 target、互指事实与合并后的重复事实作废、
/// 画像加权合并、source 标记 merged_into。全程记日志可回滚。
///
/// **名字不用特判**(0041):source 的名字是它身上的 `known_as` 事实,跟别的事实一起
/// 搬到 target、记进 `moved_subject_facts`;同名的那条按重复事实作废。撤回合并时一起搬回去
pub async fn merge_entities(
pool: &PgPool,
kb_id: Uuid,
source_id: Uuid,
target_id: Uuid,
merged_by: Option<Uuid>,
reason: &str,
) -> AppResult<Uuid> {
if source_id == target_id {
return Err(AppError::invalid(
"self_merge",
"Cannot merge an entity into itself",
));
}
let source = entity_full(pool, kb_id, source_id).await?;
let target = entity_full(pool, kb_id, target_id).await?;
if source.merged_into.is_some() || target.merged_into.is_some() {
return Err(AppError::Conflict("Entity already merged".into()));
}
let mut tx = pool.begin().await?;
// 搬动会牵连的时间线先按固定顺序锁上,再改任何一行(撤回合并同一个顺序,见 temporal
// 模块头):不锁的话,合并与撤回、合并与落库对账会各拿一半行锁互相等
let moving: Vec<Uuid> = sqlx::query_scalar(
"SELECT id FROM facts WHERE kb_id = $1 AND (subject_id = $2 OR object_id = $2)",
)
.bind(kb_id)
.bind(source_id)
.fetch_all(&mut *tx)
.await?;
let timelines =
crate::temporal::timelines_of(&mut *tx, kb_id, &moving, Some((&[source_id], target_id)))
.await?;
crate::temporal::lock_timelines(&mut tx, kb_id, &timelines).await?;
// 互指事实(合并后变自环)→ 作废
let cross: Vec<(Uuid,)> = sqlx::query_as(
"UPDATE facts SET invalidated_at = now()
WHERE kb_id = $1 AND invalidated_at IS NULL
AND ((subject_id = $2 AND object_id = $3) OR (subject_id = $3 AND object_id = $2))
RETURNING id",
)
.bind(kb_id)
.bind(source_id)
.bind(target_id)
.fetch_all(&mut *tx)
.await?;
let mut invalidated: Vec<Uuid> = cross.into_iter().map(|(id,)| id).collect();
let moved_subject: Vec<Uuid> = sqlx::query_as::<_, (Uuid,)>(
"UPDATE facts SET subject_id = $2 WHERE kb_id = $3 AND subject_id = $1 RETURNING id",
)
.bind(source_id)
.bind(target_id)
.bind(kb_id)
.fetch_all(&mut *tx)
.await?
.into_iter()
.map(|(id,)| id)
.collect();
let moved_object: Vec<Uuid> = sqlx::query_as::<_, (Uuid,)>(
"UPDATE facts SET object_id = $2 WHERE kb_id = $3 AND object_id = $1 RETURNING id",
)
.bind(source_id)
.bind(target_id)
.bind(kb_id)
.fetch_all(&mut *tx)
.await?
.into_iter()
.map(|(id,)| id)
.collect();
// 合并后 SPO+valid_from 重复的 live 事实:留最早 recorded_at 的一条,其余作废。
// 没有谓词的行不参与:开放陈述的不同短语都带 NULL,不能因此当成同一句话。
//
// **宾语两侧都要分组。** 字面值事实的 object_id 全是 NULL,只按它分组就等于
// 把同主同谓下的**所有值**当成同一条断言:一次合并之后,
// (公司, 成立年份, 2015) 与 (公司, 注册资本, …) 之外,同谓词的多个值只活得下来
// 最早记的那一个,其余无声消失,且没有 supersedes 可查。
let dups: Vec<(Vec<Uuid>,)> = sqlx::query_as(
"SELECT array_agg(id ORDER BY recorded_at, id) FROM facts
WHERE kb_id = $1 AND invalidated_at IS NULL AND predicate_id IS NOT NULL
AND (subject_id = $2 OR object_id = $2)
GROUP BY subject_id, predicate_id, object_id, object_value, valid_from
HAVING count(*) > 1",
)
.bind(kb_id)
.bind(target_id)
.fetch_all(&mut *tx)
.await?;
let mut dup_ids = Vec::new();
for (ids,) in dups {
// 先给存活行接上来源,否则下一次物化可能作废它,再按原文重建,丢掉人的修正。
// 旧行的链接暂留:撤回合并还用得上;物化按它原有的规则清理失效链接。
sqlx::query(
"INSERT INTO typed_fact_sources (fact_id, statement_id)
SELECT $1, statement_id FROM typed_fact_sources WHERE fact_id = ANY($2)
ON CONFLICT DO NOTHING",
)
.bind(ids[0])
.bind(&ids[1..])
.execute(&mut *tx)
.await?;
dup_ids.extend_from_slice(&ids[1..]);
}
if !dup_ids.is_empty() {
sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = ANY($1)")
.bind(&dup_ids)
.execute(&mut *tx)
.await?;
invalidated.extend(dup_ids);
}
// 画像加权合并
let (profile, profile_n) = match (&target.profile_embedding, &source.profile_embedding) {
(Some(t), Some(s)) if t.as_slice().len() == s.as_slice().len() => {
let (nt, ns) = (
target.profile_n.max(1) as f32,
source.profile_n.max(1) as f32,
);
let merged: Vec<f32> = t
.as_slice()
.iter()
.zip(s.as_slice())
.map(|(a, b)| (a * nt + b * ns) / (nt + ns))
.collect();
(
Some(Vector::from(merged)),
target.profile_n + source.profile_n,
)
}
(Some(t), _) => (Some(t.clone()), target.profile_n),
(None, Some(s)) => (Some(s.clone()), source.profile_n),
(None, None) => (None, 0),
};
// 类型调和:**没有类型的一侧让位**。存活方还没判出来而被并方判出来了,
// 就把那个类型带过来;否则保留存活方的。
//
// 从前这里要先查库找出 concept 那行的 id 再跟两侧比对。「还没判出来」
// 现在是 `None`(0009),一个 `or` 就说完了,那次查询也省了
let new_type_id = target.type_id.or(source.type_id);
sqlx::query(
"UPDATE entities SET profile_embedding = $2, profile_n = $3,
type_id = $4, updated_at = now() WHERE id = $1",
)
.bind(target_id)
.bind(&profile)
.bind(profile_n)
.bind(new_type_id)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE entities SET merged_into = $2, updated_at = now() WHERE id = $1")
.bind(source_id)
.bind(target_id)
.execute(&mut *tx)
.await?;
// 其余涉及 source 的 pending 审核项:**改指到合并目标,不是关掉**。
//
// 这里原本一律关掉,理由写的是"疑点若仍在会由后续 mention 重新提起"。
// **那句是错的**:包含关系召回只在**新建实体时**跑一次,而这些实体早就存在了,
// 不会再被新建,也就没有"后续 mention"来重提。关掉就是永远关掉。
//
// 实测:`Mr. Holmes` 跟 `Holmes` 配对入队(0.70),随后 `Holmes` 并入
// `Sherlock Holmes`,这一对被关成 superseded by merge——而
// `Mr. Holmes` vs `Sherlock Holmes` 这个仍然成立的问题,再没人问过。
//
// 先关掉两类真正过时的:重定向后会变成自环的,和目标对已经在队列里的。
sqlx::query(
"UPDATE resolution_reviews AS r
SET status = 'kept', reason = 'superseded by merge', decided_at = now()
WHERE r.kb_id = $1 AND r.status = 'pending'
AND (r.left_id = $2 OR r.right_id = $2)
AND NOT (least(r.left_id, r.right_id) = least($2, $3)
AND greatest(r.left_id, r.right_id) = greatest($2, $3))
AND (
(CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END) = $3
OR EXISTS (
SELECT 1 FROM resolution_reviews d
WHERE d.kb_id = $1 AND d.status = 'pending' AND d.id <> r.id
AND least(d.left_id, d.right_id)
= least($3, CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END)
AND greatest(d.left_id, d.right_id)
= greatest($3, CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END))
)",
)
.bind(kb_id)
.bind(source_id)
.bind(target_id)
.execute(&mut *tx)
.await?;
// 剩下的改指到目标,问题继续挂在队列上等裁决。
// (source, target) 这一对本身除外——它正是本次合并的裁决对象,由调用方标记 merged,
// 在这里动它会让它在历史里错误地显示为"保持分开"
sqlx::query(
"UPDATE resolution_reviews
SET left_id = CASE WHEN left_id = $2 THEN $3 ELSE left_id END,
right_id = CASE WHEN right_id = $2 THEN $3 ELSE right_id END,
reason = reason || '|redirected'
WHERE kb_id = $1 AND status = 'pending' AND (left_id = $2 OR right_id = $2)
AND NOT (least(left_id, right_id) = least($2, $3)
AND greatest(left_id, right_id) = greatest($2, $3))",
)
.bind(kb_id)
.bind(source_id)
.bind(target_id)
.execute(&mut *tx)
.await?;
let merge_id = Uuid::now_v7();
sqlx::query(
"INSERT INTO entity_merges (id, kb_id, source_id, target_id,
moved_subject_facts, moved_object_facts, invalidated_facts,
target_profile_before, target_profile_n_before, target_type_before,
merged_by, reason)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)",
)
.bind(merge_id)
.bind(kb_id)
.bind(source_id)
.bind(target_id)
.bind(&moved_subject)
.bind(&moved_object)
.bind(&invalidated)
.bind(&target.profile_embedding)
.bind(target.profile_n)
.bind(target.type_id)
.bind(merged_by)
.bind(reason)
.execute(&mut *tx)
.await?;
tx.commit().await?;
// 搬移后的时态对账:换了主/宾的事实等价于新观察落库——两个对象折成一个后,
// 唯一性不变量才第一次看得到旧开放区间与继任者相撞(如"星尘"并入"星尘项目",
// 旧负责人的 leads 应在新任起点闭合)。
// 修正行 id 记入合并账本,供审计。回滚不靠它:回滚按搬走之后剩下的行重算时间线,
// 这些引擎画的终点自然跟着变(0057)。
// 注:本步在事务外,失败有自愈性——这条时间线下一次有事实落库时整条重算。
let moved_all: Vec<Uuid> = moved_subject
.iter()
.chain(moved_object.iter())
.copied()
.collect();
// **合并是第三条改写事实的路**(#196):换掉主语或宾语,就可能把一条合法事实
// 变成签名违规——抽取写入时掰正过的方向,合并一次就能再反回去。这里不掰、不改,
// 只报:对搬动过的事实查一遍 domain / range,违反的进 `axiom_violations`
//(kind = signature),与其它公理违规同一个队列、同样三个出路。
// 放在事务之后:目标实体的类型在事务里刚调和过,提交了才看得见
match crate::reasoning::signature_breaks(&mut *pool.acquire().await?, kb_id, Some(&moved_all))
.await
{
Ok(broken) if !broken.is_empty() => {
if let Err(e) = crate::reasoning::record_signature_breaks(pool, kb_id, &broken).await {
tracing::warn!(%kb_id, error = %e, "合并后的签名违规没能入库");
}
}
Ok(_) => {}
Err(e) => tracing::warn!(%kb_id, error = %e, "合并后的签名检查失败"),
}
let report = crate::temporal::reconcile_moved_facts(pool, kb_id, &moved_all).await?;
if !report.corrected.is_empty() {
sqlx::query("UPDATE entity_merges SET temporal_corrections = $2 WHERE id = $1")
.bind(merge_id)
.bind(&report.corrected)
.execute(pool)
.await?;
}
refresh_disambiguators(pool, kb_id, &source.canonical_name).await?;
if !source
.canonical_name
.eq_ignore_ascii_case(&target.canonical_name)
{
refresh_disambiguators(pool, kb_id, &target.canonical_name).await?;
}
Ok(merge_id)
}
#[derive(Debug, sqlx::FromRow)]
struct MergeRow {
source_id: Uuid,
target_id: Uuid,
moved_subject_facts: Vec<Uuid>,
moved_object_facts: Vec<Uuid>,
invalidated_facts: Vec<Uuid>,
target_profile_before: Option<Vector>,
target_profile_n_before: i32,
target_type_before: Option<Uuid>,
reverted_at: Option<DateTime<Utc>>,
}
/// 搬过的事实,连同从它们改写出来的每一行(顺着 supersedes 往下走到底,作废的也算)
async fn with_rewrites(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
roots: &[Uuid],
) -> AppResult<Vec<Uuid>> {
Ok(sqlx::query_scalar(
"WITH RECURSIVE chain(id) AS (
SELECT unnest($1::uuid[])
UNION
SELECT f.id FROM facts f JOIN chain c ON f.supersedes = c.id
)
SELECT id FROM chain",
)
.bind(roots)
.fetch_all(&mut **tx)
.await?)
}
/// 精确回滚一次合并:事实原路搬回、作废撤销、target 画像与类型恢复快照、source 复活。
///
/// **搬回去的是搬过来的事实连同从它们改写出来的每一行。** 合并之后引擎把它关上过、人改过
/// 它的区间、人驳回过它——那些行都是它的,跟着回源实体,各自保持原样:人改的区间还在,
/// 驳回的仍是驳回的。合并当时引擎做的闭合不单独撤:两边的时间线在搬完之后按剩下的行重算,
/// 边界随搬走的行走了,关在那里的行自然重新打开,写明的终点不动(0057)。
///
/// 怎么搬分两种,为的是记录轴回放合并窗口时仍答得对(0027 的 `fact_owner_at` 只认账本):
/// 账本上的行原地改回主语/宾语;合并之后才改写出来的行不在账本上,活着的作废、在源实体上
/// 另起一行接着它,作废了的留在目标实体上——它们在那段窗口里确实挂在那里
///
/// 搬动之前先按固定顺序拿下两边所有牵连时间线的锁(见 temporal 模块头):落库对账先拿锁
/// 再锁行,这里要是先改行再拿锁,两边会互相等死
pub async fn revert_merge(pool: &PgPool, kb_id: Uuid, merge_id: Uuid) -> AppResult<()> {
let m: MergeRow = sqlx::query_as(
"SELECT source_id, target_id, moved_subject_facts, moved_object_facts,
invalidated_facts, target_profile_before,
target_profile_n_before, target_type_before, reverted_at
FROM entity_merges WHERE id = $1 AND kb_id = $2",
)
.bind(merge_id)
.bind(kb_id)
.fetch_optional(pool)
.await?
.ok_or(AppError::NotFound)?;
if m.reverted_at.is_some() {
return Err(AppError::Conflict("Merge already reverted".into()));
}
let mut tx = pool.begin().await?;
// 事实此刻挂在谁身上:目标实体,或者目标后来又并进去的实体(S 并进 T、T 再并进 C,
// 撤回 S→T 时 S 的事实在 C 身上)。只认目标的话,连环合并里撤回头一环,源实体
// 复活了、它的事实却留在链尾(#679 第四轮评审)
let holders: Vec<Uuid> = sqlx::query_scalar(
"WITH RECURSIVE chain(id) AS (
SELECT $1::uuid
UNION SELECT e.merged_into FROM entities e JOIN chain ON e.id = chain.id
WHERE e.merged_into IS NOT NULL)
SELECT id FROM chain",
)
.bind(m.target_id)
.fetch_all(&mut *tx)
.await?;
let touched: Vec<Uuid> = with_rewrites(&mut tx, &m.moved_subject_facts)
.await?
.into_iter()
.chain(with_rewrites(&mut tx, &m.moved_object_facts).await?)
.chain(m.invalidated_facts.iter().copied())
.collect();
let timelines =
crate::temporal::timelines_of(&mut *tx, kb_id, &touched, Some((&holders, m.source_id)))
.await?;
crate::temporal::lock_timelines(&mut tx, kb_id, &timelines).await?;
// 锁上之后再走一遍:等锁的时候,引擎可能刚从它们改写出新的一行
let subject_rows = with_rewrites(&mut tx, &m.moved_subject_facts).await?;
let object_rows = with_rewrites(&mut tx, &m.moved_object_facts).await?;
sqlx::query("UPDATE facts SET subject_id = $1 WHERE id = ANY($2) AND subject_id = ANY($3)")
.bind(m.source_id)
.bind(&m.moved_subject_facts)
.bind(&holders)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE facts SET object_id = $1 WHERE id = ANY($2) AND object_id = ANY($3)")
.bind(m.source_id)
.bind(&m.moved_object_facts)
.bind(&holders)
.execute(&mut *tx)
.await?;
for (rows, ledger, on_object) in [
(&subject_rows, &m.moved_subject_facts, false),
(&object_rows, &m.moved_object_facts, true),
] {
let holder = if on_object { "object_id" } else { "subject_id" };
let live: Vec<Uuid> = sqlx::query_scalar(&format!(
"SELECT id FROM facts
WHERE id = ANY($1) AND id <> ALL($2) AND invalidated_at IS NULL AND {holder} = ANY($3)"
))
.bind(rows)
.bind(ledger)
.bind(&holders)
.fetch_all(&mut *tx)
.await?;
for id in live {
let (subject, object) = if on_object {
(None, Some(m.source_id))
} else {
(Some(m.source_id), None)
};
crate::temporal::rehome_tx(&mut tx, id, subject, object).await?;
}
}
sqlx::query("UPDATE facts SET invalidated_at = NULL WHERE id = ANY($1)")
.bind(&m.invalidated_facts)
.execute(&mut *tx)
.await?;
crate::temporal::tidy_timelines_tx(&mut tx, kb_id, &timelines).await?;
let source = entity_full(pool, kb_id, m.source_id).await?;
// source 的名字是它的名字事实,已经跟着 moved_subject_facts 搬回去了
sqlx::query(
"UPDATE entities SET
profile_embedding = $2, profile_n = $3,
type_id = coalesce($4, type_id), updated_at = now()
WHERE id = $1",
)
.bind(m.target_id)
.bind(&m.target_profile_before)
.bind(m.target_profile_n_before)
.bind(m.target_type_before)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE entities SET merged_into = NULL, updated_at = now() WHERE id = $1")
.bind(m.source_id)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE entity_merges SET reverted_at = now() WHERE id = $1")
.bind(merge_id)
.execute(&mut *tx)
.await?;
tx.commit().await?;
refresh_disambiguators(pool, kb_id, &source.canonical_name).await?;
Ok(())
}
/// 合并日志(审核页历史区)。
pub async fn list_merges(
pool: &PgPool,
kb_id: Uuid,
limit: i64,
offset: i64,
) -> AppResult<Vec<MergeLogView>> {
let rows: Vec<MergeLogView> = sqlx::query_as(
"SELECT m.id, s.canonical_name AS source_name, t.canonical_name AS target_name,
u.display_name AS merged_by_name, m.reason, m.created_at, m.reverted_at
FROM entity_merges m
JOIN entities s ON s.id = m.source_id
JOIN entities t ON t.id = m.target_id
LEFT JOIN users u ON u.id = m.merged_by
WHERE m.kb_id = $1
ORDER BY m.created_at DESC, m.id DESC LIMIT $2 OFFSET $3",
)
.bind(kb_id)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await?;
Ok(rows)
}
// ---------------------------------------------------------------------------
// LLM 裁决缓存
// ---------------------------------------------------------------------------
pub async fn get_verdict(
pool: &PgPool,
kb_id: Uuid,
pair_key: &str,
) -> AppResult<Option<(Option<bool>, f32)>> {
let row: Option<(Option<bool>, f32)> = sqlx::query_as(
"SELECT same, confidence FROM resolution_verdicts WHERE kb_id = $1 AND pair_key = $2",
)
.bind(kb_id)
.bind(pair_key)
.fetch_optional(pool)
.await?;
Ok(row)
}
pub async fn put_verdict(
pool: &PgPool,
kb_id: Uuid,
pair_key: &str,
same: Option<bool>,
confidence: f32,
model: &str,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO resolution_verdicts (kb_id, pair_key, same, confidence, model)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (kb_id, pair_key)
DO UPDATE SET same = $3, confidence = $4, model = $5, created_at = now()",
)
.bind(kb_id)
.bind(pair_key)
.bind(same)
.bind(confidence)
.bind(model)
.execute(pool)
.await?;
Ok(())
}
/// 撤销一次实体改类:把它们放回原来的类型。
///
/// 类型本身不删——与谓词那边同一条理由:有实体指向过它,而"它存在过"是历史。
/// `proposed_type` 也一并恢复,否则撤销之后那些实体就再也认领不回来了。
pub async fn unadopt_types(pool: &PgPool, kb_id: Uuid, batch_id: Uuid) -> AppResult<u32> {
// from_type_id 可能是 NULL:0009 之后最常见的一次改类正是"从没有类到有类",
// 撤销就是把它推回没有类。解成 Uuid 会在这里当场崩
let rows: Vec<(Uuid, Option<Uuid>, String)> = sqlx::query_as(
"SELECT r.entity_id, r.from_type_id, t.key
FROM entity_retypes r JOIN entity_types t ON t.id = r.to_type_id
WHERE r.batch_id = $1 AND r.kb_id = $2 AND r.reverted_at IS NULL",
)
.bind(batch_id)
.bind(kb_id)
.fetch_all(pool)
.await?;
if rows.is_empty() {
return Err(AppError::NotFound);
}
let mut names: Vec<String> = Vec::new();
let mut tx = pool.begin().await?;
let mut reverted = 0u32;
for (entity_id, from_type, adopted_key) in &rows {
let row: Option<(String,)> = sqlx::query_as(
"UPDATE entities SET type_id = $2, proposed_type = $3, updated_at = now()
WHERE id = $1 RETURNING canonical_name",
)
.bind(entity_id)
.bind(from_type)
.bind(adopted_key)
.fetch_optional(&mut *tx)
.await?;
if let Some((name,)) = row {
names.push(name);
}
reverted += 1;
}
sqlx::query(
"UPDATE entity_retypes SET reverted_at = now()
WHERE batch_id = $1 AND kb_id = $2 AND reverted_at IS NULL",
)
.bind(batch_id)
.bind(kb_id)
.execute(&mut *tx)
.await?;
tx.commit().await?;
for n in &names {
refresh_disambiguators(pool, kb_id, n).await?;
}
Ok(reverted)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn like_escaped_turns_backslash_percent_and_underscore_into_literals() {
assert_eq!(like_escaped(r"a\b%c_d"), r"a\\b\%c\_d");
}
#[test]
fn normalize_fullwidth_and_whitespace() {
assert_eq!(normalize_name(" ACME Corp "), "ACME Corp");
assert_eq!(normalize_name("张三"), "张三");
assert_eq!(normalize_name("张 三"), "张 三");
}
#[test]
fn markdown_folding_is_conservative() {
for (raw, expected) in [
("**Pump 1**", "Pump 1"),
("__Pump 1__", "Pump 1"),
("__init__", "__init__"),
("`docs/setup.md`", "docs/setup.md"),
("`setup.md`", "setup.md"),
("`acme`", "`acme`"),
("`main()`", "`main()`"),
("`1.2`", "`1.2`"),
("**Pump 1*", "**Pump 1*"),
("***Pump 1***", "***Pump 1***"),
("** Pump 1 **", "** Pump 1 **"),
("****", "****"),
] {
assert_eq!(fold_markdown_markers(raw), expected, "{raw:?}");
}
}
#[test]
fn recall_keys_fold_markdown_before_stemming_and_keep_exact_spelling() {
let normalized = normalize_name(" **Phoenix Project** ");
let keys = recall_keys(&normalized);
assert_eq!(keys[0], name_key(&normalized));
for key in recall_keys("Phoenix Project") {
assert!(keys.contains(&key), "must recall {key:?}");
}
assert!(keys.contains(&"**phoenix project**".to_string()));
assert!(keys.len() <= 11);
}
#[test]
fn stem_generic_suffixes() {
assert_eq!(name_stem("星尘项目").as_deref(), Some("星尘"));
assert_eq!(name_stem("星辰科技公司").as_deref(), Some("星辰科技"));
assert_eq!(name_stem("Phoenix Project").as_deref(), Some("phoenix"));
assert_eq!(name_stem("Project Phoenix").as_deref(), Some("phoenix"));
assert_eq!(name_stem("Acme Inc.").as_deref(), Some("acme"));
assert_eq!(name_stem("星尘"), None);
assert_eq!(name_stem("项目"), None); // 剥空不算词干
assert_eq!(name_stem("项目团队"), None); // 词干本身是泛用词
assert_eq!(name_stem("Team Project"), None);
}
#[test]
fn recall_keys_bidirectional() {
// 无后缀 mention 能召回带后缀实体(增广),反之靠词干
let k = recall_keys("星尘");
assert!(k.contains(&"星尘".to_string()));
assert!(k.contains(&"星尘项目".to_string()));
let k = recall_keys("星尘项目");
assert!(k.contains(&"星尘项目".to_string()));
assert!(k.contains(&"星尘".to_string()));
let k = recall_keys("Phoenix");
assert!(k.contains(&"phoenix project".to_string()));
assert!(k.contains(&"project phoenix".to_string()));
let k = recall_keys("Project Phoenix");
assert!(k.contains(&"phoenix".to_string()));
assert!(recall_keys("张三").len() <= 10);
}
#[test]
fn type_drift_classes() {
// 还没判出类型的那一侧 → 召回候选。0009 之前这一档比的是 `concept`
// 这个 key,现在比的是"有没有类"本身
assert_eq!(
classify_type_drift(None, Some("organization")),
TypeDrift::Recall
);
assert_eq!(
classify_type_drift(Some("project"), None),
TypeDrift::Recall
);
// 两边都还没判出来:也归召回,由画像相似度说话
assert_eq!(classify_type_drift(None, None), TypeDrift::Recall);
// 易混具体类型两两 → 审核对
assert_eq!(
classify_type_drift(Some("organization"), Some("project")),
TypeDrift::Review
);
assert_eq!(
classify_type_drift(Some("project"), Some("product")),
TypeDrift::Review
);
assert_eq!(
classify_type_drift(Some("product"), Some("organization")),
TypeDrift::Review
);
// 硬互斥与未知自定义类型 → 完全分开
assert_eq!(
classify_type_drift(Some("person"), Some("organization")),
TypeDrift::Disjoint
);
assert_eq!(
classify_type_drift(Some("person"), Some("project")),
TypeDrift::Disjoint
);
assert_eq!(
classify_type_drift(Some("event"), Some("location")),
TypeDrift::Disjoint
);
assert_eq!(
classify_type_drift(Some("team"), Some("organization")),
TypeDrift::Disjoint
);
}
#[test]
fn cosine_basics() {
assert!((cosine(&[1.0, 0.0], &[1.0, 0.0]).unwrap() - 1.0).abs() < 1e-6);
assert!(cosine(&[1.0, 0.0], &[0.0, 1.0]).unwrap().abs() < 1e-6);
assert!(cosine(&[1.0], &[1.0, 2.0]).is_none());
assert!(cosine(&[0.0, 0.0], &[1.0, 1.0]).is_none());
}
}
/// 一个等着精化类型的实体,连同用来判断它是什么的全部材料。
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct TypeCandidateSubject {
pub id: Uuid,
pub canonical_name: String,
/// 本名以外的名字(名字事实,0041)。给模型看:「海探1」一个人判不出是什么,
/// 连着「海洋探测器1号」就判得出
pub other_names: Vec<String>,
/// 现在挂着的类,**可能没有**(0009:没判出来就是 NULL)。名字里的"粗"
/// 是历史——抽取现在也可能直接给一个细类,而且可能给错(实测
/// `绍兴 → address`),所以这里也可能是要被**纠正**的那个
pub coarse_key: Option<String>,
pub coarse_id: Option<Uuid>,
/// 现类的描述。裁决要判"现在这个类对不对",光看 key 不够——
/// 导入本体的 key 常常自解释不了(`entry_point` 是什么?)
pub coarse_description: Option<String>,
/// 抽取时模型自己报的类型名,**词表里没有**才会留在这儿
pub proposed_type: Option<String>,
/// 模型对它自己的说法,每个实体都有。
///
/// 这是最强的信号,因为它把任务从"读懂这是什么"换回"本体里哪个类叫这个"
/// ——短名字对短标签。实测的失败正出在另一头:拿一段中文画像去匹配
/// schema.org 的 "A software application.",两边形状根本不对等
pub specific_type: Option<String>,
/// 它参与的谓词,连着对方的名字(`produces 深蓝`、`leads by 张伟`)。
/// **跨文档累积**,这正是抽取当场没有的东西
pub roles: Vec<String>,
/// 证据引文,最多几句。抽取看的是同一批句子,但那一次要同时做实体识别、
/// 关系判断、时态解析、JSON 格式化,还要跟几十个别的实体抢注意力
/// 证据引文,**只取它当主语的那些**。宾语位的引文讲的是主语:
/// 「上海浦东新区」是 located_in 的宾语,引文却是"星云科技(上海)
/// 有限公司是一家注册于上海浦东新区的股份有限公司",整句重心在
/// "股份有限公司"上——实测那一版检索给出的候选全是 corporation 一类
pub quotes: Vec<String>,
pub fact_count: i64,
}
/// 值得送去精化类型的实体:**还没有类的**,或者模型报过一个词表外类型的。
///
/// 类型化得已经很具体的实体不动——重判一次只有下降风险,没有上升空间。
///
/// `unattended` = 自动跑(0016 C2):**跳过引擎已经看过的**(`type_resolved_at`)。候选按
/// 事实数排序、一轮六十个,不跳过的话每一轮都是同一批,后面的永远轮不到。人点的那条
/// 路传 false——人要的是把现状重新审一遍
pub async fn entities_for_type_resolution(
pool: &PgPool,
kb_id: Uuid,
limit: i64,
unattended: bool,
) -> AppResult<Vec<TypeCandidateSubject>> {
Ok(sqlx::query_as(
"SELECT e.id, e.canonical_name,
ARRAY(SELECT DISTINCT nf.object_value->>'value' FROM facts nf
JOIN relation_types nr ON nr.id = nf.predicate_id
WHERE nf.subject_id = e.id AND nr.builtin AND nr.key = 'known_as'
AND nf.invalidated_at IS NULL
AND lower(nf.object_value->>'value') <> lower(e.canonical_name)) AS other_names,
t.key AS coarse_key, t.id AS coarse_id,
t.description AS coarse_description,
e.proposed_type, e.specific_type,
-- 对方写**名字**,不写它的类型 key。
-- 写 key 是自毁:查询里出现 organization / product / event 这些词,
-- 而检索的目标正是这些类自己,于是候选就是画像里那几个词。
-- 实测「张伟」的画像是 leads→organization … works_at→organization,
-- 回来的候选是 corporation、organization、business_entity_type——
-- 检索到的是画像自己,不是这个人是什么
ARRAY(
SELECT DISTINCT COALESCE(rt.key, fact_surface_predicate(f.id))
|| CASE WHEN f.subject_id = e.id THEN ' ' ELSE ' by ' END
|| coalesce(oe.canonical_name, 'a value')
FROM facts f
LEFT JOIN relation_types rt ON rt.id = f.predicate_id
LEFT JOIN entities oe ON oe.id = CASE WHEN f.subject_id = e.id
THEN f.object_id ELSE f.subject_id END
WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
AND (f.subject_id = e.id OR f.object_id = e.id)
AND COALESCE(rt.key, fact_surface_predicate(f.id)) IS NOT NULL
-- 名字不是它扮演的角色,每个实体都有,判不出类型(0041)
AND NOT coalesce(rt.builtin AND rt.key = 'known_as', false)
LIMIT 12
) AS roles,
ARRAY(
SELECT DISTINCT ev.quote FROM fact_evidence ev
JOIN facts f2 ON f2.id = ev.fact_id
LEFT JOIN relation_types rt2 ON rt2.id = f2.predicate_id
WHERE f2.kb_id = $1 AND f2.invalidated_at IS NULL
AND f2.subject_id = e.id
AND ev.quote IS NOT NULL
AND NOT coalesce(rt2.builtin AND rt2.key = 'known_as', false)
LIMIT 3
) AS quotes,
(SELECT count(*) FROM facts f3
LEFT JOIN relation_types rt3 ON rt3.id = f3.predicate_id
WHERE f3.kb_id = $1 AND f3.invalidated_at IS NULL
AND (f3.subject_id = e.id OR f3.object_id = e.id)
AND NOT coalesce(rt3.builtin AND rt3.key = 'known_as', false)) AS fact_count
FROM entities e
LEFT JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.merged_into IS NULL
-- **人拍过板的不再重判。**
--
-- 少了这一行,下面第三种条件会把它们全都捞回来:一个人工定成
-- organization 的实体,只要 organization 有子类就够格,于是引擎
-- 每一轮都去重新裁决一遍人已经决定过的事,而账本事后才看得出是谁改的。
--
-- 「不落库」不等于「不许说话」:引擎若认为人定错了,该走 Review 队列,
-- 而不是直接改掉。憋着不说和直接改掉都是失真,只是方向相反
AND e.type_source <> 'human'
-- 值得看的三种:**还没有类的**、模型报过词表外类型的、
-- **以及现类本身还有子类的**。第三种是主力:抽取只认基类之后,
-- organization 下面挂着一大批更具体的类,那才是导进来的本体
-- 唯一的用武之地。只看前两种就把它整个漏掉了
AND (e.type_id IS NULL OR e.proposed_type IS NOT NULL OR e.specific_type IS NOT NULL
OR EXISTS (SELECT 1 FROM entity_type_parents p WHERE p.parent_id = t.id))
AND (NOT $3::bool OR e.type_resolved_at IS NULL)
ORDER BY fact_count DESC, e.created_at
LIMIT $2",
)
.bind(kb_id)
.bind(limit)
.bind(unattended)
.fetch_all(pool)
.await?)
}
/// 引擎看过了:三档(改了 / 留给人 / 不动)都算看过,自动跑不再回头。
/// 人手工改类、合并之类的写路径不清这个标记——它们本来也不在自动跑的候选里
pub async fn mark_type_judged(pool: &PgPool, kb_id: Uuid, ids: &[Uuid]) -> AppResult<u64> {
Ok(sqlx::query(
"UPDATE entities SET type_resolved_at = now() WHERE kb_id = $1 AND id = ANY($2)",
)
.bind(kb_id)
.bind(ids)
.execute(pool)
.await?
.rows_affected())
}
/// 某个类的全部后代(含自身)。精化只能往粗类的后代走。
///
/// **递归而不是一层**:本体是 DAG,`software_application ⊂ creative_work ⊂ thing`,
/// 只查一层就把绝大多数正确答案挡在门外了。
pub async fn descendants_of(pool: &PgPool, kb_id: Uuid, root: Uuid) -> AppResult<Vec<Uuid>> {
let rows: Vec<(Uuid,)> = sqlx::query_as(
"WITH RECURSIVE d(id) AS (
SELECT $2::uuid
UNION
SELECT p.child_id FROM entity_type_parents p JOIN d ON d.id = p.parent_id
)
SELECT d.id FROM d JOIN entity_types t ON t.id = d.id WHERE t.kb_id = $1",
)
.bind(kb_id)
.bind(root)
.fetch_all(pool)
.await?;
Ok(rows.into_iter().map(|(id,)| id).collect())
}
/// 记下模型对这个实体自己的说法。
///
/// **后写者不覆盖先写者**(`IS NULL` 才写),与 `set_proposed_type` 同一条:
/// 同一个实体会被多个分块提到,第一次的说法通常出自最完整的那句话,
/// 后面的分块往往只是顺带一提。
pub async fn set_specific_type(pool: &PgPool, entity_id: Uuid, value: &str) -> AppResult<()> {
sqlx::query(
"UPDATE entities SET specific_type = left($2, 80)
WHERE id = $1 AND specific_type IS NULL",
)
.bind(entity_id)
.bind(value)
.execute(pool)
.await?;
Ok(())
}
/// 跟这个实体最像的**已定类**实体,连同它们的类。
///
/// 类型消解的第二个候选来源。第一个是拿画像去搜类的描述,它的软肋实测很清楚:
/// 中文画像对 schema.org 的 "A software application.",两边形状根本不对等。
/// 这一条绕开了那道坎——**名字对名字、同语言**,而且库越大越准:
/// 「深蓝向量数据库」像「Milvus」,而 Milvus 已经标成 software_application。
///
/// 比的是双方的 `profile_embedding`(出现语境的滑动平均),**同一种向量对同一种
/// 向量**,不是拿文本画像去比语境向量。代价是零——这个向量实体消解本来就在维护。
///
/// 已知弱点:只出现在一篇文档里的实体,语境向量就是那一块的向量,同文档的实体
/// 会互相成为近邻。调用方要看得到 `same_document`,别把它当成类型证据。
/// 一批之内 [`descendants_of`] 的记忆(#514)。
///
/// 粗类来自抽取的小词表(person、organization、product 加几个),六十个主语里
/// 同一个 `coarse_id` 反复出现,同一个递归 CTE 就反复发。批内本体不动,同一输入
/// 同一结果,记住不改答案。**没有粗类的主语不进这张表**:它没有「后代」这个轴
/// (0009),整张类表都是候选;用 `Option` 当键会把它和某个真实的类混在一起
#[derive(Default)]
pub struct DescendantsMemo {
sets: std::collections::HashMap<Uuid, HashSet<Uuid>>,
}
impl DescendantsMemo {
pub async fn get(
&mut self,
pool: &PgPool,
kb_id: Uuid,
root: Option<Uuid>,
) -> AppResult<HashSet<Uuid>> {
let Some(root) = root else {
return Ok(HashSet::new());
};
if let Some(set) = self.sets.get(&root) {
return Ok(set.clone());
}
let set: HashSet<Uuid> = descendants_of(pool, kb_id, root)
.await?
.into_iter()
.collect();
self.sets.insert(root, set.clone());
Ok(set)
}
/// 记住了几个根
pub fn len(&self) -> usize {
self.sets.len()
}
pub fn is_empty(&self) -> bool {
self.sets.is_empty()
}
}
/// 一个主语的近邻:语境相似的已定类实体,连同「是否同一篇文档」。
///
/// 主语自己的向量先取出来再查:维度要写进 SQL(`vector_index` 规矩 1),SQL 里的
/// 子查询给不了这个数。没有向量的主语没有近邻,回空
pub async fn nearest_typed_entities(
pool: &PgPool,
kb_id: Uuid,
entity_id: Uuid,
limit: i64,
) -> AppResult<Vec<(String, Uuid, String, f64, bool)>> {
let me: Option<(Option<Vector>,)> =
sqlx::query_as("SELECT profile_embedding FROM entities WHERE id = $2 AND kb_id = $1")
.bind(kb_id)
.bind(entity_id)
.fetch_optional(pool)
.await?;
let Some(query_vec) = me.and_then(|(v,)| v) else {
return Ok(Vec::new());
};
let dims = query_vec.as_slice().len();
let mut tx = pool.begin().await?;
crate::vector_index::relaxed_order(pool, &mut tx).await?;
let rows = sqlx::query_as(&format!(
"WITH my_docs AS (
SELECT DISTINCT ev.document_id FROM fact_evidence ev
JOIN facts f ON f.id = ev.fact_id
WHERE f.kb_id = $1 AND (f.subject_id = $2 OR f.object_id = $2)
),
nearest AS MATERIALIZED (
SELECT e.id, e.canonical_name, t.id AS type_id, t.key,
({distance})::float8 AS distance,
EXISTS (SELECT 1 FROM fact_evidence ev2
JOIN facts f2 ON f2.id = ev2.fact_id
WHERE f2.kb_id = $1 AND (f2.subject_id = e.id OR f2.object_id = e.id)
AND ev2.document_id IN (SELECT document_id FROM my_docs))
AS same_document
-- 内连接就是那道门:没判出类型的实体(type_id IS NULL)不是答案,
-- 拿它当邻居的证据只会把「没判出来」传染开
FROM entities e
JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.merged_into IS NULL AND e.id <> $2
AND e.profile_embedding IS NOT NULL AND {same_dims}
ORDER BY {distance}
LIMIT $4
)
-- 次序在外层再排一遍,并列由实体 id 定(`vector_index::RESORT`,#652)
SELECT canonical_name, type_id, key, distance, same_document
FROM nearest ORDER BY {resort}",
distance = crate::vector_index::distance("e.profile_embedding", 3, dims),
resort = crate::vector_index::RESORT,
same_dims = crate::vector_index::same_dims("e.profile_embedding", dims),
))
.bind(kb_id)
.bind(entity_id)
.bind(&query_vec)
.bind(limit)
.fetch_all(&mut *tx)
.await?;
tx.commit().await?;
Ok(rows)
}
/// 同时跑几个近邻查询。池是 32、按「同时跑的短查询」定的(`db.rs`);六十个
/// 全表扫一起上就是那里记的池子被吃空的样子——慢请求和超时,没有一句话说池小了。
/// 八个留足了给请求的余量,而 HNSW 就位之后每个查询只有几毫秒,再高也没意义
pub const NEIGHBOUR_SCANS: usize = 8;
/// 一批主语各自的近邻,**按送进来的顺序回**:下游裁决按这个顺序读。
///
/// 六十个查询彼此无关,串行只因为循环是串行的(#514)。这里有界并发地取,
/// `buffered` 保序,推理仍在原顺序上做
pub async fn nearest_typed_for_each(
pool: &PgPool,
kb_id: Uuid,
ids: &[Uuid],
limit: i64,
) -> AppResult<Vec<Vec<(String, Uuid, String, f64, bool)>>> {
nearest_typed_for_each_with(pool, kb_id, ids, limit, NEIGHBOUR_SCANS).await
}
/// 同上,并发上限由调用方给(测试用它证明上限不改答案)
pub async fn nearest_typed_for_each_with(
pool: &PgPool,
kb_id: Uuid,
ids: &[Uuid],
limit: i64,
at_once: usize,
) -> AppResult<Vec<Vec<(String, Uuid, String, f64, bool)>>> {
use futures_util::{stream, StreamExt, TryStreamExt};
stream::iter(ids.iter().copied())
.map(|id| nearest_typed_entities(pool, kb_id, id, limit))
.buffered(at_once.max(1))
.try_collect()
.await
}
/// 按实体逐个改类,写进同一本账。返回 (批次 id, 改动数)。
///
/// 由调用方点名:类型消解裁决出来的是"这个实体是那个类",不是"叫这个说法的都是那个类"。
///
/// 账本格式一字不差,所以 [`unadopt_types`] 原样能撤。
pub async fn retype_entities(
pool: &PgPool,
kb_id: Uuid,
picks: &[(Uuid, Uuid)],
// None = 引擎自动裁决。跟 entity_merges.merged_by 一个约定,
// 实体历史据此区分"某某某改的"与"高置信自动改的"
actor: Option<Uuid>,
) -> AppResult<(Uuid, u32)> {
let batch_id = Uuid::now_v7();
let mut moved = 0u32;
let mut names: std::collections::HashSet<String> = std::collections::HashSet::new();
// 一个实体在一批里只改一次。账本主键是 (batch_id, entity_id),同一个 id
// 来两次会撞——而调用方拿到的是 500,整批一个都没落。这里挡住比在那边
// 追每一条产生 picks 的路子可靠:重复的第二条本来也没有意义
let mut seen: std::collections::HashSet<Uuid> = std::collections::HashSet::new();
for (entity_id, type_id) in picks {
if !seen.insert(*entity_id) {
continue;
}
let mut tx = pool.begin().await?;
// 已经在目标类上的不算改动,也不进账本——撤销时不该把它们推回去。
//
// **旧类型要从 CTE 里读**:`UPDATE … RETURNING` 给的是新值,而账本要记的
// 是改之前那个。直接 RETURNING type_id 拿到的就是刚写进去的那一个,
// 撤销时等于把实体"放回"它现在的位置——账本看着满满当当,实际什么都撤不了。
// 条件也一并放进 CTE:这一行还在、没被合并、且确实要变
//
// **`IS DISTINCT FROM` 而不是 `<>`**:0009 之后起点常常是 NULL,而
// `NULL <> uuid` 是 NULL 不是 true——CTE 会空掉,UPDATE 一行不动,
// 于是"给没有类的实体定类"这个最主要的场景整个变成空操作
let row: Option<(Option<Uuid>, String)> = sqlx::query_as(
"WITH before AS (
SELECT id, type_id, canonical_name FROM entities
WHERE id = $1 AND kb_id = $3 AND merged_into IS NULL
AND type_id IS DISTINCT FROM $2
)
UPDATE entities e SET type_id = $2, updated_at = now(),
type_source = CASE WHEN $4::uuid IS NULL THEN 'inferred' ELSE 'human' END
FROM before
WHERE e.id = before.id
RETURNING before.type_id, before.canonical_name",
)
.bind(entity_id)
.bind(type_id)
.bind(kb_id)
.bind(actor)
.fetch_optional(&mut *tx)
.await?;
let Some((from_type, name)) = row else {
tx.rollback().await?;
continue;
};
sqlx::query(
"INSERT INTO entity_retypes
(batch_id, kb_id, entity_id, from_type_id, to_type_id, actor_id)
VALUES ($1, $2, $3, $4, $5, $6)",
)
.bind(batch_id)
.bind(kb_id)
.bind(entity_id)
.bind(from_type)
.bind(type_id)
.bind(actor)
.execute(&mut *tx)
.await?;
tx.commit().await?;
names.insert(name);
moved += 1;
}
// 消歧后缀的兜底值就是类型标签,改了类就得重算
for n in &names {
refresh_disambiguators(pool, kb_id, n).await?;
}
Ok((batch_id, moved))
}
/// 人认可过的"粗类 → 细类"配对。
///
/// 待人工那一档由"跨没跨分类轴"触发,而那条判据测的常常是**种子类跟导入词汇表
/// 连没连上**,不是风险:schema.org 的 Place 另起 key,内置 location 零子类,
/// 于是每个城市都要问一遍。配对是类与类之间的事,实体只是碰巧撞上它——
/// 认可一次就该一直算数。
pub async fn approved_refinements(
pool: &PgPool,
kb_id: Uuid,
) -> AppResult<std::collections::HashSet<(Uuid, Uuid)>> {
let rows: Vec<(Uuid, Uuid)> = sqlx::query_as(
"SELECT from_type_id, to_type_id FROM type_refinement_pairs WHERE kb_id = $1",
)
.bind(kb_id)
.fetch_all(pool)
.await?;
Ok(rows.into_iter().collect())
}
/// 记下一个被认可的配对。重复认可是幂等的。
pub async fn approve_refinement(
pool: &PgPool,
kb_id: Uuid,
from_type_id: Uuid,
to_type_id: Uuid,
by: Uuid,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO type_refinement_pairs (kb_id, from_type_id, to_type_id, approved_by)
VALUES ($1, $2, $3, $4)
ON CONFLICT (kb_id, from_type_id, to_type_id) DO NOTHING",
)
.bind(kb_id)
.bind(from_type_id)
.bind(to_type_id)
.bind(by)
.execute(pool)
.await?;
Ok(())
}
#[cfg(test)]
mod same_type_tests {
use super::{classify_type_drift, TypeDrift};
/// **相同类型是最常见的情形,而它曾经落在 Disjoint 上。**
///
/// 这个函数生来服务"类型漂移"(同名被抽成两种类型),那里两边相同不会发生;
/// 后来被 `containment_reviews` 借去当相容性判据,那里两边相同是常态。
/// 结果是 `Sherlock Holmes` 与 `Holmes` 一对都进不了审阅队列。
#[test]
fn the_same_type_is_a_recall_candidate() {
for k in ["person", "location", "organization", "product", "event"] {
assert_eq!(
classify_type_drift(Some(k), Some(k)),
TypeDrift::Recall,
"{k} 对 {k} 必须可召回"
);
}
// 自定义类型同样——这里判的是"两边是不是同一种东西",不是"它在不在白名单里"
assert_eq!(
classify_type_drift(Some("drug"), Some("drug")),
TypeDrift::Recall
);
// 跨类型的老结论一条都不变
assert_eq!(
classify_type_drift(Some("person"), Some("organization")),
TypeDrift::Disjoint
);
}
}