后端API网关LLM 网关人工智能大模型本地部署【免费下载链接】llama-swapReliable model swapping for any local OpenAI/Anthropic compatible server - llama.cpp, vllm, etc项目地址https://gitcode.com/gh_mirrors/ll/llama-swap点击查看免费下载本文围绕 llama-swap 的两个关键配置项sendLoadingState与includeAliasesInList讲解如何让你的客户端正确发现模型、在模型冷启动swap时获得实时加载反馈而不是把等待模型加载误判为请求失败。读完后你将掌握这两个开关的完整配置方式、加载反馈流的 SSE 报文结构以及超时设置等工程实践要点。核心问题swap 不是失败而是一次等待llama-swap 的定位是按需加载模型的代理层当请求到达时如果目标模型尚未在 llama-server / vLLM 等后端上加载llama-swap 会先启动或切换对应进程再转发请求。对客户端而言这意味着两个基本动作选择模型前先读取/v1/models确认目标模型 ID 是否真实存在准备好等待请求可能在模型加载期间被挂起客户端应当容忍这段时间而不是超时重试。llama-swap 为此提供了两个互补的机制sendLoadingState: true让服务端在加载期间向客户端推送实时加载进度以流式响应形式而不是让客户端面对一个静默挂起的连接includeAliasesInList: true把配置中的模型别名aliases也暴露到/v1/models列表中客户端可以直接用别名寻址。配置速览完整配置示例可直接放入 llama-swap 配置文件如 docs/config.example.yaml 同级的运行配置sendLoadingState: true includeAliasesInList: true两个开关在源码中的定义位于 internal/config/config.go注释明确了各自的语义// send loading state in reasoning SendLoadingState bool yaml:sendLoadingState // present aliases to /v1/models OpenAI API listing IncludeAliasesInList bool yaml:includeAliasesInList需要强调一点原文档的核心结论这两个开关改变的是反馈形式而不是加载速度。模型冷启动该花多久还是花多久sendLoadingState只是让这段时间变得可见。sendLoadingState加载反馈流是如何工作的触发条件四个条件同时满足才推送加载状态从源码看加载反馈并非对任意请求生效。触发逻辑位于 internal/router/base.goshouldShowLoading : data.Streaming data.SendLoadingState isLoadingPath(req.URL.Path) !isModelReady即必须同时满足请求是流式请求data.Streaming——加载反馈寄生在 SSE 流里非流式请求不受影响配置了sendLoadingState: true请求路径命中加载白名单——目前白名单只有/v1/chat/completions前缀匹配见 internal/router/loading.go 中的loadingPaths模型尚未就绪!isModelReady——模型已加载并处于 Ready 状态时不会推送加载流。四个条件满足后llama-swap 创建一个loadingWriter接管响应先向客户端写出加载进度等模型就绪后再把同一连接交接给真正的推理处理逻辑。加载流的报文结构loadingWriter的完整实现在 internal/router/loading.go。它首先把响应头固定为标准的 SSE 流s.Header().Set(Content-Type, text/event-stream) s.Header().Set(Cache-Control, no-cache) s.Header().Set(Connection, keep-alive) s.WriteHeader(http.StatusOK) s.sendLine(━━━━━) s.sendLine(fmt.Sprintf(llama-swap loading model: %s, modelName))随后以约750ms的 tick 间隔向客户端推送心跳内容。每个数据帧都是 OpenAI 流式格式的一条 SSEdata:消息但内容字段放在delta.reasoning_content中这也是配置注释send loading state in reasoning的由来type Delta struct { ReasoningContent string json:reasoning_content } // 每帧形如 // data: {choices:[{delta:{reasoning_content:...}}]}客户端如果按标准 OpenAI 流式协议解析会在reasoning_content字段里看到加载进度文本不理解该字段的客户端通常也只是看到一段推理内容而不会把请求判为失败。加载流的具体行为包括进度提示每 tick 追加一个.保持连接活跃趣味加载语每隔随机 510 秒从 internal/router/loading_remarks.go 的loadingRemarks列表随机洗牌后循环使用中取一条如Loading weights (theyre heavy)、Reticulating splines等按约 75 字符/秒的速度打字机式输出队列位置如果请求在并发调度中排队调度器会通过PositionCh下发队列位次加载流实时显示Queue position: #N见 internal/router/base.go完成收尾模型就绪前加载流会写入Done! (X.XXs)及收尾分隔线然后停止推送并把响应权交还给真正的推理流。加载期间的错误处理一个容易忽略的细节一旦加载流发出了200 OK后续再想返回真实 HTTP 错误状态码已经不可能响应状态已提交。为此loadingWriter提供了专门的sendErrorinternal/router/loading.go把错误包装成与 llama-swap 非流式错误体相同结构的 JSON 错误帧作为流内最后一帧data:消息发出随后补data: [DONE]收尾。这样客户端即使面对流已提交后出的错也能拿到带原因的结构化错误而不是一个被截断、无[DONE]、无原因的流。includeAliasesInList把别名暴露到 /v1/modelsllama-swap 的模型配置支持为同一个模型定义多个别名别名在路由层会被解析回真实的模型 ID见 internal/config/config.go 中aliases map[string]string字段注释为 map aliases to actual model IDs。默认情况下/v1/models只列出真实模型 ID客户端必须知道别名 → 模型的映射关系才能用别名。开启includeAliasesInList: true后/v1/models会为每个别名追加一条独立记录。实现位于 internal/server/api.goif s.cfg.IncludeAliasesInList { for _, alias : range mc.Aliases { if alias : strings.TrimSpace(alias); alias ! { data append(data, newRecord( alias, mc.Name, mc.Description, mc.Metadata, caps, status, map[string]any{type: alias, modelID: id}, )) } } }从这段实现可以看出几个值得注意的行为别名记录与本体共享能力与状态capscapabilities与status都是针对真实模型一次性解析后复用的注释明确说明别名描述的是同一个上游不应与所指向的模型产生分歧元数据自描述每条别名记录的meta.llamaswap中带type: alias与modelID: 真实模型ID客户端可以据此区分别名与真实模型并在需要时反查本体空别名被过滤TrimSpace后为空的别名条目不会出现在列表中unlisted: true的模型整体不出现在列表中含其别名该过滤发生在别名展开之前internal/server/api.go。开启这个开关后客户端只需要读一次/v1/models就能拿到所有可用的寻址名真实 ID 别名直接拿来作为请求中的model字段即可无需维护本地映射表。工程实践要点结合原文档给出的操作建议落地时有三条经验值得牢记客户端超时必须大于模型冷启动时间。加载反馈再详细也只是把等待可视化。如果客户端读超时/总超时短于模型加载耗时请求依然会被客户端单方面掐断。对于动辄需要数十秒加载的大模型应按最坏加载时间含磁盘 IO、显存分配设置超时而不是默认 30 秒使用与所选 API 匹配、且支持流式的客户端。sendLoadingState的反馈走的是reasoning_content流式 delta只有流式SSE客户端才能收到非流式请求不会触发加载流见前文四个触发条件。客户端还应能正确处理流内错误帧以[DONE]结尾的结构化错误先发现后请求。无论别名是否暴露到列表/v1/models都应是客户端选模型前的第一步配合includeAliasesInList一次列表请求即可同时解决有什么模型与用什么名字请求两个问题。配置速查表配置项默认作用生效范围sendLoadingStatefalse模型加载期间向客户端推送 SSE 加载反馈进度点、趣味提示、队列位次、完成耗时流式请求且路径以/v1/chat/completions开头且模型尚未就绪includeAliasesInListfalse将配置的模型别名作为独立条目暴露到/v1/models元数据标记type: alias与真实modelID/v1/models列表接口两个开关互不依赖可单独开启只开sendLoadingState适合客户端已经知道模型 ID 的场景只开includeAliasesInList适合希望统一用别名寻址、但客户端无法展示流式加载反馈的场景两者同时开启则构成完整的发现 等待反馈客户端体验。参考起点本文主题文档见 docs/kb/guides/model-runtime/client-compatibility-and-loading-feedback.md配置字段定义见 internal/config/config.go加载流实现见 internal/router/loading.go 与 internal/router/base.go模型列表接口实现见 internal/server/api.go示例配置见 docs/config.example.yaml。赞分享后端API网关LLM 网关人工智能大模型本地部署【免费下载链接】llama-swapReliable model swapping for any local OpenAI/Anthropic compatible server - llama.cpp, vllm, etc项目地址https://gitcode.com/gh_mirrors/ll/llama-swap点击查看免费下载相关推荐Elasticsearch-NET 客户端安装与兼容性指南Elasticsearch NET 客户端安装与兼容性指南 前言 Elasticsearch NET 是 Elasticsearch 官方提供的 .NET 客户llama-swap 的 MCP 端点 /api/mcp 实战让 MCP 客户端自助查询文档与运行配置llama swap 的 MCP 端点 /api/mcp 实战让 MCP 客户端自助查询文档与运行配置 llama swap 把自身的知识库文档、实时运行配置后端API网关LLM 网关人工智能大模型本地部署Gutenberg 客户端导航兼容性指南block.json 声明、兼容性判定与实现规范Gutenberg 客户端导航兼容性指南block.json 声明、兼容性判定与实现规范 客户端导航Client Side Navigation让页面切换后端前端上一篇飞桨 Paddle Serving 服务化部署开发全流程指南Linux GPU/CPU 下的功能开发与 TIPC 自动化测试下一篇LeetCode 1590 解析Make Sum Divisible by P —— 前缀和与模运算在最短子数组问题中的应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考