[Github] Semantica：面向 AI 决策的可审计 Context Graph 基础设施

如果你的 Agent 已经接上向量数据库，却仍然回答不清“这条结论来自哪份资料、当时依据是什么、后来哪条事实推翻了它”，缺的往往不是又一个 embedding 模型，而是一层能保存实体关系、时间、决策和来源的语义基础设施。Semantica 将自己定位为面向 Context 与 accountable AI systems 的图原生基础设施：把数据整理成可查询的 Context Graph，再把推理、溯源和决策记录暴露给 Agent 与审计工具。本文以 GitHub 当前仓库和 v0.6.7 Release 为依据，拆开它能做什么、不能替你做什么，以及如何从最小安装开始验证。

它补的是 LLM 与向量检索之间的语义层

普通向量 RAG 擅长按相似度找到片段，却不会自动知道两个名字是否指向同一实体、某个关系在哪个时间点成立、两份来源是否互相冲突，也不会凭空生成一条可复盘的决策链。Semantica 的核心思路是把实体、关系、事实和决策作为图中的一等节点，再用本体、约束、规则和来源信息为这些节点增加语义。

这不是把 LLM 换成图数据库。README 明确把确定性的图构建、规则推理和 provenance 设计成不依赖 LLM 的部分；模型可以参与抽取或生成，但实体关系的存储、规则执行和审计导出有独立路径。这样做的价值在于：即使模型换了，系统仍有一份可以查询、导出、校验和重放的上下文底账。

项目 README 使用“Open Source、Self-Hostable、Auditable、Governed、Zero Vendor Lock-In”等定位词，这些是维护者对项目目标的描述，不应被直接当作第三方认证。实际效果仍取决于本体设计、来源质量、实体消歧策略和部署后的权限控制。

一条数据怎样走到 Context Graph

Semantica 给出的架构顺序不是“文档切块后立刻向量化”，而是从来源到语义和证据的多阶段管线：

这种分层很适合把“召回结果”和“可采信证据”分开管理。例如向量检索找到一段销售说明后，图层还可以沿客户、产品、合同和时间边查询相关关系，并把最终使用的来源与规则记录下来。它不会自动让脏数据变干净：抽取错了实体，图里仍然可能建立错误的边；本体约束只能帮助发现和阻止问题，不能替你判断业务事实。

决策记录是它区别于普通记忆的地方

Context Graph 之外，Semantica 把 Decision Intelligence 做成独立能力。README 列出的操作包括 record_decision、add_causal_relationship、find_similar_decisions、trace_decision_chain、analyze_decision_impact 和 check_decision_rules，并支持以 W3C PROV-O、CSV 或 JSON 导出审计结果。

下面这段代码是仓库 README 展示的最小形态，用来说明 API 轮廓；它不是本文在当前环境中的性能测试：

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

decision_id = graph.record_decision(
    category="vendor_selection",
    subject="acme_corp",
    outcome="approved",
    rationale="符合安全与成本规则",
)
chain = graph.trace_decision_chain(decision_id)
similar = graph.find_similar_decisions(category="vendor_selection")
impact = graph.analyze_decision_impact(decision_id)
compliant = graph.check_decision_rules(decision_id)

真正落地时，重要的不是把这些方法塞进 Agent prompt，而是定义“什么算一条决策、谁或什么系统作出它、使用哪些事实、哪条规则生效、何时失效”。如果这些字段没有统一约定，trace_decision_chain 得到的只是结构完整但业务含义含糊的图。

图遍历、时间快照与向量召回如何配合

Semantica 的 Context Graph 允许实体、关系、决策和事实同时存在，并提供 state_at 一类的时间点查询思路。它可以让 Agent 先用向量索引找到语义相近的文档，再通过图遍历补齐实体连接、因果关系或历史版本；也可以在合并前标记冲突，在需要时重放某个时间点的状态。

这和“给模型多塞几段历史对话”不是同一件事。普通记忆往往是文本块，图结构则能表达“谁—在什么时候—以哪份来源—做了什么决定”。代价也很明确：图的 schema、本体、实体 ID、时间语义和合并策略都需要持续维护。若团队不愿意定义这些约束，直接启用全部功能可能只会增加另一个需要同步的数据层。

下面的官方 Explorer 画面展示了关系网络、时间滑块、节点详情、候选链接和溯源入口如何放在同一界面；它是界面能力示意，不代表项目会自动为你的数据生成正确关系。

从 pip install 开始做最小验证

核心安装路径很短：

pip install semantica

安装后可以运行 semantica doctor 检查环境，再根据任务安装可选 extra。例如 LangChain 集成使用 semantica[langchain]，Explorer 使用 semantica[explorer]，Neo4j、FalkorDB、Apache AGE、Amazon Neptune、Oxigraph、Qdrant、Pinecone、Snowflake 和 Databricks 也各自有对应 extra。README 的 extra 列表很长，建议先安装 core，再按实际后端追加，不要一开始就把所有可选依赖带进生产镜像。

最小验证可以分三步：先用内存或默认图存储记录一条人工构造的实体和决策；再运行规则或 SHACL 校验，确认不合规数据会被发现；最后导出 JSON、RDF 或 PROV-O，检查来源字段是否随结果保留下来。这样得到的是“管线能跑、证据能读”的基线，不是对吞吐和召回效果的承诺。

MCP、REST、CLI 和 Explorer 是四条入口

如果你的主要消费者是 Agent，MCP 是最直接的连接方式。仓库提供 python -m semantica.mcp_server 或 semantica-mcp 启动方式，工具覆盖实体/关系抽取、记录决策、查询决策、寻找先例、获取因果链、运行推理、图分析和导出。MCP 只是工具协议；权限、数据范围、超时和审计仍应在服务端处理。

需要给内部服务调用时，可以启动 python -m semantica.server，默认示例端口为 8000。REST 端点按 enrich、graph、decisions、reasoning、provenance、ontology、embeddings、search、export、pipeline、temporal 和 deduplication 等能力分组。生产环境不要照搬公开示例把所有端点直接暴露给互联网，应在反向代理、认证、网络策略和请求日志层做限制。

CLI 适合先看配置、存储和交互式 shell；Knowledge Explorer 则适合调试图结构与审计路径。安装 semantica[explorer] 后可运行 semantica-explorer --graph my_graph.json，在本机打开 127.0.0.1:8000，查看 Knowledge Graph、Timeline、Decisions、Entity Resolution、Ontology Hub 和 Lineage 等页面。

CLI 演示图来自仓库官方 GIF 的单帧，适合把“先跑通命令和配置，再接后端”的验证顺序落到实际操作上。画面中的版本和示例数据不应被当作你本地安装后的固定输出。

v0.6.7 带来了什么，升级时看什么

GitHub 最新 Release v0.6.7 发布于 2026 年 8 月 28 日。这个版本除了功能更新，还包含 SSRF 加固和 RDF/ontology 导出正确性修复。Release highlights 包括：LangChain 一等集成、SAP OData ingestor、ContextGraph 可编辑 Markdown 往返持久化、带可选 provenance 的 Assert/Retract/Call/EmitEvent reasoning Action layer、公开的 run_shacl_validation API，以及 Explorer 的 Markdown 内容查看器。

同时，Release 记录了 Agno/OpenClaw 出站请求经过 SSRF guard、MCP export_graph 修复、并行 pipeline 修复、配置布尔环境变量覆盖和多项 OWL/SHACL/JSON-LD 导出修正。对生产用户来说，这些“正确性与安全”变化和新功能同样重要：升级前应重新跑本体校验、导出快照、MCP 工具合同和网络访问测试，不能只看新 API 是否能 import。

生产部署：自托管不等于零运维

项目提供 Docker/Kubernetes 方向的部署配置，并建议设置 SEMANTICA_SECRET_KEY、使用持久化图存储、为向量检索选择合适的托管后端。存储后端可以按 RDF/LPG 和向量需求组合，但每一种组合都会带来备份、迁移、索引重建、版本兼容和权限映射问题。先在小数据集上验证导入、去重、时间查询、导出和恢复，再决定是否拆分服务。

安全边界也要单独验收。SAP OData、数据库、文件导入和 Agent 出站请求都可能触碰 SSRF、凭据泄露或过度读取风险；应限制允许访问的主机和协议，分离读取与写入凭据，并把原始文档、图快照、向量和审计导出纳入同一套数据保留策略。自托管带来数据控制权，但不替你完成租户隔离、密钥轮换、PII 脱敏和灾备。

在架构上，Semantica 可以和 WarpNav 已整理的 OpenViking 上下文数据库 形成互补视角：前者强调图关系、决策与 provenance，后者强调 Agent 资源、记忆和技能的目录化组织；两者不是同一产品，也不应未经测试就互相替代。若你更关注代码库图谱，也可以参考 WarpNav 的 Understand Anything 代码知识图谱介绍。

“可解释”解释的是系统证据，不是模型思维

这是阅读项目时最需要保留的一条限制。Semantica 的 README 明确说明，它能解释输入系统中的数据、关系、来源、策略、决策和执行轨迹，但不会重建 GPT、Claude 或其他基础模型内部的隐式推理，更不会提供模型的 chain-of-thought。把 provenance 图导出称为“模型透明”会夸大能力。

更准确的用法是：当 Agent 给出一个结果时，系统可以回答“用了哪些事实、来自哪份来源、经过哪条规则、关联了哪些历史决策，以及在当前时间点图状态下为何得到这个结果”。最终答案仍可能受模型生成错误影响，因此高风险场景应保留原始证据、人工复核和拒答路径，把图层当作可审计的上下文底座，而不是自动正确性证明。

版本、许可与适合的项目阶段

截至 2026 年 9 月 1 日，GitHub 仓库显示约 11,585 Stars、1,297 Forks，仓库未归档且默认分支仍在持续提交；这些数字会变化，只能作为活跃度快照。v0.6.7 采用 MIT License，允许在保留许可声明的前提下使用、修改和分发，但上游数据源、模型供应商和企业内部规则的许可与合规责任不会因为使用 MIT 项目而自动消失。

它更适合已经遇到以下问题的团队：Agent 需要跨来源建立实体关系；审计人员需要追溯决策输入；业务规则需要可执行的 ontology/SHACL/Rete/Datalog 约束；或者现有向量库无法表达时间、因果和冲突。若项目只是做一次性文档问答、没有稳定的实体模型和审计要求，先用轻量 RAG 往往更容易验证。Semantica 的价值在于把“上下文”变成可查询、可复核、可演进的系统对象，同时也把 schema 和运维责任带进了项目范围。

官方入口

• GitHub 仓库： semantica-agi/semantica
• 项目主页： https://getsemantica.ai
• 文档： https://docs.getsemantica.ai
• PyPI： https://pypi.org/project/semantica/
• 最新 Release： https://github.com/semantica-agi/semantica/releases/tag/v0.6.7

核验日期：2026 年 9 月 1 日。Stars、Forks、Release、可选依赖、后端兼容性和接口细节会随仓库更新；安装与生产部署前，请以仓库 README、Release notes 和官方文档的最新内容为准。