pip install opencv-contrib-python 会卸载 opencv-python 并替换为扩展版，二者互斥；必须版本严格对齐，无gui环境应使用-headless变体，并通过 hasattr(cv2, 'sift_create') 验证功能是否可用。
pip install opencv-contrib-python 会覆盖基础包
直接运行 pip install opencv-contrib-python 不是“追加安装”，而是替换。OpenCV 的 Python 生态里，opencv-python 和 opencv-contrib-python 是互斥的两个独立包，不能共存。如果你已经装了 opencv-python，再装 opencv-contrib-python 时 pip 会自动卸载前者——但不会提示你，容易误以为“扩展成功”，结果运行 cv2.SIFT_create() 时报 AttributeError。
- 先检查是否已装基础包：
pip show opencv-python或pip list | grep opencv - 如果输出含
opencv-python，务必先卸载：pip uninstall opencv-python - 再装扩展包：
pip install opencv-contrib-python - 验证是否生效：
python -c "import cv2; print(hasattr(cv2, 'SIFT_create'))"—— 应输出True
版本必须严格对齐，否则 contrib 模块不可用
opencv-contrib-python 不是插件式加载，它和 opencv-python 的底层 C++ 库是编译绑定的。你装的 contrib 包版本号（如 4.5.5.64）必须和原 opencv-python 的完全一致，否则 cv2 导入时可能不报错，但调用 cv2.xfeatures2d.SIFT_create() 会抛 cv2.error: OpenCV(4.5.5) ... error: (-213:The function/feature is not implemented)。
调用百度文档解析API，支持18+格式，提取文本、表格、版面分析、OCR识别及RAG文档分块。适用于文档解析、文本/表格提取、结构分析、扫描件处理。触发词：文档解析、PDF解析、Word解析、表格提取、OCR、文档分析、提取文本、文档结构、扫描识别。
- 查当前安装的 OpenCV 版本：
python -c "import cv2; print(cv2.__version__)" - 装指定版本的 contrib：
pip install opencv-contrib-python==4.5.5.64（把4.5.5.64换成你实际的版本） - PyPI 上不是所有版本都有对应 contrib 包，
4.7.0.72这类新版本可能还没发布 contrib，得降级或等更新
服务器或无 GUI 环境要选 headless 变体
在 Docker、Linux 服务器、树莓派等没有图形界面的环境里，装默认的 opencv-contrib-python 可能因依赖 GTK 或 Qt 而失败，或者导入时卡住。这时候要用带 -headless 后缀的版本，它剔除了所有 GUI 相关模块（cv2.imshow 会不可用），但保留全部图像算法和 contrib 功能。
- 正确命令：
pip install opencv-contrib-python-headless - 注意：这个包也和基础版互斥，同样要先卸载
opencv-python或opencv-contrib-python - 它自带
cv2.SIFT_create、cv2.ORB_create等，且体积更小、启动更快
国内网络下安装失败的常见绕过方式
OpenCV 包体积大（常超 100MB），且 PyPI 官源在国内不稳定，容易卡在 “Collecting opencv-contrib-python” 或报 ReadTimeoutError。单纯换镜像源有时不够，因为 opencv 的 wheel 文件托管在第三方 CDN，清华源同步有延迟。
- 优先用清华源安装：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ opencv-contrib-python - 如果仍失败，加
--trusted-host：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ --trusted-host pypi.tuna.tsinghua.edu.cn opencv-contrib-python - 实在不行，去 PyPI 页面 手动下载对应平台的
.whl文件（注意匹配 Python 版本、系统架构、ABI），再本地安装：pip install xxx.whl
hasattr(cv2, 'SIFT_create') 确认，别只看 cv2.__version__。
