本地部署 humanize-chinese 要装什么——跑不起来是缺依赖还是环境版本不对？

本地部署 humanize-chinese 跑不起来，先别急着把问题归为缺依赖或环境版本不对。更稳的顺序是：先对照仓库 README 和依赖文件确认语言版本、依赖清单与额外资源，再用干净虚拟环境装一次，然后跑一段最小中文样例；失败时按终端里最先出现的报错关键词查缺模块、路径、编码、版本或资源缺失。README 没写明的部分，需要结合你的系统自行确认。

判断方向：先以仓库 README 和依赖文件为准，确认语言版本、依赖清单、是否要模型或词典等资源。适用场景是本地首次部署；操作动作是建虚拟环境、按依赖文件安装、跑最小中文样例；验证方式是看导入是否成功、输出文件是否生成；风险边界是不要用全局环境反复混装，也不要把模型文件缺失误判成代码问题。

对照仓库说明确认运行环境与依赖清单

先把运行环境和依赖清单分开看。humanize-chinese 若是 Python 项目，README 通常会写 Python 版本、是否要 GPU、是否要额外下载模型；如果只写了安装命令，没写版本，就把 requirements.txt、pyproject.toml、setup.py、environment.yml 中出现的包和版本约束当作依赖清单。仓库没有这些文件，或 README 对版本只写最新版，这部分需要自行确认。

语言版本：优先看 README 声明的 Python 或 Node 版本，其次看 pyproject.toml 的 requires-python、package.json 的 engines。
依赖清单：requirements.txt、pyproject.toml、setup.py、environment.yml、package.json 至少看一遍。
额外资源：模型权重、tokenizer、词典、规则表，README 若提到，单独记一列。

python3 `--version`
python3 -m pip `--version`
cat README.md
cat requirements.txt
cat pyproject.toml
cat environment.yml
cat package.json

把这三类信息打勾后再装。缺任何一项，后面跑不起来时都很难判断是依赖问题还是环境版本问题。

克隆仓库并按说明装依赖

建议用虚拟环境装，避免和系统 Python 混在一起。下面只是命令骨架，仓库地址、环境名和安装入口按 README 替换。如果 README 指定 conda 或 npm，就以 README 为准。

git clone <仓库地址> humanize-chinese
cd humanize-chinese
python3 -m venv .venv
source .venv/bin/activate
# Windows 激活可用 .venv/Scripts/activate
python -m pip install `--upgrade` pip
pip install -r requirements.txt
# 如果仓库用 pyproject.toml
pip install -e .
# 如果还有前端目录
npm install

安装时终端里如果出现下面这类原文，先原样保留，不要只看最后一行。它们是判断依赖和环境版本的主要线索：

ERROR: Could not find a version that satisfies the requirement ...
ERROR: Package 'xxx' requires a different Python: 3.8.10 not in '>=3.9'
WARNING: You are using pip version ...; however, version ... is available.
ModuleNotFoundError: No module named '...'

出现依赖解析冲突时，不要急着把每个包单独升级到最新。先确认虚拟环境是否激活，再看 README 有没有指定依赖安装方式。

用一段最小中文样例跑通一次转换

安装完成不等于能运行。找一段短中文样例，确认输入、输出和输出目录。输入可以是一句话：

本系统旨在通过自动化手段提升文本处理效率。

把它存成 sample.txt，然后按仓库入口执行。入口可能是模块、脚本或命令行工具，下面只是常见骨架：

python -m humanize_chinese `--input` sample.txt `--output` output/result.txt
# 或者
python run.py `--input` sample.txt `--output` output/result.txt

预期输出形式通常是改写后的中文文本，也可能是 JSON 或写回文件。实际输出以你终端打印和生成文件为准，本页不虚构一份输出文本。输出文件通常落在 output/、outputs/、result/ 或 README 指定目录；用下面命令确认：

cat output/result.txt
find . -maxdepth 3 -type f -newer sample.txt

如果命令成功但输出和输入一模一样，先检查是否漏了模型路径、规则开关或输入文件参数，不要直接判断为依赖问题。

跑不起来时按报错分别查依赖、路径与编码

不要逐条试错，按终端里最先出现的报错关键词分流。每次只改一个变量，记录改动前后的命令和输出。

缺模块：ModuleNotFoundError 或 ImportError

通常是依赖没装进当前解释器，或虚拟环境没激活。验证：

本地部署 humanize-chinese 要装什么——跑不起来是缺依赖还是环境版本不对？

which python
python -c 'import sys; print(sys.executable)'
python -c 'import 缺失模块名'
python -m pip show 包名
python -m pip check

如果 which python 指向系统 Python，而安装时用的是虚拟环境，重新激活虚拟环境再装。不要直接复制一堆 pip install，先看 requirements.txt 里缺失的是哪个包。

找不到文件：FileNotFoundError 或 No such file or directory

先确认工作目录和文件真实存在：

pwd
ls -la
find . -maxdepth 4 -name '模型文件名或配置文件名'

重点看相对路径。很多项目默认从仓库根目录读取 config 或 models，你在其他目录执行就会找不到。

编码报错：UnicodeDecodeError、UnicodeEncodeError 或 gbk codec

这更像文件编码或终端编码问题，不一定是代码问题。检查：

file -i 输入文件
export PYTHONUTF8=1
export PYTHONIOENCODING=utf-8

Windows 下可用 set PYTHONUTF8=1。不要直接改全局编码，先确认输入文件本身是不是 UTF-8。

版本不兼容：SyntaxError、TypeError、AttributeError 或依赖解析冲突

验证：

python `--version`
python -m pip list
python -m pip check
grep -n 'requires-python' pyproject.toml

README 写明 Python 3.10+，而你用 3.8，优先换虚拟环境，而不是改代码。依赖冲突明显时，也可以新建一个干净环境重装。

确认是否还需要额外的资源文件才能完整运行

humanize-chinese 如果依赖模型权重、tokenizer、词典或规则表，单装 Python 包通常不够。README 若提到需要下载模型或把资源放到指定目录，先按说明确认本地是否已具备。没有提到，就先按纯规则或纯依赖运行最小样例，再观察是否报资源加载错误。

检查方式：

ls -lah models/ 2>/dev/null
find . -maxdepth 4 -type f -name '*.bin'
find . -maxdepth 4 -type f -name '*.safetensors'
find . -maxdepth 4 -type f -name '*.gguf'
find . -maxdepth 4 -type f -name '*.txt'
du -sh models/ 2>/dev/null

再核对配置里的 model_path、model_name_or_path、dict_path、rules_path 指向哪里。文件是 0 字节、目录为空、路径只写到上一级，都算资源未就绪。离线环境需要提前准备模型文件；如果只是规则改写，可能不需要大模型，这一点以仓库 README 为准。把资源缺失和代码问题分开记录，能少走很多弯路。