World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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_typesWHERE 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_typesWHERE kb_id = $1diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rsindex 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))+}