Yeschef实战：用Claude Code调度Ollama构建局域网多机推理集群

如果你手头正好有三台吃灰的 NUC又每天都在用 Claude Code 处理编码任务看到“Yeschef: Claude Code dispatches work to Ollama on my LAN (627 tok/s on 3 NUCs)”这个标题很难不心动。我第一次看到这个实验时第一反应不是“真快”而是“这件事值得拆开看”Claude Code 的任务调度在跑Ollama 的本地推理也在跑中间多了一层叫 Yeschef 的适配层把两者连起来。这篇文章想把这件事讲透包括它解决了什么问题、复现时要注意什么以及这个方案真正适合谁。我的主判断很简单Yeschef 这类方案最重要的意义不是把 627 tok/s 当作一道漂亮的成绩而是把 Claude Code 从“只能连中心化服务”的工作流扩展成“可以调度到局域网多节点”的本地化实验。它真正改变的不是单次推理速度而是工作流的部署边界。1. 为什么本地多机推理不是“性能焦虑”而是工作流边界问题很多人看到“3 台 NUC”“627 tok/s”这种数字第一反应是比速度。如果你的目标只是比较本地模型和云端模型谁跑得快那大概率会失望。因为本地小模型的单次生成能力和经过大规模训练和优化的云端模型不在一个量级。这个实验真正有意思的地方是它把 Claude Code 这种原本依赖外部服务的工具引入到了一个完全可控的局域网环境里。1.1 单机跑本地模型问题出在哪里先聊单机 Ollama。过去半年里身边越来越多同事开始在个人电脑上跑 Ollama用来做代码补全、文本摘要、本地知识库测试。单机的价值很清楚模型文件在本地数据不出机器不需要为每次请求按 token 付费断网环境下也能继续跑。但单机有几个天然限制。第一是资源池有限。ollama run qwen2.5:7b这类模型单机跑起来没问题可一旦你同时开编辑器插件、浏览器、编译任务显存和内存马上吃紧。模型要反复加载、卸载第一次请求往往要等好几秒。第二是并发能力弱。Ollama 默认会按需加载模型同一台机器上同时来多个请求时经常出现排队。你用 Claude Code 生成代码时如果中途又发起一个解释请求体验就会明显下降。第三是模型切换成本高。跑 7B 模型刚合适换 14B 就要考虑量化换 32B 基本就只能用 CPU 或者超大内存。单机不是不能跑而是“可扩展性”很差。1.2 从“单机可用”到“局域网可用”发生了什么变化当你要把模型能力真正放进日常工具链而不是只做一次技术演示时单机就不再是效率问题而是工作流问题。Claude Code 这类工具在工作时会持续发起多次请求读文件、生成代码、调用工具、回填上下文、解释报错。这些请求不是一次性结束的而是一条又一条的对话轮次。如果每一条请求都要在本地排队等模型加载整个开发节奏就会被拖垮。把任务分发到局域网里的多台机器解决的其实是这个问题把“一台机器既要跑模型又要跑工具链”变成“工具链在这台机器上运行推理任务拆给那几台机器并行处理”。你不需要一台性能怪兽而是把已有的几台普通机器变成一个可以调度的推理池。这也是为什么 Yeschef 这类适配层值得写一篇长文。它不是简单地把 Ollama 包装成一个 API而是让 Claude Code 在发起请求时能根据局域网里的节点状态把任务分给合适的机器。2. Yeschef 的关键不是 627 tok/s而是把 Claude Code 的请求搬回局域网先说清楚 Yeschef 在标题里的角色。它不是一个模型也不是 Ollama 的替代品。从命名和实验描述看它更像一个位于 Claude Code 和 Ollama 之间的调度层或适配层。Claude Code 产生请求Yeschef 负责决定把请求转发给局域网里的哪一台 Ollama然后把生成结果返回给 Claude Code。2.1 适配层到底适配了什么Claude Code 原生设计是连接 Anthropic 的云端接口。它有一套自己的请求格式、鉴权方式和流式返回协议。要让请求落到局域网里的 Ollama不能直接把两个进程硬接在一起中间必须有一个“翻译官”。这个翻译官通常要处理四件事端点转换把 Claude Code 默认要访问的地址改成局域网内的本地服务地址。鉴权处理Claude Code 会带一个 token本地 Ollama 通常不需要复杂的云端鉴权适配层要接住这个 token 并放行。请求与响应格式转换Claude Code 发送的请求体里有模型名、消息列表、工具定义、上下文等字段Ollama 的 API 格式不完全一样需要把字段映射过去。错误与重试云端接口失败时会有明确的返回码本地多机环境下还要额外处理“这台机器模型没加载”“那台机器显存不足”“请求超时”等状态。所以 Yeschef 这个项目真正的工作量不在推理本身而在协议转换和任务调度。2.2 一次请求的完整路径Claude Code、适配层、Ollama我用一次代码生成来解释完整路径。第一步Claude Code 准备发起一个请求。它会把当前对话上下文、用户指令、文件内容打包发给配置好的 API 地址。如果环境变量指向了本地适配层请求就会先到局域网里的调度服务。第二步适配层收到请求后根据可用的 Ollama 节点列表选择一个最合适的节点。常见的调度策略包括轮询、按响应时间选择、按当前负载选择。在实验环境里可能还会把不同模型固定调度到不同机器。第三步Ollama 节点执行推理流式返回 token。适配层一边接收 token一边按照 Claude Code 期望的流式格式重新包装再返回给 Claude Code。第四步Claude Code 正常解析响应继续下一步工具调用。这个链路里最容易被低估的是第二步的调度。如果只是随机选一台机器多机部署的意义就很小。真正有价值的调度要能知道每台机器当前是否空闲、模型是否已经加载、上次响应时间是多少。否则可能所有请求都集中到同一台机器另外两台闲着。2.3 627 tok/s 最合理的读法627 tok/s 这个数字可以有几种不同解读。它可能是指三台 NUC 在某个并发压力下整个局域网服务观测到的聚合输出速度也可能是指某一次请求的流式输出速度。两种读法差别很大。如果是聚合速度它说明的是集群吞吐能力也就是“单位时间内所有节点加起来能产生多少 token”。这个数字对多机调度的意义更大因为它直接反映系统能否把请求分散到多台机器。如果只是单请求速度那 627 tok/s 只说明某一台 NUC 上的某个模型跑得不错和“多机”没有直接关系。从通常的多机推理实验来看我倾向于把 627 tok/s 理解为一个多节点聚合后的观测值。但这里要提醒一句这个数字依赖具体模型、量化级别、上下文长度、并发数以及 NUC 的硬件配置。不要把它当成一个通用基准更不要以为任何三台 NUC 都能跑到这个数。读法含义对实验的参考价值聚合吞吐多节点并发输出的总 token 速率体现集群整体调度能力单请求生成速率单个请求流式输出速度体现单机模型推理效率首 token 延迟从发出请求到收到第一个 token 的时间体现交互体验和排队情况多机聚合吞吐并不是简单地把单机速度相加。调度开销、节点空闲差异、模型加载时间、网络传输延迟都会吃掉一部分理论峰值。你能稳定复现的通常要约等于“单机吞吐 × 节点数 × 调度效率系数”而不是单机吞吐 × 节点数。3. 复现实验先准备三块拼图如果你想在自己的局域网里复现一个类似的实验不用一开始就盯着 627 tok/s先把下面三块拼图拼好。每一块缺失后面的性能都无从谈起。3.1 硬件、网络和系统的选择硬件方面NUC 只是标题里的一个选项不代表必须用 NUC。任何几台内存和磁盘足够的 x86 小主机、旧台式机、迷你服务器都可以。关键不在品牌而在内存大小、显存或者显卡型号。跑 Ollama 时模型需要常驻内存或显存内存越大能同时跑的模型越多。网络方面最稳的方案是有线网络。如果三台机器都走 WiFi尤其是 USB 无线网卡容易出现驱动不稳定、延迟抖动、吞吐忽高忽低。实验时建议把三台机器接到同一个交换机或路由器 LAN 口避免无线干扰。系统方面Ollama 对 Linux 支持最直接Windows 和 macOS 也能跑。但多机调度通常要监听端口、访问服务、写日志Linux 会更省事。这里没有哪套系统绝对更好关键是你自己能不能维护。3.2 Ollama 安装、模型拉取和版本确认Ollama 的安装整体是简单的。在 Linux 上常见做法是把官方安装脚本拉下来执行Windows 和 macOS 有安装包。但安装脚本的下载速度有时候很慢尤其是在网络环境不理想时。如果你遇到“ollama 下载太慢了”先不要慌。正常处理顺序是确认当前网络环境能否访问 Ollama 官方下载地址。检查系统是否有 DNS 或防火墙策略问题。如果确实慢可以使用你所在地区可访问的镜像源或者让网管托管安装包再内网分发。注意不要为了追求“快”随便使用不明来源的脚本。安装包一旦被篡改后面所有模型请求都可能存在问题。安全比节省几分钟重要得多。安装完成后先做两件事ollama serve ollama list第一条命令确保服务在后台运行第二条命令查看当前已经拉取了哪些模型。如果ollama list是空的接下来拉取一个实验用的小模型。比如ollama pull qwen2.5:7b这里先选择 7B 左右的量化模型是因为它更容易在多台普通机器上运行。不要一上来就拉取超大模型否则你可能花半天下载最后发现内存不够。3.3 让 Claude Code 指向本地端点的通用思路Claude Code 原生并不认识 Ollama。要让请求进入局域网常见做法是设置环境变量把 Claude Code 的 API 基础地址指向本地适配层。注意不同版本的 Claude Code 对环境变量名和本地接入方式可能不同。落地前先确认你安装的版本支持哪些配置项。一个通用的示意如下export ANTHROPIC_BASE_URLhttp://你的本地适配层地址:端口 export ANTHROPIC_AUTH_TOKENlocal-test-token这里的“本地适配层地址”可以是 yeschef 服务所在机器的 IP也可以是一个内网域名。关键是先确保 Claude Code 的请求真的到达了适配层而不是仍然发往云端。如果这一层没有跑通后面所有性能测试都没有意义。我建议先用最简单的方式验证手动发起一次非常短的请求让 Claude Code 只回复一句话然后查看适配层日志里有没有收到请求。4. 从单机基线到多机并发一个务实的压测路径当你把三块拼图拼好后不要急着上并发。正确顺序是先建立单机基线再测网络最后做多机聚合。这个顺序能帮你快速定位问题到底出在模型、网络还是调度层。4.1 第一步先测单机不要直接上集群在任意一台 NUC 上单独测 Ollama 的响应情况。最简单的测试方式ollama run qwen2.5:7b 用一句话解释什么是 HTTP 503观察三个指标首 token 等待时间模型是否已经加载。完整回复速度每秒输出多少个 token。运行时资源占用CPU、内存、显存分别多少。如果单机请求都要等十几秒才出来不要怪调度层问题在你的模型过大、量化级别不合适或者机器本身资源不足。先换更小的模型或者调整 Ollama 的并发参数。4.2 第二步测网络而不是只看带宽局域网内多机通信很多人只关心带宽。但 Claude Code 这种工具请求是高频、小包、流式返回的。它更在意的是延迟和稳定性。实测时可以在两台机器之间互 ping观察是否有持续丢包。还要确认端口是否可达。Ollama 默认监听 11434如果你的适配层在另一台机器需要确保防火墙允许内网访问这个端口。很多“请求超时”问题不是模型慢而是根本连不上。你还可以用 curl 直接测远端 Ollama 的 APIcurl http://另一台机器IP:11434/api/generate \ -d {model:qwen2.5:7b,prompt:你好}如果这一步都不通后面接 Claude Code 大概率也是失败。4.3 第三步多机聚合并发的观察指标到了这一步才开始真正压测多机。重点不是追求一个数字而是观察系统在并发下的行为。建议先设置一个很低的并发数比如 2 个并发请求看三台机器是否都有请求到达。然后逐步增加到 4、8、16。每次增加后记录响应成功率平均首 token 延迟每秒输出 token 数有没有请求排队、超时或被丢弃你很快会发现多机聚合吞吐不是一条直线上升的曲线。当调度层成为瓶颈或者某一台机器负载过高时吞吐会趋于平缓甚至下降。这不是模型出了问题而是调度策略和资源分配到了边界。5. 实际踩坑清单下载、版本、超时、乱码和并发本地化部署最难的不是跑通而是把那些看起来很小、实际非常耽误时间的问题一个个排查掉。这里列几个我在类似实验里经常遇到的坑。5.1 下载慢和安装源先确认网络环境再谈加速“ollama 下载太慢了”是一个非常普遍的现象。除了模型文件本身很大之外也可能是安装脚本下载源不稳定。我的建议是先确认最基础的事情。DNS 解析是否正常内网是否有安全策略限制了外网下载目标存储盘是否是机械硬盘。很多时候下载慢是磁盘写入速度跟不上而不是网络速度不够。如果你在安装阶段就把时间耗光了后面实验容易产生“赶紧跑完”的急躁心态。遇到下载慢换一个时间再试或者找一台网络环境更稳定的机器下好模型文件再拷贝都是可行办法。5.2 模型名、版本和 529先看日志再猜原因模型名不匹配是很隐蔽的坑。比如你本地拉取的模型叫qwen2.5:7b但适配层配置里写的却是另一个名字Claude Code 就会报出类似“is not a model this version recognizes”的错误。表面上看是版本不支持实际是模型名、路由配置和适配层版本三者不匹配。我还见过 HTTP 529 错误。529 通常表示上游服务过载。放在本地多机场景里最常见的原因是并发请求同时打到同一台机器导致 Ollama 处理不过来。排查时要先看这一段时间内各节点负载而不是急着调超时。排查这类问题我只用一条原则先看日志再猜原因。5.3 超时和乱码从输入端和适配层一起排查把 Ollama 接入 Dify 这类平台时很多人遇到过“模型处理超时”。这通常不是因为模型本身慢而是上下文太长导致请求处理时间超过了平台默认超时时间。本地模型对超长上下文的处理要比想象中吃力。解决办法不是简单地调大超时而是先缩短上下文或者限制对话轮数。“Ollama 调用乱码”也是一个高频问题。乱码的根源不一定在模型可能出在请求编码、响应解码或者适配层把流式数据切错了位置。排查时先看原始请求里的中文是否正常再看 Ollama 返回的原始 JSON 是否正常最后再看 Claude Code 收到的是什么。逐层确认比反复换模型有效。5.4 一个通用排查链路遇到问题按这个顺序排查先看现象是超时、卡住、无输出、输出异常还是速度变慢再看输入模型名、上下文长度、文件路径、消息格式、编码是否正常。再看环境Ollama 版本、Claude Code 版本、依赖版本、端口、防火墙、局域网连通性。再看参数并发数、批量数、超时时间、上下文长度、量化级别。最后看工具边界这个版本的适配层是否支持你要用的模型和功能。不要一上来就重装。多机分发涉及多个组件重装只会让问题更难定位。6. 本地推理多机分发一个五步验证框架这类实验很容易变成“调一次参数、看一次输出、再调一次参数”的无限循环。为了避免这一点我沉淀了一个五步验证框架你可以直接套用。6.1 五步法概述第一步单点跑通。确保一台机器上的 Ollama 能正常完成请求。 第二步单机基线。测出这台机器在目标模型下的真实吞吐和延迟。 第三步跨节点调度。让适配层能把请求分别发到不同机器并确认每台机器都有输出。 第四步并发压测。逐步增加并发请求观察聚合吞吐和错误率。 第五步稳定运行。跑一段时间观察是否有偶发超时、内存泄漏或节点失联。6.2 每步要回答的问题第一步要回答输入输出格式对不对模型能不能正常加载 第二步要回答这台机器当前能跑多快瓶颈在 CPU、内存还是 GPU 第三步要回答请求是不是真的分散到了所有节点有没有节点一直收不到请求 第四步要回答并发上去后系统是变快、变慢还是开始报错 第五步要回答长时间运行后结果是否稳定日志是否完整节点掉线后能不能自动恢复6.3 判断标准什么时候可以继续什么时候该停如果单点跑不通不要继续做多机。如果单机基线只有个位数 tok/s多机聚合也不会突然变成几百 tok/s。如果第四步发现并发一上去就大量超时先别急着加机器。可能是调度策略、模型加载策略或网络配置出了问题。多机并不是变快的万能药它只是把瓶颈从“单机算力”移动到了“调度和通信”上。如果第五步无法稳定运行这个方案只适合短期实验不适合作为日常工具链的一部分。7. 适用边界它适合学习、实验和隐私场景但不等于生产替代本地多机分发有很多让人兴奋的地方但兴奋之余要分清适用边界。它不是一个“上可替代云端、下可跑生成任务”的万能方案。7.1 哪些场景真的值得用如果你有隐私敏感的数据不希望它们离开自己的网络这个方案很有价值。所有请求都在局域网内完成数据不会经过第三方服务。如果你所在的环境网络不稳定或者需要离线办公本地多机也能保证基本可用。如果你主要用 Claude Code 做一些模板生成、代码解释、文档整理任务对模型能力要求不是顶层本地小模型是可以接受的。三台 NUC 的聚合吞吐对这类任务来说通常够用。如果你本身就在研究本地模型部署、任务调度、协议适配这个方案是一个很好的学习项目。它能让你理解一条请求从工具链到推理节点的完整链路这种理解比任何单一工具教程都重要。7.2 哪些场景不建议硬上如果你需要的是代码生成的高准确率、复杂工具调用、超长上下文理解本地小模型大概率达不到云端大模型的水平。这不是调度层的错而是模型本身的局限。如果你的业务需要严格的并发一致性、任务追踪和审计本地多机适配层还不够成熟。它可能没有完善的队列、持久化和幂等机制。这时候硬上会在运维阶段付出更多代价。如果你的团队没有运维基础只是为了“快”而搭一套多机推理集群不划算。多机意味着多一份维护模型版本、适配层版本、网络问题、日志收集每一项都是成本。7.3 长期维护成本很多人在实验阶段被 627 tok/s 吸引但很少想长期维护的问题。三台 NUC 意味着三套系统要打补丁、三个模型文件要更新、一个适配层要升级。只要其中一个节点掉线调度策略就不得不变化。如果你只是个人使用能接受偶尔手动重启服务那没问题。如果你想把它变成团队工具至少还要补上监控、日志告警、模型版本管理和节点健康检查。没有这些实验永远是实验。8. 回到最初627 tok/s 的启示是什么现在再回到标题里的 627 tok/s。我反而觉得这个数字不是最重要的。真正重要的是它展示了 Claude Code 这类工具可以被重新定向到你自己拥有的计算资源上。你可以用适配层把请求调度到局域网里的多台机器让它们像一个小型推理池一样工作。这个过程本身已经比单次速度更有价值。如果你也想复现类似实验我建议你先不要追求 627 tok/s。先花一个小时把一台机器上的 Ollama 跑通再花一个小时接上适配层让 Claude Code 发出第一条真正被本地模型处理的请求。然后慢慢扩展到第二台、第三台。你会经历很多次排错但也会真正理解多机调度的底层逻辑。本地推理和多机分发这件事正在从“极客玩具”变成“可用的技术方案”。它的边界很清楚不能替代云端大模型的能力但可以在隐私、离线、成本和可控性上实实在在解决问题。这个方向值得长期关注因为工作流的入口和推理服务解耦之后你能组合出很多新的使用方式。而 Yeschef 这类项目恰好是这个方向上的一块有意思的拼图。