TypeScript LLM调度器：防止批处理任务饿死交互式流量

这次我们来看一个特别适合 LLM 应用团队和 API 网关开发者的 TypeScript 项目。它解决的是 LLM 服务里一个非常典型的问题当后台批处理任务持续占用模型推理资源时前台的交互式请求会被拖到超时甚至直接被饿死。项目标题写得很直白Keep batch LLM jobs from starving interactive traffic也就是“别让批处理 LLM 任务把交互式流量饿死”。先说核心特点。这个项目不是一个大模型也不是一个完整的 LLM 推理框架而是一个调度层/队列中间件。它用 TypeScript 编写主要面向 Node.js 或 Bun 这类 JS 运行时环境。它提供的核心能力是将 LLM 请求划分为交互式和批处理两类通过优先级队列、速率限制、动态阻塞和背压控制确保交互式请求能被优先处理批处理任务则在空闲窗口里按配额慢慢跑。对于团队内部共享一个 LLM API 网关、或者在一个服务里同时处理聊天请求和离线分析任务的情况这类调度机制非常实用。本文会从项目要解决的问题出发讲清楚为什么批处理会饿死交互式流量然后给出一套通用部署思路、功能测试流程、API 集成示例、性能观察指标和常见问题排查清单。由于这个项目本身以源码库方式发布实际命令和参数需要按仓库 README 调整我会将关键代码做成可直接套用的模板。如果你正在用 TypeScript 做 LLM 应用开发或者你在维护一个多人共用的 LLM 代理服务这篇文章建议收藏备用。1. 核心能力速览能力项说明项目类型LLM 请求调度层 / 优先级队列中间件编程语言TypeScript面向 Node.js / Bun 等 JS 运行时核心功能区分交互式请求与批处理任务动态调度防止互相饿死关键机制优先级队列、令牌桶/速率限制、任务分组、背压控制是否支持批量任务是批处理任务作为独立队列调度是否支持交互式请求是交互式请求拥有更高优先级是否提供 API可通过 HTTP 或 SDK 方式集成具体看仓库实现启动方式npm / bun 命令启动或作为库集成进已有服务支持平台跨平台Linux / macOS / Windows 均可运行显存占用不直接涉及显存取决于底层 LLM 推理服务适合场景团队共享 API 网关、LLM 代理、批量推理任务调度平台需要说明的是这个项目本身不负责模型推理显存占用取决于你后端的 LLM 推理服务。调度器只做请求分发和排队控制因此部署门槛主要来自后端模型服务和业务复杂度。2. 适用场景与使用边界2.1 适合谁这个项目适合以下几类读者后端开发工程师正在用 TypeScript 搭建 LLM 应用网关希望统一管理多个模型 API 的调用。平台运维 / SRE团队内部有多个业务方共用同一个 LLM 服务经常出现某条大批量任务把服务占满、影响线上聊天体验的情况。AI 应用开发者在同一个服务里既需要处理用户实时对话又需要后台运行数据清洗、批量总结、批量 Embedding 等任务。独立开发者本地搭建 LLM 服务时希望用一个小巧的调度模块来控制并发和优先级而不是反复手工调整并发数。2.2 能解决什么问题最直接的问题就是“任务饿死”。你可能会遇到这种情况后台脚本一次性提交了几百个 LLM 总结任务模型服务并发被打满此时用户在前台发一条聊天消息等了 30 秒都没响应。这种问题的根源在于所有请求共享同一个执行资源池而批处理任务往往量大、长尾、持续占用。这个项目给出的思路是在请求入口处做分类和排队。交互式请求进入高优先级队列批处理任务进入低优先级队列同时通过配额控制批处理任务的并发和速率。这样即使批处理任务数量很多也不会全部涌进模型服务。2.3 不适合什么场景不是所有场景都需要这样的调度层。如果你的 LLM 服务只供一个小工具内部使用同一时刻最多几个请求那直接用模型服务自带的并发队列就够了。如果后端模型服务本身已经做了复杂的优先级管理比如部分推理框架支持 priority queue那么再叠加一层调度器可能会增加延迟成本和维护成本。另外这个调度器解决的是“请求分发”层面的问题不负责模型精调、提示词工程、私有数据安全等。如果你的核心诉求是降低显存占用、提高单卡吞吐应该优先去看推理后端和量化方案。2.4 使用边界与合规提醒所有 LLM 调用场景都要注意数据合规。批处理任务通常会携带大量文本数据经过调度器时会在内存和日志中短暂留存。部署前要确认数据是否允许离开本地网络、是否包含个人敏感信息、日志系统是否脱敏。涉及用户聊天记录、商业文档、版权素材时必须获得合法授权。对外提供 API 服务时还应对调用方做身份认证和限流避免被恶意刷量。3. 环境准备与前置条件这个项目的环境要求不高因为调度器本身是纯 TypeScript 逻辑核心依赖一般是队列、HTTP 客户端和配置解析库。下面给出一套通用检查清单实际版本请以仓库 package.json 为准。检查项建议操作系统Linux / macOS / Windows推荐 Linux 部署Node.js建议 Node.js 18 LTS 或更高版本Bun如果项目支持 Bun也可以直接使用启动速度更快npm / pnpm / yarn安装依赖使用任选其一后端 LLM 服务OpenAI 兼容接口或本地推理服务需可访问磁盘空间源码加依赖约几百 MB具体看安装体积端口默认按照项目 README 配置通常占用一个 HTTP 端口Redis可选如果项目支持分布式队列可能需要 Redis如果项目提供了 Docker 镜像也可以直接用 Docker 启动省去本地 Node 环境配置。要注意的是这个调度器本身不加载模型所以不需要 GPU 环境但如果后端 LLM 服务部署在同一台机器上仍然要考虑显存和 CPU 资源分配。4. 安装部署与启动方式由于这个项目没有提供一键安装包部署方式主要是通过 npm 安装依赖后启动。下面给出一套通用的 TypeScript 项目部署流程实际命令需要替换为仓库中真实定义的启动脚本和入口文件。4.1 克隆源码并安装依赖git clone project-repo-url cd project-directory npm install如果你使用 Bunbun install安装完成后检查项目根目录下的package.json找到scripts部分。通常会有如下类似的命令{ scripts: { dev: tsx src/index.ts, build: tsc, start: node dist/index.js } }4.2 配置环境变量调度器一般会读取后端 LLM 服务地址、API Key、队列参数等配置。建议使用.env文件内容类似# 后端 LLM 服务地址 LLM_BASE_URLhttp://127.0.0.1:8080/v1 LLM_API_KEYyour-api-key # 调度器监听端口 PORT3456 # 交互式请求超时时间毫秒 INTERACTIVE_TIMEOUT_MS30000注意不要把自己真实的 API Key 提交到 Git 仓库.env文件应加入.gitignore。4.3 启动调度服务开发模式启动npm run dev生产构建和启动npm run build npm start启动后如果看到控制台输出类似Scheduler listening on 0.0.0.0:3456的日志说明服务已正常运行。如果端口被占用更换PORT环境变量即可。5. 工作原理批处理如何饿死交互式流量理解了部署方式后我们再深入看一下项目解决的问题。所谓“饿死”指的是资源分配不公平。大多数模型服务使用的是先到先服务的队列。批处理任务一旦先到就会把模型服务的并发槽位占满后续的交互式请求要么在队列里长时间等待要么因为超时被客户端断开。由于批处理任务通常数量多、单个任务耗时长交互式请求的延迟会被拉得极高最终表现为“服务间歇性不可用”。这个项目的调度思路可以拆成几个关键机制请求分类在入口处识别请求类型。交互式请求来自在线用户对延迟敏感批处理请求来自后台任务允许排队等待。优先级队列交互式请求优先进入执行队列批处理请求进入另一个低优先级队列。调度器优先消费交互式队列。配额控制为批处理任务设置最大并发数和速率上限。例如同一时间最多允许 2 个批处理任务执行每秒最多提交 10 个 token 或请求。这样可以避免批处理任务瞬间打满模型服务。背压机制当模型服务响应变慢或开始报错时调度器自动降低批处理任务的提交速率甚至暂停批处理队列优先保障交互式请求。动态调整根据最近的延迟和错误率动态调整批处理任务的配额而不是使用固定值。用 TypeScript 来表达核心调度器接口大致长这样interface SchedulerOptions { interactivePriority: number; batchPriority: number; batchMaxConcurrency: number; batchMaxRPS: number; interactiveTimeoutMs: number; } interface LLMRequest { id: string; type: interactive | batch; payload: any; priority: number; timestamp: Date; } class LLMScheduler { constructor(private options: SchedulerOptions) {} async submit(request: LLMRequest): Promiseunknown { if (request.type interactive) { return this.runInteractive(request); } return this.runBatch(request); } private async runInteractive(request: LLMRequest) { // 交互式请求立即进入高优先级调度 } private async runBatch(request: LLMRequest) { // 批处理请求进入限速队列不抢占交互式资源 } }这只是一个示意。实际项目会更细致地处理队列并发、请求取消、超时、重试等问题。想进一步了解的同学可以看仓库源码中 scheduler 相关的类实现。6. 功能测试与效果验证部署完成后应该先做一轮功能验证而不是直接接入生产流量。下面给出一套通用的测试方案。6.1 基础调度测试测试目的是确认调度器可以正常接收交互式请求和批处理请求。测试步骤启动调度器。使用curl向调度器的 HTTP 接口提交一个交互式请求。再提交一个批处理请求。观察调度器日志。示例命令curl -X POST http://127.0.0.1:3456/api/chat \ -H Content-Type: application/json \ -d { type: interactive, message: Hello, what is TypeScript? }curl -X POST http://127.0.0.1:3456/api/batch \ -H Content-Type: application/json \ -d { task: summarize_docs, items: [doc1, doc2, doc3] }判断成功的标准是交互式请求返回时间明显低于批处理任务且调度器日志中显示两条请求都完成转发。6.2 高并发批处理下的延迟测试这是核心实验。目的是验证当大量批处理任务持续提交时交互式请求的延迟是否仍然可控。推荐方法准备一个批处理脚本循环提交 100 个甚至更多批处理任务。在脚本运行期间每隔几秒提交一个交互式请求并记录响应时间。对比未启用调度器时相同压力下的交互式请求延迟。判断标准交互式请求的 p95 延迟在可接受范围内。批处理任务最终都能完成没有永久积压。后端模型服务的错误率没有明显上升。6.3 背压和超时测试模拟模型服务变慢的场景。可以在后端 LLM 服务上人为增加延迟或者将调度器的batchMaxConcurrency设置为 1然后同时提交大量批处理任务和交互式请求。预期结果交互式请求不受批处理任务积压影响。批处理任务不会无限堆积调度器会触发背压机制降低提交速率。如果交互式请求长时间无法完成最终会超时并返回明确错误信息。6.4 判断成功的核心指标指标含义交互式请求 P50 / P95 延迟在线用户体验的关键指标批处理完成率最终是否全部处理成功调度器错误率超时、429、5xx 等错误占比队列积压数量批处理任务剩余数量是否持续增长这个项目的价值就在于当你把调度层加进去之后批处理任务和交互式请求不再共用同一个粗粒度队列而是各自有明确的资源预算。7. 接口 API 与批量任务设计7.1 HTTP API 集成调度器通常对外暴露两类接口一类用于提交交互式请求另一类用于提交批处理任务。具体路径和参数以仓库 README 为准。交互式请求POST /api/chat Content-Type: application/json{ type: interactive, model: gpt-4o-mini, messages: [ { role: user, content: 你好 } ], max_tokens: 512 }批处理任务POST /api/batch Content-Type: application/json{ type: batch, task_name: document_summarizer, inputs: [ { doc_id: a1, text: ... }, { doc_id: a2, text: ... } ], options: { max_concurrency: 2, interval_ms: 200 } }7.2 使用 TypeScript SDK 集成如果你在自己的 Node.js 服务中集成这个调度器可以直接调用项目导出的LLMScheduler类而不是走 HTTP 接口。示例import { LLMScheduler } from your-scheduler-package; const scheduler new LLMScheduler({ batchMaxConcurrency: 2, batchMaxRPS: 5, interactiveTimeoutMs: 30000, }); async function onUserMessage(text: string) { const result await scheduler.submit({ id: crypto.randomUUID(), type: interactive, payload: { messages: [{ role: user, content: text }] }, priority: 10, timestamp: new Date(), }); return result; } async function runBatchJob(items: string[]) { const result await scheduler.submit({ id: batch-${Date.now()}, type: batch, payload: items, priority: 1, timestamp: new Date(), }); return result; }注意这里的方法名、参数结构是通用示例真实使用时需要对照项目实际导出的类型定义。7.3 Python 批量调用示例如果你不想在业务 Python 代码里直接调用 TypeScript 模块也可以通过 HTTP 接口提交任务。下面是一个批量提交任务的 Python 脚本示例。import requests import time base_url http://127.0.0.1:3456 batch_endpoint f{base_url}/api/batch tasks [ {doc_id: fdoc-{i}, text: fcontent {i}} for i in range(20) ] for task in tasks: response requests.post(batch_endpoint, json{ type: batch, task_name: summarize_docs, inputs: [task] }, timeout10) print(response.status_code) time.sleep(0.2)这个脚本会每 200 毫秒提交一个任务配合调度器的限速功能能将批处理压力控制在合理范围。8. 资源占用与性能观察8.1 如何观察调度器资源占用调度器本身是纯逻辑代码资源占用通常很低。CPU 消耗主要来自请求解析、队列管理和 JSON 序列化内存消耗主要取决于队列积压的任务数量。如果要观察资源占用可以使用以下方法# 查看 Node.js 进程的 CPU 和内存占用 ps aux | grep node# 查看进程实时资源 top -p pid如果队列中积压了大量任务内存会相应上升但一般不会像模型推理那样吃显存。真正的高资源消耗还是在后端 LLM 推理服务。8.2 性能观察指标建议在调度器内部或外部监控系统中记录以下指标指标如何观察说明队列长度调度器日志 / Prometheus交互式和批处理队列长度应分开统计处理延迟请求日志调度器自身延迟应保持在几毫秒级后端调用耗时埋点区分模型推理耗时和网络耗时重试次数日志计数批处理失败重试是否过多积压任务等待时间任务入队时间和开始执行时间差判断批处理是否积压过久8.3 如何调整调度参数如果发现交互式请求仍然偶尔较慢可能需要降低batchMaxConcurrency。如果批处理任务积压严重可以适当提高batchMaxConcurrency或batchMaxRPS。调整逻辑类似{ batchMaxConcurrency: 2, batchMaxRPS: 5, interactiveTimeoutMs: 30000 }建议每次只调整一个参数并观察 5 到 10 分钟的指标变化避免盲目加大并发导致交互式流量重新被挤占。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面/接口打不开端口被占用或服务未启动查看日志、检查端口占用更换PORT环境变量重启服务交互式请求仍然很慢后端模型服务本身性能不足查看后端模型服务的延迟分布升级推理资源或降低批处理并发批处理任务长时间不执行批处理配额设置过小查看批处理队列长度和当前并发数适当调高batchMaxConcurrency请求返回 429 或 5xx后端限流或服务过载查看后端服务日志检查调度器的重试策略手动降低提交速率依赖安装失败Node 版本不兼容或网络问题查看 npm 报错信息切换 Node 版本或使用镜像源调度器内存持续增长队列积压任务过多查看队列长度检查批处理任务消费速度增加消费者或限制入队量任务重复执行重试逻辑没有做幂等控制检查日志中重试记录为任务添加唯一 ID后端做去重9.1 端口冲突排查如果你启动时发现端口被占用可以使用以下方法找出占用进程lsof -i :3456如果看到已有进程占用可以换一个端口启动。9.2 日志不输出的排查如果使用了异步日志或日志写入文件启动后可能看不到控制台输出。检查项目是否默认配置了日志文件路径或者需要主动开启DEBUG环境变量。DEBUG* npm run dev这样可以看到更详细的调度日志。10. 最佳实践与使用建议10.1 第一次使用先小参数测试不要一上来就把所有业务流量接入调度器。先用batchMaxConcurrency1和少量测试任务验证基本流程再逐步调大并发。这样能避免配置不当导致线上流量异常。10.2 保留一套最小可运行配置将已经验证过的调度配置保存为一个独立的配置文件例如scheduler.prod.json避免每次部署都要重新试参数。配置中关键项都要加注释。{ port: 3456, backend: { baseUrl: http://127.0.0.1:8080/v1, apiKey: env:LLM_API_KEY }, queue: { interactivePriority: 10, batchPriority: 1, batchMaxConcurrency: 2, batchMaxRPS: 5 } }10.3 模型服务、输入素材、输出结果分目录管理如果调度器被用来管理批量任务建议将输入文件、输出结果、日志分目录存放并加上时间戳。例如./data/inputs/2025-06-01/ ./data/outputs/2025-06-01/ ./data/logs/2025-06-01/10.4 批量任务要加日志和失败重试批处理任务通常要运行很长时间中间可能遇到网络抖动、模型服务重启、限流等问题。建议为每个任务记录状态pending、running、success、failed并实现指数退避重试。尝试次数 1等待 2 秒后重试 尝试次数 2等待 4 秒后重试 尝试次数 3等待 8 秒后重试10.5 接口服务要限制访问范围调度器如果对外暴露 HTTP 接口最好先绑定在内网地址而不是直接暴露到公网。添加 API Key 鉴权、IP 白名单并在前端代理层再做一层限流。10.6 涉及人脸、声音、版权素材时必须确认授权如果批处理任务涉及人脸图片、语音音频、长文本版权内容要确保数据来源合法、用途合规。对敏感数据类型做脱敏处理不把原始数据写入日志。使用者应承担相应的合规审查责任。10.7 发布或商用前做效果复核调度器能控制请求优先级但不能保证模型输出质量。在将批量处理能力接入正式业务前先抽取一批输出样本人工复核准确性和合规性。11. 总结与下一步这个项目最值得尝试的点是把“交互式请求优先”变成了一种可配置、可观测的调度策略。相比简单粗暴地限制并发数通过优先级队列、配额控制和背压机制能让批处理和交互式任务共享同一模型服务的同时保持各自的 SLA。最先应该验证的功能是在高并发批处理压力下交互式请求的延迟是否稳定。最容易踩的坑是批处理配额设置得太激进导致背压频繁触发任务重试率上升。建议从低并发起步观察队列积压、请求延迟和后端错误率这三个指标再逐步调参。后续可以扩展的方向包括接入消息队列例如 Redis Stream 或 RabbitMQ做分布式任务分发、增加多租户配额管理、加入 Prometheus 指标上报以及在调度层记录全量调用日志用于审计。如果这个项目对你有帮助建议本地部署一遍再根据自己的模型服务接口做一次压测。这样你就能知道它到底能兜住多大的压力也就能判断是否适合上生产环境。