`vector_stores.files.upload_and_poll()` can hang indefinitely with file status stuck at `in_progress`

快速结论：当调用 vector_stores.files.upload_and_poll() 时，文件上传成功、挂载到 vector store 也成功，但该 SDK 调用会无限期阻塞，底层文件状态一直停在 in_progress。优先排查的是服务端向量存储文件处理/索引是否卡住，并给轮询加上超时上限，避免调用永久等待。

适用环境：openai/openai-python openai==2.31.0，Python 3.12，操作系统 macOS。Issue 未提供 CUDA、显卡或其他依赖信息。

最快修复方案：升级到包含 #3401 的 openai 版本，该 PR 为 vector-store 文件轮询加入了可选的 max_wait_seconds，用于给轮询设置上限。Issue 中未给出具体的修复版本号，因此请以实际可用的新版本为准。

注意事项：max_wait_seconds 只是把 SDK 侧的轮询限制在有限时间内，避免无限挂起；如果索引本身在服务端停滞，仍需要通过服务端进一步排查。Issue 明确说明“stalled indexing still needs service-side investigation”。

问题场景

用户使用 OpenAI Python SDK 创建 vector store，并通过 client.vector_stores.files.upload_and_poll() 上传文件。上传和挂载都成功，但该调用一直不返回。用显式轮询复现时可以看到：vector_store_file.status 永远停留在 in_progress，vector_store_file.last_error 始终是 None，而原始上传文件 raw_file.status 已经是 processed。因此问题出现在 vector store 文件的处理/索引阶段，而不是原始文件上传阶段。

报错原文

vector_stores.files.upload_and_poll() can hang indefinitely with file status stuck at `in_progress`

file upload succeeds
attaching the file to a vector store succeeds
`upload_and_poll()` never returns
polling `vector_stores.files.retrieve()` shows the file stuck at `status="in_progress"` forever
`last_error` stays `null`

原因分析

根据 Issue 中的观察，raw_file.status 已经是 processed，但 vector store 侧的文件状态一直停在 in_progress，且 last_error 为 null。这说明上传本身没有失败，挂载也没有失败，而是向量存储文件的处理/索引阶段停滞。可能原因是服务端索引流程卡住，而 SDK 的轮询逻辑在没有超时上限时会一直等待。Issue 中也明确指出，SDK 侧可以通过 max_wait_seconds 限制轮询，但停滞的索引问题仍需服务端侧调查。

环境排查

确认 openai 库版本，Issue 中确认受影响的版本为 openai==2.31.0。
确认 Python 版本，Issue 中为 Python 3.12。
确认操作系统，Issue 中观察环境为 macOS。
确认是否使用了 vector_stores.files.upload_and_poll()，或等价的显式轮询逻辑。
若已升级 SDK，确认目标版本是否包含 #3401 中新增的 max_wait_seconds 参数。

解决步骤

先复现并确认问题：使用 Issue 中提供的 MRE，或显式轮询复现代码，观察 vector_store_file.status 是否长期停留在 in_progress，同时确认 raw_file.status 已为 processed。
检查 vector_store_file.last_error。如果它始终为 null，说明没有返回明确错误，需要按索引停滞方向排查。
升级 openai Python 包到包含 #3401 的版本，该 PR 为 vector-store 文件轮询增加了可选的 max_wait_seconds。
在调用轮询逻辑时传入 max_wait_seconds，为轮询设置上限，避免 SDK 调用无限期阻塞。Issue 摘要未提供该参数的具体写法或默认值，请以升级后的官方文档和实际签名为准。
如果加上超时后仍然观察到服务端文件状态长期停留在 in_progress，说明索引停滞仍需服务端调查，不能仅靠 SDK 侧解决。
在排查期间，可保留显式轮询日志，记录 vector_store_file.status、last_error 和 raw_file.status 的变化，用于区分 SDK 等待问题和服务端索引问题。

验证方法

升级到包含 #3401 的版本后，再次运行复现脚本，确认 upload_and_poll() 不再无限期阻塞，而是会在达到 max_wait_seconds 后返回或抛出超时相关结果。同时继续检查 vector_stores.files.retrieve() 返回的 status：如果从 in_progress 变为 completed，说明索引已恢复；如果仍然长期停留在 in_progress 且 last_error 为 null，则说明服务端索引停滞问题仍然存在，需要进一步向服务端侧反馈。