标签： Python

在 RAGFlow 本地构建 Docker 镜像（含 embedding 模型）时卡住，报错多为 [Question]: Build docker Image Fail ，优先排查网络连通性——尤其是使用 NEED_MIRROR=1 时镜像源（如 mirrors.aliyun.com）不可达或超时。

运行 MiniMax-M3 多模态模型进行推理时发生崩溃，报错为 CUDA illegal memory access。优先排查是否缺少对 MiniMax-M3 的模型架构支持，并尝试应用 vLLM 项目 PR #49149 中的补丁。

在 RAGFlow v0.19.0 中，使用 Presentation 等非 General 的 chunking 方法时，即使配置了 VLM 模型，解析过程仍不会调用 VLM，报错表现为“VLM 配置无效”。优先确认使用的 chunking 方法是否支持 VLM，当前仅 General 方法支持。

该报错通常出现在 vLLM 编译测试（例如 distributed-compile 的 CI 任务）中，当模型加载后可用 KV 缓存内存为负时触发。优先排查 GPU 显存是否不足，可尝试增大 --gpu-memory-utilization 参数（如 0.95），或升级 vLLM 到包含修复的版本。

此报错发生在 vLLM 启用 CPU KV offload 且使用滑动窗口注意力（Sliding Window Attention, SWA）时，由于调度器中 GPU 块边界计算错误，导致合法未对齐的滑动窗口负载被误判为超过限制，引发进程 abort。优先排查 offloading schedule