Skip to content

World's first open-source enterprise world model.

A phrase binds to a property (#751)

WaylandYangf760c762c864
diff --git a/crates/utopia-extract/src/align.rs b/crates/utopia-extract/src/align.rs
index b8cb76b1..9d067892 100644
--- a/crates/utopia-extract/src/align.rs
+++ b/crates/utopia-extract/src/align.rs
@@ -169,7 +169,7 @@ pub fn parse_kind_word_response(
/// 先按常规取块(第一个 `{` 到最后一个 `}`);解不开才从第一个 `{` 取到结尾去修补。
/// 取块与修补的分工同 `open.rs`:紧凑回复里 `}` 只在结尾出现,截断的回复要么没有 `}`,
/// 要么最后一个 `}` 不是结尾
-fn parse_value(raw: &str) -> anyhow::Result<Value> {
+pub(crate) fn parse_value(raw: &str) -> anyhow::Result<Value> {
let block = json_block(raw)
.and_then(|b| serde_json::from_str::<Value>(&b).map_err(anyhow::Error::from));
match block {
@@ -212,7 +212,7 @@ fn parse_pair(v: &Value, by_id: &HashMap<i64, &KindWordItem<'_>>) -> Option<Kind
}
/// id 是 JSON 整数;模型偶尔把它写成字符串,照数字读
-fn item_id(v: &Value) -> Option<i64> {
+pub(crate) fn item_id(v: &Value) -> Option<i64> {
match v {
Value::Number(n) => n.as_i64(),
Value::String(s) => s.trim().parse().ok(),
diff --git a/crates/utopia-extract/src/lib.rs b/crates/utopia-extract/src/lib.rs
index cb53522c..09b0a6d6 100644
--- a/crates/utopia-extract/src/lib.rs
+++ b/crates/utopia-extract/src/lib.rs
@@ -12,6 +12,7 @@ use utopia_llm::ChatMessage;
pub mod align;
pub mod governor;
pub mod open;
+pub mod phrase_align;
pub mod time;
/// Response-scoped reference to a persistent entity; database UUIDs must never enter prompts.
diff --git a/crates/utopia-extract/src/phrase_align.rs b/crates/utopia-extract/src/phrase_align.rs
new file mode 100644
index 00000000..7c157807
--- /dev/null
+++ b/crates/utopia-extract/src/phrase_align.rs
@@ -0,0 +1,394 @@
+//! 关系短语按签名绑到属性(0044 决定 3 的第二片)。签名 = 短语 × 主语的类 × 宾语的类
+//! (宾语是字面值时记「值」)。一个库里 distinct 的签名比陈述少得多,每条只判一次,绑定按
+//! 库缓存、按签名复用。
+//!
+//! 对齐读来源(决定 3):每条签名带着它下面的几条陈述和各自的引文进提示词,模型判的是
+//! 「**每一条**这个签名下的陈述都在陈述这个属性吗」,还要说方向:forward 是陈述的主语
+//! 就是属性的主语,reverse 是反过来(「owns」绑到 subsidiary_of)。属性可以比短语宽
+//! (「opened a plant in」是 located_in),不能比短语窄、不能只是沾边(「announced the
+//! acquisition of」不是 acquired);只报告、只评价的短语(said、is expected to)答 null;
+//! 值不是属性量的东西也答 null(股数不是营收)。候选属性的定义、定义域、值域照库里的
+//! 写法给,答案里的键照抄。
+//!
+//! 回复是紧凑 JSON:`{"b": [[id, "key" | null, "forward" | "reverse" | null]]}`。解析同
+//! 类别词那边:坏的一条计数、不毁掉整批;键不在候选里、id 不在批里、绑了却没方向、
+//! 同一个 id 的第二次都算坏;没答到的 id 是「再问」,不是 null。
+
+use std::collections::{HashMap, HashSet};
+
+use serde_json::Value;
+use utopia_llm::ChatMessage;
+
+use crate::align::{item_id, parse_value};
+
+/// 一个候选属性:键照抄进答案;其余是模型判断的依据,照库里的语言给
+#[derive(Debug, Clone)]
+pub struct PropertyCandidate<'a> {
+ pub key: &'a str,
+ pub label: &'a str,
+ pub description: &'a str,
+ /// relation(两样东西之间)或 attribute(宾语是值)
+ pub kind: &'a str,
+ /// 定义域、值域的类键;空表示没声明
+ pub domains: Vec<&'a str>,
+ pub ranges: Vec<&'a str>,
+}
+
+/// 一条待绑定的签名:短语、两端的类、例句与引文、候选属性
+#[derive(Debug, Clone)]
+pub struct PhraseItem<'a> {
+ pub id: i64,
+ /// the normalised phrase ("acquired")
+ pub phrase: &'a str,
+ /// the subject's class key; None when its kind word is bound to no class yet
+ pub subject_class: Option<&'a str>,
+ /// the object's class key; None when unbound, or when the object is a value
+ pub object_class: Option<&'a str>,
+ pub object_is_value: bool,
+ pub statement_count: i64,
+ /// rendered statements ("Brightway Builders —acquired→ Harbor Estates") with their quotes
+ pub examples: &'a [String],
+ pub quotes: &'a [String],
+ pub candidates: Vec<PropertyCandidate<'a>>,
+}
+
+/// 模型对一条签名的裁决:Some = (候选的键, 方向);None = 不绑
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PhraseChoice {
+ pub id: i64,
+ pub property: Option<(String, Direction)>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Direction {
+ Forward,
+ Reverse,
+}
+
+impl Direction {
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Direction::Forward => "forward",
+ Direction::Reverse => "reverse",
+ }
+ }
+}
+
+/// 系统消息。例子是中性的,不出自任何测量语料;规则 1 的「每一条」是整条路的判据
+const PHRASE_SYSTEM: &str = "\
+You bind the relation phrases documents use to the properties of a knowledge base's ontology. \
+Each numbered item is one signature: a phrase as the documents wrote it, the class of the thing \
+it is said of (its subject) and the class of what it points at (its object), or \"value\" when \
+the object is a figure, a title or a status; a few statements with that signature, each with the \
+sentence it was taken from; and the candidate properties, each with its key, its label, its \
+definition, its kind (a relation between two things, or an attribute whose object is a value), \
+its domain and its range. A class written as \"?\" means the documents' kind word for that side \
+is bound to no class yet.\n\
+For each item, answer with the key of the one property that every statement of this signature \
+states by that property's definition, and the direction: \"forward\" when the statement's \
+subject is the property's subject, \"reverse\" when the statement's object is; or null.\n\
+\n\
+Output exactly one JSON object and nothing else, one triple per item:\n\
+{\"b\": [[12, \"headquartered_in\", \"forward\"], [13, null, null]]}\n\
+\n\
+1. Choose a property only when each of the statements under this signature states that \
+property, by the definition as given. The property may be broader than the phrase: \"opened a \
+plant in\" states located_in; \"is the chief executive of\" states officer_of. It is never \
+narrower and never merely related: \"announced the acquisition of\" is not acquired when the \
+sentence says it was announced, not completed; \"revenue grew 18%\" is a change from the prior \
+period, not revenue.\n\
+2. Judge by the definition and by the sentences, not by the label. Labels, definitions and \
+phrases may be in any language.\n\
+3. Answer null when no candidate fits; when the sentences show the phrase meaning different \
+things under this signature; when the phrase only reports, introduces or evaluates (\"said\", \
+\"announced\", \"is expected to\") unless a candidate is about that; or when a value is not \
+what the attribute measures (a share count is not revenue, a date is not an amount).\n\
+4. The direction follows the definition: for \"X —is a subsidiary of→ Y\" subsidiary_of is \
+forward; for \"X —owns→ Y\", if subsidiary_of is the only fitting candidate, it is reverse.\n\
+5. Never invent a key, never answer with a label, never choose for an item a key that is not \
+among its candidates. One triple per item, every item answered.";
+
+fn candidate_line(c: &PropertyCandidate<'_>) -> String {
+ let mut line = format!("- {} · {} · {}", c.key, c.label, c.kind);
+ if !c.domains.is_empty() {
+ line.push_str(&format!(" · domain: {}", c.domains.join(", ")));
+ }
+ if !c.ranges.is_empty() {
+ line.push_str(&format!(" · range: {}", c.ranges.join(", ")));
+ }
+ line.push_str(&format!(" · {}", c.description));
+ line
+}
+
+/// 构造两条消息:常量系统消息 + 逐项的用户消息。每项:id、短语、两端的类、例句与引文、候选。
+pub fn build_phrase_messages(items: &[PhraseItem<'_>]) -> Vec<ChatMessage> {
+ let mut user = String::new();
+ for item in items {
+ let object = if item.object_is_value {
+ "value".to_string()
+ } else {
+ item.object_class.unwrap_or("?").to_string()
+ };
+ let mut examples = String::new();
+ for (i, ex) in item.examples.iter().enumerate() {
+ let quote = item.quotes.get(i).map(String::as_str).unwrap_or("");
+ examples.push_str(&format!("\n · {ex}\n \"{}\"", quote.trim()));
+ }
+ if examples.is_empty() {
+ examples.push_str(" (none)");
+ }
+ let candidates = if item.candidates.is_empty() {
+ " (none)".to_string()
+ } else {
+ let lines: Vec<String> = item.candidates.iter().map(candidate_line).collect();
+ format!("\n{}", lines.join("\n"))
+ };
+ user.push_str(&format!(
+ "Item {}: phrase \"{}\" · subject class: {} · object: {} · {} statements\nStatements:{examples}\nCandidates:{candidates}\n\n",
+ item.id,
+ item.phrase,
+ item.subject_class.unwrap_or("?"),
+ object,
+ item.statement_count,
+ ));
+ }
+ vec![
+ ChatMessage {
+ role: "system".into(),
+ content: PHRASE_SYSTEM.to_string(),
+ },
+ ChatMessage {
+ role: "user".into(),
+ content: user.trim_end().to_string(),
+ },
+ ]
+}
+
+/// 解析回复:`(裁决, 坏项数)`。同一个 id 只收第一次;没答到的 id 不出现。
+pub fn parse_phrase_response(
+ raw: &str,
+ items: &[PhraseItem<'_>],
+) -> anyhow::Result<(Vec<PhraseChoice>, usize)> {
+ let value = parse_value(raw)?;
+ let by_id: HashMap<i64, &PhraseItem<'_>> = items.iter().map(|i| (i.id, i)).collect();
+ let triples = value
+ .get("b")
+ .and_then(Value::as_array)
+ .map_or(&[][..], Vec::as_slice);
+ let mut choices = Vec::new();
+ let mut malformed = 0usize;
+ let mut seen = HashSet::new();
+ for t in triples {
+ match parse_triple(t, &by_id) {
+ Some(choice) if seen.insert(choice.id) => choices.push(choice),
+ _ => malformed += 1,
+ }
+ }
+ Ok((choices, malformed))
+}
+
+/// `[id, key | null, direction | null]`:绑了就得有方向,方向不认识算坏
+fn parse_triple(v: &Value, by_id: &HashMap<i64, &PhraseItem<'_>>) -> Option<PhraseChoice> {
+ let arr = v.as_array()?;
+ if arr.len() < 2 {
+ return None;
+ }
+ let id = item_id(&arr[0])?;
+ let item = by_id.get(&id)?;
+ let property = match &arr[1] {
+ Value::Null => None,
+ Value::String(written) => {
+ let key = candidate_key(item, written)?;
+ let direction = match arr.get(2).and_then(Value::as_str).map(str::trim) {
+ Some("forward") | Some("Forward") => Direction::Forward,
+ Some("reverse") | Some("Reverse") => Direction::Reverse,
+ _ => return None,
+ };
+ Some((key, direction))
+ }
+ _ => return None,
+ };
+ Some(PhraseChoice { id, property })
+}
+
+/// 模型写的键对回这一项的候选:先原样,再不分大小写(只在唯一命中时)
+fn candidate_key(item: &PhraseItem<'_>, written: &str) -> Option<String> {
+ let written = written.trim();
+ if written.is_empty() {
+ return None;
+ }
+ let keys = || item.candidates.iter().map(|c| c.key.trim());
+ if let Some(exact) = keys().find(|k| *k == written) {
+ return Some(exact.to_string());
+ }
+ let lower = written.to_lowercase();
+ let mut hits = keys().filter(|k| k.to_lowercase() == lower);
+ let first = hits.next()?;
+ hits.next().is_none().then(|| first.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn strings(values: &[&str]) -> Vec<String> {
+ values.iter().map(|s| s.to_string()).collect()
+ }
+
+ fn candidates<'a>() -> Vec<PropertyCandidate<'a>> {
+ vec![
+ PropertyCandidate {
+ key: "headquartered_in",
+ label: "headquartered in",
+ description: "The organization's principal office is at the place.",
+ kind: "relation",
+ domains: vec!["organization"],
+ ranges: vec!["place"],
+ },
+ PropertyCandidate {
+ key: "subsidiary_of",
+ label: "subsidiary of",
+ description: "The organization is owned or controlled by the other organization.",
+ kind: "relation",
+ domains: vec!["organization"],
+ ranges: vec!["organization"],
+ },
+ PropertyCandidate {
+ key: "revenue",
+ label: "revenue",
+ description: "Total income from sales for a period, as an amount of money.",
+ kind: "attribute",
+ domains: vec!["organization"],
+ ranges: vec![],
+ },
+ ]
+ }
+
+ #[test]
+ fn the_prompt_lists_the_signature_its_sentences_and_the_candidates() {
+ let examples = strings(&["Harbor Bakery —is based in→ Port Ellen"]);
+ let quotes = strings(&["Harbor Bakery is based in Port Ellen."]);
+ let items = vec![PhraseItem {
+ id: 3,
+ phrase: "is based in",
+ subject_class: Some("organization"),
+ object_class: None,
+ object_is_value: false,
+ statement_count: 4,
+ examples: &examples,
+ quotes: &quotes,
+ candidates: candidates(),
+ }];
+ let msgs = build_phrase_messages(&items);
+ let user = &msgs[1].content;
+ assert!(user.contains("Item 3: phrase \"is based in\" · subject class: organization · object: ? · 4 statements"), "{user}");
+ assert!(user.contains("· Harbor Bakery —is based in→ Port Ellen\n \"Harbor Bakery is based in Port Ellen.\""), "{user}");
+ assert!(user.contains("- headquartered_in · headquartered in · relation · domain: organization · range: place · The organization's"), "{user}");
+ assert!(
+ user.contains("- revenue · revenue · attribute · domain: organization · Total income"),
+ "{user}"
+ );
+ assert!(msgs[0]
+ .content
+ .contains("every statement of this signature"));
+ }
+
+ #[test]
+ fn a_value_signature_says_value_for_its_object() {
+ let examples = strings(&["Harbor Bakery —revenue→ $2 million"]);
+ let quotes = strings(&["Harbor Bakery's revenue was $2 million."]);
+ let items = vec![PhraseItem {
+ id: 0,
+ phrase: "revenue",
+ subject_class: Some("organization"),
+ object_class: None,
+ object_is_value: true,
+ statement_count: 1,
+ examples: &examples,
+ quotes: &quotes,
+ candidates: candidates(),
+ }];
+ let user = &build_phrase_messages(&items)[1].content;
+ assert!(user.contains("· object: value ·"), "{user}");
+ }
+
+ /// 绑上带方向;null 不绑;键照候选抄回;绑了没方向、键不在候选里、id 不在批里都算坏
+ #[test]
+ fn triples_parse_and_bad_ones_are_counted() {
+ let examples = strings(&[]);
+ let quotes = strings(&[]);
+ let mk = |id: i64, phrase: &'static str| PhraseItem {
+ id,
+ phrase,
+ subject_class: Some("organization"),
+ object_class: Some("organization"),
+ object_is_value: false,
+ statement_count: 1,
+ examples: &examples,
+ quotes: &quotes,
+ candidates: candidates(),
+ };
+ let items = vec![
+ mk(0, "owns"),
+ mk(1, "said"),
+ mk(2, "acquired"),
+ mk(3, "employs"),
+ mk(4, "x"),
+ ];
+ let raw = r#"{"b": [[0, "Subsidiary_Of", "reverse"], [1, null, null], [2, "acquired", "forward"], [3, "subsidiary_of"], ["4", "revenue", "forward"], [9, null, null], [0, null, null]]}"#;
+ let (choices, malformed) = parse_phrase_response(raw, &items).unwrap();
+ assert_eq!(
+ choices,
+ vec![
+ PhraseChoice {
+ id: 0,
+ property: Some(("subsidiary_of".into(), Direction::Reverse))
+ },
+ PhraseChoice {
+ id: 1,
+ property: None
+ },
+ PhraseChoice {
+ id: 4,
+ property: Some(("revenue".into(), Direction::Forward))
+ },
+ ]
+ );
+ // 2:键不在候选里;3:绑了没方向;9:id 不在批里;0 的第二次
+ assert_eq!(malformed, 4);
+ }
+
+ #[test]
+ fn a_truncated_reply_keeps_the_complete_triples() {
+ let examples = strings(&[]);
+ let quotes = strings(&[]);
+ let items = vec![
+ PhraseItem {
+ id: 0,
+ phrase: "a",
+ subject_class: None,
+ object_class: None,
+ object_is_value: false,
+ statement_count: 1,
+ examples: &examples,
+ quotes: &quotes,
+ candidates: candidates(),
+ },
+ PhraseItem {
+ id: 1,
+ phrase: "b",
+ subject_class: None,
+ object_class: None,
+ object_is_value: false,
+ statement_count: 1,
+ examples: &examples,
+ quotes: &quotes,
+ candidates: candidates(),
+ },
+ ];
+ let raw = r#"{"b": [[0, "revenue", "forward"], [1, "subsid"#;
+ let (choices, _) = parse_phrase_response(raw, &items).unwrap();
+ assert_eq!(choices.len(), 1);
+ assert_eq!(choices[0].id, 0);
+ }
+}
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index ea124b0b..f6770bef 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -323,6 +323,13 @@ pub async fn create_relation_type(
if let Some(q) = req.qualifiers.as_deref() {
utopia_store::ontology::set_relation_qualifiers(&state.pool, kb_id, id, q).await?;
}
+ // 多了一个属性:判成 none / undecided 的签名也许对得上了(0044 对齐第二片)
+ utopia_store::jobs::enqueue_unless_queued(
+ &state.pool,
+ "align_phrases",
+ serde_json::json!({ "kb_id": kb_id }),
+ )
+ .await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
@@ -361,6 +368,13 @@ pub async fn update_relation_type(
if let Some(q) = req.qualifiers.as_deref() {
utopia_store::ontology::set_relation_qualifiers(&state.pool, kb_id, id, q).await?;
}
+ // 属性改了定义或域/值域:绑到它的签名过期,判成 none 的也许对得上了
+ utopia_store::jobs::enqueue_unless_queued(
+ &state.pool,
+ "align_phrases",
+ serde_json::json!({ "kb_id": kb_id }),
+ )
+ .await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
diff --git a/crates/utopia-server/src/main.rs b/crates/utopia-server/src/main.rs
index 3087e44d..6c7e585f 100644
--- a/crates/utopia-server/src/main.rs
+++ b/crates/utopia-server/src/main.rs
@@ -24,6 +24,7 @@ mod ontology_index;
mod ontology_packs;
mod owl_import;
mod pack_alignment;
+mod phrase_alignment;
mod pipeline;
mod predicate_match;
mod query_engine;
@@ -506,6 +507,16 @@ async fn dispatch(st: &state::AppState, job: &utopia_store::jobs::Job) -> anyhow
.ok_or_else(|| anyhow::anyhow!("payload 缺少 kb_id"))?;
type_alignment::align_types(st, kb_id).await
}
+ // 关系短语按签名绑到属性(0044 对齐的第二片):类别词绑完排一个,属性改了再排
+ "align_phrases" => {
+ let kb_id: Uuid = job
+ .payload
+ .get("kb_id")
+ .and_then(|v| v.as_str())
+ .and_then(|s| s.parse().ok())
+ .ok_or_else(|| anyhow::anyhow!("payload 缺少 kb_id"))?;
+ phrase_alignment::align_phrases(st, kb_id).await
+ }
"resolve_time" => {
let id = payload_document_id(&job.payload)?;
time_resolution::resolve_document(st, id).await
diff --git a/crates/utopia-server/src/phrase_alignment.rs b/crates/utopia-server/src/phrase_alignment.rs
new file mode 100644
index 00000000..adcea627
--- /dev/null
+++ b/crates/utopia-server/src/phrase_alignment.rs
@@ -0,0 +1,406 @@
+//! 关系短语按签名绑到属性(0044 决定 3 的第二片;账本侧见 `utopia_store::phrase_bindings`,
+//! 合同见 `utopia_extract::phrase_align`)。
+//!
+//! 签名 = 短语 × 主语的类 × 宾语的类(宾语是字面值时记「值」)。两端的类来自类别词绑定
+//! 写到实体上的 `type_id`,所以这一步排在类别词对齐之后。一个库里 distinct 的签名比陈述
+//! 少得多,每条只判一次:**两票一致**才绑(第二票候选倒序,防「选第一个」冒充一致),
+//! 不一致记 undecided 留给审核(#725 对齐队列),没有属性对得上记 none——陈述留在开放
+//! 图谱,什么都不丢,签名计入工作台的建议。绑定按属性的 `updated_at` 与库里最新的属性
+//! 判过期,本体一改只重判过期的。这一片只记判定;按绑定把陈述算成类型化事实是下一片。
+//!
+//! 候选属性怎么来:先按声明的定义域/值域筛——签名两端的类落在属性的域/值域里的,或者
+//! 属性没声明域/值域的(两个方向都算,绑定可以是反向的)。**一端没绑到类的签名,只有
+//! 没声明那一端的属性才算候选**:类别词还没绑上时把声明了域的属性也给模型,NVDA 四篇上
+//! 现金流量表的每一行都绑到了泛泛的 value(主语 NVIDIA 没类,value 的域是指标)——裁判
+//! 判成写错的一半是它。筛完仍超过上限就不判,瞎判比不判糟。
+
+use crate::extraction::chat_retrying_rate_limits_at;
+use crate::llm_util;
+use crate::state::AppState;
+use std::collections::{HashMap, HashSet};
+use utopia_core::models::RelationTypeView;
+use utopia_extract::phrase_align::{
+ build_phrase_messages, parse_phrase_response, Direction, PhraseItem, PropertyCandidate,
+};
+use utopia_store::phrase_bindings::{self, Decision, PhraseSignature};
+use uuid::Uuid;
+
+/// 一次问多少条签名。
+const BATCH: usize = 12;
+/// 筛过定义域/值域之后候选属性最多这么多,再多就不判。
+const CANDIDATE_LIMIT: usize = 60;
+
+/// 一票:这条签名选了哪个属性、哪个方向(None = 没有属性对得上)。
+type Vote = Option<(String, Direction)>;
+
+/// 签名两端的类落在属性声明的域/值域里(没声明的不限,没绑到类的一端只被没声明的
+/// 一端接受);正反两个方向都算。
+fn fits(p: &RelationTypeView, sig: &PhraseSignature) -> bool {
+ let within = |declared: &[Uuid], class: Option<Uuid>| -> bool {
+ declared.is_empty() || class.is_some_and(|c| declared.contains(&c))
+ };
+ if sig.object_is_value {
+ p.kind == "attribute" && within(&p.domains, sig.subject_type_id)
+ } else {
+ p.kind == "relation"
+ && ((within(&p.domains, sig.subject_type_id) && within(&p.ranges, sig.object_type_id))
+ || (within(&p.domains, sig.object_type_id)
+ && within(&p.ranges, sig.subject_type_id)))
+ }
+}
+
+/// 对一个库跑一遍:新出现的和过期的签名各判一次。
+pub async fn align_phrases(state: &AppState, kb_id: Uuid) -> anyhow::Result<()> {
+ let pool = &state.pool;
+ let kb = utopia_store::kbs::get(pool, kb_id).await?;
+ let settings = utopia_store::settings::get(pool, kb.workspace_id)
+ .await?
+ .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align phrases"))?;
+ let client = llm_util::chat_client(&settings)
+ .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align phrases"))?;
+ // 一个库同时只跑一份,理由同类别词对齐(并行跑会把端点打出 502)
+ let mut guard = pool.acquire().await?;
+ let locked: bool =
+ sqlx::query_scalar("SELECT pg_try_advisory_lock(hashtext('align_phrases'), hashtext($1))")
+ .bind(kb_id.to_string())
+ .fetch_one(&mut *guard)
+ .await?;
+ if !locked {
+ // 正在跑的那份结束时会自己看一眼有没有新东西(见 align_phrases_locked 末尾);这里
+ // 不排——排回去会和跑着的那份互相踢成死循环
+ tracing::info!(%kb_id, "短语对齐已有一份在跑,这次跳过");
+ return Ok(());
+ }
+ let result = align_phrases_locked(state, kb_id, &settings, &client).await;
+ let _ = sqlx::query("SELECT pg_advisory_unlock(hashtext('align_phrases'), hashtext($1))")
+ .bind(kb_id.to_string())
+ .execute(&mut *guard)
+ .await;
+ result
+}
+
+async fn align_phrases_locked(
+ state: &AppState,
+ kb_id: Uuid,
+ settings: &utopia_core::models::LlmSettings,
+ client: &utopia_llm::LlmClient,
+) -> anyhow::Result<()> {
+ let pool = &state.pool;
+ let run_started = chrono::Utc::now();
+ let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
+ let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
+ let class_key: HashMap<Uuid, &str> = classes.iter().map(|c| (c.id, c.key.as_str())).collect();
+ let by_key: HashMap<&str, &RelationTypeView> =
+ props.iter().map(|p| (p.key.as_str(), p)).collect();
+ let sigs = phrase_bindings::signatures(pool, kb_id).await?;
+ let existing: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
+ .await?
+ .into_iter()
+ .map(|b| (b.key(), b))
+ .collect();
+ let stale: HashSet<_> = phrase_bindings::stale(pool, kb_id)
+ .await?
+ .into_iter()
+ .map(|b| b.key())
+ .collect();
+ let todo: Vec<&PhraseSignature> = sigs
+ .iter()
+ .filter(|s| match existing.get(&s.key()) {
+ None => true,
+ Some(b) => b.decided_by != "person" && stale.contains(&s.key()),
+ })
+ .collect();
+ let attempted: HashSet<_> = todo.iter().map(|s| s.key()).collect();
+ tracing::info!(%kb_id, signatures = sigs.len(), to_decide = todo.len(), properties = props.len(), "短语对齐开始");
+
+ // 没有属性可绑:每条都是「没有」;属性出现后 `stale` 会把它们再交回来
+ if props.is_empty() {
+ for s in &todo {
+ phrase_bindings::decide(
+ pool,
+ kb_id,
+ s,
+ Decision {
+ relation_type_id: None,
+ direction: None,
+ status: "none",
+ votes: &serde_json::json!({ "reason": "no properties" }),
+ decided_by: "agent",
+ },
+ )
+ .await?;
+ }
+ return Ok(());
+ }
+
+ let keys_of = |ids: &[Uuid]| -> Vec<&str> {
+ ids.iter()
+ .filter_map(|id| class_key.get(id).copied())
+ .collect()
+ };
+ let (mut bound, mut none, mut undecided, mut skipped) = (0usize, 0usize, 0usize, 0usize);
+ // 调用或解析失败的批次:这轮跳过,结束时自己再排一次
+ let mut failed = 0usize;
+ for batch in todo.chunks(BATCH) {
+ let cands: Vec<Vec<&RelationTypeView>> = batch
+ .iter()
+ .map(|s| {
+ let fitting: Vec<&RelationTypeView> = props.iter().filter(|p| fits(p, s)).collect();
+ if fitting.len() > CANDIDATE_LIMIT {
+ Vec::new()
+ } else {
+ fitting
+ }
+ })
+ .collect();
+ let mut votes: Vec<(Vote, Vote)> = vec![(None, None); batch.len()];
+ let mut answered = vec![(false, false); batch.len()];
+ for pass in 0..2 {
+ let items: Vec<PhraseItem<'_>> = batch
+ .iter()
+ .enumerate()
+ .filter(|(i, _)| !cands[*i].is_empty())
+ .map(|(i, s)| {
+ let mut list: Vec<&RelationTypeView> = cands[i].clone();
+ if pass == 1 {
+ list.reverse();
+ }
+ PhraseItem {
+ id: i as i64,
+ phrase: &s.phrase,
+ subject_class: s.subject_type_key.as_deref(),
+ object_class: s.object_type_key.as_deref(),
+ object_is_value: s.object_is_value,
+ statement_count: s.count,
+ examples: &s.examples,
+ quotes: &s.quotes,
+ candidates: list
+ .iter()
+ .map(|p| PropertyCandidate {
+ key: &p.key,
+ label: &p.label,
+ description: &p.description,
+ kind: &p.kind,
+ domains: keys_of(&p.domains),
+ ranges: keys_of(&p.ranges),
+ })
+ .collect(),
+ }
+ })
+ .collect();
+ if items.is_empty() {
+ continue;
+ }
+ let messages = build_phrase_messages(&items);
+ let reply =
+ match chat_retrying_rate_limits_at(state, settings, client, &messages, Some(0.0))
+ .await
+ {
+ Ok(r) => r,
+ Err(e) => {
+ tracing::warn!(%kb_id, error = %e, "短语对齐调用失败,这一批留到下次");
+ failed += 1;
+ continue;
+ }
+ };
+ let (choices, malformed) = match parse_phrase_response(&reply, &items) {
+ Ok(x) => x,
+ Err(e) => {
+ tracing::warn!(%kb_id, error = %e, "短语对齐回复解析失败,这一批留到下次");
+ failed += 1;
+ continue;
+ }
+ };
+ skipped += malformed;
+ for c in choices {
+ let Ok(i) = usize::try_from(c.id) else {
+ continue;
+ };
+ if let Some(slot) = votes.get_mut(i) {
+ if pass == 0 {
+ slot.0 = c.property;
+ answered[i].0 = true;
+ } else {
+ slot.1 = c.property;
+ answered[i].1 = true;
+ }
+ }
+ }
+ }
+ for (i, s) in batch.iter().enumerate() {
+ if cands[i].is_empty() {
+ skipped += 1;
+ continue;
+ }
+ let (a, b) = &votes[i];
+ let (ans_a, ans_b) = answered[i];
+ if !ans_a || !ans_b {
+ // 有一票没答到:不下结论,下次再问
+ continue;
+ }
+ let show = |v: &Vote| {
+ v.as_ref()
+ .map(|(k, d)| serde_json::json!({ "property": k, "direction": d.as_str() }))
+ .unwrap_or(serde_json::Value::Null)
+ };
+ let record = serde_json::json!({ "first": show(a), "second": show(b) });
+ if a != b {
+ phrase_bindings::decide(
+ pool,
+ kb_id,
+ s,
+ Decision {
+ relation_type_id: None,
+ direction: None,
+ status: "undecided",
+ votes: &record,
+ decided_by: "agent",
+ },
+ )
+ .await?;
+ undecided += 1;
+ continue;
+ }
+ match a
+ .as_ref()
+ .and_then(|(k, d)| by_key.get(k.as_str()).map(|p| (p, *d)))
+ {
+ Some((p, d)) => {
+ if phrase_bindings::decide(
+ pool,
+ kb_id,
+ s,
+ Decision {
+ relation_type_id: Some(p.id),
+ direction: Some(d.as_str()),
+ status: "bound",
+ votes: &record,
+ decided_by: "agent",
+ },
+ )
+ .await?
+ {
+ bound += 1;
+ }
+ }
+ None => {
+ if phrase_bindings::decide(
+ pool,
+ kb_id,
+ s,
+ Decision {
+ relation_type_id: None,
+ direction: None,
+ status: "none",
+ votes: &record,
+ decided_by: "agent",
+ },
+ )
+ .await?
+ {
+ none += 1;
+ }
+ }
+ }
+ }
+ }
+ tracing::info!(%kb_id, bound, none, undecided, skipped, failed, "短语对齐完成");
+ // 这一轮跑着的时候世界没停:新文档带来新签名,改了的属性让刚判的绑定过期,本轮没排上
+ // 的触发也都落在这里。有失败的批次、有没试过的新签名、有本轮判完又过期的绑定,就再排
+ // 一次
+ let again = failed > 0
+ || phrase_bindings::signatures(pool, kb_id)
+ .await?
+ .iter()
+ .any(|s| !attempted.contains(&s.key()) && !existing.contains_key(&s.key()))
+ || phrase_bindings::stale(pool, kb_id)
+ .await?
+ .iter()
+ .any(|b| b.decided_by != "person" && b.decided_at >= run_started);
+ if again {
+ utopia_store::jobs::enqueue_unless_queued(
+ pool,
+ "align_phrases",
+ serde_json::json!({ "kb_id": kb_id }),
+ )
+ .await?;
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn view(kind: &str, domains: Vec<Uuid>, ranges: Vec<Uuid>) -> RelationTypeView {
+ RelationTypeView {
+ id: Uuid::now_v7(),
+ key: "p".into(),
+ label: "p".into(),
+ temporal: "state".into(),
+ functional: false,
+ inverse_functional: false,
+ is_transitive: false,
+ is_symmetric: false,
+ is_asymmetric: false,
+ is_irreflexive: false,
+ inverse_of: None,
+ sub_property_of: None,
+ builtin: false,
+ description: String::new(),
+ kind: kind.into(),
+ domains,
+ ranges,
+ datatype: None,
+ unit: None,
+ qualifiers: Vec::new(),
+ usage: 0,
+ }
+ }
+
+ fn sig(subject: Option<Uuid>, object: Option<Uuid>, value: bool) -> PhraseSignature {
+ PhraseSignature {
+ phrase: "x".into(),
+ subject_type_id: subject,
+ subject_type_key: None,
+ object_type_id: object,
+ object_type_key: None,
+ object_is_value: value,
+ count: 1,
+ examples: Vec::new(),
+ quotes: Vec::new(),
+ }
+ }
+
+ /// 域/值域筛候选:声明了的要落在里面(正反都算),没声明的不限,类为空的一端不限
+ #[test]
+ fn a_property_fits_a_signature_by_its_declared_ends_in_either_direction() {
+ let (org, place, person) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let hq = view("relation", vec![org], vec![place]);
+ assert!(fits(&hq, &sig(Some(org), Some(place), false)));
+ assert!(fits(&hq, &sig(Some(place), Some(org), false)), "反向也算");
+ assert!(!fits(&hq, &sig(Some(person), Some(place), false)));
+ assert!(
+ !fits(&hq, &sig(None, Some(place), false)),
+ "没绑到类的一端不算落在声明的域里"
+ );
+ let any_to_place = view("relation", vec![], vec![place]);
+ assert!(
+ fits(&any_to_place, &sig(None, Some(place), false)),
+ "没声明的一端接受没绑到类的"
+ );
+ assert!(!fits(&hq, &sig(Some(org), None, true)), "关系不接字面值");
+ let open = view("relation", vec![], vec![]);
+ assert!(
+ fits(&open, &sig(Some(person), Some(person), false)),
+ "没声明就不限"
+ );
+ let revenue = view("attribute", vec![org], vec![]);
+ assert!(fits(&revenue, &sig(Some(org), None, true)));
+ assert!(!fits(&revenue, &sig(Some(person), None, true)));
+ assert!(
+ !fits(&revenue, &sig(Some(org), Some(place), false)),
+ "属性只接字面值"
+ );
+ }
+}
diff --git a/crates/utopia-server/src/type_alignment.rs b/crates/utopia-server/src/type_alignment.rs
index a032db48..975987d4 100644
--- a/crates/utopia-server/src/type_alignment.rs
+++ b/crates/utopia-server/src/type_alignment.rs
@@ -90,6 +90,7 @@ pub async fn align_types(state: &AppState, kb_id: Uuid) -> anyhow::Result<()> {
.fetch_one(&mut *guard)
.await?;
if !locked {
+ // 正在跑的那份结束时会自己看一眼有没有新东西(见 align_types_locked 末尾);这里不排
tracing::info!(%kb_id, "类别词对齐已有一份在跑,这次跳过");
return Ok(());
}
@@ -108,6 +109,7 @@ async fn align_types_locked(
client: &utopia_llm::LlmClient,
) -> anyhow::Result<()> {
let pool = &state.pool;
+ let run_started = chrono::Utc::now();
let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
let by_id: HashMap<Uuid, &EntityType> = classes.iter().map(|c| (c.id, c)).collect();
let by_key: HashMap<&str, &EntityType> = classes.iter().map(|c| (c.key.as_str(), c)).collect();
@@ -129,6 +131,7 @@ async fn align_types_locked(
Some(b) => b.decided_by != "person" && stale.contains(&s.kind_word),
})
.collect();
+ let attempted: HashSet<String> = todo.iter().map(|s| s.kind_word.clone()).collect();
tracing::info!(%kb_id, kind_words = sigs.len(), to_decide = todo.len(), classes = classes.len(), "类别词对齐开始");
// 没有类可绑:每个词都是「没有」,并提成建议;类出现后 `stale` 会把它们再交回来
@@ -157,6 +160,8 @@ async fn align_types_locked(
}
let (mut bound, mut none, mut undecided, mut skipped) = (0usize, 0usize, 0usize, 0usize);
+ // 调用或解析失败的批次:这轮跳过,结束时自己再排一次,不等下一篇文档来排
+ let mut failed = 0usize;
for batch in todo.chunks(BATCH) {
let cands = candidates_for(state, kb_id, batch, &classes).await?;
// 两票:第二票把候选倒过来给,防止「选第一个」这种顺序偏好冒充一致
@@ -201,6 +206,7 @@ async fn align_types_locked(
Ok(r) => r,
Err(e) => {
tracing::warn!(%kb_id, error = %e, "类别词对齐调用失败,这一批留到下次");
+ failed += 1;
continue;
}
};
@@ -208,6 +214,7 @@ async fn align_types_locked(
Ok(x) => x,
Err(e) => {
tracing::warn!(%kb_id, error = %e, "类别词对齐回复解析失败,这一批留到下次");
+ failed += 1;
continue;
}
};
@@ -299,9 +306,40 @@ async fn align_types_locked(
}
}
}
- tracing::info!(%kb_id, bound, none, undecided, skipped, "类别词对齐完成");
+ tracing::info!(%kb_id, bound, none, undecided, skipped, failed, "类别词对齐完成");
if bound > 0 {
state.emit_graph(kb_id);
}
+ // 同短语对齐:失败过、来了没试过的新词、本轮判完的又过期了,就再排一次
+ let again = failed > 0 || {
+ let stale_now: HashSet<String> = type_bindings::stale(pool, kb_id)
+ .await?
+ .into_iter()
+ .collect();
+ type_bindings::signatures(pool, kb_id)
+ .await?
+ .iter()
+ .any(|s| !attempted.contains(&s.kind_word) && !existing.contains_key(&s.kind_word))
+ || type_bindings::bindings(pool, kb_id).await?.iter().any(|b| {
+ b.decided_by != "person"
+ && b.decided_at >= run_started
+ && stale_now.contains(&b.kind_word)
+ })
+ };
+ if again {
+ utopia_store::jobs::enqueue_unless_queued(
+ pool,
+ "align_types",
+ serde_json::json!({ "kb_id": kb_id }),
+ )
+ .await?;
+ }
+ // 两端的类定了,短语的签名才定:短语对齐排在它后面
+ utopia_store::jobs::enqueue_unless_queued(
+ pool,
+ "align_phrases",
+ serde_json::json!({ "kb_id": kb_id }),
+ )
+ .await?;
Ok(())
}
diff --git a/crates/utopia-store/src/lib.rs b/crates/utopia-store/src/lib.rs
index bafa7f74..93af005e 100644
--- a/crates/utopia-store/src/lib.rs
+++ b/crates/utopia-store/src/lib.rs
@@ -27,6 +27,7 @@ pub mod ontology;
pub mod palette;
pub mod paths;
pub mod pending;
+pub mod phrase_bindings;
pub mod reasoning;
pub mod record_axis;
pub mod resolution;
diff --git a/crates/utopia-store/src/ontology.rs b/crates/utopia-store/src/ontology.rs
index cc425e41..5b96f2eb 100644
--- a/crates/utopia-store/src/ontology.rs
+++ b/crates/utopia-store/src/ontology.rs
@@ -661,7 +661,7 @@ pub async fn update_relation_type(
unit = CASE WHEN kind = 'attribute' THEN $9 ELSE unit END,
is_transitive = $10, is_symmetric = $11,
is_asymmetric = $12, is_irreflexive = $13,
- inverse_of = $14, sub_property_of = $15
+ inverse_of = $14, sub_property_of = $15, updated_at = now()
WHERE id = $2 AND kb_id = $1",
)
.bind(kb_id)
diff --git a/crates/utopia-store/src/phrase_bindings.rs b/crates/utopia-store/src/phrase_bindings.rs
new file mode 100644
index 00000000..09fb2227
--- /dev/null
+++ b/crates/utopia-store/src/phrase_bindings.rs
@@ -0,0 +1,276 @@
+//! 关系短语按签名绑到属性的账本侧(0044 决定 3 的第二片,见 0066)。
+//!
+//! 开放陈述的关系是文档自己的短语(`facts.phrase`),不选属性。这里做三件事:数出一个
+//! 库里有哪些签名(短语 × 主语的类 × 宾语的类或「值」),各带几条例句;记下每个签名判成
+//! 了什么(绑定)并判哪些过期了;给下一片(物化)一张「签名 → 属性、方向」的表。判定
+//! 本身——问模型、两票一致才绑——在 server 的 `phrase_alignment` 里,这里不认识模型。
+//!
+//! 短语的归一同类别词:空白折成一个空格、去两端、小写;[`normalize`] 与 [`PHRASE_SQL`]
+//! 必须说同一件事。
+
+use chrono::{DateTime, Utc};
+use sqlx::PgPool;
+use utopia_core::{AppError, AppResult};
+use uuid::Uuid;
+
+/// SQL 侧的归一:与 [`normalize`] 一致。`$col` 由调用处替换成列名。
+const PHRASE_SQL: &str = "lower(btrim(regexp_replace($col, '\\s+', ' ', 'g')))";
+
+fn phrase_sql(col: &str) -> String {
+ PHRASE_SQL.replace("$col", col)
+}
+
+/// 归一一个短语:空白折成一个空格、去两端、小写。"Acquired " 与 "acquired" 是一个短语。
+pub fn normalize(phrase: &str) -> String {
+ phrase
+ .split_whitespace()
+ .collect::<Vec<_>>()
+ .join(" ")
+ .to_lowercase()
+}
+
+/// 一条签名:判它该绑到哪个属性时给模型看的全部。
+#[derive(Debug, Clone, sqlx::FromRow)]
+pub struct PhraseSignature {
+ /// 归一过的短语
+ pub phrase: String,
+ /// 主语的类(类别词还没绑到类时为空)
+ pub subject_type_id: Option<Uuid>,
+ pub subject_type_key: Option<String>,
+ /// 宾语的类;宾语是字面值时为空且 `object_is_value` 为真
+ pub object_type_id: Option<Uuid>,
+ pub object_type_key: Option<String>,
+ pub object_is_value: bool,
+ /// 这个签名下活着的开放陈述数
+ pub count: i64,
+ /// 例句:最多 3 条「主语 —短语→ 宾语」,每条跟着它自己的引文
+ pub examples: Vec<String>,
+ pub quotes: Vec<String>,
+}
+
+/// 库里每条 distinct 的签名:活着的开放陈述,按短语、两端的类、宾语是不是字面值分组。
+pub async fn signatures(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<PhraseSignature>> {
+ let sql = format!(
+ "WITH live AS (
+ SELECT f.id, {phrase} AS phrase,
+ s.type_id AS subject_type_id, o.type_id AS object_type_id,
+ (f.object_id IS NULL) AS object_is_value,
+ s.canonical_name AS subject_name,
+ coalesce(o.canonical_name, f.object_value #>> '{{value}}', '') AS object_name,
+ f.phrase AS spelling, fe.chunk_id, fe.quote_start, fe.quote_end, f.recorded_at
+ FROM facts f
+ JOIN entities s ON s.id = f.subject_id
+ LEFT JOIN entities o ON o.id = f.object_id
+ LEFT JOIN fact_evidence fe ON fe.fact_id = f.id
+ WHERE f.kb_id = $1 AND f.layer = 'open' AND f.invalidated_at IS NULL
+ AND f.phrase IS NOT NULL AND btrim(f.phrase) <> ''
+ ),
+ grouped AS (
+ SELECT phrase, subject_type_id, object_type_id, object_is_value, count(*) AS count
+ FROM live GROUP BY phrase, subject_type_id, object_type_id, object_is_value
+ ),
+ picked AS (
+ SELECT g.phrase, g.subject_type_id, g.object_type_id, g.object_is_value,
+ l.subject_name || ' —' || l.spelling || '→ ' || l.object_name AS example,
+ coalesce(substr(c.text, l.quote_start + 1, l.quote_end - l.quote_start), '') AS quote,
+ row_number() OVER (PARTITION BY g.phrase, g.subject_type_id, g.object_type_id, g.object_is_value
+ ORDER BY l.recorded_at, l.id) AS rn
+ FROM grouped g
+ JOIN live l ON l.phrase = g.phrase
+ AND l.subject_type_id IS NOT DISTINCT FROM g.subject_type_id
+ AND l.object_type_id IS NOT DISTINCT FROM g.object_type_id
+ AND l.object_is_value = g.object_is_value
+ LEFT JOIN chunks c ON c.id = l.chunk_id
+ )
+ SELECT g.phrase, g.subject_type_id, st.key AS subject_type_key,
+ g.object_type_id, ot.key AS object_type_key, g.object_is_value, g.count,
+ ARRAY(SELECT p.example FROM picked p
+ WHERE p.phrase = g.phrase AND p.subject_type_id IS NOT DISTINCT FROM g.subject_type_id
+ AND p.object_type_id IS NOT DISTINCT FROM g.object_type_id
+ AND p.object_is_value = g.object_is_value AND p.rn <= 3 ORDER BY p.rn) AS examples,
+ ARRAY(SELECT p.quote FROM picked p
+ WHERE p.phrase = g.phrase AND p.subject_type_id IS NOT DISTINCT FROM g.subject_type_id
+ AND p.object_type_id IS NOT DISTINCT FROM g.object_type_id
+ AND p.object_is_value = g.object_is_value AND p.rn <= 3 ORDER BY p.rn) AS quotes
+ FROM grouped g
+ LEFT JOIN entity_types st ON st.id = g.subject_type_id
+ LEFT JOIN entity_types ot ON ot.id = g.object_type_id
+ ORDER BY g.count DESC, g.phrase",
+ phrase = phrase_sql("f.phrase")
+ );
+ Ok(sqlx::query_as(&sql).bind(kb_id).fetch_all(pool).await?)
+}
+
+/// 一条签名判成了什么。
+#[derive(Debug, Clone, sqlx::FromRow)]
+pub struct Binding {
+ pub phrase: String,
+ pub subject_type_id: Option<Uuid>,
+ pub object_type_id: Option<Uuid>,
+ pub object_is_value: bool,
+ /// `status = 'bound'` 时有值
+ pub relation_type_id: Option<Uuid>,
+ /// forward / reverse,`status = 'bound'` 时有值
+ pub direction: Option<String>,
+ /// bound / none / undecided
+ pub status: String,
+ pub decided_at: DateTime<Utc>,
+ /// agent / person
+ pub decided_by: String,
+}
+
+impl Binding {
+ /// 和签名对上的键:短语 + 两端的类 + 宾语是不是字面值
+ pub fn key(&self) -> (String, Option<Uuid>, Option<Uuid>, bool) {
+ (
+ self.phrase.clone(),
+ self.subject_type_id,
+ self.object_type_id,
+ self.object_is_value,
+ )
+ }
+}
+
+impl PhraseSignature {
+ pub fn key(&self) -> (String, Option<Uuid>, Option<Uuid>, bool) {
+ (
+ self.phrase.clone(),
+ self.subject_type_id,
+ self.object_type_id,
+ self.object_is_value,
+ )
+ }
+}
+
+/// 库里全部绑定。
+pub async fn bindings(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
+ Ok(sqlx::query_as(
+ "SELECT phrase, subject_type_id, object_type_id, object_is_value,
+ relation_type_id, direction, status, decided_at, decided_by
+ FROM phrase_bindings WHERE kb_id = $1 ORDER BY phrase",
+ )
+ .bind(kb_id)
+ .fetch_all(pool)
+ .await?)
+}
+
+/// 不再成立的绑定:绑到的属性在判定之后改过;或判成 none / undecided 之后库里长出了
+/// 新属性。属性或类被删了的,行已随级联消失。
+pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
+ Ok(sqlx::query_as(
+ "SELECT b.phrase, b.subject_type_id, b.object_type_id, b.object_is_value,
+ b.relation_type_id, b.direction, b.status, b.decided_at, b.decided_by
+ FROM phrase_bindings b
+ LEFT JOIN relation_types r ON r.id = b.relation_type_id
+ WHERE b.kb_id = $1
+ AND ((b.status = 'bound' AND r.updated_at > b.decided_at)
+ OR (b.status IN ('none', 'undecided')
+ AND b.decided_at < (SELECT max(created_at) FROM relation_types
+ WHERE kb_id = $1)))
+ ORDER BY b.phrase",
+ )
+ .bind(kb_id)
+ .fetch_all(pool)
+ .await?)
+}
+
+/// 一次判定要写的东西。
+pub struct Decision<'a> {
+ pub relation_type_id: Option<Uuid>,
+ /// forward / reverse
+ pub direction: Option<&'a str>,
+ /// bound / none / undecided
+ pub status: &'a str,
+ pub votes: &'a serde_json::Value,
+ /// agent / person
+ pub decided_by: &'a str,
+}
+
+/// 记下一条签名的判定(有则改)。返回是否写入了。
+///
+/// **人的判定不被代理覆盖**:已有行是人判的而这次是代理,原样留着、返回 false。
+/// 反过来人可以改代理的。
+pub async fn decide(
+ pool: &PgPool,
+ kb_id: Uuid,
+ sig: &PhraseSignature,
+ d: Decision<'_>,
+) -> AppResult<bool> {
+ if !matches!(d.status, "bound" | "none" | "undecided") {
+ return Err(AppError::Validation(format!(
+ "unknown binding status {:?}",
+ d.status
+ )));
+ }
+ let bound = d.status == "bound";
+ if bound != d.relation_type_id.is_some() || bound != d.direction.is_some() {
+ return Err(AppError::Validation(
+ "a bound signature needs a property and a direction and an unbound one must not have them".into(),
+ ));
+ }
+ if let Some(dir) = d.direction {
+ if !matches!(dir, "forward" | "reverse") {
+ return Err(AppError::Validation(format!("unknown direction {dir:?}")));
+ }
+ }
+ if !matches!(d.decided_by, "agent" | "person") {
+ return Err(AppError::Validation(format!(
+ "unknown decider {:?}",
+ d.decided_by
+ )));
+ }
+ let phrase = normalize(&sig.phrase);
+ if phrase.is_empty() {
+ return Err(AppError::Validation("an empty phrase binds nothing".into()));
+ }
+ let res = sqlx::query(
+ "INSERT INTO phrase_bindings
+ (id, kb_id, phrase, subject_type_id, object_type_id, object_is_value,
+ relation_type_id, direction, status, votes, statement_count, examples,
+ decided_at, decided_by)
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, now(), $13)
+ ON CONFLICT (kb_id, phrase, subject_type_id, object_type_id, object_is_value) DO UPDATE
+ SET relation_type_id = EXCLUDED.relation_type_id,
+ direction = EXCLUDED.direction,
+ status = EXCLUDED.status,
+ votes = EXCLUDED.votes,
+ statement_count = EXCLUDED.statement_count,
+ examples = EXCLUDED.examples,
+ decided_at = now(),
+ decided_by = EXCLUDED.decided_by
+ WHERE NOT (phrase_bindings.decided_by = 'person' AND EXCLUDED.decided_by = 'agent')",
+ )
+ .bind(Uuid::now_v7())
+ .bind(kb_id)
+ .bind(&phrase)
+ .bind(sig.subject_type_id)
+ .bind(if sig.object_is_value {
+ None
+ } else {
+ sig.object_type_id
+ })
+ .bind(sig.object_is_value)
+ .bind(d.relation_type_id)
+ .bind(d.direction)
+ .bind(d.status)
+ .bind(d.votes)
+ .bind(i32::try_from(sig.count).unwrap_or(i32::MAX))
+ .bind(&sig.examples)
+ .bind(d.decided_by)
+ .execute(pool)
+ .await?;
+ Ok(res.rows_affected() > 0)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::normalize;
+
+ #[test]
+ fn a_phrase_is_one_phrase_however_spaced_or_cased() {
+ assert_eq!(normalize(" Was Designed By "), "was designed by");
+ assert_eq!(normalize("Revenue"), "revenue");
+ assert_eq!(normalize("细化解读"), "细化解读");
+ assert_eq!(normalize(" "), "");
+ }
+}
diff --git a/docs/design/ontology.md b/docs/design/ontology.md
index bd900770..6ea78dea 100644
--- a/docs/design/ontology.md
+++ b/docs/design/ontology.md
@@ -49,6 +49,31 @@ classes of context neighbours, interleaved and never scored together; a class in
subtree applied on its own, a cross-axis class sent to a person, each pair acknowledged once) runs
from the ontology page; extraction no longer enqueues it [0001, 0016, #736].
+**A relation phrase binds to a property per signature** [0044 cut 2, #751]. A signature is a
+phrase as the documents wrote it, the class of its subject and the class of its object, or "value"
+when the object is a figure, a title or a status; the classes come from the kind-word bindings, and
+a side whose kind word is bound to no class is its own signature. Each signature is decided once,
+after the kind words, by the same shape as [#741]: candidates are the properties whose declared
+domain and range admit the two ends in either direction (an undeclared end admits anything), the
+model sees the signature with three of its statements and their quotes, and two votes with the
+candidates in opposite orders must agree on the property and the direction (forward when the
+statement's subject is the property's subject, reverse when its object is) for the signature to
+bind. A signature the votes disagree on is `undecided` for the alignment queue of #725; one with no
+fitting property is `none`, its statements stay in the open graph and it counts toward the
+workbench's suggestions. Bindings live in `phrase_bindings` and go stale when the property they
+bound to changes or a property is added; a person's decision is never overwritten by the agent. On
+the 25-document batch with a hand-written ontology of 14 classes and 28 properties, and 60 of
+400 kind words bound, 423 signatures cover 861 statements: 36 bind (184 statements), 110 bind to
+nothing, 1 splits the votes and 276 have no admissible property because an end is unbound; a
+judge reading the chunk finds 95% of the resulting typed facts stated by the document, 4% worded
+wrongly and 1% not stated. Offering every property to an unbound end raised coverage to 85
+signatures and dropped the judge to 87%, and on the NVDA releases, where 15 of 230 kind words
+bind, to 59%: the generic "value" attribute swallowed every cash-flow row. Coverage therefore
+follows the kind-word bindings and the ontology's size, not the binder. What still goes wrong is
+a phrase that carries part of the value ("下降 1.4%" bound to a change property loses its sign)
+and a table section read as a change ("changes in operating assets › accounts payable"). Nothing is materialised yet: the typed rows with `from_statement_id` are
+the next slice.
+
**Argument order is enforced, participation is guided.** A declared domain or range shapes
candidates and never discards a fact; argument order is the key's encoding convention, so a fact
whose subject violates the domain while the object fits is swapped by the signature and marked
@@ -102,10 +127,10 @@ the prompt, a description is read by people and by the aligner.
## Proposed and not built
-- **Alignment** (0044 cut 2): a table of signature (phrase, subject classes, object classes) to
- property and direction with confidence and ontology version; implication rules proposed by the
- aligner, approved on the workbench, executed by code with cached readings; typed rows carrying
- `from_statement_id`; recomputation per changed signature. The prototype aligner reached 14.7% and
+- **Alignment** (0044 cut 2), the rest: typed rows carrying `from_statement_id`, materialised
+ from bound signatures and recomputed per changed signature; implication rules proposed by the
+ aligner, approved on the workbench, executed by code with cached readings (the sign of "下降
+ 1.4%" is such a reading); a signature that tells a figure from words on the value side. The prototype aligner reached 14.7% and
12.1% of gold recall in two runs against 15.5% for the withdrawn bound pass, so the bar for cut 2
is parity over two clean runs [0044, #729].
- **The workbench** (0044 cut 5): the ontology page fed by suggestions from the open graph (frequent
diff --git a/docs/design/prior-work.md b/docs/design/prior-work.md
index 9ad31333..3593d222 100644
--- a/docs/design/prior-work.md
+++ b/docs/design/prior-work.md
@@ -189,9 +189,8 @@ built.
argument types [Dutta 2015]; Angeli's KBP mapping is conditioned on the type signature
[Angeli 2015]; typed markers lift relation extraction [Ling 2012, Zhong 2021]; ODKE+ exposes only
the type's slice of the ontology [Khorshidi 2025]; iText2KG lists typing as its missing
- ingredient [Lairgi 2024]. Kind words bind before relation phrases [0044 cut 2]. *Open:* the
- phrase binding reads the classes at both ends, and the (class, class) signature is part of a
- phrase binding's key.
+ ingredient [Lairgi 2024]. Kind words bind before relation phrases [0044 cut 2]; the phrase binding reads the classes at
+ both ends and the (class, class) signature is part of its key (#751).
12. **Precision is lost in the binding, not in the extraction.** Of the mapping errors in the
three-hour KBP system, 31% were definition mismatch and 23% over-generalized rules against 15%
open-extraction errors [Soderland 2013]; the top hundred predicates cover only 57 to 82% of an
diff --git a/migrations/0066_a_phrase_binds_to_a_property.sql b/migrations/0066_a_phrase_binds_to_a_property.sql
new file mode 100644
index 00000000..0f0c1191
--- /dev/null
+++ b/migrations/0066_a_phrase_binds_to_a_property.sql
@@ -0,0 +1,56 @@
+-- 一条关系短语按签名绑到一个属性(0044 决定 3 的第二片:签名 = 短语 × 主语的类 ×
+-- 宾语的类,宾语是字面值时记「值」)。
+--
+-- 开放陈述的关系是文档自己的短语(`facts.phrase`:acquired、「细化解读」、Revenue),
+-- 不选属性。属性是本体的事。一个库里 distinct 的签名比陈述少得多——同一个短语在同一对
+-- 类之间出现多少次,只判一次:判了记在 `phrase_bindings` 里,本体一改只重判过期的
+-- (绑到的属性判定后改过 `relation_types.updated_at`;判成 none / undecided 之后长出了
+-- 新属性 `relation_types.created_at`)。绑上的签名下的陈述算成类型化事实,那是下一片
+-- (物化视图,`facts.from_statement_id`);这一片只记判定。
+--
+-- 两端的类来自类别词绑定(`entities.type_id`);一端没有类的签名照样判——文档的例句
+-- 和引文就是证据——但类为空的签名和类为某个类的签名是两条不同的签名。
+-- `direction`:forward 是陈述的主语就是属性的主语,reverse 是反过来(「owns」绑到
+-- subsidiary_of)。人的判定不被代理覆盖。
+
+-- 属性改过没有,从前也只有 created_at;绑定按它判过期,每条 UPDATE relation_types 都摸一下
+ALTER TABLE relation_types ADD COLUMN updated_at TIMESTAMPTZ NOT NULL DEFAULT now();
+
+CREATE TABLE phrase_bindings (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ -- 归一过的短语:空白折成一个空格、小写、去两端空白(同 type_bindings.kind_word)
+ phrase TEXT NOT NULL,
+ -- 两端的类;空表示那一端的类别词还没绑到类(或宾语是字面值)。类删了绑定跟着走
+ subject_type_id UUID REFERENCES entity_types(id) ON DELETE CASCADE,
+ object_type_id UUID REFERENCES entity_types(id) ON DELETE CASCADE,
+ -- 宾语是字面值(金额、百分比、称号)而不是一样东西
+ object_is_value BOOLEAN NOT NULL DEFAULT false,
+ -- status 为 none / undecided 时为空;属性删了绑定跟着走
+ relation_type_id UUID REFERENCES relation_types(id) ON DELETE CASCADE,
+ -- forward:陈述的主语是属性的主语;reverse:陈述的宾语是
+ direction TEXT CHECK (direction IN ('forward', 'reverse')),
+ -- bound 绑上了
+ -- none 没有属性对得上:陈述留在开放图谱,签名计入工作台的建议
+ -- undecided 两票不一致,留给审核(#725 对齐队列)
+ status TEXT NOT NULL CHECK (status IN ('bound', 'none', 'undecided')),
+ -- 得出这个判定的那几票
+ votes JSONB,
+ -- 判定时这个签名下有几条陈述,三条例句——工作台按它排建议
+ statement_count INTEGER NOT NULL DEFAULT 0,
+ examples TEXT[] NOT NULL DEFAULT '{}',
+ decided_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 人的判定不被代理覆盖
+ decided_by TEXT NOT NULL DEFAULT 'agent' CHECK (decided_by IN ('agent', 'person')),
+ -- 一个库里一条签名一行;类为空也是一种签名(NULLS NOT DISTINCT)
+ UNIQUE NULLS NOT DISTINCT (kb_id, phrase, subject_type_id, object_type_id, object_is_value),
+ -- 绑上了就得有属性和方向,没绑就都不能有
+ CONSTRAINT phrase_bindings_shape
+ CHECK ((status = 'bound') = (relation_type_id IS NOT NULL)
+ AND (status = 'bound') = (direction IS NOT NULL)),
+ -- 宾语是字面值的签名没有宾语类
+ CONSTRAINT phrase_bindings_value_has_no_class
+ CHECK (NOT object_is_value OR object_type_id IS NULL)
+);
+
+CREATE INDEX phrase_bindings_kb_status_idx ON phrase_bindings (kb_id, status);