
把文档变成可查询的知识图谱Semantica 完整实践指南【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica如果你手上有一批非结构化文档报告、邮件、网页文本想要让 LLM 应用或 Agent 基于实体-关系结构来回答问题并且每条结论都能追溯到来源——Semantica 就是干这件事的 Python 框架。它把文本解析、实体关系抽取、建图、持久化、时序查询、决策记忆串成一条流水线核心能力是构建带溯源的知识图谱并让 Agent 有据可依。有 Python 基础、正在给 RAG 或 Agent 项目找图原生的上下文层的开发者最该读这篇。环境准备三步装好零 Key 先跑通Semantica 当前版本 0.8.0要求 Python 3.11–3.133.10 已停止支持装到 3.10 会解析到旧的 0.7.x。安装基础包即可运行本文全部示例不需要任何 LLM API Key 和模型下载pip install semantica python -c import semantica; print(semantica.__version__)可视化是可选能力用到时再补装pip install semantica[viz] # 补上 Plotly、pyvis 等画图依赖第一次跑通一句话文本立刻看到实体和边先用一行文本验证整条抽取链路这是全文所有代码的最小原型。不下载模型、不配 Key 的关键是methodpattern它走内置正则规则而不是默认的mlspaCy需装en_core_web_sm模型。from semantica.semantic_extract import NERExtractor, RelationExtractor text Apple Inc. was founded by Steve Jobs, Steve Wozniak, and \ Ronald Wayne in 1976 in Cupertino, California. entities NERExtractor(methodpattern).extract(text) rels RelationExtractor(methodpattern).extract(text, entitiesentities) for e in entities: print(e.text, e.label, e.confidence) for r in rels: print(r.subject.text, -, r.predicate, -, r.object.text)运行后你会看到类似这样的真实输出Apple Inc. ORG 0.9 Steve Jobs PERSON 0.9 ... Apple Inc. - founded_by - Steve Jobs Apple Inc. - founded_by - Steve Wozniak三个值得记住的点Entity是 dataclass字段固定为text/label/start_char/end_char/confidence/metadataconfidence可能为None表示后端不给分不是没把握。RelationExtractor.extract的entities参数是必须传的——模板只对已识别实体做匹配不会自己再跑一遍 NER。RelationExtractor默认方法就是pattern内置founded_by、works_for、born_in等句式模板见 relation_extractor.py还支持cooccurrence同现窗口、dependency依赖句法需 spaCy、llm传provider走 LLM三种方法。精度不够时把method从pattern换成llm并传provider两种方法返回的是同一种Relation结构可以直接替换。核心工作流一份文档如何变成图上的有向边把上面的演示换成真实文件链路是读文件 → 解析出纯文本 → 抽实体和关系 → 构建成图 dict。四个环节各只有一个入口函数下面按数据流动的顺序走一遍。读文件。这一环节解决目录里几十上百个文件我要拿到一个统一句柄列表的问题。ingest()是统一入口传文件路径走单文件逻辑传目录路径走目录逻辑默认递归。from semantica.ingest import FileIngestor sources FileIngestor().ingest(data/reports/) # 文件或目录均可 print(len(sources), files) # 每项是 FileObject取路径sources[0].path解析。拿到路径后交给DocumentParser它按扩展名自动路由到对应的解析器txt、md、html、csv、docx 等返回值恒含full_text和metadata两个键——后面的代码只需要关心前者from semantica.parse import DocumentParser parser DocumentParser() text parser.parse(sources[0].path)[full_text]抽取。用上一节的NERExtractorRelationExtractor把text换成刚解析出来的内容即可。两个方法参数不变。建图。抽取产出的实体和关系列表直接打包成 dict 交给GraphBuilderfrom semantica.kg import GraphBuilder ents NERExtractor(methodpattern).extract(text) rels RelationExtractor(methodpattern).extract(text, entitiesents) graph GraphBuilder().build({entities: ents, relationships: rels}) print(graph[metadata][num_entities]) # 实体数build()返回的 dict 含entities、relationships、metadata三个键是整个项目的通用图结构——后面可视化、导出、落库全部吃这个 dict不需要任何格式转换。这一步没有开任何归并开关同一实体的不同写法会各占一个节点这是刻意的默认行为最保守归并策略放到下一节按数据规模再开。从能跑到能用批量文档与重复实体归并文档量上来后真正的问题不再是能不能建图而是三份报告里 Apple、Apple Inc.、AAPL 到底是不是同一家公司不处理的话每个变体各成一个节点这家公司有几条边这类查询必然失真。把上一节的循环扩到整个目录并在GraphBuilder上打开归并sources FileIngestor().ingest(data/reports/) ents, rels [], [] for src in sources: text parser.parse(src.path)[full_text] e ner.extract(text) # 上节构造过的 NERExtractor ents.extend(e) rels.extend(rel.extract(text, entitiese)) graph GraphBuilder( merge_entitiesTrue, # 关键开关默认是 False entity_resolution_strategyfuzzy, # 默认 fuzzy想更保守改 exact resolve_conflictsTrue, # 默认 True检测抽取结果冲突 ).build({entities: ents, relationships: rels})关键在merge_entities它默认False不显式传True构建期根本不会实例化EntityResolver见 graph_builder.py。打开后默认的fuzzy策略会把 Apple / Apple Inc. 归并成同一节点entity_resolution_strategy改成exact则只做完全匹配宁可漏并也不错并适合实体名高度规范的语料实现见 entity_resolver.py。另一个规模取舍是内存ingest()会把目录里所有文件内容读进FileObject列表大目录建议改用scan_directory()它只返回path/name/size/extension/modified五字段的元信息 dict逐文档处理时再解析for info in FileIngestor().scan_directory(data/reports/, recursiveTrue): if info[extension] in (md, txt): # 顺带过滤无关扩展名 text parser.parse(info[path])[full_text] ents.extend(ner.extract(text))scan_directory的recursive默认True还支持extensions、min_size、pattern等过滤参数等于把文件筛选前移到了读文件之前。输出与集成看图、导出 RDF、落图数据库图建好之后常见的三个去向肉眼检查、交换格式、持久化。可视化。检查图的质量最直接的方式是画出来from semantica.visualization import KGVisualizer KGVisualizer().visualize_network( graph, outputhtml, file_pathgraph.html, node_color_bytype )output可选interactive/html/png/svgnode_color_bytype是默认值让不同实体类型着不同色一眼能看出哪类节点连边最密。底层是 Plotly基础包不带画图依赖报缺包时补pip install semantica[viz]。项目还自带一个 Web 版 Knowledge Explorer交互式浏览整张图谱setup 见 explorer-setup.md导出。同一张图 dict 交给不同导出器即可格式按需选择from semantica.export import RDFExporter, ParquetExporter rdf RDFExporter() rdf.export(graph, file_pathgraph.ttl, formatturtle) # 对接 RDF 生态 rdf.export(graph, file_pathgraph.jsonld, formatjsonld) # 换 JSON-LD ParquetExporter().export(graph, file_pathoutput/graph) # 喂 Spark两个参数行为值得注意RDFExporter的format只接受turtle/rdfxml/jsonld/ntriples/n3五种序列化格式传别的直接报错ParquetExporter遇到 dict 输入会按 key 拆成多个文件graph_entities.parquet、graph_relationships.parquetfile_path是基础路径而不是单文件。CSV、JSON、YAML、OWL、Arrow 等其余导出器都在 semantica/export/ 下接口形态一致。持久化。前面所有示例的图只活在进程内存里进程退出即丢。要落库把存储后端实例传给GraphBuilder构建期边建边写而不是建完再整体搬from semantica.graph_store import GraphStore store GraphStore( backendneo4j, # 目前支持 neo4j / falkordb uribolt://localhost:7687, userneo4j, passwordpassword, ) graph GraphBuilder(merge_entitiesTrue, graph_storestore).build(payload)GraphStore其余配置通过 kwargs 透传给具体后端不传backend时默认走配置里的neo4j。后端选型对比见 storage-backends.md。进阶时序查询与 Agent 决策记忆时序知识图谱。当关系本身带有效期——比如某人 2018 年起任 CEO、2022 年卸任——你需要能问某个时间点这条边还成立吗。做法是建图时给边加valid_from/valid_until查询时用TemporalGraphQueryfrom semantica.kg import GraphBuilder, TemporalGraphQuery kg GraphBuilder().build({ entities: [ {id: alice, type: Person}, {id: acme, type: Organization}, ], relationships: [ {source: alice, target: acme, type: ceo_of, valid_from: 2018-01-01, valid_until: 2022-06-01}, {source: alice, target: acme, type: advisor_of, valid_from: 2022-07-01}, ], }) tq TemporalGraphQuery(temporal_granularityday) print(tq.query_at_time(kg, query, at_time2020-06-15)[num_relationships]) # 1 print(tq.query_at_time(kg, query, at_time2023-01-01)[num_relationships]) # 1query_at_time按valid_from/valid_until区间过滤边见 temporal_query.py2020 年返回ceo_of2023 年只剩advisor_of。返回 dict 里num_relationships是过滤后的边数所以两次查询都是 1但成立的是不同的边。整条管道要时序能力时构建侧传GraphBuilder(enable_temporalTrue, temporal_granularitymonth)粒度支持从second到year七档。Agent 决策记忆。多 Agent 长程任务常前后矛盾上周选了 A 模型这周换 B 模型没有任何机制阻止。AgentContext把事实记忆、图谱记忆和决策记录放在同一层决策是一等对象而不是日志from semantica.context import AgentContext, ContextGraph from semantica.vector_store import VectorStore ctx AgentContext( vector_storeVectorStore(backendfaiss, dimension768), # 必传 knowledge_graphContextGraph(), # 决策记录落在这里 decision_trackingTrue, # 不开则 record_decision 报错 ) ctx.store(GPT-4 outperforms GPT-3.5 on reasoning benchmarks by 40%) did ctx.record_decision( categorymodel_selection, scenarioChoose LLM for production reasoning pipeline, reasoningBenchmark advantage justifies 3x cost, outcomeselected_gpt4, confidence0.91, ) print(ctx.find_precedents(model selection, limit5)) # 相关历史决策 print(ctx.analyze_decision_influence(did)) # 该决策的因果影响链硬性前置有两条违反都会直接抛错见 agent_context.pyvector_store必传不传抛ValueErrorrecord_decision依赖decision_trackingTrue且决策后端可用上面的knowledge_graph否则抛RuntimeError。其余参数都有默认值retention_days30记忆保留天数、max_memories10000、hybrid_alpha0.50 偏向量检索、1 偏图遍历。faiss 后端需另装pip install semantica[vectorstore-faiss]。常见坑与排查现象PDF 解析后抽不到任何实体。原因扫描件只有图片层、没有机器可读文本DocumentParser检测到无文本层只打警告抽取自然为空。 解法换带 OCR 的解析器pip install semantica[parse-docling]后from semantica.parse import DoclingParser parsed DoclingParser().parse(data/scan.pdf)现象大目录建图时内存溢出。原因默认图只存进程内存且ingest()会把整个目录读进内存。 解法用scan_directory()逐文档处理 把GraphStore传给GraphBuilder(graph_store...)边构建边落库。现象record_decision抛RuntimeError: Decision tracking is not enabled。原因构造AgentContext时没开decision_tracking或没传knowledge_graph。 解法补上decision_trackingTrue并传knowledge_graphContextGraph()二者缺一不可。现象visualize_network报缺少 Plotly。原因基础包不含可视化依赖。 解法pip install semantica[viz]一次装齐。现象抽取结果是空的但没报错。原因methodpattern的模板只覆盖有限句式没命中就静默返回空列表。 解法换methodml先pip install semantica[nlp-spacy]并下载 spaCy 小模型或methodllm两者返回结构与 pattern 完全一致。进一步阅读getting-started.md官方快速入门覆盖环境搭建到第一个图quickstart.md五分钟速查最小可复现路径docs/reference/逐模块 API 参考semantic_extract、kg、context 等cookbook/introduction/26 篇入门教程 Notebook从数据摄入到时序图谱cookbook/advanced/时序知识图谱、Datalog 风格推理等进阶主题docs/storage-backends.md图存储后端选型对比Neo4j / FalkorDB / Neptune 等integrations/LangChain / CrewAI / Agno / Google ADK 框架封装semantica_mcp/MCP 服务端把图谱能力挂给任意 MCP 客户端【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考