项目定位与核心能力

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(source_type=...) 调度接口实现松耦合协作，开发者可在不修改上层调用的前提下替换具体后端实现 资料来源：docs/index.md:1-50。

数据流与工作流

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 与后端适配器即可接入整体数据流。

流水线总体架构

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

数据接入（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。

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 框架的中枢：从多源接入到图谱分析，模块职责清晰，版本演进方向明确，并提供可观测、可扩展的入口点供业务方按需取舍。

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。

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

推理模块建立在 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。

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

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

一、定位与作用

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 接口以便扩展新的后端。

向量存储层的关键项目括相似度检索、混合过滤、与图谱节点的双向回写，以及与 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。

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 模型，并启用可配置的重试以保证抽取稳定性。

Pitfall Log / 踩坑日志

项目：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