目录

1. Semantica 是什么？
   • 1.1 一句话概括
   • 1.2 用一个场景理解它
   • 1.3 安装只需一行
   • 1.4 深度辨析 —— Semantica 与现有工具的关系
2. 为什么需要 Semantica？
   • 2.1 生产级 AI 面临的五大结构性盲区
3. Semantica 的核心能力
   • 3.1 Context Graphs（上下文图谱）
   • 3.2 Decision Intelligence（决策智能）
   • 3.3 Full Provenance（完整溯源）
   • 3.4 Reasoning Engines（推理引擎）
   • 3.5 Temporal Intelligence（时间智能）
   • 3.6 Ontology Hub（本体中心）
4. 四层架构详解
   • 4.1 数据在各层之间的流转
5. 快速上手：安装与基本使用
   • 5.1 安装
   • 5.2 基本使用示例
   • 5.3 知识图谱查询示例
   • 5.4 溯源追踪示例
   • 5.5 工程化最佳实践
6. 模块全景图
   • 6.1 能力分类总览
   • 6.2 模块速查表
   • 6.3 运维、监控与合规
7. 总结：Semantica 的引入清单

1. Semantica 是什么？

1.1 一句话概括

Semantica 是 AI Agent 的”问责与上下文层”（Accountability and Context Layer）。它不试图替代 LangChain 或 LlamaIndex 等编排框架，而是作为底层基础设施，填补大模型应用中的”信任空白”，让你的 AI Agent 输出变得可信、可追溯、可审计。

简单来说，LangChain 负责”怎么调用”，LlamaIndex 负责”检索什么”，而 Semantica 负责”为什么这么做”——它回答的是 AI 决策背后的依据、来源和推理路径。

1.2 用一个场景理解它

想象一下，你的 AI Agent 在医疗辅助系统中做了一个关乎患者安全的重要决策：

用户问：”我应该给这位患者开什么药？”
AI 回答：”建议使用药物 A，剂量 50mg。”

在开发环境里，这只是一个 API 调用的返回结果。但在真实的生产环境中，这个决策会面对来自不同角色的审视——每个人都需要不同维度的解释：

医生问：”AI 当时依据了哪些病历信息？”
患者问：”这个建议的医学依据是什么？”
监管问：”这个决策的过程能重现吗？是否符合最新指南？”
法务问：”出了问题，责任链条在哪？”

如果你的系统只能给出一个文本答案，而无法回答上述任何一个追问，那么你就面临一个”问责缺口”（Accountability Gap）。Semantica 就是为了填补这个缺口而生的——它在你现有的 Agent 架构下面铺了一层”证据地板”，让每一个输出都附带完整的上下文、来源和推理路径。

1.3 安装只需一行

pip install semantica

重要区分：系统级可解释性 vs 模型级可解释性

在深入使用之前，理解这个区分至关重要。市面上很多"可解释 AI"工具试图揭示 LLM 内部发生了什么——注意力权重、神经元激活、思维链等。Semantica 走的是完全不同的路线。

Semantica 提供的是系统级的可解释性，而不是基础模型级别的可解释性。它不试图打开 LLM 的黑箱——对任何外部系统来说，LLM 内部仍然是不透明的。Semantica 解释的是模型"外面"的一切：你喂给模型了什么数据、模型产出了什么决策、这些数据从哪来、决策经过了哪些规则、以及整个过程的完整时间线。

用一个类比来说：模型级可解释性像是试图理解一个法官脑子里在想什么；而 Semantica 做的是记录法官看了哪些证据、引用了哪些法条、听取了哪些证人证词、最终做出了什么判决——这些才是法庭记录里真正需要的东西。

1.4 深度辨析 —— Semantica 与现有工具的关系

很多开发者容易混淆 Semantica 与 LangChain 或 LlamaIndex 的定位——它们看起来都在"帮助构建 AI 应用"，但解决的问题层次完全不同。为了更精准地使用 Semantica，我们需要明确它在技术栈中的生态位。

1. 核心定位差异表

以下对比帮助你快速理解三者的本质区别：

特性	LangChain / LlamaIndex	Semantica
核心目标	编排与连接：快速串联 LLM、Prompt 和工具	问责与上下文：记录决策过程、存储结构化知识、提供审计线索
记忆机制	短期对话历史（Buffer）或简单的向量检索	Context Graphs：带有时间维度的、可查询的知识图谱
推理方式	依赖 LLM 的概率生成（黑盒）	混合推理：LLM 生成 + 符号逻辑推理（前向链/演绎）
可解释性	较弱，主要靠打印日志	原生支持：每个决策都有因果链和溯源记录
适用阶段	原型开发、非关键任务应用	生产环境、受监管行业（医疗/金融/法律）

2. 协同工作模式

Semantica 并不排斥 LangChain，二者是互补关系而非竞争关系。在实际工程中，推荐的架构模式是：

• 使用 LangChain 处理用户输入、Prompt 编排和工具调用——它擅长的是”调用链编排”。
• 使用 Semantica 作为 LangChain 的”记忆后端”和”审计员”——它擅长的是”记录发生了什么”。

示例逻辑：

当 LangChain 的 Agent 需要做一个关键决策（如”批准贷款”）时，调用 semantica.context.record_decision() 将决策依据、参考的上下文图谱节点、以及最终结果记录下来，而不是仅仅依赖 LLM 的文本输出。这样做的好处是：即使 LLM 产生了幻觉，你也能在审计时精确还原”决策当时看到了哪些事实”。

---

2. 为什么需要 Semantica？

2.1 生产级 AI 面临的五大结构性盲区

即使你拥有最强大的 AI Agent——使用最新的模型、精心设计的 Prompt、完善的工具链——也不意味着它是可信赖的。”能跑通 Demo”和”能上生产环境”之间存在一道巨大的鸿沟，尤其在医疗、金融、法律、国防这些”犯错会有严重后果”的领域。

以下是让现代 AI 系统无法在受监管环境中部署的五大结构性问题——它们不是”锦上添花”的优化项，而是合规团队一票否决的硬伤：

盲区	问题描述	后果
没有记忆结构	Agent 只存 embedding 向量，不存”意义”。向量之间没有语义关系，无法表达”A 是 B 的原因”或”A 与 B 矛盾”	无法问”为什么回忆起这个事实”；每次会话上下文都从零开始；相似但不相同的概念被混为一谈
没有决策轨迹	Agent 持续行动、调用工具、做出判断，但整个过程像流水一样消失，不留痕迹	无法交给审计员复盘；出了问题只能”重跑一遍”而非”回放分析”；难以定位错误源头
没有溯源能力	输出无法追溯到产生它的源文档、源数据	在医疗/金融/法律领域，无法验证信息来源，构成硬性合规障碍——FDA、SOX、GDPR 都要求”可追溯性”
没有推理透明性	给一个答案，但不知道这个答案是怎么得出来的，中间经过了哪些步骤	无法验证推理路径是否正确；无法质疑结论；无法区分”基于证据的推理”和”模型的幻觉”
没有冲突检测	来自不同来源的事实可能互相矛盾，但在向量库中悄悄共存，无人察觉	例如新旧政策冲突、不同文档的矛盾描述，导致系统输出变得不一致且不可预测

核心痛点： 这就是企业 AI 试点总是”卡住”的原因——不是模型不够好，不是 Prompt 不够精，而是合规与风控团队一直在说”还不行”。因为出了事没人能解释清楚。Semantica 的目标就是让这些结构性盲区不再是盲区。

---

3. Semantica 的核心能力

Semantica 为每个 Agent 提供可问责的基础设施——不是零散的工具集合，而是一套协同工作的完整体系。这六大能力覆盖了从"知识怎么存"到"决策怎么追踪"到"时间怎么建模"的全链路：

3.1 Context Graphs（上下文图谱）

Context Graph 是 Semantica 的基石组件。它不是简单的 key-value 存储，也不是普通的向量数据库——它是一个结构化、可查询、带时间维度的知识图谱，记录 Agent 知道的一切事实、做过的一切决策、推导出的一切结论。

你可以把它理解为 Agent 的"长期记忆"：不仅能存信息，还能理解信息之间的关系（图谱结构），还能回溯到任意时间点查看当时的知识状态（时间模型）。与传统向量存储最大的区别在于：向量库只能告诉你"哪些内容相似"，而 Context Graph 能告诉你"A 和 B 是什么关系、A 是在什么条件下被推导出来的"。

3.2 Decision Intelligence（决策智能）

在大多数 Agent 框架中，"决策"只是代码流程中的一个分支判断——执行完就消失了，无法回溯。Semantica 把每个决策提升为系统中的一等公民：它有自己的唯一 ID、完整的因果链、置信度评分，可以被搜索、被对比、被审计。

这意味着你可以做到三件以前做不到的事：搜索过去类似场景是怎么决策的（先例搜索），分析某个决策影响了哪些下游流程（因果追踪），以及检查新决策是否与历史决策保持一致（一致性保障）。

3.3 Full Provenance（完整溯源）

“这个结论从哪来的？”——这是受监管领域中被问得最多的问题。Semantica 的溯源系统确保每个事实都能链接到其源文档、摄取事件和完整的传递链。不是简单地在数据库里记一个"来源"字段，而是构建一条从原始输入到最终推理的完整证据链，每一步都有时间戳和操作记录。

• W3C PROV-O 合规的血缘追踪——这是国际公认的数据溯源标准
• 从原始输入到最终推理的完整可追溯性——任何一步都可回放
• recorded_at 时间戳 + OWL-Time 导出——满足时间归档要求
• 满足 HIPAA、SOX、GDPR、FDA 21 CFR Part 11 审计要求——覆盖主流合规框架

3.4 Reasoning Engines（推理引擎）

大多数 LLM 应用把推理过程完全交给模型黑箱处理——输入一个问题，直接得到一个答案，中间的推导过程无从得知。Semantica 的推理引擎提供可解释的推理路径：你可以看到每一步推导应用了哪条规则、基于哪些已知事实、得出了什么中间结论。它支持多种经典推理范式，可以根据场景灵活选择：

推理方式	说明
Forward Chaining（前向链）	从已知事实出发，逐步推导新结论
Rete 算法	高效模式匹配，适合大规模规则集
Deductive（演绎推理）	从一般到特殊的推理
Abductive（溯因推理）	从结果反推最佳解释
SPARQL 推理	基于 RDF 图的查询推理
Datalog	递归 Horn 子句规则

3.5 Temporal Intelligence（时间智能）

知识不是静态的。一条事实在某个时间点成立，在另一个时间点可能已经失效。“阿莫西林是一线用药"这个判断，在2020年的指南中成立，在2024年可能已经被修订。Semantica 的时间智能让你的图谱不仅知道"什么”，还知道"什么时候"——每个事实都带有时间标签，支持时间点快照查询和历史状态回放。

• Allen 区间代数：全部 13 种时间关系（before、after、during、overlaps 等），这是 AI 时间推理的标准框架
• 对历史图谱状态进行时间点查询——“2024年3月15日时，这条规则是什么？”
• 每个事实都有时间溯源戳——精确到毫秒的 recorded_at 时间标记
• OWL-Time 导出，符合标准归档要求——可与第三方合规工具对接

3.6 Ontology Hub（本体中心）

本体（Ontology）是知识图谱的"骨架"——它定义了哪些类型的实体存在、它们之间可以有什么关系、每个属性必须满足什么约束。Ontology Hub 让你不用在命令行里折腾 RDF 文件，而是在浏览器中完成完整的本体生命周期管理：从可视化编辑到验证到版本控制，一站搞定。

• 可视化 schema 编辑器——拖拽式定义实体类型和关系
• SHACL Studio：约束编写和验证——确保数据质量
• 跨本体对齐编写——当你的系统需要对接多个领域本体时
• 健康仪表盘 + 版本控制——跟踪本体的演进历史

---

4. 四层架构详解

Semantica 采用四层流水线架构，数据从原始输入逐层流向应用层。每一层只关注自己的职责，通过清晰的接口与下一层交互——这种设计让你可以只使用其中的一两层，也可以完整使用全部四层：

• Ingestion（摄取层）：负责从各种来源获取原始数据——文件、网页、RSS、数据库、Snowflake、Parquet、XML、MCP 等
• Processing（处理层）：将原始数据转换为结构化知识——文档解析、文本分块、规范化、实体抽取、关系抽取
• Intelligence（智能层）：在结构化知识之上构建高级能力——知识图谱构建、推理引擎、决策追踪、冲突检测
• Application（应用层）：将智能层的输出暴露给用户——API 服务、可视化、多格式导出、审计接口

4.1 数据在各层之间的流转

---

5. 快速上手：安装与基本使用

5.1 安装

Semantica 提供基础安装和按需安装两种方式。按需安装可以避免安装不需要的依赖：

# 基础安装
pip install semantica

# 安装所有可选依赖（Neo4j、Pinecone 等）
pip install 'semantica[all]'

# 只安装 Neo4j 支持
pip install 'semantica[neo4j]'

# 只安装 Pinecone 支持
pip install 'semantica[pinecone]'

5.2 基本使用示例

以下是一个完整的使用示例，展示 Semantica 的核心工作流：创建上下文图谱 → 存储知识 → 记录决策 → 搜索先例 → 分析影响力。注意这里使用了阿里云百炼的 text-embedding-v4 作为嵌入模型（通过 OpenAI 兼容接口调用）：

# ============================================
# Semantica 基础使用示例
# 演示：创建上下文图谱 → 存储知识 → 记录决策 → 搜索先例
# ============================================

import numpy as np
from openai import OpenAI as OpenAIClient
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore
from semantica.llms import OpenAI

# ---- 配置阿里云百炼 Embedding（通过 OpenAI 兼容接口） ----
embedding_client = OpenAIClient(api_key='sk-VRu6wkDBaA***********yRrbGFkvEn1Wo5', base_url="https://ai-gateway.costrip.cn/v1",)


def dashscope_embed(text: str) -> np.ndarray:
    """使用阿里云百炼 text-embedding-v4 生成向量"""
    resp = embedding_client.embeddings.create(model="text-embedding-v4", input=[text],)
    return np.array(resp.data[0].embedding, dtype=np.float32)


# ---- 初始化 VectorStore 并替换 embed 方法 ----
vector_store = VectorStore(backend="faiss", dimension=1024)
vector_store.embed = dashscope_embed  # 替换为百炼 Embedding

# ---- 初始化 Agent 上下文 ----
context = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    llm=OpenAI(
        model="deepseek-v4-flash",
        base_url="https://api.deepseek.com",
        api_key="sk-75c4e03a5***********168588334",
    ),
)

# 第二步：向知识图谱中存储事实
# 这些事实会被索引，后续可以被检索和推理
context.store("Qwen3-235B 在推理基准测试中比 Qwen2.5 提升 40%")
context.store("阿里云百炼提供企业级大模型服务，支持私有化部署")
context.store("在医疗领域，模型准确率需要达到 99% 以上才能上线")

# 第三步：记录一个决策
# record_decision 会捕获完整的决策生命周期和因果链
decision_id = context.record_decision(
    category="model_selection",                          # 决策类别
    scenario="为生产推理流水线选择大语言模型",            # 决策场景
    reasoning="Qwen3-235B 的基准优势证明了 3 倍成本增长是合理的",  # 推理依据
    outcome="selected_qwen3_235b",                       # 决策结果
    confidence=0.91,                                     # 置信度
)

# 第四步：搜索相关先例
# 查看过去是否有类似的决策，保障决策一致性
precedents = context.find_precedents(
    "模型选型推理",   # 搜索关键词
    limit=5           # 最多返回 5 条
)

# 第五步：分析决策影响力
# 了解这个决策对下游产生了什么影响
influence = context.analyze_decision_influence(decision_id)

# 打印结果
print(f"决策 ID: {decision_id}")
print(f"找到 {len(precedents)} 条相关先例")
print(f"决策影响范围: {influence}")

执行结果：

🔄 Semantica is processing: Storing memory: Qwen3-235B 在推理基准测试中比 Qwen2.5 提升 40%... 🔗 context AgentMemory |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -🔄 Semantica is indexing: Adding 1 vectors to FAISS index 📊 vector_store FAISSStore |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -🔄 Semantica is indexing: Adding 1 vectors to FAISS index 📊 vector_store FAISSStore |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -🔄 Semantica is indexing: Adding 1 vectors to FAISS index 📊 vector_store FAISSStore |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -决策 ID: 9d381379-d871-4e21-bb6e-4b5b092d7aac
找到 0 条相关先例
决策影响范围: {'decision_id': '9d381379-d871-4e21-bb6e-4b5b092d7aac', 'direct_influence': [], 'indirect_influence': [], 'influence_scores': [], 'total_influenced': 0, 'max_influence_score': 0.0}

5.3 知识图谱查询示例

除了自然语言式的知识存储，Semantica 还支持标准的 SPARQL 查询——这是 RDF 语义网的标准查询语言，可以精确匹配图谱中的三元组。以下示例演示了如何使用 Oxigraph 作为 RDF 后端，通过 SPARQL 查找满足特定条件的实体：

# ============================================
# 知识图谱 SPARQL 查询示例
# 演示如何对知识图谱进行结构化查询
# ============================================

import numpy as np
from openai import OpenAI as OpenAIClient
from semantica.context import AgentContext, ContextGraph
from semantica.triplet_store import TripletStore
from semantica.vector_store import VectorStore
from semantica.semantic_extract.types import Triplet

# ---- 初始化 TripletStore（内存 RDF 三元组存储） ----
triplet_store = TripletStore(backend="oxigraph")

# ---- 配置阿里云百炼 Embedding（通过 OpenAI 兼容接口） ----
embedding_client = OpenAIClient(api_key='sk-VRu6wkDBaAVe**********yRrbGFkvEn1Wo5', base_url="https://ai-gateway.costrip.cn/v1")


def dashscope_embed(text: str) -> np.ndarray:
    """使用阿里云百炼 text-embedding-v4 生成向量"""
    resp = embedding_client.embeddings.create(model="text-embedding-v4", input=[text])
    return np.array(resp.data[0].embedding, dtype=np.float32)


# ---- 初始化 VectorStore 并替换 embed 方法 ----
vector_store = VectorStore(backend="faiss", dimension=1024)
vector_store.embed = dashscope_embed

# ---- 初始化 AgentContext ----
context = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(
        triplet_store=triplet_store,
        advanced_analytics=True,
    ),
)

# ---- 定义命名空间前缀 ----
NS = "http://example.org/kb/"

# 存储一些结构化的三元组知识
# Oxigraph 要求 subject/predicate 为完整 IRI
triplet_store.add_triplet(Triplet(subject=f"{NS}Qwen3-235B", predicate=f"{NS}is_a", object="大语言模型"))
triplet_store.add_triplet(Triplet(subject=f"{NS}Qwen3-235B", predicate=f"{NS}developed_by", object="阿里云"))
triplet_store.add_triplet(Triplet(subject=f"{NS}Qwen3-235B", predicate=f"{NS}has_parameter_count", object="2350亿"))
triplet_store.add_triplet(Triplet(subject=f"{NS}阿里云百炼", predicate=f"{NS}provides", object="Qwen3-235B"))
triplet_store.add_triplet(Triplet(subject=f"{NS}阿里云百炼", predicate=f"{NS}supports", object="私有化部署"))

# 使用 SPARQL 查询知识图谱
# 查找所有由阿里云开发的模型
query = f"""
PREFIX kb: <{NS}>
SELECT ?model WHERE {{
    ?model kb:developed_by "阿里云" .
    ?model kb:is_a "大语言模型" .
}}
"""
results = triplet_store.execute_query(query)
print("阿里云开发的大语言模型:", results)

执行结果：

🔄 Semantica is storing: Executing SPARQL query 🗄️ triplet_store QueryEngine |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -阿里云开发的大语言模型: QueryResult(bindings=[{'model': {'type': 'uri', 'value': 'http://example.org/kb/Qwen3-235B'}}], variables=['model'], execution_time=0.005427122116088867, metadata={'query': 'PREFIX kb: <http://example.org/kb/> SELECT ?model WHERE { ?model kb:developed_by "阿里云" . ?model kb:is_a "大语言模型" . } LIMIT 1000', 'optimized': True, 'cached': False, 'graph': None, 'graphs': []}, triples=[])

Process finished with exit code 0

5.4 溯源追踪示例

溯源（Provenance）是 Semantica 在合规场景下的核心能力。以下示例演示了如何使用 ProvenanceManager 追踪一个事实的完整来源链——从哪份文档中提取、由谁生成、在什么时间点被记录。当审计员问"这条信息的依据是什么"时，你可以直接给出完整的证据链：

# ============================================
# 溯源（Provenance）追踪示例
# 演示如何追踪一个事实的来源
# ============================================

import numpy as np
from openai import OpenAI as OpenAIClient
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore
from semantica.provenance import ProvenanceManager

# ---- 配置阿里云百炼 Embedding（通过 OpenAI 兼容接口） ----
embedding_client = OpenAIClient(api_key='sk-VRu6wkDBa********NSlyRrbGFkvEn1Wo5', base_url="https://ai-gateway.costrip.cn/v1")


def dashscope_embed(text: str) -> np.ndarray:
    """使用阿里云百炼 text-embedding-v4 生成向量"""
    resp = embedding_client.embeddings.create(model="text-embedding-v4", input=[text])
    return np.array(resp.data[0].embedding, dtype=np.float32)


# ---- 初始化 VectorStore 并替换 embed 方法 ----
vector_store = VectorStore(backend="faiss", dimension=1024)
vector_store.embed = dashscope_embed

# ---- 初始化溯源管理器（内存存储） ----
provenance = ProvenanceManager()

# ---- 初始化 AgentContext ----
context = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(advanced_analytics=True),
)

# 模拟从文档中摄取知识
# 使用 ProvenanceManager 手动记录事实的来源
source_doc = "medical_guidelines_2024.pdf"
fact = "阿莫西林是治疗细菌性咽炎的一线用药"

entry = provenance.track_entity(
    entity_id=fact,
    source=source_doc,
    metadata={
        "author": "中华医学会",
        "publish_date": "2024-03-15",
        "document_type": "临床指南",
    },
)

# 同时将事实存入上下文（向量化 + 知识图谱）
context.store(fact)

# 追溯某个事实的完整来源链
result = provenance.get_provenance(fact)

# 输出溯源信息
print("事实溯源链:")
if result:
    for key, value in result.items():
        print(f"  {key}: {value}")
else:
    print("  未找到溯源信息")

# 查看溯源统计
stats = provenance.get_statistics()
print(f"\n溯源统计: {stats}")

执行结果：

🔄 Semantica is processing: Storing memory: 阿莫西林是治疗细菌性咽炎的一线用药... 🔗 context AgentMemory |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -🔄 Semantica is indexing: Adding 1 vectors to FAISS index 📊 vector_store FAISSStore |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -事实溯源链:
  entity_id: 阿莫西林是治疗细菌性咽炎的一线用药
  entity_type: entity
  activity_id: entity_tracking
  agent_id: semantica
  agent_type: software_agent
  is_automated: True
  role: None
  source_document: medical_guidelines_2024.pdf
  source_location: None
  source_quote: None
  timestamp: 2026-08-31T08:01:25.091513+00:00
  first_seen: 2026-08-31T08:01:25.091495+00:00
  last_updated: 2026-08-31T08:01:25.091505+00:00
  confidence: 1.0
  checksum: 1c32956f7370cec304384d94d29b90858588a7b0e96421fc6f6b8e0cfcefa94c
  sequence_id: 1
  previous_checksum: None
  parent_entity_id: None
  used_entities: []
  previous_version_id: None
  derived_from_id: None
  activity_started_at_time: None
  activity_ended_at_time: None
  acted_on_behalf_of: None
  informed_by_activities: []
  valid_from: None
  valid_until: None
  revision_type: None
  supersedes: None
  bundle_id: None
  invalidated: False
  invalidated_at_time: None
  invalidated_by: None
  invalidation_reason: None
  start_index: None
  end_index: None
  credibility: None
  metadata: {'author': '中华医学会', 'publish_date': '2024-03-15', 'document_type': '临床指南'}
  version: 1.0

溯源统计: {'total_entries': 1, 'entity_types': {'entity': 1}, 'unique_sources': 1}

Process finished with exit code 0

5.5 工程化最佳实践

在生产环境中使用 Semantica 时，遵循以下模式可以显著提升系统的稳定性和可维护性。这些经验来自真实项目中的踩坑总结：

1. 上下文图谱的”冷热分离”策略

不要将所有数据都无脑存入 Context Graph——这会导致图谱膨胀、查询变慢、管理困难。正确的做法是按访问频率分层：

• 热数据（Hot Data）：当前会话相关的实体、最近的操作记录。应加载到内存图谱或高性能图数据库（如 Neo4j/FalkorDB）中，确保毫秒级响应。
• 冷数据（Cold Data）：历史归档的决策记录、过期的法规文档。应存储在低成本的对象存储或归档数据库中，仅在审计或回溯时通过 ProvenanceManager 按需调用。

2. 决策记录的”原子性”原则

在调用 record_decision 时，确保记录的信息具备原子性——即每次决策的完整上下文都被一次性快照保存，以便后续复盘时不依赖外部状态。一个标准的决策记录应包含：

• Input State：决策时的系统状态快照（Snapshot），记录当时的所有已知信息。
• Retrieved Facts：本次决策参考了 Context Graph 中的哪些具体节点（通过 URI 链接），而不是模糊地说”参考了知识库”。
• Reasoning Path：如果是规则引擎推理，记录触发了哪条规则；如果是 LLM，记录使用的 Prompt 版本和参数——这样你才能在未来重现同样的推理过程。

3. 处理”幻觉”的防御性编程

LLM 幻觉是不可避免的现实。与其期望模型永不犯错，不如在系统层面建立防线。利用 Semantica 的 Conflict Detection（冲突检测） 能力，在存入新知识前主动检查是否与已有知识矛盾：

# 伪代码示例：在存入新知识前进行冲突检查
new_fact = "药物 A 的剂量是 100mg"
conflicts = context.kg.check_conflicts(new_fact)

if conflicts:
    # 触发人工审核或自动降级处理
    logger.warning(f"发现知识冲突: {conflicts}")
    # 调用 Ontology Hub 进行版本比对
else:
    context.store(new_fact)

---

6. 模块全景图

Semantica 提供了超过 25 个功能模块，按职责可以分为四大类。了解这些模块的定位和关系，能帮助你在实际项目中快速找到需要的能力：

6.1 能力分类总览

6.2 模块速查表

模块	核心功能	适用场景
semantica.context	上下文图谱、Agent 记忆、决策追踪	几乎所有场景的入口
semantica.kg	知识图谱构建、图算法、时间模型	需要结构化知识表示
semantica.semantic_extract	NER、关系抽取、事件抽取	从非结构化文本提取知识
semantica.reasoning	前向链、Rete、演绎、溯因推理	需要逻辑推理能力
semantica.ontology	SHACL、SKOS、本体对齐	需要领域本体管理
semantica.explorer	FastAPI Web 界面	可视化探索知识图谱
semantica.mcp_server	MCP 协议服务	连接 Claude/Cursor 等 IDE
semantica.vector_store	多种向量数据库后端	语义搜索和相似度匹配
semantica.graph_store	Neo4j/FalkorDB 等图数据库	大规模图存储和查询
semantica.triplet_store	RDF 三元组存储 + SPARQL	语义网标准兼容
semantica.ingest	多源数据摄取	从各种来源导入数据
semantica.parse	文档解析	处理 PDF/DOCX 等文档
semantica.split	文本分块	长文本切分策略
semantica.normalize	文本规范化	数据清洗和标准化
semantica.embeddings	多种 Embedding 后端	文本向量化
semantica.pipeline	流水线编排	复杂 ETL 流程
semantica.export	多格式导出	数据迁移和归档
semantica.visualization	图谱可视化	报告展示
semantica.deduplication	实体去重	数据质量提升
semantica.conflicts	冲突检测与解决	多源知识融合
semantica.provenance	W3C PROV-O 溯源	合规审计
semantica.change_management	版本控制、SHA-256 校验	知识变更管理
semantica.llms	多种大模型适配	LLM 调用
semantica.seed	基础图播种（CSV/JSON/SQL/API/RDF）	冷启动知识图谱
semantica.evals	评估与基准测试	质量保障
semantica.core	编排、配置、生命周期、插件注册	框架基础设施
semantica.utils	日志、校验、进度、哈希工具	通用辅助功能

6.3 运维、监控与合规

AI 系统上线后，运维的重点从传统应用的”服务器是否存活”转变为”模型行为是否合规”。以下三个维度是生产环境中需要持续关注的：

1. 审计日志标准化 (W3C PROV-O)

Semantica 原生支持 W3C PROV-O 标准，这意味着你的审计日志可以被第三方合规工具直接读取和分析，无需额外的格式转换。

• 建议配置：在 ProvenanceManager 中开启 detailed_tracing=True，确保每一个实体的 generatedAtTime（生成时间）和 wasAttributedTo（归因于哪个 Agent 或用户）都被精确记录。
• 价值：当监管机构询问”为什么 AI 拒绝了这位用户的申请？”时，你可以导出一个标准的 PROV-O 图谱，清晰展示从”用户输入”到”拒绝决策”的完整因果链——每一步都有时间戳和操作者记录。

2. 本体（Ontology）的版本控制

业务逻辑是随时间变化的（例如：2024年的医疗指南与2025年不同，2023年的税务规则在2024年已更新）。如果你的知识图谱只保存最新版本，那么当有人问”去年这个时候的规则是什么”时，你将无法回答。

• 使用 semantica.ontology 模块：不要硬编码业务规则。将业务规则定义为本体约束（SHACL），这样规则的变更本身也是可追踪、可版本化的。
• 时间智能：利用 Semantica 的 Temporal Intelligence，为事实打上 valid_from 和 valid_until 标签。
  • 场景：查询”2024年1月1日时的合规建议”时，系统应自动回溯到当时的知识状态，而不是使用最新的规则——这在法律诉讼中尤其重要。

3. 性能监控指标

除了常规的 API 延迟和错误率，使用 Semantica 时还需额外关注以下语义层面的指标：

• 图谱查询延迟：ContextGraph 的 SPARQL 查询复杂度是否过高？复杂图查询是否需要优化？
• 推理路径长度：Decision Intelligence 的因果链是否过长？过长的链条通常意味着系统过于复杂，决策逻辑难以向非技术人员解释——这本身就构成了合规风险。
• 溯源完整率：监控有多少输出是无法追溯到源文档的（即”裸奔”的生成内容），这个比例应该尽可能低——它是系统可信度的直接度量。

7. 总结：Semantica 的引入清单

在决定引入 Semantica 之前，请自测以下问题。这些问题帮助你判断你的项目是否真的需要 Semantica 提供的”信任基础设施”：

1. 你的 AI 应用是否涉及高风险决策（医疗诊断、金融风控、法律判定、招聘筛选）？
2. 你的客户或监管机构是否要求解释”为什么 AI 会这么说”？
3. 你是否发现 Agent 经常”遗忘”之前的设定，或在多轮对话中产生逻辑矛盾？
4. 你需要将非结构化数据（文档、报告、法规）转化为可查询、可推理的结构化知识资产吗？

如果有任何一个答案是”是”，那么 Semantica 就是你的基础设施必需品。

Semantica 不仅仅是一个代码库，它是 AI 从”玩具”走向”工具”的信任基石——让你的 AI 系统不仅能给出答案，还能解释为什么。