企业官网建设流程全解析

Hyper-Extract 安装失败？5 个最常见问题的排查清单

【免费下载链接】Hyper-ExtractHypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.项目地址: https://gitcode.com/GitHub_Trending/hy/Hyper-Extract

Hyper-Extract 是一款基于 LLM 的结构化知识抽取工具，能一条命令把非结构化文档变成图谱、超图与时空知识。如果你执行pip install hyperextract或he --version时遇到 "no matching distribution found"、"command not found" 这类报错，别慌——按下面这份清单逐项排查，5 分钟内定位原因。

安装前自检：先确认 Python 版本与验证命令

Hyper-Extract 在 pyproject.toml 中明确声明了Python 3.11+的硬性要求，这是 80% 安装失败的根源。先运行：

python --version # 需要 ≥ 3.11

安装完成后，验证命令也请提前记住：

he --version # 期望输出：Hyper-Extract CLI version 0.4.0 he config show # 查看当前 LLM / Embedder 配置

这两条命令能跑通，就说明安装与配置都成功了。

问题一：pip 报 "no matching distribution"，Python 版本低于 3.11

典型症状

ERROR: Could not find a version that satisfies the requirement hyperextract

原因：当前 Python 是 3.10 或更低版本，包索引中不存在兼容版本。

解决方法：升级到 Python 3.11+（可用 pyenv、conda 或系统包管理器），再重新执行安装。建议为项目创建独立虚拟环境，避免污染全局 Python。

问题二：faiss-cpu / langchain 依赖下载失败

典型症状：安装卡在某个依赖上，报Read timed out或Could not download。

原因：Hyper-Extract 依赖faiss-cpu、langchain、ontosight等十几个包，网络不佳时任意一个下载失败都会导致整体中断。

解决方法：

1. 切换国内镜像源后重装：

pip install hyperextract -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 仍失败可先装 uv 再安装，uv 的并发下载和缓存机制更稳定：

uv tool install hyperextract

问题三：装上了但 he 命令找不到（command not found）

典型症状：pip install显示成功，输入he却报command not found。

原因：脚本目录不在 PATH 中，或者你误用了全局 pip 安装。

解决方法（推荐隔离安装，自动处理 PATH）：

uv tool install hyperextract # 推荐 # 或 pipx install hyperextract

安装后重开一个终端再试he --version。若仍无效，检查终端环境变量中是否包含~/.local/bin（pipx/uv 的安装目录）。

问题四：he parse 报 "API key not found"，密钥未配置

典型症状：命令能跑，但提取时报 API 密钥缺失或认证失败。

原因：Hyper-Extract 依赖 LLM 与 Embedder 两个服务，首次使用必须完成一次配置，配置会持久化到~/.he/config.toml（Windows 为%USERPROFILE%\.he\config.toml）。

解决方法：按所用平台执行对应命令，之后运行he config show核对：

# OpenAI he config init -p openai -k YOUR_OPENAI_API_KEY # 阿里云百炼（国内用户常用） he config init -p bailian -k YOUR_BAILIAN_API_KEY # DeepSeek / Anthropic 仅提供 LLM，需再配一个嵌入器 he config llm -p deepseek -k YOUR_DEEPSEEK_API_KEY he config embedder -p openai -k YOUR_OPENAI_API_KEY

完整参数说明可参考文档docs/zh/cli/configuration.md，支持 OpenAI、百炼、DeepSeek、Anthropic 与本地 vLLM 五种接入方式。

问题五：模型不支持 json_schema，抽取不返回 JSON

典型症状：控制台出现messages must contain the word 'json'，或结果中 JSON 解析失败。

原因：Hyper-Extract 使用结构化输出（json_schema）约束模型，百炼平台的qwen-max和deepseek-v3只支持json_object，会出现此问题。

解决方法：换用已验证支持的模型即可：

he config llm -p bailian -k YOUR_API_KEY -m qwen-plus # 可选：qwen-turbo、qwen3.6-plus、deepseek-r1

各平台已验证的模型兼容列表见docs/zh/concepts/provider-system.md。

安装验证成功：跑一次 he show 看知识图谱

全部排查通过后，用最小任务做一次端到端验证：

he parse 示例文档.md -t general/base_graph -o ./kb/ -l zh he show ./kb/

如果能弹出交互式图谱界面，说明 LLM、Embedder、CLI 三条链路全部打通。

排查清单小结

对照表格从上到下过一遍，绝大多数"安装失败"都能迎刃而解。遇到清单之外的报错，可运行he <命令> --help查看参数详情，或在项目仓库提交 issue 反馈。🚀

【免费下载链接】Hyper-ExtractHypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.项目地址: https://gitcode.com/GitHub_Trending/hy/Hyper-Extract