Skip to content

World's first open-source enterprise world model.

Entities can be refined to a narrower type, and put back (#80)

WaylandYangc6d5e52d6f9a
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index cf85c765..6f7ea1e2 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -124,6 +124,14 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
"/kbs/{id}/ontology/type-resolution/preview",
post(ontology_routes::type_resolution_preview),
)
+ .route(
+ "/kbs/{id}/ontology/type-resolution",
+ post(ontology_routes::type_resolution_apply),
+ )
+ .route(
+ "/kbs/{id}/ontology/type-resolution/{batch_id}",
+ axum::routing::delete(ontology_routes::type_resolution_undo),
+ )
.route(
"/kbs/{id}/ontology/entity-types",
post(ontology_routes::create_entity_type),
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index 03c8bf4d..d92e832b 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -1254,6 +1254,53 @@ pub async fn type_resolution_preview(
Ok(Json(json!({ "items": items })))
}
+/// 跑一遍类型消解并落库:检索候选 → 裁决 → 三档处置。
+///
+/// 与 preview 分开是本仓库既有的形状(本体导入也是先看计划再落库)。这里还多
+/// 一层理由:改类**不进时间轴**,所以它不像事实改写那样在实体历史里自己显形,
+/// 先看一眼再动是唯一能看见它的时机。
+pub async fn type_resolution_apply(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path(kb_id): Path<Uuid>,
+) -> ApiResult<Json<serde_json::Value>> {
+ require_kb(&state, &user, kb_id, Role::Editor).await?;
+ let outcome = crate::type_resolution::resolve(&state, kb_id).await?;
+ let _ = utopia_store::audit::record(
+ &state.pool,
+ Some(kb_id),
+ user.id,
+ "ontology.types_resolved",
+ "knowledge_base",
+ Some(kb_id),
+ json!({ "retyped": outcome.retyped, "for_review": outcome.for_review.len(),
+ "left_alone": outcome.left_alone, "batch": outcome.batch }),
+ )
+ .await;
+ Ok(Json(json!(outcome)))
+}
+
+/// 撤销一次类型消解:把那一批实体放回原来的类。
+pub async fn type_resolution_undo(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path((kb_id, batch_id)): Path<(Uuid, Uuid)>,
+) -> ApiResult<Json<serde_json::Value>> {
+ require_kb(&state, &user, kb_id, Role::Editor).await?;
+ let reverted = utopia_store::resolution::unadopt_types(&state.pool, kb_id, batch_id).await?;
+ let _ = utopia_store::audit::record(
+ &state.pool,
+ Some(kb_id),
+ user.id,
+ "ontology.types_resolution_reverted",
+ "knowledge_base",
+ Some(kb_id),
+ json!({ "batch": batch_id, "reverted": reverted }),
+ )
+ .await;
+ Ok(Json(json!({ "reverted": reverted })))
+}
+
#[cfg(test)]
mod tests {
use super::{normalize_name, resolve_map_targets};
diff --git a/crates/utopia-server/src/ontology_index.rs b/crates/utopia-server/src/ontology_index.rs
index 34a8ad74..a830a822 100644
--- a/crates/utopia-server/src/ontology_index.rs
+++ b/crates/utopia-server/src/ontology_index.rs
@@ -18,6 +18,16 @@ const BATCH: usize = 64;
/// 把这个库里陈掉的本体向量补齐。没配嵌入模型就直接返回 `Ok(0)`——
/// 检索是增强,不该拦住没配模型的部署。
pub async fn refresh(state: &AppState, kb_id: Uuid) -> anyhow::Result<usize> {
+ refresh_scoped(state, kb_id, None).await
+}
+
+/// 只补一半。调用方清楚自己要哪一半时用它——类型消解只用类,
+/// 等关系嵌完是白等。补漏的那一半有后台任务兜着。
+pub async fn refresh_scoped(
+ state: &AppState,
+ kb_id: Uuid,
+ only: Option<utopia_store::ontology::TypeKind>,
+) -> anyhow::Result<usize> {
let kb = utopia_store::kbs::get(&state.pool, kb_id).await?;
let Some(settings) = utopia_store::settings::get(&state.pool, kb.workspace_id).await? else {
return Ok(0);
@@ -29,7 +39,8 @@ pub async fn refresh(state: &AppState, kb_id: Uuid) -> anyhow::Result<usize> {
return Ok(0);
};
- let stale = utopia_store::ontology::types_needing_embedding(&state.pool, kb_id, model).await?;
+ let stale =
+ utopia_store::ontology::types_needing_embedding(&state.pool, kb_id, model, only).await?;
if stale.is_empty() {
return Ok(0);
}
diff --git a/crates/utopia-server/src/type_resolution.rs b/crates/utopia-server/src/type_resolution.rs
index d060c00a..8806a32d 100644
--- a/crates/utopia-server/src/type_resolution.rs
+++ b/crates/utopia-server/src/type_resolution.rs
@@ -20,8 +20,8 @@
//! (schema.org 把软件挂在 CreativeWork 下,而抽取给的粗类是 product)。
//! 该说不的是裁决那一步,它看得到描述也看得到粗类。
-use crate::{ontology_index, AppState};
-use utopia_core::AppResult;
+use crate::{llm_util, ontology_index, AppState};
+use utopia_core::{AppError, AppResult};
use uuid::Uuid;
/// 倾倒场类的 key。挂在它下面的实体是"没判出来",不是"判成了这个"。
@@ -77,7 +77,13 @@ pub struct NeighbourVote {
/// 独立成一步是有意的——在花力气建裁决之前,先回答"检索到底找不找得到"。
/// 找不到的话,裁决做得再好也没有用。
pub async fn preview(state: &AppState, kb_id: Uuid) -> AppResult<Vec<TypeSuggestion>> {
- let _ = ontology_index::refresh(state, kb_id).await;
+ // 只补类那一半:这一步用不到关系,而一份大本体的关系有一千多条
+ let _ = ontology_index::refresh_scoped(
+ state,
+ kb_id,
+ Some(utopia_store::ontology::TypeKind::Entity),
+ )
+ .await;
let subjects = utopia_store::resolution::entities_for_type_resolution(
&state.pool,
kb_id,
@@ -212,3 +218,207 @@ fn profile_of(s: &utopia_store::resolution::TypeCandidateSubject) -> String {
}
parts.join(". ")
}
+
+/// 一条裁决结果。
+#[derive(Debug, serde::Deserialize)]
+struct Verdict {
+ /// 实体名,用来对回 preview 里的那一条
+ name: String,
+ /// 选中的类 key;判不出来时为空
+ #[serde(default)]
+ choice: Option<String>,
+ #[serde(default)]
+ confidence: Option<f32>,
+ #[serde(default)]
+ reason: Option<String>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct VerdictReply {
+ #[serde(default)]
+ verdicts: Vec<Verdict>,
+}
+
+/// 高于这条线才自动改类,其余进提案让人点。
+///
+/// 定在 0.85 而不是更低:改类**不进时间轴**(它是 entities 上的一次 UPDATE 加
+/// 一行账),所以错了不会在实体历史里留下一条刺眼的记录,也就没那么容易被
+/// 发现。可撤销不等于会被撤销——没人看见的错不会有人去撤。
+const AUTO_THRESHOLD: f32 = 0.85;
+
+/// 一次消解的结果,给调用方交代清楚三档各去了哪里。
+#[derive(Debug, serde::Serialize)]
+pub struct ResolutionOutcome {
+ pub batch: Option<Uuid>,
+ /// 自动改掉的
+ pub retyped: u32,
+ /// 有候选但置信度不够,留给人的
+ pub for_review: Vec<ReviewItem>,
+ /// 裁决说"都不是"的。**这一档必须报出来**:它跟"没跑"长得一样,
+ /// 而两者的含义完全相反
+ pub left_alone: usize,
+}
+
+#[derive(Debug, serde::Serialize)]
+pub struct ReviewItem {
+ pub entity_id: Uuid,
+ pub name: String,
+ pub coarse: String,
+ pub choice: String,
+ pub confidence: f32,
+ pub reason: Option<String>,
+}
+
+/// 跑一遍类型消解:检索候选 → 裁决 → 三档处置。
+pub async fn resolve(state: &AppState, kb_id: Uuid) -> AppResult<ResolutionOutcome> {
+ let items = preview(state, kb_id).await?;
+ let items: Vec<_> = items
+ .into_iter()
+ .filter(|i| !i.candidates.is_empty() || !i.neighbours.is_empty())
+ .collect();
+ if items.is_empty() {
+ return Ok(ResolutionOutcome {
+ batch: None,
+ retyped: 0,
+ for_review: Vec::new(),
+ left_alone: 0,
+ });
+ }
+
+ let kb = utopia_store::kbs::get(&state.pool, kb_id).await?;
+ let settings = utopia_store::settings::get(&state.pool, kb.workspace_id)
+ .await?
+ .ok_or_else(|| AppError::invalid("no_chat_model", "Chat model not configured"))?;
+ let client = llm_util::chat_client(&settings)
+ .ok_or_else(|| AppError::invalid("no_chat_model", "Chat model not configured"))?;
+
+ let reply = client
+ .chat(&[utopia_llm::ChatMessage {
+ role: "user".into(),
+ content: adjudication_prompt(&items),
+ }])
+ .await
+ .map_err(AppError::Other)?;
+ let block = utopia_extract::json_block(&reply).map_err(AppError::Other)?;
+ let parsed: VerdictReply =
+ serde_json::from_str(&block).map_err(|e| AppError::Other(e.into()))?;
+
+ // 名字对回实体,同时把每个实体允许的 key 收起来——模型偶尔会答一个
+ // 候选之外的 key(本体里可能根本没有),那种不该落库
+ let by_name: std::collections::HashMap<&str, &TypeSuggestion> =
+ items.iter().map(|i| (i.name.as_str(), i)).collect();
+ let mut picks: Vec<(Uuid, Uuid)> = Vec::new();
+ let mut for_review: Vec<ReviewItem> = Vec::new();
+ let mut left_alone = 0usize;
+ for v in &parsed.verdicts {
+ let Some(item) = by_name.get(v.name.as_str()) else {
+ continue;
+ };
+ let Some(choice) = v.choice.as_deref().map(str::trim).filter(|c| !c.is_empty()) else {
+ left_alone += 1;
+ continue;
+ };
+ // 只认候选清单里的 key。清单之外的答案不是"更好的判断",
+ // 是模型在凭记忆写一个 schema.org 里的名字——本体里未必有
+ let Some(target) = item.candidates.iter().find(|c| c.key == choice) else {
+ left_alone += 1;
+ continue;
+ };
+ let confidence = v.confidence.unwrap_or(0.0);
+ if confidence >= AUTO_THRESHOLD {
+ picks.push((item.entity_id, target.id));
+ } else {
+ for_review.push(ReviewItem {
+ entity_id: item.entity_id,
+ name: item.name.clone(),
+ coarse: item.coarse.clone(),
+ choice: choice.to_string(),
+ confidence,
+ reason: v.reason.clone(),
+ });
+ }
+ }
+ // 裁决压根没提到的实体也算"没动",否则三档加起来对不上总数
+ left_alone += items.len().saturating_sub(
+ parsed
+ .verdicts
+ .iter()
+ .filter(|v| by_name.contains_key(v.name.as_str()))
+ .count(),
+ );
+
+ let (batch, retyped) = if picks.is_empty() {
+ (None, 0)
+ } else {
+ let (b, n) = utopia_store::resolution::retype_entities(&state.pool, kb_id, &picks).await?;
+ (Some(b), n)
+ };
+ Ok(ResolutionOutcome {
+ batch,
+ retyped,
+ for_review,
+ left_alone,
+ })
+}
+
+/// 裁决提示词。
+///
+/// **"都不是"必须是个体面的答案。** 这跟 `related_to` 那个逃生舱正好相反:
+/// 那里兜底选项销毁信息,所以撤掉;这里保持粗类什么也不损失——实体照样在图上、
+/// 事实照样挂着,只是没变得更具体。硬逼模型从候选里挑一个,换来的是一批
+/// 自信的错误,而且它们不进时间轴、不容易被看见。
+fn adjudication_prompt(items: &[TypeSuggestion]) -> String {
+ let mut blocks = Vec::new();
+ for it in items {
+ let mut lines = vec![format!(
+ "### {}\ncurrently: {}\nthe extractor called it: {}\nseen as: {}",
+ it.name,
+ it.coarse,
+ it.specific_type.as_deref().unwrap_or("-"),
+ it.profile.chars().take(200).collect::<String>()
+ )];
+ lines.push("candidates:".into());
+ for c in &it.candidates {
+ let d = c.description.trim();
+ lines.push(if d.is_empty() {
+ format!("- {} ({})", c.key, c.label)
+ } else {
+ format!("- {}: {d}", c.key)
+ });
+ }
+ if !it.neighbours.is_empty() {
+ let n: Vec<String> = it
+ .neighbours
+ .iter()
+ .take(3)
+ .map(|n| format!("{} (like {})", n.key, n.examples.join(", ")))
+ .collect();
+ lines.push(format!("similar entities are typed: {}", n.join("; ")));
+ }
+ blocks.push(lines.join("\n"));
+ }
+ format!(
+ "You are refining entity types in a knowledge graph. Each entity below already has a \
+ broad type and a list of candidate narrower types retrieved from the ontology.\n\
+ \n\
+ For each entity choose ONE candidate key, or null.\n\
+ \n\
+ Choose null whenever any of these hold, and expect null to be a common answer:\n\
+ - no candidate actually means the thing (the list is retrieved by similarity, so it \
+ usually contains near-misses and sometimes contains nothing right at all);\n\
+ - the candidate is not narrower than what it already has;\n\
+ - the entity is not a thing of that kind at all — a quantity, a capability, a phrase.\n\
+ Keeping the broad type loses nothing: the entity and its facts stay exactly as they \
+ are, merely less specific. Picking a wrong narrow type is worse than picking none, \
+ because it reads as a decided fact.\n\
+ \n\
+ confidence is your own 0~1: use above 0.85 only when the candidate's definition \
+ plainly describes this entity, not when it is merely the closest of a weak list.\n\
+ \n\
+ {}\n\
+ \n\
+ Output exactly one JSON object:\n\
+ {{\"verdicts\":[{{\"name\":\"entity name exactly as given\",\"choice\":\"candidate key or null\",\"confidence\":0.0,\"reason\":\"one short clause\"}}]}}",
+ blocks.join("\n\n")
+ )
+}
diff --git a/crates/utopia-store/src/ontology.rs b/crates/utopia-store/src/ontology.rs
index 8b23c0fe..ea8dea45 100644
--- a/crates/utopia-store/src/ontology.rs
+++ b/crates/utopia-store/src/ontology.rs
@@ -811,12 +811,20 @@ fn embed_text(label: &str, description: &str) -> String {
///
/// 判据是**比对当时嵌的原文与模型名**,不是看时间戳:描述改了、模型换了,
/// 时间戳一样看不出来。这样也不必在每个改描述的写入点挂钩子——漏一个就悄悄烂掉。
+///
+/// `only` 限定只补一半。类型消解只用类,让它等 1633 个关系嵌完是白等六分钟;
+/// 而后台那个补齐任务不限,两边补的是同一批行,谁先跑到都算数。
pub async fn types_needing_embedding(
pool: &PgPool,
kb_id: Uuid,
model: &str,
+ only: Option<TypeKind>,
) -> AppResult<Vec<TypeToEmbed>> {
let mut out = Vec::new();
+ if only == Some(TypeKind::Relation) {
+ // 类型消解只用类,等 1633 个关系嵌完是白等六分钟
+ return relations_needing_embedding(pool, kb_id, model).await;
+ }
let ents: Vec<(Uuid, String, String)> = sqlx::query_as(
"SELECT id, label, coalesce(description, '') FROM entity_types
WHERE kb_id = $1
@@ -835,6 +843,19 @@ pub async fn types_needing_embedding(
kind: TypeKind::Entity,
text: embed_text(&label, &desc),
}));
+ if only == Some(TypeKind::Entity) {
+ return Ok(out);
+ }
+ out.extend(relations_needing_embedding(pool, kb_id, model).await?);
+ Ok(out)
+}
+
+async fn relations_needing_embedding(
+ pool: &PgPool,
+ kb_id: Uuid,
+ model: &str,
+) -> AppResult<Vec<TypeToEmbed>> {
+ let mut out = Vec::new();
let rels: Vec<(Uuid, String, String)> = sqlx::query_as(
"SELECT id, label, coalesce(description, '') FROM relation_types
WHERE kb_id = $1
diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rs
index a2cd3979..0de9773c 100644
--- a/crates/utopia-store/src/resolution.rs
+++ b/crates/utopia-store/src/resolution.rs
@@ -1850,3 +1850,67 @@ pub async fn nearest_typed_entities(
.fetch_all(pool)
.await?)
}
+
+/// 按实体逐个改类,写进同一本账。返回 (批次 id, 改动数)。
+///
+/// 与 [`adopt_proposed_types`] 的区别只在挑选方式:那个按 `proposed_type` 这个
+/// **说法**认领一批,这个由调用方点名——类型消解裁决出来的是"这个实体是那个类",
+/// 不是"叫这个说法的都是那个类"。
+///
+/// 账本格式一字不差,所以 [`unadopt_types`] 原样能撤。
+pub async fn retype_entities(
+ pool: &PgPool,
+ kb_id: Uuid,
+ picks: &[(Uuid, 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();
+ for (entity_id, type_id) in picks {
+ let mut tx = pool.begin().await?;
+ // 已经在目标类上的不算改动,也不进账本——撤销时不该把它们推回去。
+ //
+ // **旧类型要从 CTE 里读**:`UPDATE … RETURNING` 给的是新值,而账本要记的
+ // 是改之前那个。直接 RETURNING type_id 拿到的就是刚写进去的那一个,
+ // 撤销时等于把实体"放回"它现在的位置——账本看着满满当当,实际什么都撤不了。
+ // 条件也一并放进 CTE:这一行还在、没被合并、且确实要变
+ let row: 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 <> $2
+ )
+ UPDATE entities e SET type_id = $2, updated_at = now()
+ FROM before
+ WHERE e.id = before.id
+ RETURNING before.type_id, before.canonical_name",
+ )
+ .bind(entity_id)
+ .bind(type_id)
+ .bind(kb_id)
+ .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)
+ VALUES ($1, $2, $3, $4, $5)",
+ )
+ .bind(batch_id)
+ .bind(kb_id)
+ .bind(entity_id)
+ .bind(from_type)
+ .bind(type_id)
+ .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))
+}