LiteLLM 批量补全 API 详解：batch_completion 与多模型并发请求的实现原理-平芜编程栈

LiteLLM 批量补全 API 详解：batch_completion 与多模型并发请求的实现原理

【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm

本文围绕 LiteLLM Python SDK 的批量补全（batch completion）能力展开，完整覆盖litellm.batch_completion、litellm.batch_completion_models、litellm.batch_completion_models_all_responses三个入口的用法、参数默认值与源码级执行流程。读完后你能够：对单模型批量消息做并发补全、在多个模型之间做“首个响应即返回”的竞速、并发收集所有可用模型的响应，并理解其背后的线程池调度与错误处理机制。

三个批量 API 的定位与分工

LiteLLM 的批量补全模块位于 litellm/batch_completion/main.py，官方说明见 litellm/batch_completion/Readme.md。三个函数解决的是三类不同场景：

API	请求方向	返回策略
`litellm.batch_completion`	一个模型 + N 条消息	返回 N 个结果（含异常对象）
`litellm.batch_completion_models`	N 个模型 + 同一请求	第一个返回的响应即返回（首个成功者胜出）
`litellm.batch_completion_models_all_responses`	N 个模型 + 同一请求	收集并返回所有成功模型的响应列表

三者都通过litellm/completion逐请求调用底层实现，因此完整继承 LiteLLM 对 100+ LLM 提供商的 OpenAI 格式兼容能力。模块通过from .batch_completion.main import *在 litellm/init.py 中导出，因此可直接以litellm.batch_completion形式调用。

batch_completion：单模型批量消息补全

参数与默认值

batch_completion的签名（见 litellm/batch_completion/main.py）在标准 OpenAI 补全参数之外增加两个批量控制参数：

参数	类型	默认值	说明
`model`	str	必填	模型名，支持`provider/model`前缀格式
`messages`	list	`[]`	消息列表，每个元素本身是一组对话消息（批量语义）
`timeout`	int \| None	`600`	单次补全请求超时（秒）
`max_workers`	int \| None	`100`	线程池最大并发数
`temperature`、`top_p`、`n`、`stream`、`stop`、`max_tokens`、`presence_penalty`、`frequency_penalty`、`logit_bias`、`user`、`functions`、`function_call`、`deployment_id`、`request_timeout`	可选	与`litellm.completion`一致的透传参数
`**kwargs`	dict	无	其余 LiteLLM 参数透传给`completion`

注意messages的语义与单次completion不同：这里传入的是消息列表的列表，即每个元素都是一条完整的对话（一组role/content消息），每个元素会被单独提交为一个补全请求。

调用示例

vLLM 原生路径的用法在 litellm/llms/vllm/completion/handler.py 的文档字符串中给出了完整示例：

import litellm responses = litellm.batch_completion( model="vllm/facebook/opt-125m", messages=[ [{"role": "user", "content": "good morning? "}], [{"role": "user", "content": "what's the time? "}], ] )

任意提供商的通用用法同理，把model换成如"openai/gpt-4o-mini"即可，结果列表与输入消息顺序一一对应。

执行流程：vLLM 原生批量 vs 通用线程池

从源码实现看（litellm/batch_completion/main.py），函数分两条路径：

路径一：vLLM 原生批量。若模型前缀在litellm.provider_list中且为vllm，则通过get_optional_params组装SamplingParams后调用 vllm_handler.batch_completions。该函数会把每条消息经prompt_factory（或已注册的自定义 prompt 模板，即litellm.custom_prompt_dict）渲染为 prompt，然后一次性交给 vLLM 的llm.generate(prompts, sampling_params)执行——这是真正在推理引擎内部完成的批量调度，而非多线程模拟。

路径二：通用线程池。对其它所有模型，函数把batch_messages按每 100 条分批（内部chunks辅助函数），在ThreadPoolExecutor(max_workers=max_workers)中为每条消息提交一个litellm.completion调用。提交时会拷贝全部参数并替换messages字段，**kwargs会被单独弹出后展开合并，保证额外参数同样透传。

错误处理策略值得注意：结果收集阶段不抛出异常，而是把future.result()产生的异常对象原样追加进结果列表（源码）。也就是说返回值是“补全结果 + 异常对象”的混合列表，调用方需要自行检查每个元素的类型，以区分成功结果与失败请求。

batch_completion_models：多模型竞速，首个响应即返回

batch_completion_models（源码）向多个模型并发发送同一请求，第一个返回的响应即作为结果返回，适合“只要有一个模型成功就够”的高可用场景。它接受两种参数形式：

形式一：`models`模型名列表

response = litellm.batch_completion_models( models=["gpt-4o", "claude-sonnet-4", "llama-3.1-70b-instruct"], messages=[{"role": "user", "content": "hello"}], )

实现上以max_workers=len(models)创建线程池，为每个模型提交一个litellm.completion调用，随后按models列表顺序取第一个非None的结果返回；全部无响应时返回None。

形式二：`deployments`部署字典列表

response = litellm.batch_completion_models( deployments=[ {"model": "gpt-4o", "api_base": "https://a.example.com/v1"}, {"model": "gpt-4o", "api_base": "https://b.example.com/v1"}, ], messages=[{"role": "user", "content": "hello"}], )

这条路径使用concurrent.futures.wait(..., return_when=FIRST_COMPLETED)循环等待首个完成的 future，并有更强的容错：

部署参数合并规则：外部 kwargs 不会覆盖部署字典中已有的键（如model、api_base），从源码注释看，这正是为了避免调用方参数污染各部署的差异化配置（源码）；
若首个完成的请求抛异常，函数会把它从 futures 中剔除并继续等待下一个模型（“model 1 失败则尝试 model 2、model 3”的注释逻辑，源码）；
所有模型都失败后返回None。

与代理部署列表（model_list）的联动

这条路径并非孤立的 SDK 功能。从 litellm/main.py 的结构看，当completion()接收到model_list参数（典型场景是 Proxy 端把一个模型组映射到多个部署）时，会提取匹配model_name的所有litellm_params作为deployments，自动转调batch_completion_models——即“同一模型组内多部署竞速”在 SDK 层面就复用了同一套实现。

batch_completion_models_all_responses：收集所有模型的响应

batch_completion_models_all_responses（源码）是竞速模式的对偶：向所有模型并发发请求，收集全部成功响应后以列表返回。适合模型对比、A/B 评测等需要“全都要”的场景。

responses = litellm.batch_completion_models_all_responses( models=["gpt-4o", "claude-sonnet-4"], messages=[{"role": "user", "content": "Write a haiku about LLMs."}], ) for r in responses: print(r.model, r.choices[0].message.content)

其行为边界在源码中定义得很明确：

models为必填：kwargs中不存在models时直接抛Exception("'models' param not in kwargs")；models必须是字符串或字符串列表，否则抛TypeError；空列表直接返回[]；
全部先提交、后等待：先为每个模型提交 future，再统一取结果。回归测试 tests/test_litellm/test_batch_completion_models_all_responses.py 用记录型线程池显式断言“等待结果前所有模型调用都已提交”，防止实现退化回“串行逐个提交”；
单模型失败不阻断：失败的模型只记录 verbose 日志并跳过，测试用例test_batch_completion_models_all_responses_continues_on_model_error验证了“一个模型抛RuntimeError时其余模型响应仍完整返回”（测试）。

选型建议与实现要点小结

结合三个函数的返回语义，选型可以归纳为：

批量数据处理（同一模型、大量 prompt）：用batch_completion。若底层是本地 vLLM 服务，会走引擎原生批量，效率显著优于线程池模拟；其它提供商则由max_workers（默认 100）控制并发度，注意同时评估提供商侧的限流。
高可用竞速（多模型/多部署抢跑）：用batch_completion_models。全部模型无响应时返回None，调用方必须处理该分支。
模型对比评测：用batch_completion_models_all_responses，返回顺序与models输入顺序一致（按 futures 顺序收集），但响应本身不携带模型名之外的排序标记，需要时用response.model字段区分。

几个从源码可以确认的实现细节，供集成时参考：

三个函数均为同步阻塞 API，底层统一使用concurrent.futures.ThreadPoolExecutor并发；
batch_completion的默认timeout=600秒，远大于普通单请求场景，批量任务等待时间应据此规划；
不要将本文的 SDK 批量函数与 Proxy 侧的异步批量方法混淆——后者（如 litellm/router.py 中的abatch_completion、abatch_completion_fastest_response）是 Proxy/Router 层的另一套实现，面向代理服务的批量路由场景。

LiteLLM 批量补全 API 详解：batch_completion 与多模型并发请求的实现原理