Semantica 详细部署与配置教程

Semantica 是一个图原生基础设施，用于为 AI 系统构建可审计、可解释的“上下文图”（Context Graph）。它适合需要决策溯源、知识图谱和规则推理的高监管行业（如金融、医疗、政府）。

本教程将引导你完成从安装到运行生产级知识图谱流水线的全过程。

一、准备工作

1.1 系统要求

在开始之前，请确保你的环境满足以下要求：

组件 最低要求 推荐配置
Python 3.8 3.11 或更高
操作系统 Windows / Linux / macOS Linux / macOS
内存 (RAM) 4 GB 16 GB 或更高
存储空间 2 GB 20 GB 或更高 (用于模型和知识图谱数据)
GPU (可选) 无 支持 CUDA 的 GPU 可加速嵌入和模型推理

1.2 Python 环境（推荐）

强烈建议使用虚拟环境来隔离 Python 依赖。

使用 venv：

1
2
3
python -m venv semantica-env
source semantica-env/bin/activate  # Linux/macOS
# .\semantica-env\Scripts\activate   # Windows

使用 conda：

1
2
conda create -n semantica python=3.11
conda activate semantica

二、安装 Semantica

2.1 基础安装

使用 pip 从 PyPI 安装核心库：

1
pip install semantica

2.2 安装所有可选依赖（推荐）

[all] 标签会安装所有用于提取、可视化和图存储的依赖，适合快速体验完整功能：

1
pip install semantica[all]

Windows 用户注意：如果在 v0.5.0 之前的版本安装 [all] 失败，请升级到最新版本（pip install --upgrade semantica），或在 v0.5.0+ 版本中此问题已修复。

2.3 按需安装（生产环境推荐）

为保持环境精简，可以根据实际需求只安装特定组件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 仅核心
pip install semantica

# 可视化
pip install "semantica[viz]"

# 使用特定 LLM 提供者
pip install "semantica[llm-openai]"   # OpenAI
pip install "semantica[llm-anthropic]" # Anthropic Claude
pip install "semantica[llm-ollama]"   # 本地 Ollama

# GPU 加速 (包含 CUDA 版 PyTorch 和 FAISS)
pip install "semantica[gpu]"

# 连接特定图数据库
pip install "semantica[graph-neo4j]"   # Neo4j
pip install "semantica[graph-falkordb]" # FalkorDB
pip install "semantica[graph-apache-age]" # Apache AGE

# 连接特定向量数据库
pip install "semantica[vectorstore-qdrant]"   # Qdrant
pip install "semantica[vectorstore-pinecone]" # Pinecone

# 集成 Agent 框架
pip install "semantica[agno]"     # Agno
pip install "semantica[crewai]"   # CrewAI
pip install "semantica[langchain]" # LangChain

# 启动知识图谱探索器（交互式 Web 界面）
pip install "semantica[explorer]"

2.4 验证安装

运行以下命令检查是否成功安装：

1
2
python -c "import semantica; print(semantica.__version__)"
# 应输出版本号，例如 0.6.7

三、快速开始：构建第一个知识图谱

以下是一个端到端的示例，演示如何从文档构建知识图谱并执行查询。

3.1 创建 Python 脚本

创建一个名为 build_kg.py 的文件，并写入以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
from semantica.ingest import FileIngestor
from semantica.parse import DocumentParser
from semantica.semantic_extract import NERExtractor, RelationExtractor
from semantica.kg import GraphBuilder

# 1. 加载数据
print("1. 加载文档...")
ingestor = FileIngestor()
sources = ingestor.ingest("./data/")  # 请将 ./data/ 替换为你的文档目录

# 2. 解析文档（启用 OCR 处理扫描件）
print("2. 解析文档...")
parser = DocumentParser(ocr=True)     # 可选，使用 Tesseract OCR 处理图片 PDF
parsed_docs = [parser.parse(src) for src in sources]

# 将解析后的文本合并为一个字符串
full_text = " ".join([doc.text for doc in parsed_docs])

# 3. 提取实体和关系
# 方案 A: 基于规则的模式提取（速度快，无需 API Key）
print("3.1 提取实体和关系（使用模式匹配）...")
ner_extractor = NERExtractor(method="pattern")
entities = ner_extractor.extract(full_text)

rel_extractor = RelationExtractor(method="pattern")
relations = rel_extractor.extract(full_text, entities=entities)

# 方案 B: 使用 LLM 进行高质量提取（需设置 API Key）
# from semantica.llms import OpenAI
# llm = OpenAI(model="gpt-4o")
# ner_extractor = NERExtractor(method="llm", llm_provider=llm)
# rel_extractor = RelationExtractor(method="llm", llm_provider=llm)

# 4. 构建知识图谱
print("4. 构建知识图谱...")
builder = GraphBuilder(merge_entities=True)  # 自动合并重复实体
graph = builder.build(entities=entities, relationships=relations)

print(f"知识图谱构建完成：{len(graph.nodes)} 个节点，{len(graph.edges)} 条关系")

3.2 运行脚本

1
python build_kg.py

四、高级功能与配置

4.1 记录 AI 决策并生成审计轨迹

Semantica 的核心能力之一是将 Agent 的决策记录为图谱中的一等公民，支持完整的因果链追溯。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
from semantica.context import ContextGraph
from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

# 初始化
graph = ContextGraph(advanced_analytics=True)
prov = ProvenanceManager(storage_path="./audit.db")

# 记录决策链
decision_1 = graph.record_decision(
    category="贷款审批",
    scenario="申请人年收入 8.5万，负债率 31%，3年工作经验",
    reasoning="收入符合标准，就业稳定，无不良信用记录",
    outcome="批准",
    confidence=0.94,
)

decision_2 = graph.record_decision(
    category="利率设定",
    scenario="为已批准贷款 A-7291 设定利率",
    outcome="利率设定为 8.9%",
    reasoning="基准利率 + 2.4%，基于风险等级 B2",
    confidence=0.99,
)

# 建立因果关联
graph.add_causal_relationship(decision_1, decision_2, relationship_type="CAUSED")

# 追溯决策链
chain = graph.trace_decision_chain(decision_2)
print(f"决策链: {chain}")

# 导出为 W3C PROV-O 格式的审计报告（合规提交用）
kg_data = graph.to_kg_dict()
RDFExporter().export(kg_data, "audit_trail.ttl", format="turtle")
print("审计轨迹已导出至 audit_trail.ttl")

4.2 配置 LLM 和 Embedding

Semantica 支持通过环境变量配置各种 LLM 和 Embedding 服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 基础 LLM 配置
export OPENAI_API_KEY="sk-xxx"          # 设置 OpenAI API Key
export GROQ_API_KEY="gsk_xxx"           # 设置 Groq API Key
export ANTHROPIC_API_KEY="sk-ant-xxx"   # 设置 Anthropic API Key
export SEMANTICA_EMBEDDING_PROVIDER="openai"  # 设置 Embedding Provider

# 使用本地 Ollama
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_MODEL="llama3.2"

# 配置日志级别
export SEMANTICA_LOG_LEVEL="DEBUG"      # DEBUG, INFO, WARNING, ERROR
export SEMANTICA_LOG_FORMAT="json"      # text 或 json

4.3 使用持久化图数据库（生产环境）

对于生产环境，建议使用持久化图数据库（如 FalkorDB、Neo4j）替代默认的内存型 NetworkX。

安装 FalkorDB 并启动（使用 Docker）：

1
docker run -d --name falkordb -p 6379:6379 falkordb/falkordb:latest

配置 Semantica 使用 FalkorDB：

1
2
3
4
5
6
7
8
9
from semantica.graph_store import FalkorDBStore
from semantica.kg import GraphBuilder

# 连接到 FalkorDB
store = FalkorDBStore(host="localhost", port=6379)

# 使用持久化存储构建图谱
builder = GraphBuilder(merge_entities=True, graph_store=store)
graph = builder.build(entities=entities, relationships=relations)

4.4 使用 pgvector 向量存储

如果需要语义搜索，可以配置 pgvector。

启动 pgvector（Docker）：

1
2
3
4
5
docker run -d \
    --name pgvector \
    -e POSTGRES_PASSWORD=postgres \
    -p 5432:5432 \
    ankane/pgvector:latest

安装依赖：

1
pip install "semantica[vectorstore-pgvector]"

使用 pgvector：

1
2
3
4
5
6
from semantica.vector_store import PgVectorStore

store = PgVectorStore(
    connection_string="postgresql://postgres:postgres@localhost:5432/semantica",
    dimension=1536  # 匹配你的 Embedding 模型维度
)

4.5 启动知识图谱探索器（Explorer）

Semantica 提供了一个基于浏览器的交互式图形工作台，用于可视化、探索和编辑知识图谱。

1
2
3
4
5
6
7
8
# 安装 Explorer
pip install "semantica[explorer]"

# 启动 Explorer（假设已有知识图谱数据）
semantica-explorer --graph my_graph.json

# 或启动完整的开发服务器（需从源码目录运行）
# 访问 http://127.0.0.1:8000

五、使用 Docker Compose 部署（生产推荐）

官方提供了 docker-compose.yml 用于快速部署包含 Explorer 和 FalkorDB 的完整堆栈。

5.1 克隆仓库

1
2
git clone https://github.com/semantica-agi/semantica.git
cd semantica

5.2 启动服务

1
docker-compose up -d

这将启动两个服务：

  • semantica-knowledge-explorer: Web 界面，监听端口 8000。
  • falkordb: 图数据库，监听端口 6379。

5.3 验证

访问 http://localhost:8000 查看知识图谱探索器。

六、故障排查

常见问题 解决方案
ModuleNotFoundError 确认已激活正确的虚拟环境，运行 `pip list
安装依赖错误 升级 pip：pip install --upgrade pip build wheel。若仍失败，先安装核心 pip install semantica 再逐个添加可选依赖。
Windows 安装失败 确认 Semantica 版本 ≥ 0.5.0。若遇到 PyTorch DLL 错误，需安装 Microsoft Visual C++ Redistributable。
内存不足 (OOM) 切换到持久化图数据库（如 FalkorDB），并使用 pipeline 模块的批处理功能处理数据。
LLM 提取无结果 确认已设置正确的 API Key（如 OPENAI_API_KEY）。对于自定义网关，可能需要配置 OPENAI_BASE_URL。

七、总结

你已成功部署 Semantica 并完成了以下核心任务：

  1. 安装：通过 pip 安装了 Semantica 核心及可选组件。
  2. 构建：从文档创建了包含实体和关系的知识图谱。
  3. 审计：记录了 AI 决策并生成了符合 W3C PROV-O 标准的审计轨迹。
  4. 配置：为生产环境配置了持久化图数据库和向量存储。
  5. 部署：使用 Docker Compose 启动了完整的服务栈。

接下来，你可以探索官方提供的 Cookbook 中的更多示例，涵盖 GraphRAG、时间图谱、AML 规则引擎等高级用例