[Bug]: vLLM Batch/Files API returns 404 – LiteLLM attempts to call non-existent upstream /v1/files endpoint

快速结论：此报错通常发生在 LiteLLM Proxy 向 vLLM 部署转发 batch/files 请求时，因为标准 vLLM OpenAI 兼容服务器未实现 /v1/files 和 /v1/batches 端点。优先确认上游 vLLM 是否已启用专门的 batch 端点支持（如通过环境变量或启动参数），或者检查 LiteLLM 配置中是否正确指定了支持 batch 的 vLLM 路由设置。

问题场景

用户在 LiteLLM Proxy (v1.80.8 及更高版本) 中尝试使用 vLLM 的 “Batch and Files API” 功能。用户通过 POST /v1/files 请求向 LiteLLM Proxy 提交 batch 文件时，请求失败并返回 404 错误。用户使用的上游模型为 meta-llama/Llama-3.3-70B-Instruct 和 gemma4-26b 等 vLLM 部署。

报错原文

curl https://***/v1/files \
  -H "Authorization: Bearer sk-***" \
  -H "x-litellm-model: meta-llama/Llama-3.3-70B-Instruct" \
  -F purpose="batch" \
  -F file="@test-batch.jsonl"

Response:
{"error":{"message":"Error code: 404 - {'detail': 'Not Found'}","type":null,"param":null,"code":"404"}}

# LiteLLM Proxy server-side log:
09:28:37 - LiteLLM Proxy:ERROR: files_endpoints.py:413 - litellm.proxy.proxy_server.create_file(): Exception occured - Error code: 404 - {'detail': 'Not Found'}
Traceback (most recent call last):
  File "/usr/lib/python3.13/site-packages/litellm/proxy/openai_files_endpoints/files_endpoints.py", line 360, in create_file
    response = await route_create_file(
               ^^^^^^^^^^^^^^^^^^^^^^^^
  ...
  File "/usr/lib/python3.13/site-packages/litellm/llms/openai/openai.py", line 1552, in acreate_file
    response = await openai_client.files.create(**create_file_data)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/openai/_base_client.py", line 1594, in request
    raise self._make_status_error_from_response(err.response) from None
openai.NotFoundError: Error code: 404 - {'detail': 'Not Found'}

原因分析

LiteLLM Proxy 在处理 POST /v1/files 请求时，通过 route_create_file 最终调用 openai_client.files.create，将请求直接转发到上游 vLLM 服务器的 /v1/files 端点。但是，标准的 vLLM OpenAI 兼容服务器（用于在线推理）并未实现 /v1/files 和 /v1/batches 端点（参见 vLLM API 文档）。vLLM 仅通过离线推理（offline inference）或标准请求的内部连续批处理来支持 batch 处理。因此，当 LiteLLM 假设上游 vLLM 提供者支持完整 OpenAI Batch API 规范时，vLLM 返回 404 导致请求失败。

环境排查

确认 LiteLLM 版本：Issue 中报告了 v1.80.8 和 v1.92.0 均出现该问题。
确认上游 vLLM 服务器版本：Issue 中涉及 v0.20.0。
确认上游 vLLM 是否已启用 batch/files 端点支持（可能需要特定环境变量或启动参数，vLLM 社区有相关讨论）。
检查 LiteLLM 配置的 model 映射（如 model_list）是否针对 vLLM 正确设置了支持 batch 的路由参数。
确认 Python 版本为 3.13（Issue 日志显示）。
如仍失败，可参考 LiteLLM 提供的 batch 相关文档：https://docs.litellm.ai/docs/providers/vllm_batches。

解决步骤

确认上游 vLLM 是否支持 batch/files 端点：检查 vLLM 服务启动时的日志或文档，确认其是否通过环境变量（如 --enable-openai-batch-endpoint 或其他类似参数）启用了 batch 功能。标准 vLLM 在线服务器默认不支持，可能需要使用专门分支或额外配置。
检查 LiteLLM 配置：确保在 LiteLLM Proxy 的 config.yaml 中，针对 vLLM 的 model 配置正确设置了 api_base 和 model 参数。如果使用的是 custom 或 openai 路由，可能需要添加额外的 litellm_params 来指示该模型支持 batch。
升级 LiteLLM 版本（可优先尝试）：该 Issue 在 v1.92.0 中仍有报告，但后续版本可能修复了路由逻辑或增加了对上游 vLLM batch 端点的兼容性。请升级到最新版 LiteLLM 重试。
确认使用的端点：如果上游 vLLM 确实不支持，可能原因在于 LiteLLM 的 batch 功能仅适用于配备了正确后端（如自定义 batch 服务）的部署。请检查是否误用了不支持 batch 的普通 vLLM 实例。
参考相关 Issue 和讨论：查阅 Issue #17996 中描述的类似问题，关注是否有已知的配置变通方法。
查看详细日志：如果仍然失败，请查看 LiteLLM Proxy 的 debug 日志（开启 --debug），确认请求被路由到的上游 URL 具体是什么。

验证方法

使用 curl 或其他 HTTP 客户端重新发送 POST /v1/files 请求（带上相同的头部和表单数据），并观察返回的 HTTP 状态码和响应体。如果返回 200 或 201 以及正常的文件 ID 信息，则问题已解决。如果继续返回 404，则需进一步排查上游 vLLM 的批量端点可用性。

参考来源

BerriAI/litellm #18188

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: vLLM Batch/Files API returns 404 – LiteLLM attempts to call non-existent upstream /v1/files endpoint