Semantica 深度解析：把「可审计」做到位，却没把「对不对」做出来

选型的时候你依赖哪些信号？Star 曲线、README 的完整度、CI 徽章是不是绿的、有没有文档站和 Discord、CHANGELOG 写不写得细。这些信号被广泛使用，是因为它们通常是相关的——一个愿意把 README 写到 75 KB 的团队，多半也愿意把测试写好。

semantica-agi/semantica 是一个把这些信号全部拉满、然后逐个证伪的样本。它 2026 年 8 月 10 日冲上 GitHub Trending 第 1，两天涨到 5,247 星，README 首页写着「The Open Source Palantir for AI Agents」，目标客户是金融、医疗、法务、政府这类受监管行业。

我把 v0.6.5 装进一个干净的 Python 3.11 虚拟环境，跑通了它自己的 Quick Start，跑完了它自带的 4,400 个测试，逐行读了它宣称的四个推理引擎。下面所有终端输出都是实际运行结果。

---

它宣称自己是什么

Semantica 的定位不是「又一个 GraphRAG」。它的主张更大：做 LLM、向量库、Agent 框架下面的一层确定性基础设施——图谱构建、推理、溯源三件事都不需要 LLM 参与。

README 首页的能力清单包括：Context Graph（上下文图）、Decision Intelligence（每个决策都是一等可查询对象）、W3C PROV-O 全链路溯源、确定性推理（前向链 + Rete + Datalog + SPARQL）、SHACL/OWL/SKOS 本体治理、冲突检测、实体消歧、时间旅行快照，以及一套 RDF + LPG 双范式的存储层。

这个清单的宽度在开源里确实没有第二家。178,456 行 Python、349 个源文件、29 个数据接入器、9 种图存储后端。

广度本身不是问题。此前拆过的 GitNexus 有 12 阶段索引流水线，复杂度不低，但每一阶段都能对上一个可检验的产物。问题在于广度有没有对应的验证密度。

---

先说好的：溯源层是真材实料

拆解一个项目最公平的做法，是先找出它真正做对的部分。Semantica 的溯源模块是我在开源里见过完成度最高的实现之一，不是营销话术。

ProvenanceManager 输出的是合法的 PROV-O Turtle，带 qualifiedAssociation 和 qualifiedGeneration 这类限定关系（很多号称支持 PROV-O 的项目只会输出 wasGeneratedBy 就收工），并且每条记录带 checksum + previous_checksum 构成哈希链：

>>> pm.verify_chain()
{'valid': True, 'total_entries': 2, 'broken_links': []}

ex:acme_corp a prov:Entity ;
    prov:generatedAtTime "2026-08-12T08:51:41"^^xsd:dateTime ;
    prov:qualifiedAssociation [ a prov:Association ;
            prov:agent ex:semantica ;
            prov:hadRole ex:role_generator ] ;
    prov:qualifiedGeneration [ a prov:Generation ;
            prov:activity ex:entity_tracking ] ;
    prov:wasAttributedTo ex:semantica .

同样真实的还有三件事：

后端覆盖面。 RDF 侧支持 Oxigraph（内嵌，无需外部服务）、Blazegraph、Jena、RDF4J、Anzo；LPG 侧支持 Neo4j、FalkorDB、Apache AGE、AWS Neptune。单个后端 1,000–1,800 行，是认真写过的。同时支持 RDF 与 LPG 两种范式，在开源项目里几乎只有它这么干——我此前拆过的 Cognee 也只覆盖了 LPG + 向量这一侧。

Datalog 推理器。 datalog_reasoner.py 有正确的合一（unification）实现：变量绑定冲突检测、arity 校验、增量绑定字典。这一点必须和下面 Rete 的情况分开说——这个项目的质量高度不均匀，不能一棍子打死。

安全工程的投入。 独立的 ingest/ssrf.py、sparql_escaping.py、query_sanitize.py；CI 里跑 CodeQL、Checkov、Microsoft Defender for DevOps，还有一个专门校验 GitHub Action 是否全部 pin 到 commit SHA 的工作流。已公开披露并修复了 SPARQL 注入、Cypher 标签注入、SSRF DNS rebinding、ReDoS、WebSocket Origin 绕过等多个 GHSA 通告。

179 KB 的 CHANGELOG 也值得一提：它会直接写「这个错误被一个宽泛的 except 静默吞掉了」「Pinecone 的元数据过滤开箱即用状态下从来就是不工作的」。这种自曝家丑的记录在同类项目里是加分项。

这些是真资产。也正因为它们是真的，接下来的问题才更值得说清楚。

---

三条实测为假的核心宣传

一、Rete 推理引擎会让任意规则在任意事实上触发

README 头版承诺「Deterministic Reasoning：Forward chaining、Rete network、Datalog、SPARQL，fully explainable paths, not black boxes」。

Rete 算法的全部价值在于判别：Alpha 网络按条件过滤事实，Beta 网络按变量绑定做连接，只有真正匹配的组合才走到终端节点。而 semantica/reasoning/rete_engine.py 里，这两个判别函数长这样：

def _matches(self, fact: Fact) -> bool:
    """Check if fact matches condition."""
    # Simple matching - can be enhanced
    return True

def _can_join(self, left_fact: Fact, right_fact: Fact) -> bool:
    """Check if facts can be joined."""
    # Simple join logic - can be enhanced
    return True

两个无条件 return True。也就是说，这不是一个「实现得比较粗糙的 Rete」，而是一个拆掉了判别逻辑的 Rete 外形。实测：

# 规则：is_manager(X) → is_employee(X)
# 事实：likes_pizza(bob)      ← 与规则条件毫无关系

facts added:    ['likes_pizza(bob)']
rule condition: ['is_manager(X)']
matches fired:  [('manager_is_employee', ['likes_pizza(bob)'], confidence=1.0)]

=> 引擎推出了 is_employee(bob)，置信度 1.0

一条关于「经理」的规则，在一条关于「披萨」的事实上触发了，置信度 1.0，并且这条推论会被写进图谱、打上 PROV-O 溯源戳。

对一个卖给「信贷审批要能扛住监管机构事后追问」场景的产品，这不是缺陷，是反向价值：它会生产出带完整审计链条的假推论。真正的黑箱至少不会假装自己是确定性的。

二、判例检索在两种配置下分别是全假阳性和全假阴性

Decision Intelligence 是这个项目的头号卖点：把每个 Agent 决策存成一等对象，之后能按「相似场景」检索历史判例。

评分公式是 0.7 × 内容相似度 + 0.3 × 结构相似度。问题出在结构相似度这一项：

def _calculate_structural_similarity_for_decision(self, decision_id: str, scenario: str) -> float:
    ...
    similar_nodes = self.find_similar_nodes(decision_id, similarity_type="structural", top_k=5)

注意签名里的 scenario——它是查询词，而函数体里从头到尾没有用到它。这个函数算的是「这个决策节点和图里其他节点的结构像不像」，而所有决策节点结构都一样（互不相连的孤立节点），于是结构相似度恒为 1.0，每条决策恒得 0.3 × 1.0 = 0.3 分，刚好等于 find_similar_decisions 的默认阈值 0.3。

我在图里存了三条毫不相干的决策（HIPAA 云选型 / 德国工资供应商 / 是否上 Kubernetes），然后查：

advanced_analytics=True     ← README Quick Start 推荐的配置
   'HIPAA cloud'                  -> [0.5, 0.3, 0.3]
   'banana pizza quantum unicorn' -> [0.3, 0.3, 0.3]   ← 全部命中
   ''  (空查询)                    -> [0.3, 0.3, 0.3]   ← 全部命中

advanced_analytics=False
   'HIPAA cloud'                  -> []   ← 明确匹配的那条也检不出
   'banana pizza quantum unicorn' -> []

开着高级分析：查什么都返回全部，包括空字符串。关掉高级分析：内容相似度单独跑不过 0.3 阈值，查什么都返回空。没有一个配置是可用的。

三、「无需 LLM 的确定性抽取」产出的是语义垃圾

这是全项目最核心的技术主张。我用一句最标准的并购新闻测试：

"Acme Corp, headquartered in Berlin, acquired WidgetCo for $4.2 billion in March 2024. CEO Jane Doe said the deal closes in Q3."

场景 A：开箱即用（README 从头到尾没提要下载 spaCy 模型）

spaCy model en_core_web_sm not found. ML method will fallback.

实体：Acme Corp/ORG、Jane Doe/PERSON、2024/DATE
      漏掉 Berlin、WidgetCo、$4.2 billion、March、Q3
关系：Acme Corp --related_to--> Jane Doe
      Acme Corp --related_to--> 2024        ← 纯共现噪声

模型缺失时它静默降级成正则抽取，只在 stdout 打一行警告，返回值结构完全一样，调用方拿不到任何可编程的失败信号。

场景 B：手动 python -m spacy download en_core_web_sm 之后

实体：7/7 全对（Acme Corp、Berlin、WidgetCo、$4.2 billion、March 2024、Jane Doe、Q3）
关系：$4.2 billion --located_in--> March 2024   (confidence=0.7)

实体识别借 spaCy 之力是好的。但关系只抽出一条，而且是「42 亿美元位于 2024 年 3 月」——一条语义上根本不成立的三元组，带着 0.7 置信度进入知识图谱。

而全文唯一真正重要的事实 acquired(Acme Corp, WidgetCo)，两种场景下都没有被抽出来。

原因在实现里：所谓「确定性关系抽取」的主力路径是共现统计 + 正则模板，谓词从一张小的模式表里猜。知识图谱的价值几乎全在关系上，实体只是节点。

顺带两个部署上必须知道的点：RelationExtractor 初始化时会自动从 HuggingFace Hub 下载模型文件（实测有 Fetching 5 files 的网络请求）；所有 spaCy 抽出的实体置信度恒为 1.0，正则抽取恒为 0.7——这是常量，不是校准值。对一个把 confidence 写进审计记录的产品，这有误导性。

---

为什么这些问题能活下来：CI 从来不跑测试

仓库有 258 个测试文件、87,841 行测试代码、6,714 个断言。这个投入量本身是可信的。

但 9 个 GitHub Actions 工作流里，没有任何一个执行 pytest。ci.yml 只做三件事：装前端依赖、跑 3 个 JS 测试、构建 wheel 并检查静态资源有没有打进去。benchmark.yml 引用的 benchmarks/ 目录在仓库里根本不存在。

于是我在 CI 指定的同一个 Python 3.11 上、装齐依赖后自己跑了一遍：

160 failed, 4061 passed, 161 skipped, 186 deselected  in 104s

失败中包含核心功能（非缺依赖）：
  tests/kg/test_algorithms.py::test_betweenness_centrality
  tests/kg/test_algorithms.py::test_closeness_centrality
  tests/kg/test_algorithms.py::test_eigenvector_centrality
  tests/kg/test_algorithms.py::test_louvain_communities   ← 社区检测返回空
  tests/semantic_extract/test_extractors.py（批处理全线）
  tests/seed/test_seed_manager.py::test_load_from_csv

错误类型分布（前几名，均为真实缺陷而非环境问题）：
  17 × ProcessingError
  14 × TypeError: 'NoneType' object is not subscriptable
  14 × TypeError: '>' not supported between MagicMock and MagicMock
  11 × TypeError: object.__new__(X): X is not a type object

README 首页挂着 CI 徽章，而且是绿的。它绿是因为它没测任何东西。

这一条基本解释了前面所有问题为什么能长期存在——这不是「测试写得不好」，是「测试从来没被当作门禁」。8 万行测试代码写完就躺在仓库里，只在有人手动跑的时候才有意义。

顺带发现的其他工程问题

文档与真实 API 大面积对不上。 直接照抄 README 和模块 docstring：

>>> graph.get_graph_metrics()   # 模块 docstring 明确列为 "Enhanced Method"
AttributeError: 'ContextGraph' object has no attribute 'get_graph_metrics'

>>> graph.check_decision_rules({"category": "vendor_selection"})  # README 原文
{'compliant': False, 'violations': ['Confidence too low: 0',
                                    'Invalid outcome: None',
                                    'Missing required field: decision_maker']}
# README 把它当筛选条件用，实现却把这个 dict 当成"待校验的决策对象"
# 不报错，返回一个看起来很像回事、实际毫无意义的合规判定

官方 issue #920 已经承认「ContextGraph 模块 docstring 的示例不可运行」。对 AI 编码助手场景尤其糟糕——docstring 正是它们的主要输入。

依赖体积失控。 torch、transformers、spacy、opencv-python、librosa、gensim、faiss-cpu、umap-learn、matplotlib、seaborn、plotly、ipywidgets 全部是强制核心依赖，不是 extras。pip install semantica 拉 134 个包，macOS ARM 实测 1.8 GB，Linux x86_64 会拉 CUDA 版 torch，通常 4–6 GB。一个「上下文与溯源基础设施」库让你为了记录一条决策而装下 PyTorch 和 OpenCV，在容器镜像和 Serverless 场景基本不可接受。

顺带：Python 3.14 上直接装不上（gensim 没有 cp314 wheel，源码编译失败，实测复现）；requires-python = ">=3.8" 是假的（numpy≥2.0.2 要 3.9+，scikit-learn≥1.7 要 3.10+），实际可用区间是 3.10–3.13；PyPI 元数据写着 Development Status :: 5 - Production/Stable，而版本号是 0.6.5。

大规模静默失败。 except Exception 出现 1,256 次，其中 40 处直接 pass。结构相似度计算失败时返回 0.0 而不是抛错——错误被折叠成一个合法的低分，调用方无从区分「不相似」和「算挂了」。

广度优先生成的痕迹。 模块 docstring 动辄 80 行、逐条罗列每个方法名（且部分方法不存在）；semantica/evals/ 整个模块的内容是 __status__ = "coming_soon"——一个以抽取质量为立身之本的项目，没有任何抽取准确率基准；仓库根目录的 mcp/（1,597 行、功能更全）不会被打进 wheel，pip 装到的是 semantica/mcp_server/（617 行），两套 MCP 实现并存。

---

与同类项目对比

项目	Stars	PyPI 月下载	定位	相对 Semantica 的优势	Semantica 的相对优势
semantica	5.2k	~4.4k	上下文图 + 决策溯源 + 确定性推理	—	—
mem0ai/mem0	63.1k	4,079k	智能体记忆层	成熟度、生态、真实用量高 3 个数量级；API 面小易接入	PROV-O 溯源与 RDF/OWL 标准支持，mem0 没有
getzep/graphiti	29.8k	1,575k	时序知识图谱记忆	双时态模型工业级、增量更新、有公开基准	后端更多（含 RDF 全家桶），不绑 Neo4j
HKUDS/LightRAG	38.8k	313k	图增强 RAG	论文支撑 + 检索质量有基准；实现精简	有本体/SHACL/冲突检测，LightRAG 只做检索
microsoft/graphrag	35.4k	71k	LLM 驱动的图 RAG	微软背书、社区摘要方法有论文与评测	号称不依赖 LLM（但见上文）、可自托管全栈
topoteretes/cognee	30.0k	196k	AI 记忆 / ECL 管线	定位最接近，管线更收敛，依赖更轻	RDF/W3C 标准栈与合规导出更完整
neo4j/neo4j-graphrag-python	1.3k	—	官方 GraphRAG SDK	Neo4j 官方维护、行为可预期、依赖极轻	不绑单一后端，功能面宽得多

（数据截至 2026-08-12）

这张表的读法：Semantica 在「功能清单」这一维上确实赢过所有人——没有第二个开源项目一次性覆盖 RDF+LPG 双范式、PROV-O、SHACL、OWL、SKOS、Datalog、可视化工作台、MCP、CLI、REST。它输的是每一项的深度和验证程度。竞品普遍做得窄，但窄的那部分是经过基准、被百万级下载量捶打过的——Graphify 那种「只做知识图谱构建、其余全部外接」的路线，功能清单短得多，可验证面却完整得多。

顺着这张表还能看出另一件事：星标数和真实使用量之间的比值，是个比 Star 绝对值有用得多的信号。

mem0 每颗星对应 64.6 次月下载，Graphiti 52.9 次，而 Semantica 是 0.85 次——低了差不多两个数量级。热榜带来的是注意力，不是采用。这个比值可以直接加进你的开源选型清单：star 是营销的函数，下载量是使用的函数，两者背离越大，README 与代码的距离通常也越大。

---

多维度评分

维度	评分	依据
溯源与审计能力	8/10	合法 PROV-O + 哈希链 + verify_chain()，开源里少见的完成度
后端与生态覆盖	8/10	9 种图存储、29 个 ingestor、MCP/CLI/REST/可视化俱全
安全工程	7/10	独立 SSRF/注入防护模块、CodeQL/Checkov、Action pinning、GHSA 响应及时
图谱与存储正确性	6/10	后端实现认真，但中心性与社区检测用例本地失败
文档准确性	4/10	README 示例与真实 API 不符，docstring 列出不存在的方法
依赖与部署友好度	3/10	强制 torch/opencv，1.8–6 GB，无轻量安装路径，Python 版本声明不实
工程与测试纪律	2/10	8 万行测试 + 0 个 CI 测试步骤 + 160 条本地失败
抽取质量（无 LLM 路径）	2/10	关系抽取实质是共现 + 正则，产出语义错误三元组
推理引擎正确性	1/10	Rete 判别逻辑为空，任意规则匹配任意事实
决策检索相关性	1/10	两种配置分别为全假阳性 / 全假阴性

作为完整平台：3/10。单独把 semantica.provenance 拎出来：8/10。

---

结论：可以关注，不可信任

Semantica 把「AI 可审计性」这个真问题的外壳做得比任何开源项目都完整，把内核——推理是否正确、检索是否相关、抽取是否准确——留在了未验证状态，并且用一套不跑测试的 CI 掩盖了这件事。

具体建议：

可以考虑的场景。 只用溯源模块：需要给已有管线补一层 W3C PROV-O 审计链时，semantica.provenance 值得直接拿来用（或者读它的 schemas.py 自己实现，避开全量依赖）。需要真 RDF 语义栈：如果合规要求点名 OWL/SHACL/SPARQL 而不是「向量库加一点图」，它的三元组栈是少有的开源选择。以及做技术原型和概念演示——Explorer UI、cookbook、CLI 齐全，演示「可解释 AI 治理」很快。

不要用的场景。 任何进入生产的决策路径；受监管行业的合规系统（这恰恰是它宣传的目标场景，也恰恰是「带溯源的错误结论」危害最大的地方）；对镜像体积和冷启动敏感的部署；以及「只是想要 Agent 记忆」——mem0 和 Graphiti 在这件事上成熟度高出数量级。

如果还是要用，至少做这几件事：锁 Python 3.11/3.12；安装后立刻 python -m spacy download en_core_web_sm（否则你拿到的是正则结果且不会报错）；先跑一遍 pytest tests -m "not integration" 把与你用到的模块相关的失败筛出来（CI 不会替你做）；把 rete_engine 视为不可用，需要规则引擎就走它的 datalog_reasoner 或换 experta / durable_rules；关系抽取一律接 LLM 路径；离线环境先审计 HuggingFace Hub 的出网请求。

最后一点是这次调研真正的收获，它比 Semantica 本身更通用：当一个项目同时具备「极高的功能广度」「极低的下载/星比」「CI 不跑功能测试」这三个特征时，README 的可信度需要按代码实测重新定价。 三个信号都是公开可查的，加起来只要十分钟——比我这次花掉的几个小时便宜得多。

这个判断可以翻转。如果作者把 CI 接上 pytest、把 evals 从 "coming soon" 变成真基准、把 Rete 和判例检索修好，一两个版本就够了。底子是在的：溯源层和 RDF 栈是真资产，维护者对 issue 的响应也很积极。我会继续跟。

---

参考资料

• semantica-agi/semantica GitHub 仓库 — 5,247 Star / 567 Fork（截至 2026-08-12）
• semantica · PyPI — v0.6.5，2026-08-11 发布
• Issue #920: ContextGraph 模块 docstring 示例不可运行
• Issue #922: ContextGraph.add_edge 无去重，重复入图
• Issue #923: ContextGraph.to_dict() 缺锁，并发写入下 RuntimeError
• Issue #889: 每次调用都执行 spacy.load()，约 120ms/次
• GHSA-8c7v-62gr-hj6g: 本体 URL 抓取的未校验重定向（High）
• Trendshift 趋势数据 — 2026-08-10 登顶
• getsemantica.ai 官方站点
• mem0ai/mem0 · getzep/graphiti · HKUDS/LightRAG · microsoft/graphrag · topoteretes/cognee — 对比数据源
• PyPI Stats API — 月下载量数据（2026-08-12 取数）