学习有如母亲一般慈爱，它用纯洁和温柔的欢乐来哺育孩子，如果向它要求额外的报酬，也许就是罪过。—— 巴尔扎克

Semantica：让 AI 的上下文、决策与责任拥有一张可追溯的图

项目地址：https://github.com/semantica-agi/semantica

当 AI 开始参与越来越重要的工作，问题便不再只是“它能不能给出答案”。

更关键的问题变成了：

它知道什么？

它为什么会这样判断？

这条结论来自哪里？

此前发生过哪些相似决策？

当一项决策影响了后续流程，又该如何回溯它的因果链路？

Semantica 想做的，正是为这些问题提供一层可以被查询、被解释、被审计、被治理的图原生基础设施。

它将自己定位为面向上下文与可问责 AI 系统的图原生基础设施。这里的重点并不只是把文本变成向量，也不只是为模型堆叠一层记忆，而是把数据、实体、关系、规则、推理、决策、溯源和时间共同组织进一张能够持续生长的图里。

在这张图中，AI 的上下文不再是一段转瞬即逝的提示词，不再只是隐藏在向量索引里的相似片段，而是变成可以连接、遍历、追问和导出的知识结构。

从“记住内容”走向“理解关系”

许多 AI 系统能够检索相似文本，却很难完整解释信息之间的关系。

它们或许能找到一份合同、一条记录、一段对话，但当问题进一步变成“这个人和这项协议之间隔着哪些关系”“这项决定受到了哪些前置条件影响”“这个结论对应的原始来源是什么”时，单纯依赖向量相似度往往显得不够从容。

Semantica 提供的 Context Graph，试图成为传统 RAG 之外的一层结构化记忆。

它不只关注“什么内容相似”，也关注“什么事物彼此连接”“为什么连接”“这些关系在什么时候成立”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from semantica.context import ContextGraph, AgentContext
from semantica.vector_store import VectorStore

graph = ContextGraph(advanced_analytics=True)

graph.add_node("acme_corp", "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen", "Person", name="Alice Chen", role="CTO")
graph.add_node("contract_001", "Contract", value=2_400_000, currency="USD")

graph.add_edge("alice_chen", "acme_corp", edge_type="works_for", since="2019-03-01")
graph.add_edge("acme_corp", "contract_001", edge_type="party_to", signed="2024-01-15")

neighbors = graph.get_neighbors("acme_corp", hops=2)
snapshot = graph.state_at("2024-01-01")

vs = VectorStore(backend="faiss")
ctx = AgentContext(vector_store=vs, knowledge_graph=graph)

ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
retrieved = ctx.retrieve("who approved the Acme contract?")

在这里，节点承载类型化信息，边表达带有语义的关系，图遍历能够沿着连接向外扩展。上下文不再是一叠孤立的文本碎片，而像一座拥有道路、坐标与历史痕迹的城市。

让决策从瞬间消失的推断，变成可追问的对象

Semantica 最鲜明的一条主线，是 Decision Intelligence。

在许多系统中，决策可能只是一条日志，或者一次模型输出。它发生过，但很难被严谨地重新组织、查询和解释。

而在 Semantica 的设计里，决策是图中的一等对象。

一条决策可以记录自己的类别、场景、推理过程、结果、置信度和附加元数据。它还可以与前置原因、后续影响和相似历史决策建立连接。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

chain = graph.trace_decision_chain(decision_id)
similar = graph.find_similar_decisions("cloud vendor", max_results=5)
impact = graph.analyze_decision_impact(decision_id)
compliant = graph.check_decision_rules(
    {"category": "vendor_selection"}
)

这段流程中，记录决策只是开始。

之后，系统可以追踪完整的因果祖先链，查找历史上的相似先例，分析一项决策的下游影响，还可以通过规则检查它是否满足既定政策。

于是，“为什么做出这个决定”不再只能依赖某个模型临时生成一段解释，而能够回到图中的结构化记录里寻找答案。

因果关系，让决策链真正连起来

单独保存一系列决策还不够。真正让决策具备可审计价值的，是它们之间的因果连接。

Semantica 支持将一个决策与它造成、影响或作为先例支撑的后续决策关联起来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

app_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"},
)

uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Underwriting review for A-7291",
    reasoning="DTI within policy; clean 36-month credit history",
    outcome="approved",
    confidence=0.94,
)

rate_id = graph.record_decision(
    category="interest_rate",
    scenario="Rate assignment for approved loan A-7291",
    outcome="rate_set_8.9pct",
    reasoning="Prime + 2.4% based on risk tier B2",
    confidence=0.99,
)

graph.add_causal_relationship(
    app_id,
    uw_id,
    relationship_type="CAUSED",
)

graph.add_causal_relationship(
    uw_id,
    rate_id,
    relationship_type="INFLUENCED",
)

chain = graph.trace_decision_chain(rate_id)
similar = graph.find_similar_decisions(
    "personal loan approval, 31% DTI",
    max_results=5,
)
impact = graph.analyze_decision_impact(uw_id)

当一个结果需要被回溯时，系统不必在一片零散记录中翻找。因果链条已经成为图的一部分。

这让“发生了什么”与“为什么发生”开始拥有同一份结构化表达。

不只采集数据，还要理解数据

知识图谱的旅程通常从原始数据开始。

文件、网页、数据库、接口、流数据、邮件、代码仓库、企业数据平台中的表格，它们格式不同、结构不同、语义不同，也经常彼此矛盾。

Semantica 将这条路径拆成一条端到端的知识管道：

1
2
3
Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
   → Knowledge Graph → Ontology · Reasoning · Provenance · Decisions → Enriched KG
   → Vector Store + Polyglot Graph Store → Export / Visualize / REST · MCP · CLI

从数据接入开始，信息会经历解析、规范化、切分、抽取、冲突检测、去重与图构建。

这条链路的意义在于，知识图谱并不是一个只在最后出现的存储目标。它更像整条数据处理流程中逐步形成的结构化结果。

面向多来源数据的统一接入

Semantica 提供统一的数据接入接口，覆盖文件、网页、数据库、API、流、邮件、Git 仓库、Parquet、Databricks、Snowflake 与 MCP 服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from semantica.ingest import FileIngestor, WebIngestor, ParquetIngestor, DBIngestor

docs = FileIngestor().ingest_directory(
    "./contracts/",
    recursive=True,
)

pages = WebIngestor().ingest_url(
    "https://example.com/reports/annual-2024.html"
)

records = ParquetIngestor().ingest(
    "./data/transactions.parquet"
)

rows = DBIngestor().ingest_database(
    connection_string="postgresql://user:pass@localhost/mydb",
    include_tables=["customer_events"],
    max_rows_per_table=50_000,
)

对于企业数据平台，Semantica 也提供了 Databricks 与 Snowflake 的接入能力。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from semantica.ingest import DatabricksIngestor, SnowflakeIngestor

databricks = DatabricksIngestor(
    host="https://adb-xxx.azuredatabricks.net",
    token="dapi-xxxxxxxx",
    http_path="/sql/1.0/warehouses/xxxxxxxx",
    catalog="main",
)

customers = databricks.ingest_table(
    "customers",
    limit=10_000,
)

table_lineage = databricks.get_table_lineage(
    "customers",
    catalog="main",
    schema="default",
)

snowflake = SnowflakeIngestor(
    account="myaccount",
    user="myuser",
    password="mypassword",
    warehouse="COMPUTE_WH",
    database="MYDB",
)

orders = snowflake.ingest_table(
    "ORDERS",
    limit=10_000,
)

数据进入系统后，并不会自动变成可信的知识。它还需要被拆解、识别、关联、验证与整理。

从文本中提取实体、关系、事件与三元组

当原始数据主要是文本时，真正的难题往往不是保存内容，而是识别内容中蕴含的结构。

谁是关键人物？

哪些组织发生了联系？

什么事件发生在什么时间？

一句自然语言描述能够拆解出哪些主体、谓词与客体？

Semantica 的语义抽取模块将命名实体识别、关系抽取、事件检测和三元组生成组织在一起。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
from semantica.semantic_extract import (
    NamedEntityRecognizer,
    RelationExtractor,
    EventDetector,
    TripletExtractor,
)

text = """
Anthropic CEO Dario Amodei announced a $7.3B Series E funding round in partnership
with Google and Spark Capital, valuing the company at $61.5B as of Q4 2024.
"""

ner = NamedEntityRecognizer(confidence_threshold=0.7)
entities = ner.extract_entities(text)

rel_extractor = RelationExtractor(
    confidence_threshold=0.6,
    bidirectional=True,
)
relations = rel_extractor.extract_relations(
    text,
    entities=entities,
)

events = EventDetector(
    extract_participants=True,
    extract_time=True,
).detect_events(text)

triplets = TripletExtractor(
    include_temporal=True,
    include_provenance=True,
).extract_triplets(text)

从一段文本中提取出的，不再只是可搜索的字词，而可以成为知识图谱中的实体、关系、事件和带有时间与溯源信息的三元组。

先面对冲突，再进入知识库

多来源数据最容易带来一个现实问题：同一个实体在不同来源里，可能有不同的职位、金额、时间或关系。

如果系统只是简单覆盖，知识库看似整洁，实则可能在悄悄丢失事实冲突。

Semantica 把冲突检测放在图谱构建之前，让相互矛盾的信息先被识别和标记。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
from semantica.conflicts import ConflictDetector, ConflictResolver, SourceTracker

entities_from_source_a = [
    {
        "id": "alice_chen",
        "role": "CTO",
        "salary": 250_000,
        "start_date": "2019-03-01",
    },
]

entities_from_source_b = [
    {
        "id": "alice_chen",
        "role": "VP Eng",
        "salary": 275_000,
        "start_date": "2019-03-01",
    },
]

detector = ConflictDetector()
conflicts = detector.detect_conflicts(
    entities_from_source_a + entities_from_source_b
)

resolver = ConflictResolver()

resolved = resolver.resolve_conflicts(
    conflicts,
    strategy="credibility_weighted",
)

tracker = SourceTracker()

tracker.register_source(
    "source_a",
    source_type="document",
    credibility_score=0.85,
)

tracker.register_source(
    "source_b",
    source_type="document",
    credibility_score=0.72,
)

这里可以处理值冲突、类型冲突、关系冲突、时间冲突与逻辑冲突，并支持基于可信度、最新时间或投票等策略进行处理。

一张能够承担上下文与决策责任的图，不能只收集事实，也必须能够正视事实之间的不一致。

实体去重，让同一个对象不再四处分身

知识图谱还会遇到另一个常见问题：同一个组织、人物或实体，可能因为拼写、简称、格式差异或来源不同而出现多个版本。

Semantica 提供实体解析与去重能力，通过阻塞、聚类和语义相似度识别重复对象，并支持保留溯源信息的合并。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
from semantica.deduplication import DuplicateDetector, EntityMerger

entities = [
    {
        "id": "e1",
        "name": "Acme Corporation",
        "domain": "acme.com",
    },
    {
        "id": "e2",
        "name": "Acme Corp.",
        "domain": "acme.com",
    },
    {
        "id": "e3",
        "name": "ACME Corp",
        "domain": "acme.co",
    },
    {
        "id": "e4",
        "name": "Globex Industries",
        "domain": "globex.com",
    },
]

detector = DuplicateDetector(
    similarity_threshold=0.75,
    use_clustering=True,
)

candidates = detector.detect_duplicates(entities)
groups = detector.detect_duplicate_groups(entities)

merger = EntityMerger(preserve_provenance=True)

ops = merger.merge_duplicates(
    entities,
    strategy="keep_most_complete",
)

history = merger.get_merge_history()

这让知识图谱有机会从“相同名字很多”的数据集合，逐步变成“同一实体拥有统一身份，同时保留来源脉络”的结构化知识空间。

图谱之上，运行确定性的推理

LLM 擅长生成，但在需要规则明确、过程可解释的场景中，确定性推理依然扮演重要角色。

Semantica 提供前向链推理、Rete 网络、Datalog 与 SPARQL 相关能力，让事实与规则可以在可解释的路径中产生结论。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
from semantica.reasoning import ReteEngine, Rule, Fact, RuleType

rete = ReteEngine()

rete.build_network([
    Rule(
        rule_id="aml_flag",
        name="Flag high-risk transactions",
        conditions=[
            {
                "field": "amount",
                "operator": ">",
                "value": 10_000,
            },
            {
                "field": "country",
                "operator": "in",
                "value": ["IR", "KP", "SY"],
            },
        ],
        conclusion="flag_for_compliance_review",
        rule_type=RuleType.IMPLICATION,
    ),
])

rete.add_fact(
    Fact(
        "tx_001",
        "transaction",
        [
            {
                "amount": 15_000,
                "country": "IR",
            },
        ],
    )
)

flagged = rete.match_patterns()

规则在这里不再只是散落在业务代码里的条件判断，而可以成为推理层的一部分。

与此同时，Datalog 可以用于递归图查询。

1
2
3
4
5
6
7
8
9
10
11
12
from semantica.reasoning import DatalogReasoner

engine = DatalogReasoner()

engine.add_fact("parent(tom, bob)")
engine.add_fact("parent(bob, ann)")
engine.add_fact("parent(ann, pat)")

engine.add_rule("ancestor(X, Y) :- parent(X, Y).")
engine.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")

ancestors = engine.query("ancestor(tom, ?X)")

当结论需要解释时，Semantica 还提供解释生成能力，让系统不仅给出结果，也能够呈现推理过程。

1
2
3
4
5
6
7
8
9
10
11
from semantica.reasoning import ExplanationGenerator, Reasoner

reasoner = Reasoner()

reasoner.add_fact("parent(tom, bob)")
reasoner.add_rule("ancestor(X, Y) :- parent(X, Y)")

result = reasoner.forward_chain()

explainer = ExplanationGenerator()
explanation = explainer.generate_explanation(result)

不让来源消失：每一个事实都可以追溯

在可问责 AI 的语境中，一个实体、一段关系或一项结论的来源，往往和结论本身一样重要。

Semantica 的溯源模块围绕 W3C PROV-O 记录实体和关系的来源信息，并支持查询谱系与追踪祖先链。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
from semantica.provenance import ProvenanceManager

prov = ProvenanceManager(
    storage_path="./provenance.db"
)

prov.track_entity(
    entity_id="acme_corp",
    source="contracts/acme_master_agreement_2024.pdf",
    metadata={
        "page": 1,
        "confidence": 0.97,
        "extractor": "NamedEntityRecognizer",
    },
)

prov.track_relationship(
    relationship_id="alice_works_for_acme",
    source="hr_records/employees_q1_2024.csv",
    metadata={
        "source_entity_id": "alice_chen",
        "target_entity_id": "acme_corp",
    },
)

lineage = prov.get_lineage("acme_corp")
trail = prov.trace_lineage("alice_chen")
entry = prov.get_provenance("acme_corp")

当系统被追问“这个信息从哪里来”时，答案不必依赖模糊的记忆，也不必靠人工回查原始文件。来源本身就是知识图谱中的重要组成部分。

时间不是附属字段，而是图的一条坐标轴

事实会变化。

某个人曾经在某家公司任职，但后来离开。

某个关系在过去成立，在今天已经失效。

更微妙的是，事实在世界中成立的时间，与系统记录到这一事实的时间，也可能不同。

Semantica 提供双时间事实、时间范围查询与时间点快照能力，让图不仅记录连接，也记录连接在何时有效。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
from datetime import datetime

from semantica.context import ContextGraph
from semantica.kg import BiTemporalFact

graph = ContextGraph(advanced_analytics=True)

graph.add_node(
    "alice_chen",
    "Person",
    role="VP Engineering",
)

graph.add_node(
    "acme_corp",
    "Organization",
    valuation=1_200_000_000,
)

graph.add_edge(
    "alice_chen",
    "acme_corp",
    edge_type="works_for",
    valid_from="2024-03-01T00:00:00",
    valid_until="2025-01-01T00:00:00",
)

snapshot_2023 = graph.state_at("2023-06-01")
snapshot_2024 = graph.state_at("2024-01-01")

fact = BiTemporalFact(
    valid_from=datetime(2024, 3, 1),
    valid_until=datetime(2025, 1, 1),
    recorded_at=datetime(2024, 3, 5),
)

时间让图谱不只是一张静态关系图，而拥有了回看历史、理解变迁与区分记录时刻的能力。

从知识图谱走向图分析

当知识图谱逐步成形，它不只是存放结构化事实的容器，也能够成为分析对象。

Semantica 支持中心性计算、社区发现、最短路径与链接预测等图分析能力。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
from semantica.ingest import FileIngestor
from semantica.kg import (
    GraphBuilder,
    GraphAnalyzer,
    CentralityCalculator,
    CommunityDetector,
    PathFinder,
    LinkPredictor,
)

sources = FileIngestor().ingest_directory(
    "./contracts/",
    recursive=True,
)

kg = GraphBuilder(
    merge_entities=True,
    enable_temporal=True,
).build(sources)

analyzer = GraphAnalyzer()
analysis = analyzer.analyze_graph(kg)

centrality = CentralityCalculator()

degree = centrality.calculate_degree_centrality(kg)
betweenness = centrality.calculate_betweenness_centrality(kg)

communities = CommunityDetector().detect_communities(
    kg,
    method="louvain",
)

path = PathFinder().find_shortest_path(
    kg,
    "alice_chen",
    "contract_001",
)

predictions = LinkPredictor().predict_links(
    kg,
    top_k=10,
)

中心性可以帮助寻找连接最密集的实体，社区发现能够呈现自然形成的关系簇，路径查询能够揭示两个节点之间的连接路线，链接预测则面向潜在关系提供分析入口。

图并不只是用来保存关系，也可以帮助人们从关系中发现结构。

图原生切分，为 GraphRAG 保住语义边界

文档切分是知识检索中的基础步骤，但普通切分方式很容易在不合适的位置打断实体、关系或语义单元。

Semantica 的切分模块支持递归、词元、句子、段落、语义、实体感知、关系感知、图式、本体感知与分层等多种方式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
from semantica.split import (
    TextSplitter,
    EntityAwareChunker,
    RelationAwareChunker,
)

text = open("contracts/master_agreement.txt").read()

chunks = TextSplitter(
    method="recursive",
    chunk_size=1000,
    chunk_overlap=200,
).split(text)

chunks = TextSplitter(
    method="entity_aware",
    ner_method="llm",
    chunk_size=1000,
).split(text)

chunks = RelationAwareChunker(
    chunk_size=1000,
    preserve_triplets=True,
).chunk(text)

chunks = TextSplitter(
    method="graph_based",
    chunk_size=1000,
).split(text)

chunks = TextSplitter(
    method="hierarchical",
    levels=["section", "paragraph"],
).split(text)

当切分过程开始理解实体边界、关系三元组与图社区结构时，后续的检索与知识图谱构建也拥有了更完整的语义材料。

本体与约束，为知识空间建立秩序

如果知识图谱是一座不断扩张的城市，本体则像城市中的分类体系、命名系统和建设规则。

Semantica 提供本体生成、类与属性推断、优化，以及 SHACL 验证与 SKOS 词汇管理能力。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
from semantica.ontology import OntologyGenerator, OntologyValidator

data = {
    "entities": [
        {
            "id": "acme_corp",
            "type": "Organization",
            "industry": "SaaS",
            "founded": 2012,
        },
        {
            "id": "alice_chen",
            "type": "Person",
            "role": "CTO",
            "since": 2019,
        },
    ],
    "relationships": [
        {
            "source": "alice_chen",
            "target": "acme_corp",
            "type": "works_for",
        },
    ],
}

gen = OntologyGenerator(
    base_uri="https://semantica.dev/ontology/"
)

ontology = gen.generate_ontology(data)
classes = gen.infer_classes(data)
props = gen.infer_properties(data, classes)
optimized = gen.optimize_ontology(ontology)

validator = OntologyValidator()
report = validator.validate(ontology)

本体让图中的类型、属性与关系拥有更清晰的语义框架，SHACL 则为这些结构提供验证能力。

当系统需要处理治理、合规、约束与跨来源知识对齐时，这一层结构尤为重要。

多种图存储与多种导出形式

Semantica 面向 RDF 与标记属性图提供多图存储支持。

在 RDF 侧，README 中列出了嵌入式 Oxigraph、Blazegraph、Apache Jena 与 Eclipse RDF4J。

在标记属性图侧，README 中列出了 Neo4j、FalkorDB、Apache AGE 与 AWS Neptune。

同时，它也支持多种向量存储后端，包括 FAISS、Qdrant、Weaviate、Milvus、Pinecone、PgVector、SQLite 与内存存储。

对于构建完成的知识图谱，Semantica 可以导出 RDF、OWL、Parquet、Cypher、JSON-LD 等格式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
from semantica.export import (
    RDFExporter,
    JSONExporter,
    ParquetExporter,
    LPGExporter,
    ReportGenerator,
)

kg = {
    "entities": [],
    "relationships": [],
}

rdf = RDFExporter()

turtle_str = rdf.export_to_rdf(
    kg,
    format="turtle",
)

jsonld_str = rdf.export_to_rdf(
    kg,
    format="json-ld",
)

rdf.export(
    kg,
    "kg_audit.ttl",
    format="turtle",
)

ParquetExporter(
    compression="snappy"
).export_knowledge_graph(
    kg,
    "kg_snapshot",
)

JSONExporter().export_knowledge_graph(
    kg,
    "kg.json",
)

LPGExporter().export(
    kg,
    "kg_import.cypher",
)

ReportGenerator().generate_report(
    {
        "title": "KG Audit Report",
        "summary": "Weekly ingestion summary",
        "metrics": {
            "entities": len(kg["entities"]),
        },
    },
    file_path="audit_report.html",
    format="html",
)

对于需要在不同图系统、审计流程、分析平台与下游应用之间流动的数据而言，导出能力让知识图谱不被锁死在单一表现形式中。

可视化，让图中的结构真正可见

图的价值不仅在于机器可以查询，也在于人可以理解。

Semantica 提供交互式图工作台能力，用于呈现力导向图、社区结构、本体层级、嵌入投影与时间轴。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
from semantica.visualization import (
    KGVisualizer,
    OntologyVisualizer,
    EmbeddingVisualizer,
    TemporalVisualizer,
)

viz = KGVisualizer(
    layout="force",
    color_scheme="default",
)

viz.visualize_network(
    kg,
    output="interactive",
    file_path="kg.html",
)

viz.visualize_communities(
    kg,
    communities,
    output="interactive",
)

viz.visualize_centrality(
    kg,
    centrality,
    centrality_type="degree",
)

OntologyVisualizer().visualize_hierarchy(
    ontology,
    output="interactive",
)

TemporalVisualizer().visualize_timeline(
    kg,
    output="interactive",
)

Knowledge Explorer 则把这种能力进一步组织成浏览器中的图工作台。

它包含知识图谱、时间线、决策、注册表、实体解析、图谱概览、本体中心与谱系等工作区。

在知识图谱工作区中，可以浏览实时图谱、使用 ForceAtlas2 布局、查看自我中心模式、观察语义距离热力图与路径高亮。

在时间线中，可以通过时间事件浏览图谱演化。

在决策工作区中，可以浏览已记录决策的因果链、结果标签与置信度。

在谱系工作区中，可以查看任意实体的 W3C PROV-O 溯源信息。

用浏览器打开 Knowledge Explorer

安装带有 Explorer 扩展的包后，可以直接指向一个图 JSON 文件启动仪表盘。

1
pip install "semantica[explorer]"
1
semantica-explorer --graph my_graph.json

默认情况下，服务会在本地地址启动，并自动打开浏览器。

也可以指定端口，或者关闭自动打开浏览器的行为。

1
semantica-explorer --graph my_graph.json --port 8080
1
semantica-explorer --graph my_graph.json --no-browser

对于参与前端开发的场景，Explorer 还提供基于 React、TypeScript 与 Vite 的源码开发方式。

1
pip install -e ".[explorer]"
1
2
cd explorer
npm ci
1
semantica-explorer --graph path/to/my_graph.json --no-browser
1
npm run dev

前端开发服务器会将 API 与 WebSocket 请求代理到 Python 后端，让图的更新、工作区交互和开发调试形成更顺畅的循环。

MCP，让 AI 工具可以直接操作知识图

Semantica 还提供 MCP Server，用于将知识图谱能力接入支持 MCP 的 AI 工具。

它采用标准输入输出传输方式，读取换行分隔的 JSON-RPC 2.0 请求，并将响应写入标准输出。

1
pip install -e ".[mcp]"
1
python -m mcp

MCP Server 提供 17 个工具，覆盖实体抽取、关系抽取、完整语义抽取流程、决策记录、决策查询、先例检索、因果链追踪、影响分析、图实体与关系写入、图搜索、图摘要、图分析、规则推理、溯因推理、图导出与溯源查询。

其中，决策智能相关工具包括：

  • record_decision
  • query_decisions
  • find_precedents
  • get_causal_chain
  • analyze_decision_impact

知识图谱相关工具包括：

  • add_entity
  • add_relationship
  • search_graph
  • get_graph_summary
  • get_graph_analytics

推理与导出相关工具包括：

  • run_reasoning
  • abductive_reasoning
  • export_graph
  • get_provenance

它还提供图摘要、近期决策、模式信息与本体模式等资源入口。

这样一来，AI 工具不只是在对话中产生文本，也能够连接到一张具有实体、关系、规则、决策和溯源信息的图。

用声明式管道把流程串起来

当数据接入、语义抽取、关系抽取、图构建、去重与导出需要组合为完整流程时，Semantica 提供了 Pipeline DSL。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
from semantica.pipeline import PipelineBuilder, ExecutionEngine

builder = PipelineBuilder()

builder.add_step(
    "ingest",
    step_type="ingest",
    source="./contracts/",
    recursive=True,
)

builder.add_step(
    "extract",
    step_type="ner_extract",
)

builder.add_step(
    "relations",
    step_type="relation_extract",
)

builder.add_step(
    "build_kg",
    step_type="kg_build",
    merge_entities=True,
)

builder.add_step(
    "deduplicate",
    step_type="deduplicate",
    threshold=0.75,
)

builder.add_step(
    "export",
    step_type="export",
    format="turtle",
    output="kg.ttl",
)

pipeline = (
    builder
    .connect_steps("ingest", "extract")
    .connect_steps("extract", "relations")
    .connect_steps("relations", "build_kg")
    .connect_steps("build_kg", "deduplicate")
    .connect_steps("deduplicate", "export")
    .set_parallelism(4)
    .build(name="contracts_pipeline")
)

engine = ExecutionEngine()

result = engine.execute_pipeline(pipeline)
status = engine.get_pipeline_status(pipeline.name)
progress = engine.get_progress(pipeline.name)

这段管道从目录中的文档开始，经过实体抽取、关系抽取、知识图谱构建、去重与导出，最终形成一个可执行的流程。

对于需要将多阶段知识处理任务组织起来的场景，这种声明式表达让各个步骤之间的依赖关系更清晰。

一个面向审计链路的实践模式

Semantica README 给出了一个围绕受监管决策审计的模式。

它从记录带有因果关系的决策链开始，为实体附加溯源信息，再将图数据映射为可导出的知识结构。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
from semantica.context import ContextGraph
from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

graph = ContextGraph(advanced_analytics=True)

prov = ProvenanceManager(
    storage_path="./audit.db"
)

d1 = graph.record_decision(
    category="drug_interaction_check",
    scenario="Patient P-4821: warfarin + amiodarone co-prescribed",
    reasoning="Amiodarone potentiates warfarin's anticoagulant effect",
    outcome="flag_for_review",
    confidence=0.91,
)

d2 = graph.record_decision(
    category="dosage_adjustment",
    scenario="INR monitoring plan for P-4821",
    reasoning="Reduce warfarin dose per interaction severity; recheck INR in 5 days",
    outcome="dose_reduced_30pct",
    confidence=0.87,
)

graph.add_causal_relationship(
    d1,
    d2,
    relationship_type="CAUSED",
)

prov.track_entity(
    "patient_P4821",
    source="ehr/medication_orders_2024.json",
    metadata={
        "extractor": "NamedEntityRecognizer",
    },
)

graph_dict = graph.to_dict()

kg = {
    "entities": [
        {
            "id": node["id"],
            "type": node["type"],
            "text": node["content"],
        }
        for node in graph_dict["nodes"]
    ],
    "relationships": [
        {
            "source_id": edge["source"],
            "target_id": edge["target"],
            "type": edge["type"],
        }
        for edge in graph_dict["edges"]
    ],
}

RDFExporter().export(
    kg,
    "audit_trail.ttl",
    format="turtle",
)

这条链路把决策、因果关系、实体来源与导出结果连接在一起。

它所呈现的并不是一份孤立的模型输出，而是一张能够继续追踪、查询与审计的决策知识图。

从安装开始

Semantica 可以通过 pip 安装。

1
pip install semantica

安装后，可以使用诊断命令检查环境。

1
semantica doctor

README 中给出的诊断输出会检查 Python 版本、Semantica 版本、FAISS 向量存储与配置文件状态。

对于想快速开始构建上下文图、记录决策、追踪因果链与执行规则检查的场景，最小入口就是从 ContextGraph 开始。

一张图，承载 AI 的上下文与责任

Semantica 的核心气质，在于它没有把 AI 上下文简单视为可被召回的片段，也没有把 AI 决策视为一次性输出。

在它的图模型中，上下文可以被组织，实体可以被连接，冲突可以被标记，重复可以被处理，规则可以被运行，时间可以被回看，来源可以被追踪，决策可以被解释，影响可以被分析。

这让 AI 系统中的知识不再只是漂浮在向量、提示词和日志之间。

它们开始落在一张有结构、有因果、有时间、有来源，也有责任边界的图里。