高级多格式导出 · Semantica Cookbook

1概览

这个高级 notebook 演示了 Semantica 导出模块的全面导出能力，涵盖所有 8 种导出格式以及报告生成。你将学习如何将同一个知识图谱同时导出为多种格式、使用高级功能，以及利用方法注册表系统。

文档：API 参考

你将学到什么

将知识图谱导出为全部 8 种受支持的格式
直接使用导出器类进行细粒度控制
生成多种格式的专业报告
使用 RDF 序列化、验证和命名空间管理
注册并使用自定义导出方法
以编程方式配置导出设置
为向量存储导出向量和嵌入
使用 LPG 格式导出到图数据库

涵盖的导出格式

JSON/JSON-LD - 标准 JSON 和 JSON-LD 格式
RDF - Turtle、RDF/XML、JSON-LD、N-Triples、N3
CSV - 用于实体和关系的表格格式
图格式 - 用于可视化工具的 GraphML、GEXF、DOT
OWL - 用于本体的 OWL/XML 和 Turtle
向量 - 用于向量存储的 JSON、NumPy、Binary、FAISS
LPG - 用于图数据库的 Cypher 和 LPG
YAML - 语义网络和模式 YAML
报告 - HTML、Markdown、JSON、Text 报告

2安装

从 PyPI 安装 Semantica：

pip install semantica
# 或安装所有可选依赖：
pip install semantica[all]

# 安装 Semantica
!pip install semantica

# 导入用于构建知识图谱的核心模块
from semantica.kg import GraphBuilder
from semantica.embeddings import EmbeddingGenerator
from semantica.ontology import OntologyGenerator
import os

# 创建导出目录
os.makedirs("exports", exist_ok=True)

3步骤 1：创建示例知识图谱和数据

创建一个包含实体、关系、嵌入和本体的示例知识图谱，用于全面的导出演示。

# 步骤 1：创建示例知识图谱、嵌入与本体
builder = GraphBuilder()

# 定义示例实体
entities = [
    {"id": "e1", "type": "Person", "name": "Alice", "properties": {"age": 30}},
    {"id": "e2", "type": "Person", "name": "Bob", "properties": {"age": 35}},
    {"id": "e3", "type": "Organization", "name": "Tech Corp", "properties": {"founded": 2010}},
]

# 定义实体间的关系
relationships = [
    {"source": "e1", "target": "e2", "type": "knows"},
    {"source": "e1", "target": "e3", "type": "works_for"},
]

# 构建知识图谱
knowledge_graph = builder.build(entities + relationships)

# 为实体名称生成向量嵌入
embedding_generator = EmbeddingGenerator()
texts = [e["name"] for e in entities]
embeddings = embedding_generator.generate_embeddings(texts, data_type="text")

# 从知识图谱生成本体
ontology_generator = OntologyGenerator()
ontology = ontology_generator.generate_from_graph(knowledge_graph)

4步骤 2：导出为 JSON

使用类和便捷函数两种方式将知识图谱导出为 JSON 格式。

JSONExporter 功能： - 标准 JSON 序列化 - 支持带 @context 的 JSON-LD 格式 - 可配置的缩进 - 元数据和溯源追踪

from semantica.export import JSONExporter

# 使用自定义设置创建 JSON 导出器
json_exporter = JSONExporter(indent=2, include_metadata=True)

# 导出为 JSON 格式
json_exporter.export_knowledge_graph(knowledge_graph, "exports/output.json")

# 导出为 JSON-LD 格式
json_exporter.export_knowledge_graph(knowledge_graph, "exports/output.jsonld", format="json-ld")

5步骤 3：导出为 RDF

将知识图谱导出为多种 RDF 格式（Turtle、RDF/XML、JSON-LD、N-Triples）。

RDFExporter 功能： - 支持多种 RDF 格式（Turtle、RDF/XML、JSON-LD、N-Triples、N3） - 命名空间管理 - RDF 验证 - 格式转换能力

from semantica.export import RDFExporter, RDFSerializer, RDFValidator

# 创建 RDF 导出器
rdf_exporter = RDFExporter()

# 导出为 Turtle 格式（人类可读）
rdf_exporter.export_knowledge_graph(knowledge_graph, "exports/output.ttl", format="turtle")

# 导出为 RDF/XML 格式
rdf_exporter.export_knowledge_graph(knowledge_graph, "exports/output.rdf", format="rdfxml")

# 导出为 JSON-LD 格式
rdf_exporter.export_knowledge_graph(knowledge_graph, "exports/output.jsonld", format="jsonld")

# 导出为 N-Triples 格式
rdf_exporter.export_knowledge_graph(knowledge_graph, "exports/output.nt", format="ntriples")

# 使用 RDFSerializer 进行格式转换
serializer = RDFSerializer()
rdf_data = serializer.convert_kg_to_rdf(knowledge_graph)
turtle_string = serializer.serialize_to_turtle(rdf_data)

# 使用 RDFValidator 进行验证
validator = RDFValidator()
validation_result = validator.validate_rdf_syntax(turtle_string, format="turtle")
print(f"RDF validation: {validation_result.get('is_valid', False)}")

6步骤 4：导出为 CSV

将知识图谱导出为 CSV 格式以进行表格分析。

CSVExporter 功能： - 实体和关系使用单独的文件 - 可配置的分隔符（逗号、制表符、分号） - 自动生成表头 - 元数据序列化

from semantica.export import CSVExporter

# 使用自定义分隔符创建 CSV 导出器
csv_exporter = CSVExporter(delimiter=",")

# 导出完整知识图谱
csv_exporter.export_knowledge_graph(knowledge_graph, "exports/output")

# 单独导出实体
entities = knowledge_graph.get("entities", [])
csv_exporter.export_entities(entities, "exports/entities.csv")

# 单独导出关系
relationships = knowledge_graph.get("relationships", [])
csv_exporter.export_relationships(relationships, "exports/relationships.csv")

7步骤 5：导出为图格式（GraphML、GEXF、DOT）

将知识图谱导出为图格式以供可视化工具使用。

GraphExporter 功能： - GraphML 格式（Cytoscape、yEd） - GEXF 格式（Gephi） - DOT 格式（Graphviz） - 节点和边属性映射

from semantica.export import GraphExporter

# 创建图导出器
graph_exporter = GraphExporter()

# 导出为 GraphML 格式（用于 Cytoscape、yEd）
graph_exporter.export_knowledge_graph(knowledge_graph, "exports/output.graphml", format="graphml")

# 导出为 GEXF 格式（用于 Gephi）
graph_exporter.export_knowledge_graph(knowledge_graph, "exports/output.gexf", format="gexf")

# 导出为 DOT 格式（用于 Graphviz）
graph_exporter.export_knowledge_graph(knowledge_graph, "exports/output.dot", format="dot")

8步骤 6：导出为 OWL

将本体导出为 OWL 格式。注意： OWLExporter 期望的是本体结构，而不是知识图谱。

OWLExporter 功能： - OWL/XML 格式 - Turtle 格式的 OWL - 类层级导出 - 属性定义导出

from semantica.export import OWLExporter

# 使用自定义 URI 和版本创建 OWL 导出器
owl_exporter = OWLExporter(ontology_uri="https://example.org/ontology/", version="1.0")

# 将完整本体导出为 OWL/XML
owl_exporter.export(ontology, "exports/output.owl", format="owl-xml")

# 导出为 Turtle 格式的 OWL
owl_exporter.export(ontology, "exports/output_owl.ttl", format="turtle")

# 仅导出类
classes = ontology.get("classes", [])
owl_exporter.export_classes(classes, "exports/classes.owl")

# 仅导出属性
properties = ontology.get("object_properties", [])
owl_exporter.export_properties(properties, "exports/properties.owl", property_type="object")

9步骤 7：导出为向量格式

将向量嵌入导出为各种格式以供向量存储使用。

VectorExporter 功能： - JSON 格式 - NumPy 格式 - Binary 格式 - FAISS 格式 - 向量存储集成（Weaviate、Qdrant）

from semantica.export import VectorExporter

# 创建向量导出器
vector_exporter = VectorExporter()

# 导出为 JSON 格式
vector_exporter.export(embeddings, "exports/output_vectors.json", format="json")

# 导出为 NumPy 格式
vector_exporter.export(embeddings, "exports/output_vectors.npy", format="numpy")

# 导出为 Binary 格式
vector_exporter.export(embeddings, "exports/output_vectors.bin", format="binary")

# 导出为 FAISS 格式
vector_exporter.export(embeddings, "exports/output_vectors.faiss", format="faiss")

10步骤 8：导出为 LPG（带标签的属性图）

将知识图谱导出为 LPG 格式，用于 Neo4j 和 Memgraph 等图数据库。

LPGExporter 功能： - Cypher 查询格式 - 带标签的属性图格式 - 批量节点/关系导出 - 索引生成

from semantica.export import LPGExporter

# 创建 LPG 导出器
lpg_exporter = LPGExporter()

# 导出为 Cypher 格式（用于 Neo4j、Memgraph）
lpg_exporter.export_knowledge_graph(knowledge_graph, "exports/output.cypher", format="cypher")

# 导出为 LPG 格式
lpg_exporter.export_knowledge_graph(knowledge_graph, "exports/output.lpg", format="lpg")

11步骤 9：导出为 YAML

将语义网络和模式导出为 YAML 格式。

YAML 导出器功能： - 语义网络 YAML 导出 - 模式 YAML 导出 - 人类可读格式

from semantica.export import SemanticNetworkYAMLExporter, YAMLSchemaExporter

# 使用 SemanticNetworkYAMLExporter 处理知识图谱
yaml_exporter = SemanticNetworkYAMLExporter()
yaml_exporter.export(knowledge_graph, "exports/output_network.yaml")

# 使用 YAMLSchemaExporter 处理本体模式
schema_exporter = YAMLSchemaExporter()
yaml_content = schema_exporter.export_ontology_schema(ontology)
with open("exports/output_schema.yaml", "w") as f:
    f.write(yaml_content)

12步骤 10：生成报告

使用 ReportGenerator 生成多种格式的专业报告。

ReportGenerator 功能： - 带样式的 HTML 报告 - Markdown 报告 - JSON 报告 - 纯文本报告 - 质量指标聚合

from semantica.export import ReportGenerator

# 准备报告数据
report_data = {
    "title": "Knowledge Graph Export Report",
    "summary": "Comprehensive export of knowledge graph to multiple formats",
    "knowledge_graph": {
        "entities": len(knowledge_graph.get("entities", [])),
        "relationships": len(knowledge_graph.get("relationships", []))
    },
    "formats_exported": ["JSON", "RDF", "CSV", "GraphML", "GEXF", "OWL", "Vector", "LPG", "YAML"],
    "export_timestamp": "2024-01-01T00:00:00Z"
}

# 创建报告生成器
report_generator = ReportGenerator()

# 生成 HTML 报告
report_generator.generate_report(report_data, "exports/report.html", format="html")

# 生成 Markdown 报告
report_generator.generate_report(report_data, "https://github.com/semantica-agi/semantica", format="markdown")

# 生成 JSON 报告
report_generator.generate_report(report_data, "exports/report.json", format="json")

# 生成 Text 报告
report_generator.generate_report(report_data, "exports/report.txt", format="text")

13步骤 11：方法注册表与自定义方法

使用 MethodRegistry 系统注册并使用自定义导出方法。

MethodRegistry 功能： - 注册自定义导出方法 - 列出可用方法 - 按名称获取方法 - 注销方法

from semantica.export import MethodRegistry, method_registry, JSONExporter

# 定义一个自定义导出方法
def custom_json_export(data, file_path, **kwargs):
    """Custom JSON export with additional formatting."""
    import json
    with open(file_path, 'w') as f:
        json.dump(data, f, indent=4, sort_keys=True)
    print(f"Custom export completed: {file_path}")

# 注册自定义方法
MethodRegistry.register("json", "custom_formatted", custom_json_export)

# 列出所有可用方法
all_methods = method_registry.list_all()
print("Available methods:", all_methods)

# 列出特定任务的方法
json_methods = method_registry.list_all("json")
print("JSON methods:", json_methods)

# 使用 JSONExporter 使用已注册的方法
json_exporter = JSONExporter()
# 自定义方法可以通过注册表系统使用
custom_method = method_registry.get("json", "custom_formatted")
if custom_method:
    custom_method(knowledge_graph, "exports/custom_output.json")

14步骤 12：配置管理

使用 ExportConfig 配置导出设置。

ExportConfig 功能： - 环境变量支持 - 配置文件支持 - 编程式配置 - 方法特定配置

from semantica.export import ExportConfig, export_config, JSONExporter

# 获取当前配置
config = export_config.get("default")
print("Default config:", config)

# 以编程方式设置配置
export_config.set("json", {"indent": 4, "include_metadata": True})
export_config.set("rdf", {"format": "turtle", "base_uri": "https://example.org/"})

# 获取方法特定配置
json_config = export_config.get_method_config("json")
print("JSON config:", json_config)

# 设置方法特定配置
export_config.set_method_config("csv", {"delimiter": "\t"})

# 使用已配置的设置
json_exporter = JSONExporter(**export_config.get_method_config("json"))
json_exporter.export_knowledge_graph(knowledge_graph, "exports/output_configured.json")

15步骤 13：验证所有导出

验证所有导出的文件是否已成功创建。

# 列出所有导出的文件
export_files = [
    "exports/output.json",
    "exports/output.jsonld",
    "exports/output.ttl",
    "exports/output.rdf",
    "exports/output.nt",
    "exports/output.csv",
    "exports/entities.csv",
    "exports/relationships.csv",
    "exports/output.graphml",
    "exports/output.gexf",
    "exports/output.dot",
    "exports/output.owl",
    "exports/output_owl.ttl",
    "exports/output_vectors.json",
    "exports/output_vectors.npy",
    "exports/output.cypher",
    "exports/output_network.yaml",
    "exports/output_schema.yaml",
    "exports/report.html",
    "https://github.com/semantica-agi/semantica",
    "exports/report.json",
    "exports/report.txt"
]

print("📊 Export Summary:")
print("=" * 60)
for file in export_files:
    if os.path.exists(file):
        size = os.path.getsize(file)
        print(f"✅ {file:50} ({size:>10,} bytes)")
    else:
        print(f"❌ {file:50} (not found)")

print("=" * 60)
print(f"Total files checked: {len(export_files)}")
print(f"Files created: {sum(1 for f in export_files if os.path.exists(f))}")