很多人在做 NLP 和关键词提取项目时第一个卡点往往不是分词、不是关键词算法而是环境。我刚接触 Jupyter Notebook 那段时间也走过弯路先装 Anaconda再在 base 环境里 pip install 一堆包头两天跑词频统计还挺顺后来需要引入 transformer 模型升级 numpy 时把 jieba 的依赖直接弄崩了。我一度以为是代码写错了折腾半天才意识到是环境被污染的连锁反应。后来把环境重建一次用虚拟环境隔离对应的问题就消失了。围绕 Jupyter Notebook、Python 虚拟环境、NLP、关键词提取这四个关键词我现在的判断很明确做 NLP 项目虚拟环境不是可选的高级工程能力而是开始写业务逻辑之前就应该做好的基础隔离。真正跑通一个关键词提取 demo 很容易但能不能在其他机器、其他时间、其他项目里可复现地运行才是这套环境搭建的核心价值。1. 为什么 NLP 和关键词提取项目必须先解决环境问题1.1 你真正踩过的可能不是代码问题而是依赖问题关键词提取本身听起来很轻量先分词再统计权重最后返回 TopN 关键词。如果不做复杂语义模型甚至只需要jieba一个库就能跑通。但实际项目很少止步于“跑通 Demo”。你很快就会加停用词过滤、加词性过滤、加自定义词典然后尝试用 TF-IDF 和 TextRank 对比效果再往后可能想用预训练模型做语义关键词于是引入scikit-learn、pandas、transformers、torch或者sentence-transformers。问题就在依赖叠加的过程里jieba依赖某个基础版本scikit-learn对numpy有版本要求transformers又可能拉取新版numpy。一旦没有环境隔离新项目升级的包会直接作用到老项目上。老项目可能看起来没崩但关键词结果悄悄变了更糟的情况是一启动就报ImportError: cannot import name xxx from numpy。这类问题很隐蔽因为它不以“你的代码有 bug”的方式出现而以“版本不兼容”的方式出现。你会在 Stack Overflow 上翻很久最后发现只是依赖版本被顶掉了。1.2 虚拟环境解决的三个问题隔离、复现、回滚虚拟环境不是用来“显得专业”的它真正解决了三个具体问题隔离。每个项目拥有独立的site-packages目录项目 A 用numpy 1.24项目 B 用numpy 1.26不会互相覆盖。关键词提取项目可以继续用稳定的旧版jieba深度学习项目可以放心升级transformers。复现。虚拟环境允许你把当前依赖导出为清单文件另一个同事或另一台机器只要按清单重建环境就能得到和当前基本一致的环境。NLP 实验对版本很敏感分词器版本、模型权重、向量化方式都可能影响结果。没有复现能力实验结果就缺少可信度。回滚。环境坏了直接删掉重建一个成本通常很低。如果没有虚拟环境一旦系统 Python 被改坏你可能需要重装解释器或慢慢清理包这个成本会高得多。所以更准确地讲虚拟环境是在为“项目生命周期”负责而不是为“某一次运行”负责。2. 两条路线conda 虚拟环境和 venv 虚拟环境怎么选2.1 用 conda/Miniconda 管理环境适合大多数 NLP 项目Anaconda 最大的好处是预装了很多数据科学包开箱即用。但它的体积也很大里面很多包可能你用不上。我更建议用 Miniconda它保留了conda这个核心命令需要什么就装什么更轻量。conda 对 NLP 项目很友好核心原因有两个一是它能独立管理 Python 解释器版本比如项目要python 3.10conda 可以直接创建二是它预编译的包对底层依赖处理得更省心尤其涉及numpy、scipy、pandas这类带 C 扩展的库时conda 的依赖解析通常比裸pip更稳。常见流程是这样conda create -n nlp-env python3.11 conda activate nlp-env这里nlp-env是环境名你可以按项目名来命名。创建完成后所有后续安装都应该在这个环境下进行。不要把所有东西都堆在base环境里否则又回到环境污染的老路上。2.2 用 venvpip 管理环境适合轻量需求和独立 Python 开发者如果你已经安装了官方 Python而且不想再引入额外的环境管理工具venv是更原生、更轻量的选择。它是 Python 标准库的一部分不需要额外安装。创建和激活python -m venv .venv source .venv/bin/activateWindows 下激活命令略有不同.venv\Scripts\activate激活后你的命令行提示符前面会多一个(.venv)前缀表示当前已经进入虚拟环境。然后就可以用pip install安装依赖了pip install jupyter numpy pandas scikit-learn jiebavenv的缺点是不能直接创建指定版本的 Python 解释器它依赖你系统里已经存在的python命令。如果你的系统同时有 Python 3.9、3.11、3.12你需要在创建时指定具体解释器例如python3.11 -m venv .venv2.3 选型对照conda vs venv维度conda / Minicondavenv pipPython 版本管理可以安装并切换多个 Python 版本需要系统已有对应版本的解释器包安装来源conda 渠道 pip主要是 PyPI底层依赖处理对 C 扩展、系统库更省心依赖 wheel复杂环境可能需要额外编译工具环境体积通常更大更小学习成本中等低适合场景深度学习、复杂 NLP 环境、多项目并行轻量脚本、数据分析、Web 服务、普通关键词提取如果已经装了 Anaconda直接用 conda 没问题如果是从零开始并且没有特殊系统依赖venv 也完全够用。真正要避免的是“系统里本来有一个 Python又装一个 Anaconda两个混着用”这会让 PATH 变得难以追踪。3. 把虚拟环境正确挂到 Jupyter Notebook 上3.1 Jupyter Notebook 和 Python 内核是两回事很多人在终端里激活了虚拟环境再启动 Jupyter Notebook然后在 Notebook 里执行import jieba依然报错。原因是Jupyter Notebook 本身是前端界面真正执行 Python 代码的是一个独立的进程叫 Kernel。你打开 Notebook 时使用的 Python 内核不一定是你刚刚在终端里激活的那个环境。创建了虚拟环境不代表 Jupyter 会自动用它。要让它生效必须把这个环境“注册”成 Jupyter 的一个内核。3.2 用 ipykernel 把当前环境注册成内核在已经激活虚拟环境的前提下安装ipykernelpython -m pip install ipykernel然后注册内核python -m ipykernel install --user --name nlp-env --display-name Python (nlp-env)这里的参数说明一下--name nlp-env是内核的唯一标识名建议和虚拟环境名保持一致。--display-name Python (nlp-env)是 Jupyter Notebook 界面上显示的名字你可以自由设置。--user表示写入当前用户目录避免权限问题。注册完可以查看内核列表jupyter kernelspec list如果看到nlp-env对应的路径说明注册成功。之后启动 Jupyter Notebook在Kernel - Change Kernel里选择Python (nlp-env)即可。有一点要注意执行python -m ipykernel时一定要先确保当前虚拟环境已激活。因为python -m会调用当前环境下的 Python 解释器而不是随便找一个全局的python。3.3 跑代码前先确认 sys.executable 和包路径环境是否真的正确单靠“我记得切了内核”不够。最稳妥的方式是在 Notebook 里写一个环境探针单元格import sys print(sys.executable)如果输出的路径不是你虚拟环境下的 Python 解释器路径说明当前内核选错了。也可以执行!which pythonWindows 下则用!where python还可以检查sys.path和包的实际路径import jieba print(jieba.__file__)这个输出会告诉你当前jieba到底是从哪个目录加载的。如果路径指向虚拟环境说明内核关联正确否则就需要回到内核选择或重新注册。不要只对比python --version因为不同解释器可能版本完全相同但来自不同路径。关键要看sys.executable。4. 最小依赖与一个能跑通的关键词提取样例4.1 最小依赖不要一上来就装 transformers 和 torchNLP 领域最容易犯的错误是一开始就把所有可能的依赖都装进环境。等到项目沉淀一段时间依赖清单膨胀到几十上百个出了问题你自己都不知道是谁和谁冲突。针对关键词提取最小依赖其实是这些库用途是否必需jieba中文分词、TF-IDF/TextRank 关键词提取必需numpy数值计算基础通常需要scikit-learn做向量化、建模、评估和关键词权重对比需要时再加pandas处理结构化结果需要时再加matplotlib可视化关键词分布可选transformers/torch语义关键词、摘要、预训练模型后续按需添加安装命令可以只装最核心的pip install jieba numpy pandas scikit-learn如果你用的是 conda 环境同样用 pip 安装即可但优先考虑直接用 conda 安装numpy、pandas这类包也可以因为 conda 对底层依赖处理更稳。这个阶段不要把transformers和torch装进去它们体积大、依赖多等你真正要用语义模型时再增量加会更安全。4.2 TF-IDF 关键词提取一条命令跑通第一版用jieba.analyse.extract_tags就能实现基于 TF-IDF 的关键词提取。TF-IDF 的思想可以理解成一个词在一篇文章里出现次数足够多但在整个语料里又足够少见那它对这篇文章就有代表性。一个最小示例import jieba.analyse text 作者在文章里强调NLP 项目开始之前必须先搭好 Python 虚拟环境 并且把 Jupyter Notebook 的内核指向正确的虚拟环境这样才能避免版本冲突。 关键词提取看起来只是分词和统计但一旦依赖混乱整个实验很可能不可复现。 keywords jieba.analyse.extract_tags(text, topK10, withWeightTrue) for word, weight in keywords: print(word, weight)运行后你会得到一组关键词和权重。topK表示返回多少个关键词withWeightTrue可以同时返回权重。这样跑通至少说明环境没问题、分词能执行、关键词提取流程能出结果。但注意这段文本只是一段示例TF-IDF 原本需要语料库来计算逆文档频率单文档下结果很粗糙只适合用来验证流程。4.3 TextRank 调优与单条样例之后的边界jieba还提供了textrank方法keywords jieba.analyse.textrank(text, topK10, withWeightTrue) for word, weight in keywords: print(word, weight)TextRank 的思路是用图排序把词语看成节点通过词共现关系迭代计算权重不依赖外部语料库。它和 TF-IDF 的侧重点不同结果也不太一样。如果直接跑你可能会发现输出里包含很多停用词比如“一个”“以及”“开始”这类。这时需要做两件事设置停用词表过滤常见功能和语气词。选用或调整自定义词典让专业领域词被正确切分。单条样例跑通后不要急着把整个语料批量送进去。真实场景要先做清洗再验证算法在少量样本上的效果最后才扩大批次。这也是环境搭建和算法开发共同的主线先跑通再优化最后工程化。5. 环境搭好了但 Jupyter 里 import 报错怎么排查5.1 先区分“终端能用”和“Notebook 能用”一种很常见的现象是在终端conda activate nlp-env之后执行python -c import jieba不报错但打开 Jupyter Notebook新建一个 Notebook执行import jieba却报ModuleNotFoundError。问题几乎都出在内核上。终端里能用说明虚拟环境本身没坏Notebook 里不能用大概率是因为 Notebook 当前使用的内核不是nlp-env。排查时先不要急着重装环境按下面顺序走一遍看一下报错是ModuleNotFoundError、ImportError还是版本冲突。在 Notebook 里执行import sys; print(sys.executable)确认当前解释器路径。在终端里 activate 后执行同样的命令对比两个路径。通过 Notemenu 的Kernel - Change Kernel切换到Python (nlp-env)。如果内核列表里没有重新执行注册命令。5.2 怎么查当前 Notebook 到底在用哪个 Python查解释器路径是最可靠的。我建议把下面几行放在一个 Notebook 单元格里环境一有问题就跑一下import sys print(sys.executable) !which python !pip --versionWindows 下把!which python换成!where python。关键是理解sys.executable的含义它告诉你当前内核实际使用的 Python 可执行文件路径。如果它指向.../nlp-env/bin/python说明内核选对了否则就要调整。如果想更深入一点可以在终端执行jupyter kernelspec list找到nlp-env对应的目录然后打开里面的kernel.json查看可执行文件的路径。这能帮你确认 Jupyter 注册的内核是不是你的虚拟环境。5.3!pip install、PATH 顺序、conda 和 pip 混用的隐患在 Notebook 里执行!pip install package很方便但也很危险。!前缀会启动一个子 shell 执行命令它调用的pip不一定来自当前内核。如果系统里存在多个 Python 环境!pip install很可能把包装到了错误的环境。更稳妥的两个方式%pip install jieba或者!python -m pip install jieba%pip是 IPython 的魔法命令通常会绑定当前内核的 Python!python -m pip强调用当前解释器执行 pip也能减少路径混淆。但它们的前提依然是“当前内核正确”。如果内核本身就选错了装到哪都白搭。conda 和 pip 混用也会带来问题。在 conda 环境里执行pip install时如果pip指向系统 Python最终包会装到系统 site-packages而不是 conda 环境的 site-packages。所以最好的习惯是统一用python -m pip install并且每次安装后都检查pip --version或sys.executable。PATH 顺序则会影响你在终端里敲python时实际执行的是哪个解释器。如果同时装了 Anaconda 和独立 Python终端里which python指向哪个取决于 PATH 顺序。解决办法不是反复改 PATH而是养成“先 activate 再安装”的习惯并用conda info --envs或which python做确认。5.4 一个通用的排查顺序表下面的表格可以作为一个通用排查清单排查环节核心检查处理方向现象是报错、空白页面还是运行结果异常先明确问题类型不要混在一起排查内核sys.executable是否指向虚拟环境重新选择或注册内核包列表pip list里是否有目标包用python -m pip install安装包版本安装版本是否与代码依赖兼容锁定版本或升级/降级环境变量which python/where python指向哪里检查 PATH 顺序和 activate 状态残留conda/pip 缓存或旧 site-packages 是否干扰重建环境或清理缓存顺序很重要先看现象再看内核再看包再看版本最后才怀疑环境变量和残留问题。不要一上来就重装 Anaconda 或换 Python 版本那样会把问题扩大。6. 把环境变成项目资产可复现和增量演进6.1 立即导出 requirements.txt 或 environment.yml环境跑通后第一件事是冻结依赖清单。这就像给项目拍一张快照之后任何时间都能从这张快照恢复环境。用 pip 管理时在虚拟环境激活状态下执行pip freeze requirements.txt这份文件会列出当前环境里所有包和精确版本号。恢复环境时pip install -r requirements.txt用 conda 管理时可以导出包含 conda 信息的环境文件conda env export environment.yml恢复时conda env create -f environment.ymlpip freeze和conda env export的差异在于pip freeze只记录 pip 安装的包environment.yml会同时记录 conda 包、pip 包以及 Python 版本、构建源等信息更适合复现完整的 conda 环境。建议习惯是每完成一个阶段比如说跑通最小流程、加入一个新库、调整了主要版本都重新导出一份清单。这样项目演进过程中随时有回滚点。6.2 这套方案适合谁不适合谁适合的场景在同一台机器上同时做多个 NLP 项目需要不同库版本。做研究或实验需要向同事、审稿人、开源社区复现环境。项目在持续迭代依赖会不断增加必须控制版本变化。想用 Jupyter Notebook 写 NLP 代码又不想被默认内核坑到。不太适合或可以不这样做的场景只是临时跑一个一次性脚本跑完就删。项目已经通过 Docker 或云端 Notebook 做了环境隔离虚拟环境的角色会弱化。团队有统一的基础镜像和依赖管理工具已经形成流程。但即使在这些场景里用requirements.txt或environment.yml记录依赖仍然有价值。区别只是“要不要创建本地虚拟环境”而不是“要不要记录依赖”。6.3 维持环境的通用框架解耦、注册、冻结把上面的经验浓缩成一个可复用框架就是六个字解耦、注册、冻结。解耦用 conda 或 venv 创建独立环境不让项目直接跑在系统 Python 或 base 环境里。这一步决定了后续所有依赖是否可控。注册把创建好的环境通过ipykernel注册到 Jupyter Notebook并在代码运行前确认sys.executable指向正确。这一步解决了“终端能用但 Notebook 不能用”的大部分问题。冻结每次跑通一个阶段就导出requirements.txt或environment.yml。这一步让环境变成项目资产随时可以重建和分享。以后做其他数据科学项目时这个框架也成立。先想清楚环境边界再安装依赖再把前端工具和内核关联起来最后把关键依赖记录下来。环境管理真正要解决的问题不是“找一个万能环境”而是“让每一个项目都能在可控的环境里稳定运行”。随着项目复杂度提升你还会接触到uv、Poetry 这类新工具它们会改变“创建环境”和“安装依赖”的具体写法但核心心智仍然是解释器、依赖、内核这三件事。把这几个概念弄清楚了工具怎么换都只是形式变化。对你现在最直接的建议是如果你的关键词提取项目还没有建立虚拟环境先停下手头的安装操作。创建虚拟环境激活它安装jieba和必要依赖注册内核然后在 Notebook 里先打印一次sys.executable再跑 TF-IDF 示例。等这一步稳定了再考虑要不要加入更重的模型。单次跑通只说明流程没断真正的稳定来自隔离、确认和冻结这三件事都做到了。