当 AI Agent 在贷款审批中给出"通过"时,六个月后监管机构问"为什么",你需要一个精确到每一步推理链的审计报告。向量数据库只能回答"什么和这条记录相似",无法回答"这个决策基于哪些证据、经过哪些推理步骤、受哪些上游影响"。Semantica(GitHub: semantica-agi/semantica)尝试用图原生基础设施解决这个问题:在 LLM 和向量存储之下叠加一层确定性的上下文图、决策记录和溯源系统,不依赖 LLM 即可完成知识图谱构建、推理和审计。

该项目定位为"开源版 Palantir for AI Agents",核心目标是让 AI 决策具备可追溯、可查询、可审计的结构化记录。截至本文发布时,Semantica 在 GitHub 获得 3,871 Star,日增 967 Star,最新版本 v0.6.0 于 2026 年 7 月 21 日发布,MIT 许可证。
架构:确定性管线而非黑箱
Semantica 的处理管线从数据采集到最终输出共经历九个阶段:
Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
→ Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
→ Vector Store + Polyglot Graph Store → Export / Visualize / REST · MCP · CLI管线的关键特征是确定性:知识图谱构建、推理引擎和溯源层完全不需要 LLM 参与。这意味着在受监管行业中,这些组件的输出是可预测、可复现的,不受模型随机性影响。
数据采集层
Semantica 支持 20 余种数据源接入:
| 类别 | 支持的源 |
|---|---|
| 本地文件 | PDF、DOCX、PPTX、HTML、TXT、CSV、JSON、YAML、Excel、XML |
| 数据库 | PostgreSQL、MySQL、SQLite、Oracle、SQL Server、MongoDB、DuckDB |
| 企业平台 | Databricks(Unity Catalog + Delta Lake)、Snowflake、Google Drive、Elasticsearch |
| 消息流 | Kafka、RabbitMQ、Kinesis、Pulsar |
| 其他 | Web 页面、RSS/Atom、REST API、Git 仓库、邮件(IMAP/POP3)、MCP 资源、Apache Arrow |
Databricks 连接器在 v0.6.0 新增,支持 PAT 和 OAuth M2M 两种认证方式,可直接从 Unity Catalog 中拉取表结构和血缘信息,将其转化为图节点。
抽取与冲突检测
文本经过解析和标准化后,进入 NER(命名实体识别)、关系抽取和事件检测阶段。抽取采用流水线模式,所有组件可独立替换:
from semantica.semantic_extract import (
NamedEntityRecognizer, RelationExtractor,
EventDetector, TripletExtractor,
)
ner = NamedEntityRecognizer(confidence_threshold=0.7)
entities = ner.extract_entities(text)
# → [Entity(name="Dario Amodei", type="PERSON"),
# Entity(name="Anthropic", type="ORG"), ...]
rel_extractor = RelationExtractor(confidence_threshold=0.6, bidirectional=True)
relations = rel_extractor.extract_relations(text, entities=entities)
# → [Relation(subject="Dario Amodei", predicate="ceo_of", object="Anthropic"), ...]冲突检测模块在知识合并前拦截矛盾数据。当两个来源对同一实体给出不同的属性值(例如一个来源写 Alice 的职位是 CTO,另一个写 VP Engineering),系统会标记冲突并按策略解决:
from semantica.conflicts import ConflictDetector
detector = ConflictDetector()
conflicts = detector.detect_conflicts(entities_from_source_a + entities_from_source_b)
# → [Conflict(entity="alice_chen", field="role",
# values=["CTO","VP Eng"], severity="HIGH")]冲突解决策略包括 credibility_weighted(按来源可信度加权)、most_recent(取最新)和 voting(多数投票)。来源可信度通过 SourceTracker 跟踪并在每次冲突解决中动态调整。
Context Graph:结构化记忆层
Semantica 的核心抽象是 Context Graph,一种超越向量相似度的结构化记忆。在传统 RAG 中,检索基于 embedding 距离,只能回答"什么和这条记录相似"。Context Graph 将每个实体、关系、决策和事实都建模为一等图节点,支持图遍历查询。
from semantica.context import ContextGraph
graph = ContextGraph(advanced_analytics=True)
graph.add_node("acme_corp", "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen", "Person", name="Alice Chen", role="CTO")
graph.add_node("contract_001", "Contract", value=2_400_000, currency="USD")
graph.add_edge("alice_chen", "acme_corp", edge_type="works_for", since="2019-03-01")
graph.add_edge("acme_corp", "contract_001", edge_type="party_to", signed="2024-01-15")与传统方案的对比:
| 能力 | Vector DB + RAG | LLM Memory | Semantica |
|---|---|---|---|
| 检索方式 | Embedding 相似度 | Token 窗口 | 图遍历 + 语义搜索 |
| 决策历史 | 不存储 | 不存储 | 一等可查询对象 |
| 溯源 | 无 | 无 | W3C PROV-O,源链接 |
| 冲突检测 | 静默覆盖 | 静默覆盖 | 检测、标记、解决 |
| 策略执行 | 无 | 无 | 内置规则引擎 + SHACL |
Semantica 的设计理念是补充而非替代现有技术栈:保留已有的 LLM、向量存储和 Agent 框架,在其之上叠加决策记录、因果推理、溯源和审计能力。
决策智能:可审计的推理链
决策智能(Decision Intelligence)是 Semantica 最具差异化的模块。每个 AI 决策被建模为图中的永久节点,携带完整的结构化上下文:类别、场景、推理过程、结果、置信度和元数据。
以贷款审批为例,一个完整的审计链路包含三步:
# 第一步:记录申请决策
app_id = graph.record_decision(
category="credit_application",
scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
reasoning="Income meets threshold; employment stable; no adverse credit events",
outcome="proceed_to_underwriting",
confidence=0.88,
metadata={"applicant_id": "A-7291"},
)
# 第二步:记录承销决策
uw_id = graph.record_decision(
category="loan_underwriting",
scenario="Underwriting review for A-7291",
reasoning="DTI within policy; clean 36-month credit history",
outcome="approved",
confidence=0.94,
)
# 第三步:记录利率设定
rate_id = graph.record_decision(
category="interest_rate",
scenario="Rate assignment for approved loan A-7291",
outcome="rate_set_8.9pct",
reasoning="Prime + 2.4% based on risk tier B2",
confidence=0.99,
)三个决策通过因果关系链接,形成可追溯的完整链路:
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")
graph.add_causal_relationship(uw_id, rate_id, relationship_type="INFLUENCED")构建完成后,系统提供四种查询方式回答审计需求:
trace_decision_chain(rate_id):回溯完整因果祖先链,从利率设定一直追到最初的申请find_similar_decisions("personal loan approval, 31% DTI"):按语义搜索历史先例analyze_decision_impact(uw_id):查看某个决策影响了哪些下游节点check_decision_rules({"category": "loan_underwriting"}):策略合规校验
决策记录可导出为 W3C PROV-O 格式,这是多数合规框架接受的监管提交格式,也可导出为 CSV 或 JSON。
确定性推理引擎
Semantica 内置三套推理引擎,全部基于确定性规则而非 LLM:
Rete 引擎:经典的模式匹配算法,用于前向链推理。以反洗钱规则为例:
from semantica.reasoning import ReteEngine, Rule, Fact, RuleType
rete = ReteEngine()
rete.build_network([
Rule(
rule_id="aml_flag",
name="Flag high-risk transactions",
conditions=[
{"field": "amount", "operator": ">", "value": 10_000},
{"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
],
conclusion="flag_for_compliance_review",
rule_type=RuleType.IMPLICATION,
),
])
rete.add_fact(Fact("tx_001", "transaction", [{"amount": 15_000, "country": "IR"}]))
flagged = rete.match_patterns()
# → [{"rule": "aml_flag", "matched_facts": ["tx_001"],
# "conclusion": "flag_for_compliance_review"}]README 中注明了一个已知限制:v0.6.0 的 Rete 引擎 alpha-node 条件匹配器设计较为简单,建议在实际部署前用 match_patterns() 输出对照真实规则集进行验证。
Datalog 推理器:支持递归查询,适合处理图上的传递关系:
from semantica.reasoning import DatalogReasoner
engine = DatalogReasoner()
engine.add_fact("parent(tom, bob)")
engine.add_rule("ancestor(X, Y) :- parent(X, Y).")
engine.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")
ancestors = engine.query("ancestor(tom, ?X)")
# → [{"X": "bob"}, {"X": "ann"}, {"X": "pat"}]ExplanationGenerator:每个推理结果都附带完整的推理步骤和理由,可以追踪从事实到结论的每一步路径。
多语种图存储
Semantica 的存储层同时支持 RDF(资源描述框架)和 LPG(标记属性图)两种图模型:
| 图模型 | 后端 |
|---|---|
| RDF | Oxigraph(嵌入式)、Blazegraph、Apache Jena、Eclipse RDF4J |
| LPG | Neo4j、FalkorDB、Apache AGE、AWS Neptune |
| 向量 | FAISS、Qdrant、Weaviate、Milvus、Pinecone、pgvector、SQLite-vec、内存 |
v0.6.0 为 Apache Jena 后端添加了 Named-Graph 支持,实现了 Blazegraph、RDF4J 和 Jena 之间的跨后端命名图一致性。同时引入了参数化的 SPARQL CONSTRUCT 查询模板,从 Blazegraph 专属扩展到 RDF4J 和 Jena。
所有后端可在不修改业务代码的前提下互换。Semantica 同时支持 W3C 标准查询语言 SPARQL 和属性图查询语言 Cypher。
溯源与本体治理
W3C PROV-O 溯源
每个实体和关系都绑定到其来源,形成完整的血缘链:
from semantica.provenance import ProvenanceManager
prov = ProvenanceManager(storage_path="./provenance.db")
prov.track_entity(
entity_id="acme_corp",
source="contracts/acme_master_agreement_2024.pdf",
metadata={"page": 1, "confidence": 0.97, "extractor": "NamedEntityRecognizer"},
)
lineage = prov.trace_lineage("alice_chen") # 完整祖先链SHACL/OWL 本体治理
本体模块支持从数据自动生成本体、验证图结构和管理词汇表:
from semantica.ontology import OntologyGenerator, OntologyValidator
ontology = gen.generate_ontology(data)
classes = gen.infer_classes(data)
report = validator.validate(ontology)
# → ValidationResult(valid=True, consistent=True, satisfiable=True)SHACL(Shapes Constraint Language)约束用于确保知识图谱中的数据符合预定义的结构规则,在金融和医疗等强合规场景中至关重要。
双时态图与时间旅行
Semantica 支持双时态(bi-temporal)建模,区分两个时间维度:
- valid_time:事实在现实世界中成立的时间段
- recorded_at:系统获知该事实的时间点
graph.add_edge(
"alice_chen", "acme_corp", edge_type="works_for",
valid_from="2024-03-01T00:00:00",
valid_until="2025-01-01T00:00:00",
)
snapshot_2023 = graph.state_at("2023-06-01") # 按时间点回放图状态这种设计可以回答"Alice 在 2024 年 6 月时是否仍在 Acme 任职"这类时间敏感的查询,而无需重新处理历史数据。
性能基准
v0.6.0 在一个 118,000 节点的生产图上测得以下数据(AMD EPYC、64 GB RAM):
| 操作 | 优化前 | 优化后 | 提升 |
|---|---|---|---|
| 节点搜索(118k 节点) | 24 ms | 0.004 ms | 6,000 倍 |
| Embedding 缓存命中 | 冷加载 | 基于修订的缓存 | 10 倍吞吐 |
| 语义去重 | 基准 | 优化候选生成 | 6.98 倍 |
| 候选生成 | 基准 | blocking 策略 | 63.6% |
去重和候选生成的数字来自 CHANGELOG 中的历史测量记录,而非自动化测试断言。
集成与部署
Semantica 提供四种接入方式:
MCP Server:30 秒接入 Claude Desktop、Windsurf、Cline 等 MCP 兼容客户端:
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}MCP 暴露 12 个工具,涵盖实体抽取、关系提取、决策记录、因果链查询、图分析和导出。
REST API:python -m semantica.server 在端口 8000 启动后端,端点覆盖 enrich、graph、decisions、reasoning、provenance、ontology 等 12 个模块。
CLI:随包附带,无需额外安装。semantica doctor 执行健康检查,semantica 启动交互式面板。
Agno 多 Agent 共享上下文:多个 Agent 读写同一个 Context Graph,研究员 Agent 的发现可以即时被分析师 Agent 读取,无需数据复制或同步。
安装方式:
pip install semantica # 核心包
pip install semantica[all] # 全部可选依赖
pip install semantica[graph-neo4j] # Neo4j 支持
pip install semantica[db-databricks] # Databricks 连接器
pip install semantica[vectorstore-qdrant] # Qdrant 向量存储生产环境建议使用 Docker 或 Kubernetes 部署,配置持久化图存储后端和托管向量存储。环境变量 SEMANTICA_SECRET_KEY 用于加密敏感配置。
适用场景
Semantica 面向 AI 决策必须可解释、可审计且可辩护的场景,同时要求数据不离开自有基础设施:
- 金融:贷款承销审计链、欺诈检测、AML 合规
- 医疗:临床决策支持、药物相互作用图谱
- 法律:证据溯源研究、合同分析、判例推理
- 政府与国防:政策决策记录、涉密信息治理,完全自托管
- 网络安全:威胁归因、事件响应时间线、IOC 溯源
这些领域的共同点是:AI 输出必须经得起审计员的"为什么"追问,而传统的向量数据库和 LLM 记忆无法提供结构化的决策溯源。Semantica 的价值在于把决策记录、因果推理和审计导出做成了基础设施级别的组件,通过确定性规则而非概率模型保证可复现性。
来源:semantica-agi/semantica · 文档 · PyPI