第 1 章 · 01 Semantica 定位与确定性哲学

第 1 章 · 01 Semantica 定位与确定性哲学

本节摘要：本节是全书的地基，不拆任何零件，先回答三个问题——Semantica 是什么（v0.6.5，MIT，semantica-agi 组织出品的图原生可信 AI 基础设施，自封「开源版 Palantir」，官网 getsemantica.ai）；「确定性」哲学指什么（不依赖 LLM 即可完成知识图谱构建、推理与溯源，让每个 AI 决策可追溯、可审计）；它为什么被监管级场景当刚需（README 反复使用的贷款审批合规例子：AI 拒绝了贷款，监管问「为什么」，Semantica 能给出完整证据链）。最后用一张对比表说清它与 LangChain、LlamaIndex、GraphRAG 库的定位差异，并给出体量坐标。

内容来源：原项目源码 semantica 主包（README.md、ARCHITECTURE.md、pyproject.toml）

⚠️ 注意：Semantica 提供的是「系统级可解释性」，不是「模型级可解释性」。README 第 63 行的免责声明写得非常直白：它不解释 LLM 内部的思维链，只解释模型外部的事实——喂进去什么上下文、产出什么决策、证据从哪来、套用了哪些策略。期待「透视大模型脑回路」的读者，从这一节起就要校准预期。

学习目标

1. 说出 Semantica 的定位：图原生可信 AI 基础设施，「开源版 Palantir」。
2. 复述确定性哲学：图谱构建、推理、溯源全程无需 LLM，同样输入必得同样输出。
3. 用贷款审批合规例子讲清「可审计决策」在监管场景为什么是刚需。
4. 画出 Semantica 与 LLM、向量库、Agent 框架的分层关系：它在它们之下。
5. 用对比表说清它与 LangChain、LlamaIndex、GraphRAG 库的定位差异。
6. 记住体量坐标：28.6 万行 Python、27 个子模块、288 个测试文件、37 个 notebook。

一、Semantica 是什么：图原生的「开源版 Palantir」

先看自我介绍。README 第 17 行的副标题只有一个短语：

#### *The Open Source Palantir for AI Agents*
​

Palantir 是以「把企业碎片数据变成可治理、可追溯的决策底座」闻名的平台，Semantica 把这个定位开源化了。从 pyproject.toml 与 README 徽章可以确认基本坐标：版本 v0.6.5（2026 年 8 月前后，迭代约每月一个 minor）、许可证 MIT、组织 semantica-agi、官网与文档在 getsemantica.ai。

它的自我定性写在 README 第 61 行：

Semantica sits underneath your LLM, vector store, and agent framework as a
deterministic infrastructure layer: no LLM required for graph construction,
reasoning, or provenance.
​

两个关键词：underneath（在 LLM、向量库、Agent 框架之下）与 deterministic（确定性）。它不是又一个 Agent 框架，也不是又一个 RAG 库，而是给上层 AI 应用供血的「结构化知识层」：把碎片化的原始数据变成带溯源的知识图谱，把每次 AI 决策变成可查询的图节点。所谓「图原生」是指它的核心抽象不是字符串或向量，而是图——实体、关系、事实、决策全部是一等图节点，检索靠图遍历加语义搜索，而不是只靠「嵌入相似度」。

二、确定性哲学：不靠 LLM 的图谱、推理与溯源

「确定性」是全书的关键词，展开说是三件事都不需要 LLM：

• 图谱构建不需要 LLM：NER、关系、三元组抽取提供 pattern 与 ML（spaCy）两条本地路线，LLM 只是可选增强（第 3 章详读）；
• 推理不需要 LLM：Rete 前向链、Datalog、SPARQL 三套确定性推理引擎，结论能给出完整推理路径（第 5 章）；
• 溯源不需要 LLM：每个事实的来源记录走 W3C PROV-O 标准，纯数据工程（第 7 章）。

为什么在 LLM 时代这反而成了卖点？因为幻觉不可消除，只能被包围。当 LLM 参与决策时，让它「踩」在一个确定性的知识底座上：喂给它的上下文来自可溯源的图谱，它的决策被记录成带因果链的图节点。于是每个 AI 决策可追溯、可审计——LLM 负责生成，Semantica 负责让生成的每一步有据可查。README 第 109 行总结得很克制：Semantica 是补充而不是替代，你的 LLM、向量库、Agent 框架原样保留，它在其上追加决策记录、因果推理、溯源、本体治理、冲突检测与审计轨迹。

三、监管级场景：贷款审批合规的证据链

README 用大量篇幅讲同一类故事：强监管行业（金融、医疗、法律、政府）不能上线黑箱，也不能把数据交给别人的 SaaS。最典型的例子是贷款审批：AI 拒绝了一笔贷款，监管问「为什么」，系统必须给出完整证据链。README 第 186 行的原文一针见血——在受监管领域，每个 AI 决策必须可溯源到证据、能向审计员申辩。Quick Start 里的三段决策记录就是这条证据链的骨架：

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,
)
# 关系类型必须是 CAUSED、INFLUENCED、PRECEDENT_FOR 之一
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")
​

注意 record_decision 的五个字段：类别、场景、理由、结果、置信度——这就是监管问询时要出示的全部要素。决策之间用 add_causal_relationship 连成因果链之后，trace_decision_chain 可以从任何一个决策回溯到根因，find_similar_decisions 能做先例语义搜索（「过去类似的申请是怎么批的」），最后用 PROV-O 格式导出成监管接受的审计轨迹。第 6 章会把这条链拆到源码级。

四、旗舰配方：受监管决策的审计轨迹

README 里有一个被标记为「flagship pattern」的完整配方，把定位落到可复制的代码上——记录因果链接的决策链、给每个实体挂溯源、导出监管就绪的审计轨迹：

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,
)
# relationship_type 必须是 CAUSED、INFLUENCED、PRECEDENT_FOR 之一
graph.add_causal_relationship(d1, d2, relationship_type="CAUSED")

# 给每个实体追踪溯源:来源文档+抽取器
prov.track_entity("patient_P4821", source="ehr/medication_orders_2024.json",
                  metadata={"extractor": "NamedEntityRecognizer"})

# to_kg_dict() 是官方适配器,吐出 RDFExporter 期望的形状,免手工映射字段
kg = graph.to_kg_dict()
RDFExporter().export(kg, "audit_trail.ttl", format="turtle")
​

三行主线值得圈点：决策进图（record_decision）、事实挂源（prov.track_entity，连「这条事实是哪个抽取器抽的」都记了）、图转 Turtle 导出（一行完成监管提交格式）。这个配方里出现的三个模块——context、provenance、export——会在第 6、7、9 章逐一精读。

五、分层定位：与 LangChain、LlamaIndex、GraphRAG 库的差异

README 第 96 到 107 行有一张自比表（向量库 RAG 与纯 LLM 记忆各有三列「None」）。我们把它扩写成四列，补上框架类库：

一句话概括差异：框架类库帮你「调用 LLM」，GraphRAG 帮你「检索喂给 LLM」，Semantica 帮你「为 LLM 的行为兜底」。它不跟你抢编排层的位置——你可以继续用 LangChain 写 Agent，只是在 Agent 下面垫上这层确定性的知识、推理与审计。

六、体量坐标：一套完整的知识管线

给这本书建立尺度感，四个数字：

• 28.6 万行 Python：核心包 semantica/ 约 18.2 万行，测试约 9.7 万行；
• 27 个子模块：从 ingest 到 context，正好对应一条完整的知识管线（下一节展开）；
• 288 个测试文件：对核心包约 0.5:1 的测试密度，在开源 KG 项目里相当罕见；
• 37 个 cookbook notebook：introduction 21 册渐进式加 advanced 14 册，与本书八章装配路径天然对齐。

更难得的是可运行性：核心功能（内存图、FAISS 向量库、inmemory 存储）无需任何 API key 即可跑通，semantica doctor 五秒自检环境。教学环境友好意味着每一节你都可以边读边敲。

README 还列了五类目标用户，可以当作「这套基础设施为谁而建」的注脚：要给 Agent 接上可查询结构化上下文的 AI/ML 平台团队；想把 Databricks/Snowflake 里的表原地变成带血缘知识图谱的数据平台团队；要向监管交差的合规与风控团队；不能上黑箱也不能出数据的受监管企业；以及想把 KG＋推理＋溯源栈自托管、可换后端的基础设施工程师。本书的目标读者与第一类和第三类高度重合。

💡 装配要点：记住一句话定位——「Palantir 的开源平替，垫在 LLM 之下的确定性知识层」。确定性哲学的三根柱子（图谱不靠 LLM、推理不靠 LLM、溯源不靠 LLM）分别对应本书第 3 章、第 5 章、第 7 章；贷款审批合规例子是第 6 章压轴的预告片。判断某功能「是不是 Semantica 的菜」，就看它是否服务于「可追溯、可审计」这四个字。

本节要点回顾

• Semantica：v0.6.5，MIT，semantica-agi，自称「The Open Source Palantir for AI Agents」，图原生可信 AI 基础设施。
• 确定性哲学：图构建、推理、溯源三件事都不需要 LLM；LLM 负责生成，Semantica 负责让每一步有据可查。
• 系统级可解释性，非模型级：解释模型外的事实与流程，不解释模型内的思维链。
• 监管刚需：贷款审批例子里，record_decision＋add_causal_relationship＋PROV-O 导出构成完整证据链。
• 分层：LangChain 管编排、GraphRAG 管检索、Semantica 管兜底（溯源/推理/冲突/时态/审计）。
• 体量：28.6 万行 Python、27 子模块、288 测试文件、37 notebook；无 key 可跑通。

下一节：02 Semantica 编排器与八段管线——拆开 Semantica 编排器这个总门面，看清八段管线如何被 PipelineBuilder 装配成流水线，以及 5 个程序入口与「无 key 跑通」的可运行性设计。