# https://github.com/semantica-agi/semantica 项目说明书

生成时间：2026-07-07 15:38:18 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [数据流水线与知识图谱构建](#page-2)
- [决策智能、推理与治理](#page-3)
- [存储后端、集成与部署](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[数据流水线与知识图谱构建](#page-2), [决策智能、推理与治理](#page-3), [存储后端、集成与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/semantica-agi/semantica/blob/main/README.md)
- [ARCHITECTURE.md](https://github.com/semantica-agi/semantica/blob/main/ARCHITECTURE.md)
- [docs/architecture.md](https://github.com/semantica-agi/semantica/blob/main/docs/architecture.md)
- [docs/index.md](https://github.com/semantica-agi/semantica/blob/main/docs/index.md)
- [docs/getting-started.md](https://github.com/semantica-agi/semantica/blob/main/docs/getting-started.md)
- [docs/quickstart.md](https://github.com/semantica-agi/semantica/blob/main/docs/quickstart.md)
</details>

# 项目概述与系统架构

Semantica 是一个面向 AI Agent 的开源语义智能框架，专注于构建上下文图（Context Graph）与决策智能层。其核心价值在于将多源异构数据通过语义抽取、推理与对齐，转化为具备可追溯性与可解释性的知识结构，从而为下游推理 Agent 提供高质量的语义基底。

## 项目定位与核心能力

Semantica 自首个稳定版（v0.3.0）起即确立了"Production/Stable"的成熟度定位，采用 MIT 许可证发布，支持 Python 3.8 – 3.12 运行环境，可通过 `pip install semantica` 一键安装 资料来源：[README.md:1-40]()。

框架围绕五大核心能力构建：

- **多模态数据接入**：覆盖结构化数据库（如 Snowflake）、半结构化文件（Parquet、Apache Arrow/Feather、JSON）以及本体文件（RDF/OWL、Turtle、JSON-LD、N3）。
- **语义抽取与推理**：支持命名实体识别（NER）、关系抽取、多创始人 LLM 抽取（Multi-Founder LLM Extraction）等能力，并兼容用户自定义 HuggingFace 模型（BYOM）。
- **知识图谱构建**：提供完整的图谱构建、操作与高级算法实现。
- **向量检索集成**：原生支持 Pinecone 等向量库，社区亦在讨论 pgVector、Apache AGE、SQLite-vec 等扩展集成 资料来源：[docs/getting-started.md:1-60]()。
- **决策追溯**：遵循 W3C PROV-O 规范实现跨模块的来源追踪与决策生命周期管理。

## 系统架构分层

Semantica 的整体架构遵循清晰的模块化分层设计，共划分为 17 个核心模块 资料来源：[ARCHITECTURE.md:1-80]()。

| 层级 | 模块示例 | 主要职责 |
|------|----------|----------|
| 接入层（Ingest） | `ArrowIngestor`、`SnowflakeIngestor`、`OntologyIngestor` | 多源数据接入与格式归一化 |
| 抽取层（Extract） | Semantic Extraction、NER、Relation Extraction | 从文本/结构化数据中识别实体与关系 |
| 图谱层（Graph） | Knowledge Graph、Decision Tracking、Provenance | 上下文图谱构建、决策与血缘管理 |
| 存储层（Storage） | Vector Stores（Pinecone 等）、Graph Backends | 向量与图数据的持久化 |
| 服务层（Serve） | `SemanticaAPI`、Distance Intelligence、Ontology Hub | 对外接口、距离计算与本体对齐 |

各模块之间通过统一的 `ingest(source_type=...)` 调度接口实现松耦合协作，开发者可在不修改上层调用的前提下替换具体后端实现 资料来源：[docs/index.md:1-50]()。

## 数据流与工作流

```mermaid
flowchart LR
    A[多源数据] --> B[Ingest 接入层]
    B --> C[Semantic Extraction 抽取层]
    C --> D[Knowledge Graph 图谱层]
    D --> E[Vector Store + Graph Backend 存储层]
    E --> F[Decision / Provenance 追溯]
    F --> G[API / Explorer 服务接口]
    G --> H[AI Agent 消费]
```

数据从外部源进入 `Ingestor` 后，依次经过实体抽取、关系构建与图谱融合，进入向量与图后端进行持久化；决策与血缘元数据（Provenance）会同步记录以满足审计与回溯需求。距离智能（Distance Intelligence）能力允许跨节点测量语义距离，并在 API 与 Explorer 中暴露给调用方 资料来源：[docs/architecture.md:1-90]()。

## 部署与扩展性

框架默认以 Python 包形式发布，同时也提供 REST API 服务（`SemanticaAPI`）。v0.5.0 引入的 Ontology Hub 工作区进一步扩展了浏览、加载、对齐与校验本体的能力，使 Semantica 可作为团队级语义基础设施使用 资料来源：[docs/quickstart.md:1-70]()。

社区方面，开发者在 Issue #247 与 #240 中持续呼吁扩展更多向量库与图数据库后端（如 pgVector、Apache AGE、SQLite-vec），这反映了框架在存储可插拔架构上的开放性设计目标 资料来源：[docs/getting-started.md:60-120]()。基于现有的模块化基础，后续后端的集成通常只需新增对应的 `Ingestor` 与后端适配器即可接入整体数据流。

---

<a id='page-2'></a>

## 数据流水线与知识图谱构建

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [决策智能、推理与治理](#page-3), [存储后端、集成与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/guides/ingest.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/ingest.md)
- [docs/guides/pipeline.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/pipeline.md)
- [docs/guides/semantic-extraction.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/semantic-extraction.md)
- [docs/guides/graph-analytics.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/graph-analytics.md)
- [docs/guides/deduplication.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/deduplication.md)
- [semantica/ingest/__init__.py](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/__init__.py)
- [semantica/pipeline/__init__.py](https://github.com/semantica-agi/semantica/blob/main/semantica/pipeline/__init__.py)
- [semantica/semantic_extract/__init__.py](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py)
- [semantica/deduplicate/__init__.py](https://github.com/semantica-agi/semantica/blob/main/semantica/deduplicate/__init__.py)
- [semantica/graph/analytics.py](https://github.com/semantica-agi/semantica/blob/main/semantica/graph/analytics.py)
</details>

# 数据流水线与知识图谱构建

Semantica 是一个面向 AI Agent 的开源上下文图谱（context graph）与决策智能框架。其核心价值在于将异构数据通过标准化流水线转化为结构化的知识图谱，供下游推理、检索与决策使用。`数据流水线与知识图谱构建` 模块覆盖了从原始数据进入到最终图谱落库的全链路，是项目最基础也是最关键的子能力之一。

## 流水线总体架构

Semantica 流水线遵循经典的 **ETL → Extract → Resolve → Build** 四阶段范式，各阶段通过统一的 `Pipeline` 编排器串联，确保可观测、可中断、可恢复。资料来源：[docs/guides/pipeline.md]() 描述了流水线的核心入口与阶段划分；入口模块统一由 `semantica.pipeline.__init__` 暴露，便于上层应用以单文件依赖方式集成。资料来源：[semantica/pipeline/__init__.py:1-40]()

| 阶段 | 职责 | 关键模块 |
|------|------|----------|
| Ingest | 多源数据接入与格式归一化 | `semantica/ingest/` |
| Semantic Extract | 实体、关系、事件抽取 | `semantica/semantic_extract/` |
| Deduplicate | 实体对齐与冲突消解 | `semantica/deduplicate/` |
| Graph Build | 节点/边写入与索引 | `semantica/graph/` |

## 数据接入（Ingest）

`ingest` 子包提供了面向多种数据源的统一接入能力。截至 v0.5.1，官方支持的接入器包括 Apache Arrow/Feather/IPC、Parquet、Snowflake、Ontology（RDF/OWL）、CSV、JSON、PDF、网页等。所有接入器都遵循一致的 `Ingestor` 接口，并通过顶层 `ingest(source_type=...)` 调度器路由。资料来源：[semantica/ingest/__init__.py:1-60]() 暴露了诸如 `ArrowIngestor`、`SnowflakeIngestor`、`OntologyIngestor` 等具体实现，并附带 `ingest_arrow()`、`ingest_ontology()` 等便捷函数。

v0.5.1 新增的 Apache Arrow 通道支持 IPC File / IPC Stream / Feather v1/v2，并允许通过 `columns`、`row_limit` 参数进行列裁剪与行限制，满足大数据量批处理场景。资料来源：[docs/guides/ingest.md]() 中详细说明了各接入器的参数与返回值结构 `IngestData`/`DataBatch`。

## 语义抽取与对齐

通过统一接入层进入的数据会被送入语义抽取模块。`semantica.semantic_extract` 子包基于 LLM 与传统 NLP 混合策略，从非结构化文本中抽取实体、关系及事件三元组，并附带置信度与时间戳。v0.2.5 引入的 BYOM（Bring Your Own Model）能力允许用户接入 Hugging Face 自定义模型，提升抽取粒度与领域适配性。资料来源：[docs/guides/semantic-extraction.md:1-80]()

随后，抽取结果进入去重与实体对齐阶段。`semantica.deduplicate` 通过向量相似度、字符串规范化以及本体映射（ontology alignment）实现实体合并，避免图谱中出现重复节点。资料来源：[semantica/deduplicate/__init__.py]() 公开了 `deduplicate_entities`、`merge_duplicates` 等高层 API。资料来源：[docs/guides/deduplication.md]() 描述了基于嵌入向量余弦距离与 Jaro-Winkler 字符串相似度的双路判定策略。

## 图谱构建与图分析

完成抽取与对齐后，图谱构建器将三元组写入图存储（支持 NetworkX、Neo4j 等后端），同时输出嵌入向量到向量数据库（如 Pinecone、FAISS）。`semantica.graph.analytics` 模块进一步提供中心度、社区发现、最短路径等常见图算法。资料来源：[semantica/graph/analytics.py:1-120]()。

```mermaid
graph LR
  A[多源数据] --> B[Ingest 接入]
  B --> C[语义抽取]
  C --> D[去重对齐]
  D --> E[图谱写入]
  E --> F[图分析/推理]
```

v0.5.0 引入的 **Distance Intelligence** 进一步增强了节点间的语义距离度量能力，可在图谱层面评估任意两节点的近邻性与拓扑关系，资料来源：[docs/guides/graph-analytics.md]()。同时新增的 Ontology Hub 工作区允许用户在工作台浏览、对齐、校验本体，资料来源：[docs/guides/ingest.md]() 的 Ontology 章节。

## 社区关注与扩展点

社区中反馈较为集中的扩展诉求集中在存储后端层面：例如 #247 请求的 pgVector 与 Apache AGE 集成，以及 #240 提出的 SQLite + sqlite-vec 轻量级向量库支持。资料来源：[GitHub Issue #247]()、[GitHub Issue #240]()。这两类诉求均落在流水线末端——即图谱/向量落库环节——意味着流水线架构具备良好的可插拔空间，后续接入只需实现 `VectorStore` 与 `GraphStore` 接口即可平滑替换。

总体而言，`数据流水线与知识图谱构建` 是 Semantica 框架的中枢：从多源接入到图谱分析，模块职责清晰，版本演进方向明确，并提供可观测、可扩展的入口点供业务方按需取舍。

---

<a id='page-3'></a>

## 决策智能、推理与治理

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据流水线与知识图谱构建](#page-2), [存储后端、集成与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/guides/decision-intelligence.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/decision-intelligence.md)
- [docs/guides/reasoning.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/reasoning.md)
- [docs/guides/provenance.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/provenance.md)
- [docs/guides/governance.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/governance.md)
- [docs/guides/ontology.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/ontology.md)
- [docs/guides/shacl-validation.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/shacl-validation.md)
- [docs/guides/context-graphs.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/context-graphs.md)
- [CHANGELOG.md](https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md)
</details>

# 决策智能、推理与治理

Semantica 的「决策智能、推理与治理」是一个面向 AI Agent 的高层能力栈，负责在上下文图谱（context graph）之上完成**语义抽取 → 多跳推理 → 决策追踪 → 端到端治理**的闭环。该栈最早在 `v0.3.0-alpha` 引入决策追踪系统（Decision Tracking System），随后在 `v0.2.6` 中完成 W3C PROV-O 兼容的溯源层，并在 `v0.4.0` 中加入**双时态智能（bi-temporal intelligence）**能力，使其同时具备"事件发生时间"与"系统记录时间"两条时间线  资料来源：[CHANGELOG.md:0-0]()。

本页面向第一次接触 Semantica 的工程师，重点回答三个问题：

1. **决策智能**如何把分散的实体与关系组织为可追溯的决策记录？
2. **推理**模块如何在图谱上做多跳与跨域语义推理？
3. **治理**层如何保证数据质量、合规与可审计性？

## 决策智能：决策的生命周期与上下文图谱

Semantica 将每一次 AI 决策视为图谱上的一个**一阶实体**，并赋予其完整的生命周期：提议（proposed）→ 评估（evaluated）→ 批准（approved）→ 执行（executed）→ 审计（audited）。决策节点通过 `used`、`generated`、`derivedFrom` 等关系反向链接到原始证据节点，从而形成完整的取证链  资料来源：[docs/guides/decision-intelligence.md:0-0]()。

上下文图谱作为基础设施，将文本、表格、本体、向量检索结果统一为带类型的节点与边，使决策不再漂浮在 LLM 上下文中，而是具备**可查询、可回放、可比对**的结构  资料来源：[docs/guides/context-graphs.md:0-0]()。在 `v0.3.0-alpha` 的发布说明中明确指出，"complete decision lifecycle management with audit trails"是该系统的核心交付  资料来源：[CHANGELOG.md:0-0]()。

| 阶段 | 关键产物 | 关联模块 |
| --- | --- | --- |
| 提出 | `Decision` 节点 | 抽取、对齐 |
| 评估 | `Evaluation` 节点 + 分数 | 推理、向量化 |
| 批准 | `Policy` 节点 + 签名 | 治理 |
| 执行 | `ActionExecution` 节点 | Agent 运行时 |
| 审计 | PROV-O 资源 | 溯源 |

## 推理：从单跳到多跳的语义检索

推理模块建立在 **v0.2.6 之后兼容 PROV-O 的图谱**之上，提供三类原子能力：

- **本体内推理**：基于 RDF/OWL 的子类、公理与传递性进行零样本推理；
- **向量近邻推理**：通过嵌入相似度在上下文图谱中检索语义相近的节点；
- **多跳图推理**：在图上进行 BFS/最短路径与社区检测，回答"X 与 Y 通过哪些实体关联"。

`v0.5.0` 进一步引入"**Distance Intelligence**"，允许跨图谱/API/Explorer 测量任意两个节点之间的**语义距离**，使推理结果可以量化展示  资料来源：[CHANGELOG.md:0-0]()。`v0.4.0` 的双时态栈允许对同一查询分别构造 valid-time 与 transaction-time 两个时间切片，避免"事后改写历史"的歧义  资料来源：[CHANGELOG.md:0-0]()  资料来源：[docs/guides/reasoning.md:0-0]()。

## 治理：溯源、合规与本体校验

治理层由三部分组成，目标是让决策可被**外部审计**、**外部合规框架**复用：

1. **PROV-O 溯源**：`v0.2.6` 在全部 17 个模块中落地 W3C PROV-O 兼容的 Entity/Activity/Agent 资源，支持跨模块 lineage 查询  资料来源：[CHANGELOG.md:0-0]()  资料来源：[docs/guides/provenance.md:0-0]()；
2. **本体（Ontology）管控**：`v0.2.4` 引入 `OntologyIngestor`，支持 Turtle、RDF/XML、JSON-LD、N3；`v0.5.0` 进一步提供 **Ontology Hub**，用于浏览、对齐与校验  资料来源：[CHANGELOG.md:0-0]()  资料来源：[docs/guides/ontology.md:0-0]()；
3. **SHACL 形状校验**：通过 `ShaclValidator`（`docs/guides/shacl-validation.md` 中描述）执行形状约束，使决策记录必须符合组织级或行业级 schema，否则写入被拒  资料来源：[docs/guides/shacl-validation.md:0-0]()  资料来源：[docs/guides/governance.md:0-0]()。

下图为三层治理的协作关系：

```mermaid
flowchart LR
  A[抽取] --> B[上下文图谱]
  B --> C[推理]
  C --> D[决策节点]
  D --> E[PROV-O 溯源]
  D --> F[本体校验]
  D --> G[SHACL 形状]
  E --> H[审计仪表盘]
  F --> H
  G --> H
```

## 端到端工作流与社区关注

一个典型端到端流程为：**(1) 上传异构数据**（CSV/数据库/Arrow）→ **(2) 通过 `OntologyIngestor` 对齐到 RDF/OWL** → **(3) `ArrowIngestor` 等新接入器把额外文件纳入图谱**（`v0.5.1` 新增）→ **(4) 推理引擎计算语义距离并产出候选决策** → **(5) PROV-O 记录 lineage 并由 SHACL 校验通过** → **(6) 写入决策追踪系统等待审计**  资料来源：[CHANGELOG.md:0-0]()。

社区对治理层的两大诉求集中在 **存储后端的可扩展性**：

- Issue #247 询问 **pgVector / Apache AGE** 集成，期望把向量检索与图查询合并到统一平台，减少治理数据的搬运  资料来源：[community_context:0-0]()；
- Issue #240 建议添加 **SQLite + sqlite-vec** 的轻量嵌入方案，方便边缘场景部署  资料来源：[community_context:0-0]()。

这两条诉求都与"治理数据应与决策数据同库同源"的理念一致，目前官方路线图尚未给出 ETA，但治理栈的抽象（PROV-O + 本体 + SHACL）已经为后端切换做好准备  资料来源：[docs/guides/governance.md:0-0]()。

## 小结

决策智能、推理与治理三层在 Semantica 中并非彼此孤立的模块，而是围绕**上下文图谱**彼此补强：决策智能把行为沉淀为节点；推理负责在节点间发现证据；治理用本体、形状与溯源三方约束保障质量与合规。理解这一闭环，是后续扩展自定义接入器、向量后端或合规策略的起点。

---

<a id='page-4'></a>

## 存储后端、集成与部署

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据流水线与知识图谱构建](#page-2), [决策智能、推理与治理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/vector_stores/overview.md](https://github.com/semantica-agi/semantica/blob/main/docs/vector_stores/overview.md)
- [docs/vector_stores/pinecone.md](https://github.com/semantica-agi/semantica/blob/main/docs/vector_stores/pinecone.md)
- [docs/integrations/snowflake.md](https://github.com/semantica-agi/semantica/blob/main/docs/integrations/snowflake.md)
- [docs/ingestion/arrow.md](https://github.com/semantica-agi/semantica/blob/main/docs/ingestion/arrow.md)
- [docs/ingestion/ontology.md](https://github.com/semantica-agi/semantica/blob/main/docs/ingestion/ontology.md)
- [docs/ingestion/parquet.md](https://github.com/semantica-agi/semantica/blob/main/docs/ingestion/parquet.md)
- [docs/guides/mcp-server.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/mcp-server.md)
- [docs/guides/llm-integrations.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/llm-integrations.md)
- [docs/guides/agent-memory.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/agent-memory.md)
- [docs/guides/export.md](https://github.com/semantica-agi/semantica/blob/main/docs/guides/export.md)
- [docs/deployment/overview.md](https://github.com/semantica-agi/semantica/blob/main/docs/deployment/overview.md)
</details>

# 存储后端、集成与部署

## 一、定位与作用

Semantica 是一个面向 AI Agent 的"上下文图谱 + 决策智能"框架，其存储后端、集成层与部署形态构成了框架对外可扩展的三条主干线：

- **存储后端**：负责向量、图谱、关系型数据的持久化与检索；
- **集成层**：覆盖结构化数据源（Snowflake）、列式文件（Parquet、Arrow/Feather）、本体文件（RDF/OWL）以及外部 LLM；
- **部署形态**：通过 MCP（Model Context Protocol）服务器将能力暴露给 Agent，或作为 Python SDK 嵌入业务进程。

社区中关于 **pgVector + Apache AGE**（[#247]）以及 **SQLite + sqlite-vec**（[#240]）的集成请求反映出用户希望 Semantica 在"统一存储 + 轻量边缘"两条路径上持续扩展，这也是本主题未来演进的明确方向。

资料来源：[docs/vector_stores/overview.md:1-15]()

## 二、向量与图存储后端

Semantica 在 v0.2.5 起引入 **Pinecone Vector Store** 原生支持，作为云端托管向量库的代表实现；同时保留了可插拔的 `VectorStore` 接口以便扩展新的后端。

| 后端类型 | 代表实现 | 适用场景 |
| --- | --- | --- |
| 云端托管向量库 | Pinecone | 弹性伸缩、生产级 SLA |
| 本地/嵌入式向量库 | 计划中的 SQLite + sqlite-vec（社区 #240） | 边缘、轻量、嵌入式部署 |
| 关系型 + 向量扩展 | 计划中的 pgVector（社区 #247） | 统一 SQL + 向量检索 |
| 图数据库扩展 | 计划中的 Apache AGE（社区 #247） | 在同一 PostgreSQL 内同时跑关系、向量、图谱 |

向量存储层的关键能力包括相似度检索、混合过滤、与图谱节点的双向回写，以及与 Agent 记忆模块的接口对接 资料来源：[docs/vector_stores/pinecone.md:10-40]()。

## 三、数据集成层

集成层面向"如何把外部数据搬进 Semantica"，按数据形态可划分为四类：

1. **结构化数据库**：v0.2.7 引入 Snowflake 连接器，支持密码、OAuth、密钥对、SSO 多认证方式，并提供表/查询摄入、Schema 自省与 SQL 注入防护 资料来源：[docs/integrations/snowflake.md:5-30]()。
2. **列式文件**：v0.5.0 引入 Parquet 摄取，针对大宽表与高吞吐批处理优化；v0.5.1 新增 Apache Arrow / Feather / IPC 摄取，由 `ArrowIngestor` 通过 PyArrow 实现，支持按列、按批、按行数限制读取，并提供 `ingest_arrow()` 与 `ingest(source_type="arrow")` 统一调度 资料来源：[docs/ingestion/arrow.md:1-35]()、资料来源：[docs/ingestion/parquet.md:1-25]()。
3. **本体文件**：v0.2.4 引入 `OntologyIngestor`，解析 Turtle、RDF/XML、JSON-LD、N3，并暴露 `ingest_ontology()` 与统一 `ingest(source_type="ontology")` 接口，支持目录递归扫描与 `OntologyData` 元数据封装 资料来源：[docs/ingestion/ontology.md:5-28]()。
4. **导出与交换**：提供 Apache Arrow 导出能力，便于在 Python 生态中零拷贝共享 资料来源：[docs/guides/export.md:1-20]()。

## 四、LLM 集成、Agent 记忆与 MCP 部署

框架对 LLM 厂商与自定义模型均保持开放：通过统一的 LLM 抽象层支持托管 API 与 **BYOM（Bring Your Own Model）**，例如自定义 Hugging Face 模型用于 NER/关系抽取，并配套可配置的重试逻辑 资料来源：[docs/guides/llm-integrations.md:1-40]()。

在此基础上，`agent-memory` 模块把上下文图谱转化为 Agent 可读写的长期记忆，支持记忆的写入、检索与生命周期管理 资料来源：[docs/guides/agent-memory.md:1-30]()。

部署层面，Semantica 提供 **MCP Server**，把图谱查询、向量检索、距离计算等能力以标准化协议暴露给任意兼容 MCP 的客户端（如 Claude Desktop、其他 Agent 框架），从而把"上下文图谱即服务"嵌入到更广义的 Agent 工具链中 资料来源：[docs/guides/mcp-server.md:1-45]()。

```mermaid
flowchart LR
  A[数据源<br/>Snowflake / Parquet / Arrow / Ontology] --> B[集成层<br/>ingest_*]
  B --> C[向量存储<br/>Pinecone 等]
  B --> D[图存储 / 上下文图谱]
  D --> E[Agent 记忆]
  C --> E
  E --> F[MCP Server / Python SDK]
  F --> G[外部 Agent]
```

## 五、选型与演进建议

- **生产云端**：选 Pinecone + Snowflake + MCP Server，关注 pgVector/Apache AGE 进展以降低成本 资料来源：[docs/deployment/overview.md:1-30]()。
- **边缘/嵌入式**：跟踪 SQLite + sqlite-vec（#240），结合 Arrow 本地摄入构建离线流水线。
- **知识密集场景**：组合 Ontology 摄取与语义抽取，让本体约束直接进入图谱与检索路径。
- **自定义模型**：优先使用 BYOM 接入 Hugging Face 模型，并启用可配置的重试以保证抽取稳定性。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：semantica-agi/semantica

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：[FEATURE] Evaluation Framework for Semantica。

## 1. 配置坑 · 来源证据：[FEATURE] Evaluation Framework for Semantica

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[FEATURE] Evaluation Framework for Semantica
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/semantica-agi/semantica/issues/228 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/semantica-agi/semantica | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/semantica-agi/semantica | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/semantica-agi/semantica | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/semantica-agi/semantica | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/semantica-agi/semantica | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/semantica-agi/semantica | release_recency=unknown

<!-- canonical_name: semantica-agi/semantica; human_manual_source: deepwiki_human_wiki -->