Semantica · 中文源码精读教程

Semantica · 中文源码精读教程

管线装配:沿八段知识管线逐段装配,拆解一个"图原生的可信 AI 基础设施"

这本教程讲什么

这是一份带读源码的 Semantica 精读教程。

Semantica(v0.6.5,MIT,semantica-agi 组织)自封为 "The Open Source Palantir for AI Agents"(开源版 Palantir)。它的定位很独特:位于 LLM/向量库/Agent 框架之下的确定性基础设施层——不依赖 LLM 即可完成知识图谱构建、推理和溯源。卖点是监管级场景的刚需:每个 AI 决策可追溯、可审计。README 反复用贷款审批合规做例子:AI 拒绝了你的贷款,监管问"为什么",Semantica 能给出完整的证据链。

Python 约 28.6 万行(核心包 18.2 万 + 测试 9.7 万),27 个子模块。它的能力覆盖一个完整的知识管线:25+ 种数据源接入(ingest)→文档解析(parse)→实体归一(normalize)→语义抽取(extract)→冲突检测→实体去重→图谱构建(kg)→确定性推理(reasoning)→决策智能(context),外加 8 种向量库、4 种图数据库、RDF 三元组库的 polyglot 存储抽象(一行参数切换后端),以及 W3C PROV-O 全链路溯源、双时态知识图谱(valid time 与 recorded time 独立)、SHACL 本体验证。

💡 核心心法:Semantica 的灵魂是确定性——在 LLM 动辄幻觉的时代,它构建的图谱、推理的结论、记录的决策,全部有据可查:每个事实知道从哪来(PROV-O 溯源)、每个结论能给出推理路径(Rete/Datalog/SPARQL)、每个决策留下因果链(ContextGraph)。本教程采用管线装配式:沿八段知识管线逐段装配——像搭流水线一样,每章装配一段,讲清这段的输入输出、实现机制、可插拔后端。

好消息:项目自带 37 个 cookbook notebook(introduction 21 册渐进式 + advanced 14 册),与管线八段天然对齐;ARCHITECTURE.md 有完整管线 Mermaid 图;核心功能(内存图/FAISS/inmemory 向量库)无需 API key 即可跑通——教学环境极其友好。

八段知识管线(全书主线)

第 3 章(图谱构建)、第 5 章(确定性推理)、第 6 章(决策智能)是三个高点;第 6 章决策智能是全书压轴。

十章装配路径

第 1 章 Semantica 全貌与管线总览 ── 定位/八段管线/可运行性
第 2 章 管线前段:摄入与解析 ── ingest/parse/normalize/split
第 3 章 ★ 管线中段:语义抽取与图谱构建 ── extract/kg/GraphBuilder
第 4 章 数据治理:冲突与去重 ── conflicts/deduplication/归一
第 5 章 ★ 确定性推理 ── Rete/Datalog/SPARQL/溯因/解释器
第 6 章 ★ 决策智能压轴 ── ContextGraph/决策记录/因果链/先例
第 7 章 溯源与时态 ── PROV-O/双时态图/GDPR 撤回
第 8 章 Polyglot 存储抽象 ── 8向量库/4图库/RDF库/Registry
第 9 章 语义检索与本体 ── GraphRAG/向量库/本体 OWL/SHACL
第 10 章 生态与全书回顾 ── Explorer/MCP/插件/部署/全书回顾
​

章节目录

第 1 章 Semantica 全貌与管线总览
Semantica 是什么(开源版 Palantir/图原生基础设施/v0.6.5);"确定性"哲学(不依赖 LLM 的图谱与推理);监管级场景定位(贷款审批合规);八段管线总览(ARCHITECTURE.md 的 Mermaid);Semantica 编排器(core/orchestrator)与 PipelineBuilder DSL;5 个入口(CLI/server/worker/explorer/mcp);可运行性(无 key 跑通+doctor 自检)。

第 2 章 管线前段:摄入与解析
ingest(25+ 数据源:文件/网页/数据库/Snowflake/Databricks/Kafka/邮件/Git/MCP);parse(文档/结构化/代码/网页/邮件五类解析器);normalize(文本/实体/日期/数字归一);split(13 种 GraphRAG 原生分块:entity_aware/relation_aware/graph_based/ontology_aware)。

第 3 章 ★ 管线中段:语义抽取与图谱构建
semantic_extract(NER/关系/事件/三元组抽取+共指消解;ML/pattern/LLM 三种方法可切换);kg 模块(25 文件);GraphBuilder(从抽取结果构建知识图谱);EntityResolver 实体消解;图分析(中心性/社区/链接预测)。

第 4 章 数据治理:冲突与去重
conflicts(冲突检测器 1423 行/冲突消解/来源追踪);deduplication(阻塞+语义去重/实体合并);多源数据融合的经典难题;配 cookbook 对应章节。

第 5 章 ★ 确定性推理(全书高潮之一)
reasoning 模块(11 文件);Rete 前向链推理;Datalog(支持自然语言图查询);SPARQL;溯因(abductive)/演绎(deductive)推理;ExplanationGenerator 可解释推理路径;"不靠 LLM 的推理"为什么在监管场景是刚需。

第 6 章 ★ 决策智能压轴(全书高潮之二)
context 模块(1.9 万行,旗舰);ContextGraph(context_graph.py 4260 行);record_decision 把 AI 决策存为图节点;因果链追踪;先例语义搜索(precedent search);影响面分析;PolicyEngine 策略门禁;AgentContext/AgentMemory(给 agent 用的上下文与记忆);贷款审批合规完整配方。

第 7 章 溯源与时态
provenance(W3C PROV-O 溯源管理器 1486 行:每个事实可回答"从哪来");审计轨迹导出为监管格式;双时态知识图谱(valid time 与 recorded time 独立;state_at 时间点快照;temporal_query 1765 行);0.6.5 新增 retraction/purge(GDPR 删除权场景);change_management 变更记录。

第 8 章 Polyglot 存储抽象
vector_store(8 后端:FAISS/Qdrant/Weaviate/Milvus/Pinecone/PgVector/SQLite-vec/inmemory);graph_store(4 图库:Neo4j/FalkorDB/Apache AGE/Amazon Neptune);triplet_store(RDF 三元组库:Oxigraph 内嵌/Blazegraph/Jena/RDF4J);MethodRegistry/PluginRegistry 可插拔体系;一行参数切换后端的实现机制。

第 9 章 语义检索与本体工程
embeddings(嵌入生成/池化策略/图嵌入);HybridSearch 混合检索(向量+图 RRF 融合);GraphRAG(向量检索+多跳图扩展,query_with_reasoning 返回可审计推理路径);ontology(本体生成/OWL/SHACL 约束验证/SKOS 词表/本体评估器);export(11 种导出格式:RDF Turtle/JSON-LD/N-Triples/OWL/SHACL/Parquet/Cypher/GraphML)。

第 10 章 生态与全书回顾
explorer(FastAPI 后端 8905 行 + React 前端 sigma.js 图工作台,配 demo gif);mcp(MCP server:decisions/export/extraction/graph/reasoning 五类工具);integrations(Agno/CrewAI/OpenClaw);plugins(8 种编辑器插件);CLI(50+ 命令);deploy(azure/gcp/helm/kubernetes 等);cookbook 37 册导读;全书回顾。

适合读者

• 构建 RAG/知识图谱/Agent 记忆系统的 AI 工程师
• 金融/医疗/法律等强监管领域的 AI 落地者(可审计决策是刚需)
• 对知识图谱、本体工程、确定性推理感兴趣的研究者
• 想学习"polyglot 存储 + registry 可插拔"架构设计的开发者

前置知识:Python 基础;RAG/知识图谱基本概念(embedding/三元组,不必熟练);可选:SPARQL/OWL(第 5/9 章会用)。

注意事项

• 管线装配主线:每章标注装配的是管线哪一段
• 源码带行号引用如 context_graph.py:4260
• > 💡 **装配要点**:... 标注每节精华
• > ⚠️ **注意**:... 标注重依赖安装(torch/spaCy)/evals 空壳/examples 薄弱等

关于源码版本

对照源码来自 semantica-main(MIT,semantica-agi),版本 0.6.5(2026-08)。核心包 semantica/(27 子模块约 18.2 万行),测试 288 文件约 9.7 万行,cookbook 37 个 notebook,explorer 前端 React 约 3 万行。迭代快(约每月一个 minor),以 CHANGELOG 为准。