Semantica：面向可审计 AI 的图原生基础设施

上一篇拆了管省钱的 prompt-cache，这篇接着拆管认账的。
Agent 跑在生产上有个老问题：它存的是 embedding，不是意义——上下文说不清来历，决策事后无从审计。
在信贷、医疗这类行当里，「AI 为什么这么判」是监管几个月后真会来问的问题，向量库答不上来。
Semantica 用知识图谱来补这块，把源码翻了一遍，记下来。

定位

一个 Python 框架，pip install semantica 就有，自我介绍是「Open Source Palantir for AI Agents」——营销词放一边，实际是三层东西：
把多源脏数据变成知识图谱的流水线；架在图上的确定性智能层（本体、推理、溯源、决策记录）；以及一圈出口（REST、MCP、CLI、可视化工作台）。
关键立场是图构建、推理、溯源全程不需要 LLM——确定性、可复算、能给监管看，LLM 只是可选的抽取增强。
它不替换你手里的向量库和 agent 框架，是垫在下面多记一层账。

Semantica 数据管线：五段推进，治理在入图之前

（交互版，可播放数据流轨迹。）

数据管线

管线五段，每段都是独立可导入的模块，不强迫全家桶：

ingest 是三十多个摄取器套一个统一接口：本地文件（PDF/DOCX/Excel 等十来种）、SQL 库、Kafka/Kinesis 流、Git 仓库、IMAP 邮箱、MCP 资源，
连 Databricks（Unity Catalog + 血缘）和 Snowflake 都有原生连接器——湖仓里的表直接变图节点，不用先导 CSV。
parse → normalize → split 做整备，分块器是它的特色：entity_aware 切法保证命名实体不被切断在两个 chunk 里，关系感知切法保三元组完整，这是给 GraphRAG 准备的。
semantic_extract 出结构：NER、关系、事件、三元组、共指消解。NER 默认走 spaCy，也可以换 regex、HuggingFace 模型或 LLM。
conflicts 在入图前对账：值、类型、关系、时态、逻辑五类冲突，检出后按来源可信度加权、按时间取新、或投票化解——不同来源说法打架时不会静默覆盖。
deduplication 做实体归一：blocking 出候选、语义相似度聚类、保留溯源地合并，「Acme Corp.」和「ACME Corp」在这里变成一个节点。

决策智能

这是它的招牌功能：把每次 AI 决策从一条转瞬即逝的推理，变成图里的一等公民节点。

决策智能生命周期：记录、关联、查证、出账

（交互版）核心 API 一共六个动作，串起来就是审计链：

python

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# app_id 是上一笔「受理申请」决策的返回值，记录方式相同，略
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,
)
# 因果边只有三种：CAUSED / INFLUENCED / PRECEDENT_FOR
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")

chain   = graph.trace_decision_chain(uw_id)        # 回溯到根因
similar = graph.find_similar_decisions("低 DTI 个贷审批")  # 先例检索
impact  = graph.analyze_decision_impact(uw_id)     # 下游影响面

先例检索不是简单的文本匹配：决策节点同时带语义 embedding 和 Node2Vec 结构 embedding，两路相似度加权混合——
「场景像」和「在图里的位置像」都算数。最后整条链可以导出 W3C PROV-O，这是多数合规框架认的血缘格式。
时间维度也是一等的：边带 valid_from / valid_until，事实分「世上何时为真」与「系统何时得知」两条时间轴，state_at("2024-01-01") 直接取历史快照。

推理与溯源

推理层全是老牌确定性技术：前向链、Rete 网络、递归 Datalog、SPARQL，配一个 ExplanationGenerator 把结论的推导路径一步步吐出来。
Datalog 写规则确实舒服，两行就是传递闭包：

python

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

溯源由 ProvenanceManager 管，每个实体、每条关系登记来源文件和抽取器，落 SQLite，能答「这个结论从哪份文档第几页来的」。

存储

存储是多态的：RDF 三元组库（内嵌 Oxigraph 免部署，Blazegraph/Jena/RDF4J 走 SPARQL over HTTP）、
属性图库（Neo4j、FalkorDB、Apache AGE、AWS Neptune）、向量库（FAISS/Qdrant/Weaviate/Milvus/Pinecone/PgVector），换后端不改业务代码。
但要知道：ContextGraph 本体是纯 Python 的进程内字典图（节点 dict + 邻接表 + RLock），持久化靠手动 save_to_file 存 JSON，或者把图推去外部图库——它自己不是数据库。

上手

bash

pip install semantica
semantica doctor          # 5 秒体检：Python / faiss / 配置各项 pass
pip install "semantica[explorer]"
semantica-explorer --graph my_graph.json   # 浏览器工作台，127.0.0.1:8000

Explorer 是 React + Sigma.js 的图工作台：力导布局的活图、时间轴推演、决策因果链浏览、重复实体人工合并、SHACL 可视化编辑。
接 Claude Desktop 这类 MCP 客户端也就一行：python -m semantica.mcp_server，暴露 record_decision、find_precedents、get_causal_chain 等十来个工具。

能力

决策记录与因果链：record / trace / impact / precedent / 规则门，全程可导出
知识管线：30+ 源摄取、实体感知分块、NER/关系/事件抽取、冲突对账、实体归一
确定性推理：前向链 / Rete / Datalog / SPARQL，附推导路径解释
溯源：W3C PROV-O，每个事实挂来源，SQLite 持久化
双时态图：valid time 与 record time 分轴，任意时点快照
多态存储：RDF × 4、LPG × 4、向量库 × 6，后端可换
出口：RDF/OWL/Parquet/Cypher/JSON-LD 导出、REST、MCP、CLI、Explorer 工作台

边界与风险

图的质量上限是抽取的质量。 默认 NER 是 spaCy 加一套启发式置信度（按长度和首字母大小写打分），
英文通用文本尚可，中文或垂直领域不换模型基本不能用；想要好效果还得上 HuggingFace 领域模型或 LLM 抽取——
「不需要 LLM」说的是图构建和推理这段，抽取的钱省不掉。

ContextGraph 是内存态。 进程一退图就没了，除非手动存 JSON 或推外部图库；号称 11.8 万节点的生产图节点检索 0.004ms，
那是内存索引的速度，多副本、跨进程一致性、崩溃恢复全要靠 Neo4j 这类后端自己搭。它是内存里的智能层，不是存储引擎。

Rete 引擎的条件匹配器 README 自己承认「这个版本故意做得简单」，拿去当生产合规门之前，先用自己的规则集验一遍输出。

API 面积很大但还年轻：README 里好几处「这个方法和你想的不一样」的补丁式注解——RDFExporter 要的字典形状和 to_dict() 给的不一致得手动映射、
PipelineBuilder.add_step 不能链式调用、一批摄取器还没导出到顶层命名空间。文档在追代码的痕迹很明显，照着示例跑通再往深处走。

安全上刚交过一次学费：v0.6.5 一口气修了 5 个外报漏洞——Explorer API 曾经全路由无鉴权（Critical）、Neo4j/Neptune 的 Cypher 注入、
SPARQL 注入、SSRF。响应速度不错，但也说明 Explorer 和 REST 这层别裸暴露公网，版本要跟紧。

最后一条是性质上的：record_decision 靠应用主动调用，agent 不调它就没有审计链——
它提供的是审计的基础设施，不是审计的强制力，制度得自己配。

连着两篇读的都是给 LLM 打下手的基础设施，一个管省钱，一个管认账。热闹都在模型那边，真出事的时候翻的却是这些账本。