Kev 本地部署卡在依赖环节，通常不是代码本身有 bug，而是运行环境里的 Python 版本、依赖包集合或系统库与项目要求对不上。进程起不来、报模块缺失时，先别急着重装系统或改源码，按报错类型分流，再逐项核对环境要求，能更快判断卡点在哪一层。

本地部署 Kev 报错时，多数依赖问题可以归为缺模块、版本不兼容和编译失败三类。建议先看完整 traceback 的关键行，再对照安装说明核对 Python、包管理器和系统库，用虚拟环境复现最小安装。修复后重新执行启动命令，以进程是否退出、日志是否出现监听或运行标记作为验证。如果本地无法定位，把操作系统、Python 版本、依赖清单和完整报错一起整理出来，不要只贴一句 ModuleNotFoundError。

从报错日志里区分缺模块、版本不兼容和编译失败

先把终端里的报错完整读一遍，重点看 traceback 最后几行和 pip 输出的前几行。三类问题的处理顺序完全不同：缺模块先补包，版本冲突先看约束，编译失败先查系统库。

缺模块的典型日志长这样：

ModuleNotFoundError: No module named 'xxx'
ImportError: cannot import name 'yyy' from 'zzz'

看到 ModuleNotFoundError，先确认这个模块属于哪个 pip 包，再用 pip show 查它是否装在了当前解释器下。ImportError 里带 cannot import name，往往不是完全没装，而是装了但版本里没有这个符号，先查该包的版本范围。

版本冲突通常出现在 pip 安装阶段：

ERROR: Cannot install A and B because these package versions have conflicting dependencies.
The conflict is caused by:
    A 某版本 depends on C>=某范围
    B 某版本 depends on C<某版本

这类报错先看“谁依赖谁”的链条，再决定是固定某个包的版本，还是换一个兼容的 Python 版本。不要盲目 `--force-reinstall`，那样可能把冲突推到运行期。

编译失败会涉及 C 扩展或系统头文件：

fatal error: Python.h: No such file or directory
error: command 'gcc' failed with exit status 1
Could not build wheels for xxx, which is required to install pyproject.toml-based projects

先查是否缺 python3-dev / python3-devel、gcc、make 这类基础构建工具，再确认系统里有没有对应的开发库。编译失败和缺模块不同，装再多 Python 包也不一定解决。

核对运行环境：Python、包管理器和系统库的最低要求

打开 Kev 仓库的 README 或安装文档，找到 Requirements、Prerequisites 或 Installation 一类段落，把里面写的最低版本和系统依赖逐条抄到一张清单里。不要凭印象跳过这一步，文档里写 Python 版本范围、CUDA 版本、系统包名，往往就是卡住的原因。

抄完之后逐项核对。下面这些命令是通用的，把输出和文档要求对一下：

python `--version`
python3 `--version`
pip `--version`
pip list
which python
which pip

检查清单可以按这个顺序打勾：

• 当前 shell 用的 python 是哪个路径，是否和安装文档建议的一致。
• Python 版本是否落在文档声明的范围内，太新或太旧都可能让依赖装不上。
• pip 版本是否能正常解析依赖，过旧的 pip 对新的包元数据支持不好。
• 系统库：文档里提到的 libxxx、ffmpeg、gcc、python3-dev 之类是否已经安装。
• 如果涉及 GPU，驱动和 CUDA 运行时是否与文档要求匹配，不要只看 nvidia-smi 的驱动版本。

这一节的结论不靠猜：某项输出和文档要求对不上，就先处理那一项，再回到安装步骤。

用虚拟环境隔离依赖，复现最小安装流程

全局环境里已经装过很多包时，依赖冲突很难判断是 Kev 引入的还是旧包造成的。建议在项目目录下建一个干净虚拟环境，把安装步骤重新走一遍，保证每一步都可重复。

cd /path/to/kev
python3 -m venv .venv
source .venv/bin/activate
python -m pip install `--upgrade` pip
pip install -r requirements.txt

Windows 下激活命令换成 .venv\Scripts\activate 即可，其余步骤一致。安装过程中把完整输出重定向到文件，方便回看：

pip install -r requirements.txt 2>&1 | tee install.log

装完后不要只看“Successfully installed”，再运行一次启动命令，观察报错有没有变化。如果从“No module named xxx”变成版本冲突或编译错误，说明前一类问题已经排掉，可以顺着新报错继续查。验证方式就是同一套命令在虚拟环境里能稳定复现同一个结果。

启动 Kev 并确认进程没有因依赖缺失退出

依赖装好后，用文档给出的启动方式跑一次。下面是一个通用骨架，把占位路径换成实际值：

python -m kev.server `--model-path` /path/to/model `--config` /path/to/config.yaml

如果项目提供的是脚本，也可以：

bash scripts/run_server.sh `--model-path` /path/to/model

启动后分两步确认。第一步看进程还在不在：

ps -ef | grep kev
pgrep -af kev

如果进程几秒内就退出，说明还有依赖在导入阶段就失败了，回到上一步看日志。第二步看日志有没有到“开始服务”的位置。不同项目输出不一样，通常会出现监听地址、端口、模型加载完成或脚本开始运行这类标记。可以新开一个终端跟踪：

tail -f /path/to/kev.log

日志停在某个 import 行不动，或者出现 Traceback 后进程结束，都算没通过。只有进程持续存在、日志出现监听或运行标记，才说明依赖环节没有把启动拦住。

把环境信息整理成可提交的最小问题报告

如果按上面几步还是卡住，先别急着贴一句报错就问。把下面这些信息收集齐，别人才能判断是环境问题还是项目本身的依赖声明有问题：

• 操作系统和发行版，例如 Ubuntu 22.04、macOS 14、Windows 11。
• CPU 架构，例如 x86_64 或 arm64。
• Python 版本和解释器路径：python `--version`、which python。
• pip 版本，以及 pip list 或 pip freeze 的完整输出。
• 是否使用虚拟环境，虚拟环境创建命令和安装命令。
• 完整报错，包括 traceback 和 pip 的冲突解析输出，不要只截最后一行。
• 复现命令，也就是你执行的那一行启动或安装命令。
• 如果改过 requirements.txt 或锁文件，说明改了什么、为什么改。

整理成一份文本，按“环境、命令、报错、已尝试”四段放。这样即使问题不在本地环境，也能让别人快速排除掉明显的版本不匹配。