AI AGENT · CONTEXT GRAPH2026.08

有聊天记录就能审计？

把每次决定

连回事实与来源

KNOWLEDGE GRAPH · PROVENANCE · AUDIT

SEMANTICA

GRAPHAGENT

12 PARTS + PRACTICE

PART 02

RAG 缺口

相似不等于关系

PART 06

决策链实战

记录与追溯

PART 10

落地成本

先做最小验证

很多 AI Agent 演示都很顺：读资料、调用工具、给出结论，一两分钟完成任务。

真正进入业务后，问题会变成另一种样子。三个月后有人追问“当时为什么批准”“依据来自哪份文件”“这次判断和以前是否冲突”，普通对话记录和向量检索很难给出稳定答案。

开源项目 Semantica 处理的就是这类问题。它把实体、关系、事实、来源和 Agent 决策放进一张可查询的图，再保留决策之间的因果链与数据来源。

这篇文章会带你理解它与 RAG 的区别，并用 Python 记录一条可以回查的 Agent 决策链。

01

PART

Semantica 是什么

OVERVIEW · AGENT INFRASTRUCTURE

Semantica 是一套面向 AI Agent 的上下文图和知识图谱基础设施，使用 Python 开发，采用 MIT 许可证，可以自行部署。

它位于 LLM、Agent 框架和数据存储之间。上层模型继续负责理解和生成，Semantica 负责保存结构化上下文、记录决策、建立关系、执行确定性规则，并回答“这条结论从哪里来”。

项目当前包含知识图谱构建、决策记录、来源追踪、规则推理、冲突检测、实体去重、图分析、可视化、REST API、MCP 服务和多种数据库连接器。

这不是一个安装后就能直接聊天的桌面应用。它更像开发组件，适合已经在搭建 Agent、RAG 或企业数据平台的团队。

02

PART

普通 RAG 缺少什么

RAG · RELATIONSHIP GAP

向量检索擅长寻找“语义上相似的内容”。用户询问一份合同，系统可以从文档库召回相关段落，再让 LLM 生成答案。

但相似度不能完整表达业务关系。例如：

谁批准了这份合同；

批准时引用了哪条政策；

安全审查是否发生在付款审批之前；

后续哪些决定受到了这次审批影响；

两份来源对同一个客户给出了什么冲突信息。

这些问题依赖明确的实体、关系、时间和来源。把所有内容切成文本块再做向量检索，能找回材料，却很难稳定重建完整决策过程。

Semantica 的思路是保留向量检索，同时增加一层 Context Graph。文本相似性继续负责“可能相关”，图遍历负责“明确连接”，来源记录负责“证据来自哪里”。

03

PART

Context Graph 如何工作

CONTEXT · STRUCTURED MEMORY

来源

Source

上下文

Graph

决策

Decision

审计

Audit

Context Graph 可以理解为 Agent 的结构化记忆。

人物、公司、合同、政策、事件和决策都可以成为节点。节点之间通过 works_for、party_to、approved_by、caused 等关系连接。每条事实还能附带时间、来源和其他属性。

一次业务操作结束后，系统留下的不只是最终答案，还包括：

1

Agent 看到了哪些事实；

2

这些事实来自哪里；

3

Agent 做出了什么决定；

4

决定之间有什么因果关系；

5

后续操作受到了哪些影响。

需要审计时，可以沿着图向上追溯证据，也可以向下查看影响范围。

04

PART

Semantica 能提供哪些能力

CAPABILITIES · FOUR LAYERS

仓库的模块很多，可以先按四层理解。

数据进入与清洗

支持文件、网页、数据库、API、Git、邮件、流式数据以及部分企业数据平台。数据进入后，可以进行规范化、切块、实体抽取、关系抽取、冲突检测和去重。

图谱与存储

可以构建知识图谱和上下文图，并连接 RDF 三元组存储、Neo4j、FalkorDB、Apache AGE、AWS Neptune 以及多种向量数据库。

本地小项目可以从嵌入式或内存方案开始，不必一上来部署完整图数据库集群。

决策与推理

每次 Agent 决策都能保存为独立节点，随后建立原因、影响和先例关系。规则层支持前向链、Rete、Datalog、SPARQL 和 SHACL 等方式。

图构建、来源追踪和规则推理可以使用确定性流程，不要求每一步都调用 LLM。处理非结构化材料时，实体与关系抽取仍可能需要 NLP 模型或 LLM，具体取决于你的管道设计。

查询与对外连接

结果可以通过 Python、命令行、REST API 或 MCP 提供给 Agent。系统还能导出 JSON、CSV、RDF、OWL、Parquet、Cypher 和 JSON-LD 等格式。

05

PART

用 uv 创建示例项目

SETUP · PYTHON PROJECT

安装提醒

默认依赖包含 PyTorch、Transformers、spaCy 和 FAISS，首次安装需要准备网络、磁盘和等待时间。

Semantica 当前的 Python 包名是 semantica，要求 Python 3.8 或更高版本。为了减少环境冲突，建议放进独立项目。

powershell

uv init semantica-demo

cd semantica-demo

uv add semantica

安装完成后，运行官方诊断命令：

powershell

uv run semantica doctor

诊断会检查 Python、Semantica、向量存储和配置文件等项目。

需要注意，Semantica 的默认依赖包含 PyTorch、Transformers、spaCy、FAISS、Pandas 和图分析组件，安装包不算轻。网络和磁盘空间都要留出余量。

不要为了体验一个决策链示例，就把所有数据库、LLM 和云平台扩展一次装齐。等工作流需要时再添加对应 extra。

06

PART

记录第一条 Agent 决策

TUTORIAL · DECISION CHAIN

在项目根目录新建 decision_demo.py，写入下面的代码：

python

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

review_id = graph.record_decision(

    category=“supplier_review”,

    scenario=“审查供应商 A 的年度服务续约”,

    reasoning=“过去 12 个月服务可用率达到合同要求，报价未超过预算”,

    outcome=“进入安全复核”,

    confidence=0.91,

)

security_id = graph.record_decision(

    category=“security_review”,

    scenario=“检查供应商 A 的数据处理与访问控制”,

    reasoning=“审计报告有效，未发现未关闭的高危问题”,

    outcome=“安全复核通过”,

    confidence=0.88,

)

approval_id = graph.record_decision(

    category=“contract_approval”,

    scenario=“批准供应商 A 的年度续约”,

    reasoning=“业务指标达标，预算合规，安全复核通过”,

    outcome=“批准续约”,

    confidence=0.94,

)

graph.add_causal_relationship(

    review_id,

    security_id,

    relationship_type=“CAUSED”,

)

graph.add_causal_relationship(

    security_id,

    approval_id,

    relationship_type=“INFLUENCED”,

)

chain = graph.trace_decision_chain(approval_id)

impact = graph.analyze_decision_impact(review_id)

print(“审批链：”, chain)

print(“影响范围：”, impact)

运行：

powershell

uv run python decision_demo.py

这段代码记录了业务审查、安全复核和合同批准，并用两条因果关系把它们连接起来。

以后有人询问“为什么续约”，系统可以从批准节点向上追溯，而不是让 LLM 根据一堆日志临时编一个解释。

07

PART

再加入业务实体和关系

GRAPH · ENTITIES AND EDGES

决策链回答了“发生了什么”，知识图谱还能补充“涉及谁、哪份合同和什么组织”。

python

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

graph.add_node(

    “supplier_a”,

    “Organization”,

    name=“供应商 A”,

    industry=“Cloud Service”,

)

graph.add_node(

    “contract_2026”,

    “Contract”,

    value=480000,

    currency=“CNY”,

)

graph.add_node(

    “security_team”,

    “Team”,

    name=“信息安全组”,

)

graph.add_edge(

    “supplier_a”,

    “contract_2026”,

    edge_type=“party_to”,

)

graph.add_edge(

    “security_team”,

    “contract_2026”,

    edge_type=“reviewed”,

    reviewed_at=“2026-08-01”,

)

neighbors = graph.get_neighbors(“contract_2026”, hops=2)

print(neighbors)

在真实项目里，实体 ID 应来自稳定的业务主键，避免把公司简称、全称和历史名称当成三个不同实体。

08

PART

来源追踪有什么用

PROVENANCE · SOURCE TRACE

知识图谱最容易出现的问题是“看起来关系很完整，却没人知道事实来自哪里”。

Semantica 使用 W3C PROV-O 记录来源关系。你可以把实体关联到合同文件、数据库记录、API 响应或抽取程序，并保存处理时间和抽取器信息。

这样做有两个直接好处：

数据出错时能定位源文件和处理步骤；

接受审计时可以导出事实、决策和证据之间的关系。

来源记录仍然需要你的业务代码认真填写。工具只能提供结构，无法自动保证录入的数据真实、完整或符合法规。

09

PART

冲突检测比自动覆盖更重要

CONFLICTS · KEEP DISAGREEMENT

企业数据经常互相打架。CRM 显示客户地址是上海，合同系统保存的是北京，最新邮件里又出现了深圳。

简单的知识库可能用最近写入的数据覆盖旧值。这样查询结果看起来很干净，真实分歧却消失了。

Semantica 提供冲突检测和实体去重模块，允许系统保留不同来源的事实，再按照规则决定采用、合并或标记人工复核。

这类能力对合同、风控、医疗和主数据管理更有价值。对普通问答机器人，它可能显得过重。

10

PART

如何接入现有 Agent 和 RAG

INTEGRATION · EXISTING STACK

Semantica 的定位是补充现有技术栈。原来的 LLM、向量数据库和 Agent 框架可以继续使用。

一条比较清晰的接入流程是：

1

文档进入现有解析和切块管道；

2

文本块写入向量数据库，用于语义召回；

3

实体、关系、事实和来源写入 Context Graph；

4

Agent 检索时同时获取文本证据和图关系；

5

Agent 作出重要决定后调用 record_decision()；

6

审计或复盘时查询因果链、来源与历史快照。

如果使用支持 MCP 的客户端，也可以通过 Semantica 的 MCP 服务读取或写入图谱。不过，允许 Agent 写入正式知识图谱前，需要增加身份认证、权限控制、输入校验和审批流程。

11

PART

不要忽略这些成本

REALITY · IMPLEMENTATION COST

先做小范围验证

图谱层会增加数据建模、权限和运维工作，确认关系查询确实有业务价值后再扩大范围。

知识图谱不会自动把混乱数据变得可靠。落地 Semantica 之前，要评估下面几项成本。

本体和关系设计

团队需要约定哪些实体值得保存、关系怎样命名、哪些字段必须存在。没有统一模型，图谱很快会变成另一种数据堆积。

实体消歧

同名人物、公司别名和重复合同需要稳定的匹配规则。自动去重只能辅助，重要业务实体仍应使用主数据 ID。

来源质量

错误来源被完整追踪后，仍然是错误数据。可追溯解决的是“能否找到责任链”，并不等于输入天然可信。

权限与隐私

决策图可能包含客户、患者、员工和合同信息。谁能查看、修改和导出，应在接入阶段就确定。

运维复杂度

小型内存图和企业级 Neo4j、Neptune 的运维成本完全不同。先用最小后端验证查询价值，再决定是否扩展。

12

PART

哪些项目适合使用 Semantica

FIT · USE CASES

下面这些场景值得进一步测试：

Agent 会影响审批、授信、诊疗、合同或合规结果；

需要回答每条结论来自哪里；

多个 Agent 需要共享统一业务上下文；

业务问题依赖多跳关系和时间状态；

数据来源冲突，不能简单覆盖；

团队已经有向量 RAG，正在补充决策记录与治理能力。

如果项目只是个人问答助手、短期原型或简单文档搜索，直接使用向量检索会更轻。先确认是否真的需要关系查询、来源追踪和决策审计，再引入完整图谱层。

///

LAST

从一个真实问题开始

PRACTICE · FINAL ADVICE

评估 Semantica 时，不要先导入整个数据仓库。

选择一个经常被追问的业务决定，例如供应商续约、贷款审批或告警处置。只建相关实体、证据和三到五个决策节点，然后测试四个问题：

1

能否解释最终决定的直接原因；

2

能否追溯到原始数据来源；

3

能否发现相互冲突的事实；

4

能否查看决定造成的后续影响。

这四个问题能稳定回答，再扩大数据范围。若它们回答不了，继续增加节点数量只会让问题更难排查。

对 AI Agent 来说，给出答案只是任务的一半。涉及真实业务时，系统还要保存足够的证据，让答案在几个月后仍能被解释和复核。

我是dennis

觉得这篇文章有用，可以点赞、在看或转发给正在搭建 AI Agent 的朋友。

THANKS FOR READING