把企业数据变成可溯源的知识图谱（Semantica）

AI agent 大多靠向量检索找相似，返回一个分数，看不到实体之间的关系，也没法解释这个结果为什么被选中。放到金融、医疗、法务这类受监管的场景，这个「为什么」是要写进审计材料的，向量库答不上来。

Semantica 是用 Python 写的图原生上下文基础设施，把企业数据摄取成 Context Graph 与知识图谱，内置本体管理、确定性推理和决策溯源，供 AI 平台团队、数据团队与合规审计团队使用。

它被放在 LLM、向量库和 agent 框架下面一层。图构建、推理、溯源都是确定性流程，不依赖 LLM；要用 LLM 时走 semantica.llms，供应商可选 OpenAI、Anthropic、Gemini。输入是多源企业数据，输出是可查询的图结构，决策溯源与审计轨迹跟着结构一起产生。

项目开源在 GitHub，仓库地址是 https://github.com/semantica-agi/semantica ，MIT 许可证，主要语言 Python。抓取时 Star 13605、Fork 1557、开放 Issue 124，最新版本 v0.7.0 发布于 2026-09-22，最近一次提交在 2026-10-01。

它说的「溯源」是系统级的：解释的是喂进去的上下文、产出的决策、涉及的来源和执行轨迹。LLM 内部的推理过程对任何外部系统都不透明，这一层也不去重建它。

基础用法

安装与依赖

README 给出的安装方式只有一行命令：

pip install semantica

Python 版本要求 3.10 及以上，包发布在 PyPI，最新为 semantica 0.7.0。仓库另外附了 Dockerfile 与 docker-compose.yml、docker-compose.dev.yml，用于容器化部署。

仓库根目录里 requirements-ci.txt 有 562.2 KB，整个仓库 51824 KB。README 前 8000 字范围内没有列出完整依赖清单，也没有说明哪些图后端是必装、哪些可以选装。

最短能跑通的示例

README 开头只有一个安装代码块，之后直接进入平台介绍。在能读到的范围内，仓库没有给出可直接复制的 Python 调用示例，所以「装完之后第一段代码怎么写」这一步，仓库里没有说明。

找示例的位置有三个：cookbook/ 目录、examples/ 目录，以及仓库根部的 poc_runner.py。MCP server 相关内容在 semantica_mcp/ 目录。这些脚本各自怎么运行，仓库同样没有说明。

确认它跑起来了

一条可用的验证路径是 Knowledge Explorer。它是浏览器端的仪表盘，用来可视化探索本体与知识图谱，前端代码在 explorer/ 目录，配合 docker-compose.yml 可以起本地服务。

跑通的表现是 Explorer 页面能打开，画布上能看到节点和连边，边的 type 或 edge_type 标签（例如 works_for、leads、owns）正常渲染。边标签渲染曾经是坏的，v0.6.7 之前一直不显示，现在已修。

另一处观察点是终端输出。MCP server 早期版本会把进度条写进 stdout，污染 JSON-RPC 报文，这个问题已经修掉，进度条不再走 stdout。

主要功能

数据到图谱

• 数据摄取与 Context Graph 构建：把企业数据摄取进来，抽取关键内容，构建 Context Graph 与知识图谱。Context Graph 承载的是业务上下文，包含定义、关系与规则。具体的 CLI 命令或 Python 入口，README 前 8000 字里没有给出。
• 本体与受控词表管理：用 OWL、SHACL、SKOS 把实体在业务里的含义写显式，包括它的定义、关系和规则。SKOS 词汇表工作区的前端 React UI 与配套的 FastAPI 后端路由已经完成。
• 实体解析与冲突处理：来自多源、格式混乱的数据里，互相冲突的事实会被标出，重复的实体会被合并，而不是静默覆盖掉其中一个。这条写在 README 的目标人群描述里，具体调用方式仓库没有说明。
• 增量与 Delta 处理：只处理发生变化的部分，用版本化图和 delta 驱动管道，避免每轮全量重跑。仓库没有给出对应的开关字段或配置示例。

推理、溯源与集成

• 确定性推理与 SPARQL CONSTRUCT 模板：可以定义可参数化的 CONSTRUCT 模板，生成推断出来的或转换过的子图，结果能写入 triplet store，也可以限定作用范围。模板怎么注册、怎么调用，仓库里没有说明。
• 多后端图存储与导出：图存储同时支持 RDF 和 LPG 两种模型，遵循 W3C 标准。Apache AGE 集成让 PostgreSQL 可以直接当图数据库后端。导出支持 Apache Arrow 和 Turtle，Turtle 对应 format="ttl"。
• 决策智能与端到端溯源：每次决策用的上下文、来源、相关关系和执行轨迹都留在图里。ContextGraph.find_similar_decisions() 用来找相似决策，AgentContext.find_precedents() 用来找先例。
• 框架集成与 Knowledge Explorer：提供 LlamaIndex 集成（BaseRetriever、PropertyGraphStore 一类接口）和 LangChain 集成（SemanticaGraphStore、SemanticaRetriever），另外还有 MCP server 与浏览器端的 Knowledge Explorer。

参数与配置

常用参数

能从仓库与 Issue 里确认的配置点不多。安装层面是包名 semantica 加 Python 3.10+。导出层面有一个 format 参数，导出 Turtle 时写 format="ttl"。

MCP server 用 SEMANTICA_KG_PATH 这个环境变量指向知识图谱路径。该变量曾经在设置后不持久，重启就丢，问题已经修掉。

LLM 接入走 semantica.llms 模块，供应商在 OpenAI、Anthropic、Gemini 等之间选。具体的初始化参数与模型名写法，仓库前 8000 字没有说明。

配置文件

仓库根目录有 pyproject.toml、docker-compose.yml、docker-compose.dev.yml、.pre-commit-config.yaml、.checkov.yaml、osv-scanner.toml。

这些文件各自有哪些字段、哪些字段必填，仓库里没有说明。想换图后端或关掉某个集成，得自己去读源码。

实际使用中的坑

下面几条来自 GitHub Issue，都是用户实际撞到的问题，目前都标为已解决。

• MCP server 装不起来：进度条写进 stdout，破坏了 JSON-RPC 报文；SEMANTICA_KG_PATH 设置后不持久；mcp/README.md 里有 3 个 setup 步骤是坏的。在 Claude Code 上按文档配置的人会直接卡住。
• 决策 embedding 从不填充：AgentContext.find_precedents() 一直返回空列表，ContextGraph.find_similar_decisions() 在 save/load 之后也返回空。报出的环境是 Windows 11、Python 3.11.9、semantica 0.6.5。这两个方法正好是决策智能的核心接口，撞上就整条链路失效。
• TTL 导出报错：调用 format="ttl" 抛 ValidationError，入门 notebook 里也缺这段，新用户基本摸不到 Turtle 导出。
• Explorer 上边标签不显示：即使数据里带了 type 或 edge_type，画布上也不渲染连接边的标签，看图上只能看到点，看不出关系类型。

还有两条待解决的 Issue 不算 bug：把 Semantica 列进 Qdrant 的集成目录，以及把 LangChain 集成上游到 LangChain 官方文档。属于生态曝光类的工作。

几个同类怎么选

下面三项放在一起，是为了让读者看清各自的位置，不是推荐顺序。

• Semantica（本项目）：适合要自托管知识图谱与决策溯源、所在行业受监管的 AI 平台团队、数据团队与合规审计团队。部署方式为 pip install semantica，仓库另有 Dockerfile 与 docker-compose.yml，部署形态是库加服务。主要限制是本体、图后端、溯源链路都要自己接和配，装完只拿到一个包；README 与文档以英文为主，中文版由 readme-i18n 提供，仓库体积 51824 KB，requirements-ci.txt 有 562.2 KB。需要 W3C 标准本体（OWL/SHACL/SKOS）、需要能换图后端、并且要把决策溯源直接落进结构里时，选它更合适。项目地址：https://github.com/semantica-agi/semantica 。
• openbkn-ai/bkn-studio：适合需要 Web 界面来搭建、管理并协作维护业务知识网络的团队。仓库说明它是 OpenBKN 的 Web 控制台，具体部署步骤未逐一核实。主要限制是它属于 OpenBKN 生态的界面层，图后端与推理栈和 Semantica 不是同一套，其余能力未逐一核实。团队已经在用 OpenBKN、缺的只是浏览器里的操作与协作界面时，选它更合适。项目地址：https://github.com/openbkn-ai/bkn-studio 。
• Graphify：把代码库变成可查询的知识图谱：适合想把代码仓库本身变成可查询知识图谱的开发者。站内有专门文章拆解它的原理。主要限制是它处理的对象是代码库，与企业多源业务数据的摄取、本体管理和决策溯源不是同一件事，其余未逐一核实。当要理解的对象是一个代码仓库，而不是企业业务数据时，选它更合适。

Semantica 的短板在上手成本：本体、图后端、推理和溯源都交给使用者自己配，装完只有一个库，能在浏览器里看的界面还要另外起。团队已经有 OpenBKN 并且只缺一个管理协作界面时，bkn-studio 更直接；目标只是读懂一个代码仓库时，用 Graphify 更省事。反过来，需要 W3C 本体标准、需要能换后端，并且要把决策溯源写进结构里，这两者都不覆盖。

适合谁

需要把企业数据变成可查询、可追溯知识图谱的 AI 平台团队适合用。它的价值集中在受监管场景：金融、医疗、法务、政府、国防这类地方，AI 的决策要能向监管方解释清楚。数据团队如果已经在 Databricks、Snowflake 或 SAP 上有现成的表，想在不外迁数据的前提下建带血缘的知识图谱，也可以看看。

合规、风控和审计团队是另一类使用者，他们要的是「AI 为什么这么做」这个问题有个能交出去的答案。

只想给 RAG 加个向量库、不需要本体和溯源的团队用不上它，配置成本比收益大。已经在用托管 SaaS 解决问题、也不介意把数据交出去的团队，同样没必要换。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。