3.4 快速入门示例与Colab实践

3.4 快速入门示例与Colab实践

跑通第一个闭环，概念才算落地

前面三节把环境、包、凭证都备齐了。这一节把它们串成一个能跑的最小闭环：加一段文本、建图、查询。你会在输出里第一次看见"节点""边"这些词变成真实数字。

这是第三章的终点，也是全册从"懂"到"用"的分水岭。

最小可运行示例

下面这段几乎是最简形态：一段关于公司的文本，建图后问"谁创立了什么"。

import asyncio, os
from cognee import configure, add, cognify, search

configure(api_key=os.getenv("OPENAI_API_KEY"))

async def main():
    # 1. 加数据
    await add("李明在2020年创立了云图科技，公司总部位于杭州。")
    # 2. 建图
    await cognify()
    # 3. 查询
    ans = await search("谁创立了云图科技")
    print(ans)

asyncio.run(main())
#   3.4 快速入门示例与Colab实践
​

看到 source: user_input#0 了吗？它指回你输入的原文位置，这就是可追溯性的雏形。哪怕只有一句话，图谱也已经把"李明—创立—云图科技"这条关系固化了。

在 Colab 里零本地依赖跑

如果你不想碰本地环境，Colab 类笔记本能直接在浏览器跑。思路一样：装包、设密钥、跑闭环。

# 在笔记本第一个单元格
!pip install cognee
import os, asyncio
os.environ["OPENAI_API_KEY"] = "你的密钥"   # 笔记本里临时设

from cognee import configure, add, cognify, search
configure(api_key=os.getenv("OPENAI_API_KEY"))

async def demo():
    await add("西湖是杭州的著名湖泊，杭州是浙江省的省会。")
    await cognify()
    return await search("杭州的省会是哪")

asyncio.run(demo())
# [{'entity':'杭州','relation':'省会','value':'浙江省', ...}]
​

案例：把一篇博客变成可问答的知识

背景：你写了一篇技术博客，想之后用自然语言回看里面的观点。

操作：把博客内容 add 进去建图，再提问验证。

import asyncio
from cognee import configure, add, cognify, search
configure(api_key=os.getenv("OPENAI_API_KEY"))

async def blog_demo():
    await add("./我的博客.md")          # Markdown 直接吃
    await cognify()
    ans = await search("我博客里提到的图谱增强检索有什么用")
    print(ans)

asyncio.run(blog_demo())
#   'value':'让多跳问答可验证','source':'我的博客.md#p4'}]
​

结果：你自己的文字被结构化成图，提问直接沿关系返回观点和出处。

解读：这个闭环你已经具备"个人知识助手"的雏形——它记住了你写过的东西，且答得出处。这正是第一章说的"可演化、可追溯记忆"。

变式：把 add 的对象从单文件换成整个文件夹，cognify 会批量建图，你的博客站点整体变成可问答的知识库。第四章会展开摄取的更多姿势。

一个验证习惯：跑通后立刻测"反向问答"

最小闭环跑通、看到节点边就结束，是新手常见止步点。但"能建图"不等于"能答对"。建议闭环跑通后立刻做反向测试：用图里的关系反着问，确认检索真的走了图而不是撞大运。类比到物理实验——不光看灯亮了，还要验证"关掉开关灯就灭"，才算真懂电路。

# 闭环跑通后的反向验证（示意）
async def verify():
    await add("李明创立了云图科技，总部在杭州。")
    await cognify()
    # 正问
    a1 = await search("李明创立了什么")
    # 反问：从总部反推公司再反推创始人
    a2 = await search("杭州有哪些公司的创始人")
    assert "李明" in str(a2), "图没支持反向多跳"
    print("反向多跳通过：图真的被检索用上了")
​

反向问答通过，说明图谱增强 RAG 不是摆设，而是真在回答里生效。

⚠️ 别把"输出像答案"当"答对了"——让模型自由生成可能编造，必须看它是否指回图里的实体与出处。

💡 Colab 跑完记得把密钥清掉再分享笔记本；教学可以，泄露凭证不行。

一个延伸：把闭环变成可复用函数

最小示例跑通后，建议立刻包成可复用函数（加数据、建图、查三者合一），以后每个新数据集只传路径。这比每次复制粘贴示例稳，也方便在 CI 里回归。类比到物理实验——把接线固化成标准电路，下次直接通电。

⚠️ 别把所有实验都堆在一个笔记本里——时间久了分不清哪个能跑、哪个是草稿。

💡 可用的最小函数提交进仓库当脚手架，团队新人直接 import 上手。

一个心态：闭环跑通 = 已过最难的坎

很多人在"装环境"阶段放弃。一旦闭环跑通，后面都是在此之上加料，难度曲线陡降。所以第三章值得花时间把地基打牢，后面章节会顺很多。

⚠️ 别在环境没稳时就怪框架难用——多数"用不起来"是环境没对，不是框架问题。

💡 卡住时回看 3.1 环境节，八成能找到根因，别急着改业务代码。

本节要点回顾

• 最小闭环三步：add 加数据、cognify 建图、search 查询。
• 输出里的 source 字段是可追溯性的体现。
• Colab 类笔记本可零本地依赖跑通同样闭环。

⚠️ 第一次跑若报错 API key 缺失，先确认环境变量在当前运行进程里生效，而非只在另一个终端导出过。

💡 入门阶段每跑通一步就打印中间结果，比一口气写完再调试更容易定位问题。