6.3 开发与维护最佳实践

6.3 开发与维护最佳实践

走过弯路的人留下的几条规矩

Cognee 上手不难，但用久了对"怎么不把图搞乱"有讲究。这一节把开发与维护的经验压成可执行的几条，省得你重交学费。

这是第六章第三站，偏"工程内功"。

实践一：本体先定，再建图

开口建图前，先想清楚实体类型有哪些（公司/人/产品/地点）。类型定义得细，去重和歧义处理就干净。我们见过把"苹果"当公司又当水果混一起的图，查询全乱。

# 建图前先固化本体（示意）
ONTOLOGY = {
    "Company": ["名称", "成立年份"],
    "Person": ["姓名"],
    "Product": ["名称", "厂商"],
}
# 抽取模板按本体约束，避免类型漂移
​

实践二：抽取质量用样本验证

不要全量建完才发现抽错。先拿 20 份样本跑 cognify，人工抽查三元组，确认关系对再放量。

实践三：数据源与子图对应管理

第五章提过，增删按来源走。维护时给每个数据源打标签，废弃源及时 delete，图才不会缠成毛线。

# 维护：列出所有来源，定期清理下线源
sources = cognee.list_sources()
for s in sources:
    if s["status"] == "deprecated":
        cognee.delete(source=s["name"])
        print("已清理:", s["name"])
# 已清理: 旧版合同_2022
​

实践四：监控图健康度

给图设几个健康指标：节点数增速、孤立节点比例、三元组平均度数。异常波动往往预示抽取或数据源出问题。

# 健康度快照（示意）
health = {
    "nodes": cognee.graph_stats()["nodes"],
    "orphans": cognee.orphan_ratio(),        # 无关系的孤立节点
    "avg_degree": cognee.avg_degree(),
}
print(health)
# 孤立率突增可能意味着新数据源解析失败
​

案例：本体漂移导致的查询崩坏

背景：某项目初期没定本体，抽取把"订单"和"订单号"当两个实体，图里查询"订单状态"总是空。

操作：补一道实体链接节点，把"订单号"归并到"订单"。

import asyncio
from cognee import GraphPipeline, add, cognify

LINK = {"订单号": "订单", "单号": "订单"}

def link(triples):
    return [(LINK.get(s, s), p, LINK.get(o, o)) for s, p, o in triples]

async def fix():
    pipe = GraphPipeline()
    pipe.add_step("extract", extract_triples)
    pipe.add_step("link", link)
    pipe.add_step("write", write_graph)
    await add("./订单系统文档")
    await cognify(pipeline=pipe)
    print("本体归并后，订单查询恢复")

asyncio.run(fix())
# 本体归并后，订单查询恢复
​

结果：归并后"订单状态"能正常沿关系命中，查询崩坏消失。

解读：这个案例印证实践一——本体先定。事后补节点能救，但成本高于事前定。维护的最佳实践，大多是把"事前该做"的事制度化。

变式：若本体要演进（如新增"退款单"类型），在 ONTOLOGY 里加定义并跑样本验证，再放量，避免又一次漂移。

一个维护动作：图要定期"体检"

实践一、二讲建图前的规矩，但图会随业务长大、漂移。建议设一个定期体检：查孤立节点、查同名候选、查关系类型分布。类比到金融系统——每日对账，异常早发现，等月底才发现差额就难查了。

# 图体检示意
async def health_check():
    isolated = await cognee.get_isolated_nodes()     # 无连接的孤儿
    dup = await cognee.find_same_label_diff_id()     # 同名异 id 候选
    print("孤立节点:", len(isolated), "重名候选:", len(dup))
    # 孤立多 -> 某批抽取失败；重名多 -> 本体漂移
​

体检能早抓"图悄悄变脏"的信号，比用户投诉答非所问再救火便宜得多。

⚠️ 别等"用户说答错了"才查图——那时脏数据可能已扩散到多处，清理成本翻倍。

💡 把体检接进定时任务（如每周），异常自动告警，维护从救火变预防。

一个协作：本体变更要走评审

本体是图的地基，谁都能改就会漂移。建议本体变更走评审（PR + 双人确认），像改数据库 schema 一样慎重。类比到建筑——改承重结构要审图，不能谁拿工具谁就敲。

⚠️ 别让实习生直接改线上本体——一个类型名写错，全图去重逻辑就偏，影响面极广。

💡 本体存版本化文件，每次变更有 diff 有 owner，出问题能回滚到上一个干净版本。

一个提醒：最佳实践也会过时

本章列的规矩基于当前 Cognee 能力。框架演进后，某些实践可能变（如自动评测普及后"人工抽样"就退场）。保持实践与方法同步更新，别把旧经验当教条。

⚠️ 别照搬一年前的旧实践——Cognee 迭代快，旧经验可能已不适用新版本。

💡 最佳实践文档标版本与日期，过期项打标，新人不会误用陈旧经验。

本节要点回顾

• 本体先定再建图，类型细才能去重干净。
• 先样本验证抽取质量，再全量放量。
• 数据源与子图对应，按来源增删；监控孤立率等健康度。

⚠️ 别跳过样本验证直接全量。错误会被放大进整张图，清洗比预防贵十倍。

💡 把四条实践写成项目 checklist，每次建图前过一遍，比靠记忆可靠。