ValueError: not find model file path /ragflow/rag/res/deepdoc/det.onnx

快速结论：这个报错发生在 RAGFlow 首次启动时 OCR 模块初始化阶段，核心原因是系统在 /ragflow/rag/res/deepdoc/ 目录下找不到 det.onnx 等内置 ONNX 模型文件。优先检查模型文件是否完整，以及启动时能否正常从 HuggingFace 下载缺失的模型。

适用环境：RAGFlow Docker 部署环境（ragflow-be 容器），Python 3.10（容器内 /ragflow/.venv），未检测到 GPU（日志显示 found 0 gpus）。

最快修复方案：暂无确认的一步修复方案。Issue 回复明确指出这是 RAGFlow 的设计硬性要求，需要确保 det.onnx、rec.onnx 等模型文件存在于 /ragflow/rag/res/deepdoc/ 目录中；若自动下载失败，需手动放置文件后重启服务。

注意事项：该问题并非 bug，而是功能依赖要求。自动下载依赖 HuggingFace 网络访问，在中国大陆网络环境下可能失败，需要提前准备离线模型文件。

问题场景

用户在 RAGFlow 首次启动时，通过 docker logs -f ragflow-be 查看后端日志，发现 OCR 相关的内置模型加载失败。用户已确认 /ragflow/rag/res/deepdoc/ 目录下存在 det.onnx 等文件，但系统运行时报错找不到文件，导致 ragflow_server 启动中断。

报错原文

Traceback (most recent call last):
  File "/ragflow/deepdoc/vision/ocr.py", line 539, in __init__
    self.text_detector = [TextDetector(model_dir, 0)]
  File "/ragflow/deepdoc/vision/ocr.py", line 424, in __init__
    self.predictor, self.run_options = load_model(model_dir, 'det', device_id)
  File "/ragflow/deepdoc/vision/ocr.py", line 81, in load_model
    raise ValueError("not find model file path {}".format(
ValueError: not find model file path /ragflow/rag/res/deepdoc/det.onnx

原因分析

可能原因：RAGFlow 设计上要求 det.onnx、rec.onnx 等模型文件必须存在于 rag/res/deepdoc 目录。若缺失，系统会尝试从 HuggingFace 自动下载（日志中可见 Fetching 10 files 的下载过程）。以下情况会导致加载失败：

模型文件未下载完成或下载后未正确落盘到指定目录。
网络受限导致 HuggingFace 下载失败或超时。
容器挂载卷路径与实际访问路径不一致（日志显示容器内路径为 /ragflow/rag/res/deepdoc，但实际模型文件所在目录可能因挂载卷映射不同而错位）。
Issue 正文中用户列出文件时使用了 root@ee0a5c06f350:/ragflow/rag/res/deepdoc# ls，该容器 ID 与后续 docker logs 显示的主机名 ee0a5c06f350 不一致，提示可能存在多个容器实例，模型文件可能放在了错误的容器或数据卷中。

环境排查

确认容器内 /ragflow/rag/res/deepdoc/ 目录下是否存在 det.onnx 和 rec.onnx 文件，并检查文件大小是否大于 0。
确认 Docker 挂载卷映射是否正确，确保宿主机上的模型文件能同步到容器内的正确路径。
检查容器网络能否访问 HuggingFace（日志中出现 Fetching 10 files 说明下载流程已触发，需确认是否完整下载）。
日志显示 found 0 gpus，需确认是否真的未配置 GPU，以及是否影响 OCR 初始化流程。
检查是否存在多个 ragflow-be 容器实例（对比日志中的主机名与目录列表所在容器 ID）。

解决步骤

进入 ragflow-be 容器，手动确认模型文件是否完整：docker exec -it ragflow-be ls -lh /ragflow/rag/res/deepdoc/，检查 det.onnx 与 rec.onnx 是否存在且非空。
若文件缺失，可优先尝试手动从 HuggingFace 或其他镜像源下载 det.onnx 和 rec.onnx，放入容器内 /ragflow/rag/res/deepdoc/ 目录。
若存在 Docker 卷挂载，确认宿主机对应目录是否已放置模型文件，然后重启 ragflow-be 容器：docker restart ragflow-be。
检查日志中的设备检测部分（found 0 gpus），确认 OCR 初始化是否有设备可用；若 CPU-only 环境下报“设备数量必须 ≥ 1”的错误，需要确认 RAGFlow 版本是否支持纯 CPU 模式。
若自动下载失败且网络受限，可考虑配置 HuggingFace 镜像源（如 hf-mirror.com）后重新启动服务触发下载。
确认所有相关容器使用同一数据卷，避免多个实例指向不同路径。

验证方法

重新查看 docker logs -f ragflow-be，观察是否还出现 ValueError: not find model file path 或 Number of devices must be >= 1 错误；正常启动时会看到 init database on cluster mode successfully 和 RAGFlow server 启动成功的日志，且不再出现 Traceback。