Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
故障排除
常见问题的解决方案。
安装问题
pip 安装失败
问题:安装时出现错误
解决方案:
- 升级 pip:
pip install --upgrade pip - 使用 Python 3.11+:
python --version - 在虚拟环境中安装:
python -m venv venv source venv/bin/activate pip install hyperextract
ImportError: No module named 'hyperextract'
问题:安装后无法导入
解决方案:
- 检查 Python 版本:
python --version(需要 3.11+) - 验证安装:
pip list | grep hyper - 检查虚拟环境是否已激活
- 重新安装:
pip install --force-reinstall hyperextract
配置问题
API 密钥未找到
错误:No API key configured
解决方案:
CLI 配置(推荐):
# OpenAI / 百炼(一步到位) he config init -p openai -k YOUR_API_KEY # Anthropic / DeepSeek(LLM + 独立嵌入器) he config llm -p deepseek -k YOUR_DEEPSEEK_API_KEY he config embedder -p openai -k YOUR_OPENAI_API_KEY环境变量:
export OPENAI_API_KEY=your-api-key export ANTHROPIC_API_KEY=your-api-key # 用于 Anthropic export DEEPSEEK_API_KEY=your-api-key # 用于 DeepSeek验证配置:
he config show
API 密钥无效
错误:Authentication failed
解决方案:
- 验证密钥是否正确
- 检查是否有额外的空格
- Anthropic:确保使用
ANTHROPIC_API_KEY(而非OPENAI_API_KEY) - DeepSeek:确保使用
DEEPSEEK_API_KEY(而非OPENAI_API_KEY) - 检查密钥是否有可用额度/配额
运行问题
模板未找到
错误:Template 'xxx' not found
解决方案:
列出可用模板:
he list template检查拼写:
# 正确 he parse doc.md -t general/biography_graph # 错误 he parse doc.md -t general/biography使用 Python 搜索:
from hyperextract import Template templates = Template.list(filter_by_query="bio")
需要指定语言
错误:--lang is required
解决方案:
# 添加语言参数
he parse doc.md -t general/biography_graph -o ./out/ -l zh
注意:方法模板不需要语言参数。
输出目录已存在
错误:Output directory already exists
解决方案:
强制覆盖:
he parse doc.md -t general/graph -o ./out/ -l zh -f使用不同目录:
he parse doc.md -t general/graph -o ./out2/ -l zh删除现有目录:
rm -rf ./out/ he parse doc.md -t general/graph -o ./out/ -l zh
索引和搜索问题
索引未找到
错误:Search index not built
解决方案:
he build-index ./output/
搜索返回空结果
问题:he search 找不到结果
解决方案:
验证索引是否存在:
he info ./output/ # 应该显示:Index: Built尝试不同的查询:
he search ./output/ "不同的关键词"增加 top_k:
he search ./output/ "查询" -n 10检查数据是否存在:
he info ./output/ # 应该显示 Nodes > 0
对话失败
错误:Chat failed: index not found
解决方案:
he build-index ./output/
he talk ./output/ -q "你的问题"
性能问题
提取速度非常慢
问题:处理时间过长
解决方案:
批量处理时跳过索引:
he parse doc.md -t general/graph -o ./out/ -l zh --no-index减少分块大小(Python):
ka = Template.create("general/graph", "zh") ka.chunk_size = 1024 # 默认:2048减少工作线程(如果达到速率限制):
ka = Template.create("general/graph", "zh") ka.max_workers = 5 # 默认:10
内存不足
问题:进程被终止或出现内存错误
解决方案:
处理更小的分块:
for chunk in split_document(text, chunk_size=1000): result.feed_text(chunk)保存中间结果:
for i, doc in enumerate(documents): result.feed_text(doc) if i % 5 == 0: result.dump(f"./checkpoint_{i}/")中间步骤不构建索引:
# 只在最后构建 result.build_index()
数据问题
没有提取到实体
问题:结果为空
解决方案:
检查输入文本:
wc -l document.md # 检查是否为空尝试不同的模板:
he parse doc.md -t general/model -l zh检查语言:
# 错误的语言 he parse chinese_doc.md -t general/graph -l en # 正确 he parse chinese_doc.md -t general/graph -l zh
知识库损坏
问题:无法加载或读取错误
解决方案:
检查文件结构:
ls ./ka/ # 应该有:data.json, metadata.json验证 JSON:
python -c "import json; json.load(open('./ka/data.json'))"重新提取:
rm -rf ./ka/ he parse doc.md -t general/graph -o ./ka/ -l zh
仍有问题?
- 检查日志 — 查看详细的错误信息
- 更新到最新版本 —
pip install --upgrade hyperextract - 查看 GitHub Issues — github.com/yifanfeng97/hyper-extract/issues
- 创建新 issue — 包含错误消息和复现步骤
调试模式
启用详细输出:
import logging
logging.basicConfig(level=logging.DEBUG)
from hyperextract import Template
ka = Template.create("general/graph", "zh")
或在 CLI 配置中:
[defaults]
verbose = true