3.2 Cognee安装与升级

3.2 Cognee安装与升级

一行命令背后的依赖树

pip install cognee 看起来简单，但它会拉进图数据库驱动、异步库、LLM SDK 一整棵依赖树。这一节讲清安装时发生了什么、怎么验证装对了、以及升级时怎么不翻车。

这是第三章第二站，地基（环境）好了，现在把框架本身请进来。

安装与验证

最简单的方式是直接装发布版。装完务必验证导入和版本，确认不是装到了错的分支或残包。

# 安装最新稳定版
pip install cognee

# 验证导入与版本
python -c "import cognee; print('cognee', cognee.__version__)"

# 验证子模块可用（图、搜索等）
python -c "import cognee; print([a for a in dir(cognee) if not a.startswith('_')][:8])"
# ['add', 'cognify', 'search', 'delete', ...]
​

如果导入报 ModuleNotFoundError，八成是装到了错误的 Python（没激活虚拟环境），用 which python 确认路径再重装。

升级策略：小步快跑

Cognee 发版频繁，API 偶尔变动。我们建议小步升级：先看 changelog，再升级，再跑一遍既有脚本。不要用 pip install --upgrade 一口气拉到最新然后才发现代码全崩。

# 查看当前版本与可升级版本
pip index versions cognee        # 或 pip install cognee== 触发提示

# 小步升级到指定版本，而非盲目最新
pip install cognee==0.1.45
python -c "import cognee; print(cognee.__version__)"
# 0.1.45
​

从源码安装（开发场景）

如果你想改 Cognee 本身或试用未发布特性，从源码装：

git clone <cognee 仓库>
cd cognee
pip install -e .     # 可编辑安装，改代码即时生效
python -c "import cognee; print(cognee.__version__)"
# 0.1.45.dev0
​

-e 是可编辑模式，适合给框架提 PR 或在上面做二次开发。普通使用者不必走这条路，发布版更稳。

案例：生产环境的安全升级

背景：线上跑着 0.1.40，官方修了安全漏洞，需升到 0.1.45，但不能影响业务。

操作：在预发环境先走三步走。

# 预发环境
pip install cognee==0.1.45
python run_regression.py     # 跑既有回归脚本

# pip install cognee==0.1.45  (生产同版本)
​

结果：预发验证通过后才动生产，避免"升级即事故"。

解读：升级风险不在"装新包"，而在"新包改了行为"。小步+回归是把风险关进笼子。

变式：若回归发现某 API 变了，先在代码里适配再升，不要硬升后现场改——现场改最容易漏。

一个升级纪律：先看变更，再动生产

升级 Cognee 大概率带来抽取模板或图结构的调整。直接在生产库上 pip install -U 是最危险的动作——新版本可能期望新的图 schema，旧图读不出。类比到金融系统升级：先读发版说明，在影子环境跑一遍，再切流量。

# 安全的升级路径示意
pip install cognee==0.1.43     # 指定版本，不盲目追最新
python -c "import cognee; print(cognee.__version__)"  # 确认生效
# 在测试库跑一遍 cognify + search，确认图结构兼容
​

若新版本改了图 schema，通常需要对测试库做一次重建验证，确认无报错再上生产。

⚠️ 别在周五下午升级生产图库——出问题周末没人，且图重建可能跑很久。

💡 升级前先导出当前图结构摘要（节点数/边数），升级后对比，数量级对不上立刻回滚。

一个验证清单：装完别急着写业务

安装成功只是第一步，建议跑三道验证：导入成功、版本正确、子模块可用。任一道不过，后面写的业务代码都可能莫名其妙报错。类比到建筑——水电通了先试开关节点，再搬家具。

⚠️ 别跳过版本核对——装到旧版可能 API 已变，写成新版写法当场炸。

💡 把三道验证写成一条命令放进 CI，环境变了自动红，比人工记得牢。

一个提醒：锁版本也是一种稳定性

生产环境把 Cognee 版本写死在锁文件里，不追最新，是主动选择稳定而非落后。新特性等你验证过再升，节奏在你手里。

⚠️ 别被"最新版有某某功能"诱惑盲升——没验证的新功能可能引入不兼容，生产先稳后新。

💡 设个例行的升级评审（如每季度），集中评估而非随到随升，节奏可控。

一个对照：不同装法适用不同场景

安装方式不止 pip 一种。开发期用源码装（可改可调试），生产用发布版（稳定）。选错只是麻烦，但选对省心。类比到建筑——施工期用临时电，交房用正式电，阶段匹配效率最高。

⚠️ 别在生产用源码可编辑装——你改一行框架代码，升级和维护都背上债。

💡 开发用 editable 装方便改，生产切回发布版，两套环境职责分明。

本节要点回顾

• pip install cognee 会拉整棵依赖树，装完要验证导入和版本。
• 升级用指定版本号，避免盲目最新。
• 源码装 -e 适合二次开发，普通用户用发布版。

⚠️ 生产环境禁止 pip install --upgrade cognee 无脑拉最新。API 变动会让脚本静默失效。

💡 升级前先把回归脚本准备好，没回归就别谈安全升级。