面向 AI Agent 的开源 Palantir

提示词、工具调用、Token、延迟、链路追踪，甚至某个答案背后检索到的文本片段，全部都可以被检视。

但六个月后，当有人提出那个更难的问题——"Agent 为什么会做出这个决策？"——答案就变成了一场重建工作。

你翻日志、重放提示词、检查向量库命中结果，还得祈祷底层数据从那之后没有变过。

对于一个会做出重大决策的 AI 系统来说，这是一种糟糕的架构。

这正是 Semantica 试图解决的问题，而最有意思的部分在于它的数据模型。

Semantica 将 Agent 上下文——即事实、关系、决策、来源、规则和因果链接——转化为一个你日后可以查询的图谱。

决策成为了一等公民对象。

这改变了你能提出的问题：

对于 Agent 而言，这是一种比"记忆"更有用的原语，因为它是一个决策图谱。

大多数 Agent 技术栈中缺失的一层

典型的生产技术栈运行流程是：用户事件 → Agent 框架 → LLM → 工具和 API → 向量数据库 → 日志和链路追踪。

在 Agent 开始做出关键决策之前，这套体系运转良好。

向量数据库或追踪系统并不是为了回答这些问题而设计的：系统当时相信什么、它决定了什么、是什么导致了那个决策、以及因此发生了什么？

Semantica 在技术栈中插入了一个图谱原生层：

Sources
  ↓  Ingest → Parse → Normalize → Split → Extract
  ↓  Conflict detection → Deduplication
  ↓  Knowledge graph
  ↓  Ontology
+ Reasoning
+ Provenance
+ Decisions
  ↓  Enriched context graph
  ↓  Vector store / Graph store / RDF store
  ↓  REST / MCP / CLI / Explorer / your agent

Sources
  ↓  Ingest → Parse → Normalize → Split → Extract
  ↓  Conflict detection → Deduplication
  ↓  Knowledge graph
  ↓  Ontology
+ Reasoning
+ Provenance
+ Decisions
  ↓  Enriched context graph
  ↓  Vector store / Graph store / RDF store
  ↓  REST / MCP / CLI / Explorer / your agent

该仓库提供了独立的模块，涵盖数据摄取、信息抽取、图谱构建、推理、来源追踪、决策智能、本体管理、向量搜索、时序查询、导出和可视化。

其核心思想是将 Agent 状态提升为结构化数据。

上下文图谱不是更好的 RAG

人们很容易把 Semantica 归到 GraphRAG 门下，但这低估了它。

其核心抽象是上下文图谱（context graph）：实体、关系、事实、决策、因果链接和时序状态共存于一个可查询的结构中，旁边还有一个向量库用于语义召回。

你不再需要在嵌入和图谱之间二选一。

每一层回答不同的问题：

Semantica 让 LLM 周围的基础设施变得可检视、可复现。

编者按： 如果你想深入了解本地 LLM 和 Agentic 技术栈，可以加入我们的 Agent Foundry 项目，获得动手实践的深度培训。

安装与版本注意事项

pip install semantica
semantica doctor


# everything, including optional integrations
pip install "semantica[all]"

pip install semantica
semantica doctor


# everything, including optional integrations
pip install "semantica[all]"

一个提醒：这个项目迭代很快。

请锁定你验证过的版本；如果你需要未发布的功能，请从源码检出安装并锁定 commit。

快速上手：把决策变成数据

from semantica.context import ContextGraph


ctx = ContextGraph(advanced_analytics=True)


decision_id = ctx.record_decision(
    category="vendor_selection",
    scenario="Choose a model provider for a regulated workflow",
    reasoning="Provider B supports required deployment controls and data residency",
    outcome="selected_provider_b",
    confidence=0.92,
)


chain = ctx.trace_decision_chain(decision_id)
precedents = ctx.find_similar_decisions("regulated model-provider selection", max_results=5)
impact = ctx.analyze_decision_impact(decision_id)

from semantica.context import ContextGraph


ctx = ContextGraph(advanced_analytics=True)


decision_id = ctx.record_decision(
    category="vendor_selection",
    scenario="Choose a model provider for a regulated workflow",
    reasoning="Provider B supports required deployment controls and data residency",
    outcome="selected_provider_b",
    confidence=0.92,
)


chain = ctx.trace_decision_chain(decision_id)
precedents = ctx.find_similar_decisions("regulated model-provider selection", max_results=5)
impact = ctx.analyze_decision_impact(decision_id)

这看起来简单得几乎不像话。

关键在于 record_decision() 在架构层面意味着什么：你不再把自由形式的推理塞进一行日志里，然后祈祷你的可观测性后端永远保持权威记录的地位。

你显式地对类别、场景、理由、结果、置信度以及与其他决策的关联进行建模。

一个警告： 不要用 reasoning 字段来持久化隐藏的模型思维链（chain-of-thought），而应该用它来记录你的应用准备好为之辩护的理由：考虑过的证据、应用的策略、跨越的阈值、人工覆盖。

这在生产环境中无论如何都更有用。

因果决策链

单个决策很有意思，但决策链才是基础设施。

以一个 Agent 化的采购流程为例：安全 Agent 给供应商打分，合规 Agent 检查数据驻留，采购 Agent 进行选择，财务 Agent 批准合同。

大多数系统存储四条独立的追踪记录。

Semantica 让这些关系变得显式：

security_id = ctx.record_decision(
    category="security_review",
    scenario="Evaluate Vendor B for production AI workload",
    reasoning="SOC 2 controls verified; private networking available",
    outcome="security_approved",
    confidence=0.95,
)


selection_id = ctx.record_decision(
    category="vendor_selection",
    scenario="Choose provider after security and compliance review",
    reasoning="Vendor B passed required controls and residency constraints",
    outcome="selected_vendor_b",
    confidence=0.91,
)


contract_id = ctx.record_decision(
    category="contract_approval",
    scenario="Approve annual Vendor B platform agreement",
    reasoning="Selected vendor is approved; budget within threshold",
    outcome="contract_approved",
    confidence=0.97,
)


ctx.add_causal_relationship(security_id, selection_id, relationship_type="CAUSED")
ctx.add_causal_relationship(selection_id, contract_id, relationship_type="INFLUENCED")


why_contract = ctx.trace_decision_chain(contract_id)
blast_radius = ctx.analyze_decision_impact(selection_id)

security_id = ctx.record_decision(
    category="security_review",
    scenario="Evaluate Vendor B for production AI workload",
    reasoning="SOC 2 controls verified; private networking available",
    outcome="security_approved",
    confidence=0.95,
)


selection_id = ctx.record_decision(
    category="vendor_selection",
    scenario="Choose provider after security and compliance review",
    reasoning="Vendor B passed required controls and residency constraints",
    outcome="selected_vendor_b",
    confidence=0.91,
)


contract_id = ctx.record_decision(
    category="contract_approval",
    scenario="Approve annual Vendor B platform agreement",
    reasoning="Selected vendor is approved; budget within threshold",
    outcome="contract_approved",
    confidence=0.97,
)


ctx.add_causal_relationship(security_id, selection_id, relationship_type="CAUSED")
ctx.add_causal_relationship(selection_id, contract_id, relationship_type="INFLUENCED")


why_contract = ctx.trace_decision_chain(contract_id)
blast_radius = ctx.analyze_decision_impact(selection_id)

该 API 目前支持三种关系类型：CAUSED（导致）、INFLUENCED（影响）和 PRECEDENT_FOR（先例）。

现在想象一下，供应商 B 在下个季度的安全审查中未通过。

你不再问"哪些追踪记录提到了供应商 B？"，而是问：哪些后续决策受到了原始选择决策的影响？

这就是决策的爆炸半径分析，正是 Agent 从副驾驶进化为自主审批、路由、采购、部署和拒绝的系统时所需要的操作。

从真实数据构建图谱

当决策记录附着在真实的知识图谱上，而不是手写的事实上时，它们会变得更有价值。

Semantica 提供了针对文件、网页内容、数据库、数据流、Git 仓库、邮件、Parquet、Snowflake 和 Databricks 的数据摄取器：

from semantica.ingest import FileIngestor
from semantica.kg import GraphBuilder


sources = FileIngestor().ingest_directory("./contracts/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)

from semantica.ingest import FileIngestor
from semantica.kg import GraphBuilder


sources = FileIngestor().ingest_directory("./contracts/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)

该流水线会进行规范化、切分、实体和关系抽取、冲突事实标记、去重，并构建图谱。

来源追踪：让"为什么"变得可辩护

因果链告诉你决策 B 依赖于决策 A，但你仍然需要知道是什么证据支撑了决策 A。

Semantica 的来源追踪模块建立在 W3C PROV-O 之上，这是用于表示来源信息的标准本体：

from semantica.provenance import ProvenanceManager


prov = ProvenanceManager(storage_path="./provenance.db")


prov.track_entity(
    entity_id="vendor_b",
    source="security/vendor_b_assessment_2026.pdf",
    metadata={"page": 12, "extractor": "NamedEntityRecognizer", "confidence": 0.98},
)


lineage = prov.get_lineage("vendor_b")

from semantica.provenance import ProvenanceManager


prov = ProvenanceManager(storage_path="./provenance.db")


prov.track_entity(
    entity_id="vendor_b",
    source="security/vendor_b_assessment_2026.pdf",
    metadata={"page": 12, "extractor": "NamedEntityRecognizer", "confidence": 0.98},
)


lineage = prov.get_lineage("vendor_b")

因果性解释依赖关系，来源追踪解释起源。

你需要两者才能在不猜测的情况下重建一个决策。

来源条目现在采用哈希链式结构，每条都携带一个序列 ID 和一个指向前一条目的校验和链接，verify_chain() 可以检测该历史中的断裂。

事实可以被失效（invalidate）而不是硬删除：

integrity = prov.verify_chain()


prov.invalidate(
    "vendor_b",
    agent_id="human_security_reviewer",
    reason="Certificate expired; prior approval no longer valid",
)

integrity = prov.verify_chain()


prov.invalidate(
    "vendor_b",
    agent_id="human_security_reviewer",
    reason="Certificate expired; prior approval no longer valid",
)

一个可变的 approved=false 行告诉你当前的真相。

而审计账本还会告诉你这个批准曾经存在过、谁撤销了它、以及为什么。

这是一种不同的需求，也是高风险 Agent 状态所需要的正确需求。

确定性推理：把策略排除在提示词之外

Semantica 内置了前向链推理（forward chaining）、Rete、Datalog 和 SPARQL 引擎。

核心要点是：不要让 LLM 去即兴发挥你的系统已经知道的规则。

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType


engine = ReteEngine()


engine.build_network([
    Rule(
        rule_id="manual_review",
        name="Escalate high-value restricted transactions",
        conditions=[
            {"field": "amount", "operator": ">", "value": 10000},
            {"field": "risk_tier", "operator": "in", "value": ["high", "critical"]},
        ],
        conclusion="require_manual_review",
        rule_type=RuleType.IMPLICATION,
    )
])


engine.add_fact(Fact("tx_001", "transaction", [{"amount": 25000, "risk_tier": "high"}]))
matches = engine.match_patterns()

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType


engine = ReteEngine()


engine.build_network([
    Rule(
        rule_id="manual_review",
        name="Escalate high-value restricted transactions",
        conditions=[
            {"field": "amount", "operator": ">", "value": 10000},
            {"field": "risk_tier", "operator": "in", "value": ["high", "critical"]},
        ],
        conclusion="require_manual_review",
        rule_type=RuleType.IMPLICATION,
    )
])


engine.add_fact(Fact("tx_001", "transaction", [{"amount": 25000, "risk_tier": "high"}]))
matches = engine.match_patterns()

如果一个策略决策来自确定性规则，你可以在决策元数据中记录规则 ID，并在日后复现该结果。

LLM 仍然负责抽取事实和提议行动，但策略关卡不再是提示词形式的英文描述。

一个提醒：Rete 条件匹配器是有意做得简单的，在将其接入生产合规关卡之前，你应该针对真实的规则集验证 match_patterns()。

不要在没有测试的情况下把一个演示用的规则引擎变成监管控制手段。

标准比框架更长寿

Semantica 依赖 W3C PROV-O 做来源追踪、RDF 做表示、SPARQL 做查询、SHACL 做图谱约束、OWL 做本体。

和最新的 Agent SDK 相比，这看起来有些过时——而这恰恰是它有用的原因。

Agent 框架会不断更迭，但审计要求不会。

你的监管者并不关心是哪个 Agent 循环产生了这个决策。

开放标准让记录与模型供应商和当月流行的框架解耦。

MCP 把图谱变成 Agent 工具

Semantica 通过 Model Context Protocol（MCP）服务器暴露所有功能：

python -m semantica.mcp_server
# or
semantica-mcp
{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "semantica.mcp_server"]
    }
  }
}

python -m semantica.mcp_server
# or
semantica-mcp
{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "semantica.mcp_server"]
    }
  }
}

该服务器暴露实体和关系抽取、决策记录和查询、先例搜索、因果链、图谱编辑、推理、分析和导出功能。

你的 Agent 通过标准化工具来记录或检视状态。

它在你的技术栈中的位置

Semantica 将自己定位为底层的持久化上下文和问责层：上方是 Agent 运行时，中间是决策、因果链接、来源、推理和约束，下方是图谱和向量存储。

当 LLM 保持概率性的同时，它周围的状态不再是转瞬即逝的。

可观测性是不够的

你仍然需要链路追踪、指标、评估和 Token 统计，但可观测性是以执行为中心的：它告诉你软件在一次运行中做了什么。

决策图谱是以领域为中心的：它记录系统作为业务状态的一部分做出了什么决策。

以一个承保 Agent 为例。

一条追踪记录显示模型调用了信用 API 并返回了 approved（已批准）。

决策图谱则表示为：

Applicant
 ├── income → $85k
 ├── DTI → 31%
 └── credit_history → clean_36_months


Decision: proceed_to_underwriting
 ├── based_on → applicant facts
 ├── sourced_from → application + credit report
 └── CAUSED → underwriting decision


Decision: approved
 ├── governed_by → lending policy
 └── INFLUENCED → interest-rate decision

Applicant
 ├── income → $85k
 ├── DTI → 31%
 └── credit_history → clean_36_months


Decision: proceed_to_underwriting
 ├── based_on → applicant facts
 ├── sourced_from → application + credit report
 └── CAUSED → underwriting decision


Decision: approved
 ├── governed_by → lending policy
 └── INFLUENCED → interest-rate decision

你可以在数月后检视这些内容，而无需重放原始的模型对话。

企业已经将订单、交易、审批和会计事件视为持久化的领域实体。

AI 决策应该加入它们的行列。

结语

下一个问题是让 Agent 在时间维度上可问责，而不仅仅是可解释。

作为架构的问责：决策 → 因果父节点 → 证据 → 来源 → 策略评估 → 下游影响 → 后续修正。

Semantica 是将这些原语打包到一个层中的、较为完整的开源尝试之一。