1概览
本 notebook 将带你从一份简单文档开始，创建你的第一个知识图谱。你将学习从摄取文件到可视化最终知识图谱的完整端到端工作流。
[!TIP] 如果你是 Semantica 的新手，这是最理想的起点。无需任何知识图谱的先验知识！
🎯 学习目标
- 理解工作流：学习
File → Parse → Extract → Graph流水线 - 摄取数据：使用
FileIngestor加载文档 - 解析内容：使用
DocumentParser提取文本 - 抽取知识：使用
NERExtractor识别实体 - 构建图谱：使用
GraphBuilder构建图谱 - 可视化：使用
KGVisualizer让你的图谱生动呈现
2安装
从 PyPI 安装 Semantica：
pip install semantica
# 或安装所有可选依赖：
pip install semantica[all]
3🔄 简单端到端工作流
完整工作流包含四个主要步骤：
- 📥 摄取 - 从文件或其他来源加载数据
- 📄 解析 - 从文档中提取并结构化内容
- ⛏️ 抽取 - 识别实体和关系
- 🕸️ 构建图谱 - 构建知识图谱
每个步骤都在下面的代码单元中演示。
[!TIP] 替代方案：使用 Semantica 框架
若想采用更简单、更高层的方式，你可以使用
Semantica框架类，它会编排所有这些步骤：```python
使用 Semantica 框架类编排完整流水线
from semantica.core import Semantica
初始化框架
framework = Semantica() framework.initialize()
构建知识库：摄取文档并生成嵌入与图谱
result = framework.build_knowledge_base( sources=["sample_document.txt"], embeddings=True, graph=True )
关闭框架，释放资源
framework.shutdown() ```
本 notebook 展示的是用于学习的分步方式。更多细节请参阅 Core Module Usage Guide。
4📂 步骤 1：摄取文件
在这一步，我们将使用 FileIngestor 加载一份文档。该摄取器支持多种文件格式，包括 PDF、DOCX、TXT 等。
# 安装 Semantica
!pip install semantica
from semantica.ingest import FileIngestor
from pathlib import Path
# 初始化摄取器
ingestor = FileIngestor()
# 创建一份示例文档用于演示
sample_text = """
Apple Inc. is a technology company founded by Steve Jobs, Steve Wozniak, and Ronald Wayne in 1976.
The company is headquartered in Cupertino, California.
Tim Cook is the current CEO of Apple Inc.
Apple designs and manufactures consumer electronics, software, and online services.
"""
sample_file = Path("sample_document.txt")
sample_file.write_text(sample_text)
print(f"File: {sample_file}")
print(f"Content length: {len(sample_text)} characters")
# 摄取文件
file_object = ingestor.ingest_file(sample_file, read_content=True)
print(f" File name: {file_object.name}")
print(f" File type: {file_object.file_type}")
print(f" Content available: {file_object.content is not None}")
5📄 步骤 2：解析文档
摄取文件后，我们需要解析它以提取文本内容。DocumentParser 处理各种文件格式并提取结构化内容。
from semantica.parse import DocumentParser
parser = DocumentParser()
# 解析文档以提取文本
parsed_document = parser.parse_document(str(sample_file))
parsed_content = parsed_document.get("content", "")
print(f" Parsed content length: {len(parsed_content) if parsed_content else 0} characters")
print(f" Preview: {parsed_content[:200] if parsed_content else 'N/A'}...")
6⛏️ 步骤 3：抽取实体
现在我们将使用命名实体识别（NER）从解析后的文本中抽取实体。它会识别文本中的人物、组织、地点、日期和其他实体。
[!NOTE] 在真实场景中，你会使用带有 LLM 或模型后端的
NERExtractor。这里我们为演示目的模拟其输出。
from semantica.semantic_extract import NamedEntityRecognizer, NERExtractor
ner = NamedEntityRecognizer()
extractor = NERExtractor()
print(f"\nText: {parsed_content[:100]}...")
# 模拟的抽取结果
expected_entities = [
{"text": "Apple Inc.", "type": "Organization", "start": 0, "end": 10},
{"text": "Steve Jobs", "type": "Person", "start": 50, "end": 60},
{"text": "Steve Wozniak", "type": "Person", "start": 62, "end": 75},
{"text": "Ronald Wayne", "type": "Person", "start": 81, "end": 93},
{"text": "1976", "type": "Date", "start": 97, "end": 101},
{"text": "Cupertino, California", "type": "Location", "start": 130, "end": 151},
{"text": "Tim Cook", "type": "Person", "start": 153, "end": 161},
]
for entity in expected_entities:
print(f" - {entity['text']} ({entity['type']})")
7🕸️ 步骤 4：构建知识图谱
利用抽取出的实体和关系，我们将构建一个知识图谱。图谱将实体表示为节点，将关系表示为边。
from semantica.kg import GraphBuilder
import networkx as nx
builder = GraphBuilder()
# 为图谱构建准备数据
entities_data = [
{"id": f"entity_{i}", "name": entity["text"], "type": entity["type"]}
for i, entity in enumerate(expected_entities)
]
relationships_data = [
{"source": "entity_0", "target": "entity_1", "type": "founded_by"},
{"source": "entity_0", "target": "entity_2", "type": "founded_by"},
{"source": "entity_0", "target": "entity_3", "type": "founded_by"},
{"source": "entity_0", "target": "entity_4", "type": "founded_in"},
{"source": "entity_0", "target": "entity_5", "type": "located_in"},
{"source": "entity_6", "target": "entity_0", "type": "ceo_of"},
]
# 使用 NetworkX 构建图谱
kg = nx.DiGraph()
for entity in entities_data:
kg.add_node(entity["id"], name=entity["name"], type=entity["type"])
for rel in relationships_data:
source_name = entities_data[int(rel["source"].split("_")[1])]["name"]
target_name = entities_data[int(rel["target"].split("_")[1])]["name"]
kg.add_edge(rel["source"], rel["target"], type=rel["type"])
print(f" Nodes (entities): {len(kg.nodes)}")
print(f" Edges (relationships): {len(kg.edges)}")
for node_id in kg.nodes():
node_data = kg.nodes[node_id]
print(f" Node: {node_data['name']} ({node_data['type']})")
for source, target, data in kg.edges(data=True):
source_name = kg.nodes[source]['name']
target_name = kg.nodes[target]['name']
print(f" {source_name} --[{data['type']}]--> {target_name}")
8📊 步骤 5：可视化与分析
最后，我们将可视化知识图谱并分析其结构。这有助于你理解数据中的关系和实体。
from semantica.visualization import KGVisualizer
visualizer = KGVisualizer()
print(f" Total entities: {len(kg.nodes)}")
print(f" Total relationships: {len(kg.edges)}")
entity_types = {}
for node_id in kg.nodes():
entity_type = kg.nodes[node_id]['type']
entity_types[entity_type] = entity_types.get(entity_type, 0) + 1
for etype, count in entity_types.items():
print(f" - {etype}: {count}")
rel_types = {}
for _, _, data in kg.edges(data=True):
rel_type = data.get('type', 'unknown')
rel_types[rel_type] = rel_types.get(rel_type, 0) + 1
for rtype, count in rel_types.items():
print(f" - {rtype}: {count}")
# 清理
if sample_file.exists():
sample_file.unlink()