在实际的 NLP 与关键词提取项目中环境配置混乱带来的问题往往比算法本身更先暴露出来。很多人把分词、TF-IDF、TextRank 的逻辑写好之后却在import jieba这一步失败或者在 Jupyter Notebook 中运行的 Python 解释器与命令行里不是同一个导致依赖装好了却找不到包。这个系列的第二部分专门解决 Jupyter Notebook 与 Python 虚拟环境这组基础设施问题。如果你跳过或没有读过 P1也不影响这一篇的使用。P1 阶段主要解决 Python 本身的安装问题P2 会围绕“虚拟环境 Jupyter Notebook NLP 关键词提取依赖”这条主线把从创建环境、激活环境、注册 kernel到最后跑通一个最小关键词提取示例的完整流程讲清楚。做完之后你的机器上会有一套干净、可复现、便于切换到其他项目的 NLP 开发环境。1. 先明确这套环境要解决什么问题1.1 P2 在整个系列里的任务边界NLP 项目与普通脚本项目有一个明显差异它的依赖数量多、版本耦合紧。一个关键词提取任务通常会同时用到分词库、机器学习库、数值计算库和数据处理库。如果所有项目共用同一个全局 Python 环境只要某个项目升级了numpy或scikit-learn另一个项目可能就无法运行。P2 要完成的任务可以拆成四件事创建专门的 Python 虚拟环境。把 Jupyter Notebook 接入这个虚拟环境。安装 NLP 与关键词提取常用依赖。用最小示例验证环境真正可用。这一套流程与具体算法无关但它是所有后续实验的前提。你可以在上面跑 jieba、nltk、spacy、gensim也可以跑基于 scikit-learn 的自定义 TF-IDF 流程甚至后续接入 PyTorch 或 Transformers 时只会增加依赖不会改变环境隔离的基本逻辑。1.2 全局 Python 环境在 NLP 项目中的瓶颈很多新手最常犯的错误是“直接在全局环境里 pip install 一切”。短期内似乎很顺利但项目一多就会遇到三个典型问题。一是依赖冲突。关键词提取项目中numpy的版本往往受scikit-learn约束而另一个目标检测项目可能需要更新的numpy。两个项目的需求无法在一个全局环境中同时满足。二是系统环境被污染。如果机器上的 Python 身兼多职比如被系统工具、IDE 插件或 CI 脚本使用那么全局安装大量第三方包后一旦某个包与系统组件冲突排查范围会变得非常大。三是复现困难。换一台电脑或者让同事运行你的 Notebook 时对方很难从你的环境中还原出完全一致的依赖。没有虚拟环境的项目几乎无法做到“一键复现”。虚拟环境的本质是在同一个 Python 解释器基础上隔离出一套独立的三方包目录。项目 A 和项目 B 可以各自拥有不同版本的依赖互不干扰。1.3 这一轮完成后的验收指标在做任何操作之前先明确验收标准。这篇文章完成后应该同时满足以下条件检查项验收标准虚拟环境已创建项目目录下存在.venv文件夹Python 解释器指向正确激活环境后which python或where python指向.venvpip 指向正确python -m pip --version显示路径在.venv内Jupyter 已安装激活环境后能执行jupyter notebookkernel 已注册jupyter kernelspec list能看到新注册的 NLP 内核Notebook 中使用正确解释器cell 内sys.executable输出.venv中的 Python 路径关键词提取依赖可导入jieba、scikit-learn、pandas、numpy均能 import 成功后续每一步操作都以这七个条件为目标。这样可以避免“以为配好了实际上 Notebook 用的还是另一个环境”这种最常见的问题。2. 选择 Python 版本和虚拟环境工具2.1 NLP 依赖对 Python 版本的影响NLP 生态对 Python 版本的适配通常会出现“滞后”现象。大型依赖库在 Python 发布新版本后往往需要几个月才能完成适配。因此不建议直接使用最新版 Python而应该选择大多数第三方库已经稳定支持的版本。从当前 NLP 项目实践来看Python 3.9、3.10、3.11 是相对稳妥的选择。落地的同学应先确认自己的分词库、scikit-learn、jupyter是否支持当前 Python 版本。检查方法很简单python --version如果机器上同时存在多个 Python 版本建议创建虚拟环境时显式指定python3.11 -m venv .venv这里的关键点是虚拟环境并不拷贝 Python 解释器而是复用系统里的某个基础解释器同时创建一套独立的site-packages目录。因此创建虚拟环境前必须先确认基础解释器版本是项目能接受的。2.2 venv 与 conda 的选型Python 原生的venv是最轻量、最通用的方案。它不需要额外安装工具使用 Python 内置模块即可创建环境。绝大多数教学和中小型 NLP 项目都推荐使用。conda的适用场景则偏向重依赖管理。它不仅能管理 Python 包还能管理 Python 解释器版本、非 Python 的二进制库。比如安装nltk或scikit-learn时conda 会自动处理底层编译依赖减少二进制不兼容的情况。表格对比两种方案对比项venvconda是否需要额外安装否Python 3.3 内置需要安装 Miniconda 或 Anaconda是否管理 Python 版本复用当前解释器可以创建指定 Python 版本环境依赖来源PyPIconda 源以及 PyPI二进制冲突可能遇到通常更少环境文件导出requirements.txtenvironment.yml 或 requirements.txt适合场景普通 Python 项目、Notebook 开发深度学习、需要特定 Python 版本、需要复杂二进制库如果原始项目没有明确要求使用 conda建议先用 venv。它的学习曲线更短文件结构更透明后续切换到 Docker 时也更直接。2.3 动手前的基础检查在创建环境之前先执行一组基础检查。这一步可以避免很多“装好了却找不到包”的后续问题。python --version which python python -m pip --version三个命令分别确认解释器版本、解释器路径、pip 路径。正常情况下python -m pip --version会显示当前解释器的绝对路径。如果这一命令报错说明 pip 模块缺失需要先处理 Python 安装问题再继续后面的操作。注意运行pip install时推荐统一使用python -m pip而不是直接用pip。pip命令可能来自 PATH 中的另一个 Python而python -m pip能准确对应当前激活的解释器。3. 创建虚拟环境目录结构、激活与路径校验3.1 项目目录结构与 .venv 创建先规划项目目录。建议为 NLP 关键词提取项目单独创建一个文件夹不要让 Notebook 和虚拟环境散落在各处。mkdir nlp-keyword-extraction cd nlp-keyword-extraction python -m venv .venv这里使用.venv作为目录名而不是venv主要是为了避免与系统其他工具冲突。目录名本身只是一种约定可以用任何名称但保持统一会让后续配置和 IDE 识别更简单。创建命令执行结束后在项目目录下执行ls -a此时应该能看到.venv目录。如果看不到说明创建失败或命令执行目录不对。3.2 激活虚拟环境不同平台的命令差异虚拟环境创建后还需要激活。激活的本质是修改当前终端的环境变量把.venv中的Scripts或bin目录放到PATH最前面。Windows PowerShell.venv\Scripts\Activate.ps1Windows CMD.venv\Scripts\activate.batmacOS 或 Linuxsource .venv/bin/activate激活成功后命令行提示符通常会出现(.venv)前缀。例如(.venv) userhost:~/nlp-keyword-extraction$这个前缀是判断激活状态最直观的信号。3.3 激活后的第一件事确认 python 和 pip 路径激活环境后不要急着安装依赖先执行以下命令which python python --version python -m pip --versionWindows 系统把which替换为where。正常情况下列结果中的路径必须包含.venv目录。例如/User/name/nlp-keyword-extraction/.venv/bin/python如果python仍然指向系统路径说明激活没有生效。常见原因是终端窗口是在激活之前打开的此时应重新打开终端再激活或检查激活命令是否执行成功。确认路径正确后先升级 pippython -m pip install --upgrade pip升级 pip 的原因是版本过旧时安装大依赖包可能失败也可能无法正确解析依赖关系。4. 把 Jupyter Notebook 接入虚拟环境4.1 kernel 与虚拟环境的关系Jupyter Notebook 本身是一个网页界面它不直接运行 Python 代码而是通过 kernel 执行代码。kernel 本质上是“后端解释器进程”。Notebook 负责编辑和展示kernel 负责计算和返回结果。把虚拟环境注册为 kernel就是告诉 Jupyter运行代码时使用这个虚拟环境里的 Python 解释器和依赖。注册完成后Notebook 可以在多个 kernel 之间切换。即使全局环境也安装了 Jupyter只要 Notebook 选择的是新的 kernel它就会使用虚拟环境中的依赖。这种机制是 Jupyter 能在多项目之间自由切换的关键。4.2 安装 jupyter 和 ipykernel在虚拟环境激活状态下安装 Jupyter 和内核工具。python -m pip install jupyter ipykernel安装jupyter是为了获得 Notebook 和 JupyterLab 界面安装ipykernel是为了把当前环境注册为内核。如果只是需要 Notebook 编辑器也可以只安装notebook但安装完整的jupyter会更省心它同时包含 Notebook 和 JupyterLabpython -m pip install jupyterlab两种安装方式的区别在于界面组件。JupyterLab 是新一代交互界面Notebook 则是经典界面。学习阶段可以都装上后续选一个主力。4.3 注册并验证 kernel注册内核命令如下python -m ipykernel install --user --namenlp-kernel --display-namePython 3.11 (NLP)参数含义参数作用--user将内核注册到当前用户目录避免需要管理员权限--name内核的机器名必须是唯一标识--display-name在 Notebook 界面中显示的名称可以写成有辨识度的名字执行完成后用以下命令检查jupyter kernelspec list输出中应该包含nlp-kernel并且路径在用户目录下。这说明注册成功。启动 Notebookjupyter notebook如果需要指定端口可以加上端口参数jupyter notebook --port8890浏览器打开后先不要急于建 Notebook。在入口界面右上角选择新建时kernel 列表里应该能看到Python 3.11 (NLP)这个选项。5. 安装 NLP 与关键词提取相关依赖5.1 需要安装的依赖及用途关键词提取的经典实现路径是先对文本进行分词再进行权重计算。中文场景中jieba是最常用的分词库英文场景中nltk或spacy常用。权重计算则往往依赖scikit-learn的 TF-IDF 向量化能力或者 jieba 内置的 TF-IDF 与 TextRank 算法。以下是一组典型依赖包名用途在关键词提取中的作用jieba中文分词将文本切成词供 TF-IDF 或 TextRank 计算scikit-learn机器学习基础库自定义 TF-IDF 向量化、模型评估pandas数据处理整理文本数据、结果表格化numpy数值计算支撑 scikit-learn 和高维数组操作nltk英文文本处理英文分词、停用词过滤、词形还原jupyter交互式环境运行 Notebook 和 kernelipykernel内核桥接让 Jupyter 使用虚拟环境解释器如果后续要做更复杂的关键词提取可能还会用到gensim主题模型、transformersBERT 文本表示等。这些依赖建议在需要时再安装避免初期环境过于臃肿。5.2 在虚拟环境中执行安装在虚拟环境激活状态下执行python -m pip install jieba scikit-learn pandas numpy nltk安装完成后验证每个包都能正常导入python -c import jieba, sklearn, pandas, numpy, nltk; print(all imports ok)如果输出all imports ok说明这些基础依赖已就绪。这里必须注意一定要在激活环境后执行否则安装的包会进入全局 Python而虚拟环境中的 Notebook 仍然找不到。安装或运行过程中jieba首次使用时会初始化词典和 IDF 文件因此第一次运行中文分词时速度可能稍慢这是正常现象。5.3 处理安装阶段最常见的问题安装阶段最常见的报错有两类一是网络超时二是二进制编译失败。网络问题通常表现为timeout或Could not find a version that satisfies the requirement。这时可以改用国内镜像源例如清华源python -m pip install jieba scikit-learn pandas numpy -i https://pypi.tuna.tsinghua.edu.cn/simple使用镜像源时要注意不要安装来源不明的第三方包尽量只用官方 PyPI 或知名镜像。二进制编译问题通常出现在numpy、scipy等需要本地编译的库上。在 Windows 上推荐使用 Python 官方安装包配合普通 pip 安装通常能获取预编译的 wheel 文件。如果遇到“Microsoft Visual C 14.0 is required”这种错误说明需要安装对应版本的 Visual C Build Tools或者使用镜像源获取预编译 wheel。注意生产服务器和 CI 环境中不建议把镜像源写死在 pip 配置里以免依赖源不可用时造成构建失败。可以在项目文档中统一记录安装命令。6. 在 Notebook 中跑通一个最小关键词提取示例6.1 第一步检查 Notebook 正在使用的解释器打开 Notebook 后先新建一个 Notebook。确认右上角 kernel 显示为Python 3.11 (NLP)或你命名的显示名称。在第一个 cell 中运行import sys print(sys.executable)如果环境配置正确输出应该是项目目录下.venv路径中的 Python 解释器例如/home/user/nlp-keyword-extraction/.venv/bin/python在 Windows 下则是类似这样的路径C:\Users\user\nlp-keyword-extraction\.venv\Scripts\python.exe这一步是整个环境配置中最关键的验证点。如果sys.executable指向的是系统全局 Python那么就算之前依赖装得再多Notebook 也无法使用。6.2 基于 jieba 的 TF-IDF 关键词提取确认解释器正确后第二个 cell 中运行关键词提取示例。这里使用 jieba 内置的 TF-IDF 算法import jieba import jieba.analyse text ( 关键词提取是从非结构化文本中快速获取核心信息的重要步骤。 在舆情分析、新闻分类、文档检索、智能客服等业务场景中 关键词提取通常位于文本预处理的后续阶段 为摘要、推荐和标签生成提供输入。 ) tags jieba.analyse.extract_tags(text, topK5, withWeightTrue) for word, weight in tags: print(f{word}\t{weight:.4f})运行结果是一组(词, 权重)对。由于 jieba 默认使用自带 IDF 词频表不同 jieba 版本的输出顺序和权重可能略有差异但只要输出的是可读词语并且没有抛ModuleNotFoundError就说明分词与权重计算流程正常。TF-IDF 的原理并不复杂TF 衡量词在文档中出现的频率IDF 衡量词在整个语料中的稀有程度。高频且稀有的词TF-IDF 得分高通常就是文档主题词。6.3 基于 jieba 的 TextRank 关键词提取TextRank 是另一种常见算法。它不再依赖外部 IDF 语料而是把词语看成图中的节点根据词共现关系迭代算出权重。运行以下代码tags jieba.analyse.textrank(text, topK5, withWeightTrue) for word, weight in tags: print(f{word}\t{weight:.4f})TextRank 与 TF-IDF 的结果会有所不同。因为 TextRank 更关注词语之间的连接关系而 TF-IDF 更关注词频和稀有度。同一段文本上这两种算法给出不同关键词是正常现象。从环境验证角度看只要两种算法都能正常运行就说明 Jupyter、jieba、kernel 三者已经处于同一套环境内。6.4 如何判断结果和环境都正常判断标准有两条sys.executable路径在.venv内。jieba能正常完成分词和关键词提取。如果只满足第一条不满足第二条说明依赖没有完全安装在当前虚拟环境。如果只满足第二条不满足第一条说明你用的是全局环境虽然碰巧能运行但不可复现。import sklearn print(sklearn.__version__)运行这个 cell如果输出一个版本号说明scikit-learn也在当前环境中可用。到这里P2 的核心目标就完成了。7. Jupyter 与虚拟环境组合的排错手册7.1 内核列表里找不到刚注册的环境现象执行python -m ipykernel install --user --namenlp-kernel后打开 Notebook内核列表里没有看到新名称。可能原因注册内核和打开 Notebook 使用了不同的终端注册时没有激活虚拟环境。浏览器页面在注册之前已经打开没有刷新。内核名称冲突被已有内核覆盖。排查路径jupyter kernelspec list如果列表里有nlp-kernel说明注册成功问题只是页面缓存。刷新浏览器后再查看。如果列表里没有用激活状态下的python重新执行注册命令。7.2 Notebook 里 import 不到已经安装的包现象终端中执行python -c import jieba正常但 Notebook cell 中import jieba报ModuleNotFoundError。可能原因Notebook 当前选择的是另一个 kernel例如python3它指向系统全局环境。Notebook 启动于虚拟环境激活之前它看到的 kernel 列表本身没有问题但当前选错。检查方式import sys print(sys.executable) print(sys.path)解决方案在 Notebook 顶部切换 kernel重新选择Python 3.11 (NLP)。切换后再看sys.executable是否在.venv内。7.3 同一个依赖在命令行和 Notebook 中版本不一致现象终端中python -m pip show numpy显示 1.24.2但 Notebook 中numpy.__version__显示 1.26.0。原因命令行和 Notebook 各自使用了不同的 Python 环境。命令行激活的是虚拟环境而 Notebook 内核不是同一个。也可能 Notebook 启动时读到了全局环境的 site-packages。解决方案先确认 Notebook 的sys.executable是否是.venv路径。如果路径正确再看python -m pip list与 Notebook 内pip的列表差异。根本办法是统一内核来源确保 Notebook 只使用注册进当前项目的 kernel。7.4 Windows 激活脚本被策略阻止现象在 PowerShell 中输入.venv\Scripts\Activate.ps1提示“禁止运行脚本”。原因Windows PowerShell 默认执行策略禁止运行脚本文件。解决方案使用当前用户级别放宽策略。Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后重新打开终端再次激活。如果不想调整系统策略可以改用 CMD.venv\Scripts\activate.bat7.5 Notebook 页面空白或端口异常现象执行jupyter notebook后浏览器打开空白页或提示 kernel 无法连接。可能原因浏览器缓存了旧页面资源。Notebook 版本过旧与当前浏览器不兼容。端口被占用。排查顺序用无痕窗口访问 Notebook 地址排除浏览器缓存问题。检查终端输出是否有明显报错日志。升级相关组件python -m pip install --upgrade notebook jupyter-client ipykernel换端口启动jupyter notebook --port8890这类问题大多数情况下与 kernel 环境的依赖无关而是前端或缓存问题。问题现象常见原因检查与处理kernel 列表没有新环境未刷新、注册失败jupyter kernelspec list刷新页面重新注册Notebook 中缺少包kernel 选错环境sys.executable切换 kernel版本不一致命令行与 Notebook 环境不同统一 kernel 来源PowerShell 激活失败执行策略限制设置RemoteSigned或使用 CMD页面空白缓存或版本问题无痕窗口升级组件换端口8. 从学习环境走向工程化8.1 用 requirements.txt 锁定依赖学习阶段环境装满依赖没关系。但一旦项目要给别人复现就要把依赖固化下来。在虚拟环境激活状态下导出python -m pip freeze requirements.txt查看文件内容确认其中记录了主要依赖的精确版本jieba0.42.1 numpy1.24.2 pandas2.0.3 scikit-learn1.3.0新环境还原python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt这里有一点需要注意pip freeze会把所有间接依赖也写进去文件可能很长。如果希望只记录顶层依赖可以手工整理一个精简版 requirements再配合测试环境来验证。8.2 在 VS Code 和 PyCharm 中使用同一套环境VS Code 打开项目目录后需要选择正确的 Python 解释器。按CtrlShiftP输入Python: Select Interpreter选择路径以.venv开头的解释器。这样 VS Code 里的 Jupyter Notebook 也会使用同一套虚拟环境。PyCharm 的做法是在Settings中选择Project Interpreter然后添加本地虚拟环境路径。如果 Notebook 是建在 PyCharm 内的还需要在 Notebook 右下角选择同一个 kernel。IDE 中出现“找不到包”的报错第一反应不是卸载重装而是先看解释器选择是否正确。8.3 从 Notebook 迁移到脚本或服务的注意事项Notebook 适合探索和验证但不适合直接放到生产环境定时运行。生产环境的执行单元应该是脚本或服务。通常做法是保留 Notebok 用于算法验证同时把稳定后的逻辑整理成 Python 模块nlp-keyword-extraction/ ├── .venv/ ├── notebooks/ │ └── keyword_demo.ipynb ├── src/ │ └── keyword_extract.py ├── data/ │ └── sample.txt └── requirements.txt脚本化的好处是便于测试、日志、监控和错误处理。Notebook 因为保留了大量中间输出在工作台上运行没问题但在无人值守的调度环境中会很难处理。一个常见思路是验证阶段用 Notebook交付阶段用脚本。8.4 可复用的环境检查清单最后给出一个可以直接拿来用的检查清单。以后不管在本地还是服务器上新建 NLP 项目按这个顺序检查序号检查项命令或操作1Python 版本python --version2虚拟环境存在ls -a查看到.venv3虚拟环境激活提示符显示(.venv)4python 路径正确which python指向.venv5pip 路径正确python -m pip --version6Jupyter 已安装jupyter --version7kernel 已注册jupyter kernelspec list8Notebook 解释器cell 内sys.executable指向.venv9依赖可导入import jieba, sklearn, pandas, numpy10示例可运行jieba 关键词提取输出正常这套检查清单并不局限于 jieba 项目。它适用于任何基于 Jupyter 的 Python 数据项目。只要把第 9 步替换成你项目的核心依赖就能快速迁移到其他场景。P2 这条主线的核心判断是虚拟环境解决依赖隔离Jupyter kernel 解决解释器绑定二者合起来才是一套可复现的 NLP 开发环境。后续如果要继续深入关键词提取可以按两条路走下去一条是文本预处理方向包括分词、停用词过滤、词形还原另一条是算法方向包括如何训练自己的 TF-IDF 模型、如何用 TextRank 增强关键词覆盖、以及如何用预训练模型生成关键词。但无论哪条路先保证环境是干净且可控的会比学习算法本身更加重要。