把 claude、litellm、LM Studio 和 Qwen3-coder 这四个名字串起来做成一套完全跑在本地的免费编码链路这是我最近一直在折腾的事。说白了并不玄乎LM Studio 负责把 Qwen3-coder 这个开源模型在本地跑起来LiteLLM 在中间做一层“格式翻译官”让本来只认 Claude API 格式的客户端——比如 Claude Code 这类命令行编程工具或者你自己写的 Agent 脚本——能直接调用这台本地模型。整条链路打通之后日常写代码、改 bug、生成测试都够用而且不需要为每次请求付费。这篇文章会把整套方案从选型到部署再到调优完整拆一遍。我会讲清楚四个组件各管什么、为什么中间非要插一个 LiteLLM、LM Studio 的参数怎么设置才不白干、Qwen3-coder 到底选哪个尺寸、以及我实际跑下来踩过的坑。内容适合那些不想让 API 账单一天天花出去、又舍不得扔掉现有 Claude 工作流的开发者也适合正在犹豫要不要入坑本地模型的新手。1. 项目全景这套免费链路到底怎么串1.1 先从数据流看全貌四个组件各干一件事整个系统从用户输入到模型输出实际上就是一条很短的转发链。你在 Claude Code或者其他认 Claude API 格式的工具里输入指令请求首先到达 LiteLLM 在 9000 端口起的网关LiteLLM 把 Claude 消息格式翻译成 OpenAI 兼容格式然后转发给 LM Studio 在 1234 端口起的本地服务LM Studio 把请求交给显卡上的 Qwen3-coder 模型等模型生成完流式响应再沿着原路返回客户端。为了方便理解我习惯把这个链想象成一家餐厅。Claude 生态工具是拿着固定菜单点菜的客人他只说 Anthropic 格式的“普通话”LiteLLM 是前台翻译把客人的话转成后厨听得懂的“粤语”也就是 OpenAI 兼容格式LM Studio 是灶台负责把食材加热Qwen3-coder 是掌勺师傅真正决定菜好不好吃。这套方案里最关键的差异在于这位师傅不收小时费只要你付得起自己机器的那点电费。少掉任何一个环节这条链都跑不通。有人会问能不能把 Claude Code 直接指向 LM Studio不行LM Studio 默认开放的是 OpenAI 兼容接口而 Claude 工具发的请求是 Anthropic messages 结构两者字段名和消息组织方式都不一样。有人会问能不能只用 Qwen3-coder 加上一个 OpenAI 接口然后自己写脚本能但你要自己处理流式事件、工具调用块、错误码转换这些细节远比表面看起来麻烦。所以用 LiteLLM 做统一网关是目前配置成本最低、后期又最好维护的选择。1.2 这套方案解决的三个实际问题第一个痛点是 API 费用。日常高频使用对话模型不管是代码补全、生成测试还是解释历史代码每一次请求都在消耗 token 费用。把模型搬到本地之后调用不再按 token 计费只要机器开着你可以反复测试、试错、让它生成十个版本再逐个挑选心态完全不同。第二个痛点是数据隐私。写代码这件事很特殊你贴进对话框的片段往往包含内部业务逻辑、未公开的接口设计甚至偶尔会不小心带上密钥或内网地址。本地推理意味着这些内容不会经过任何第三方服务全部停留在你自己的机器上。对于在意代码资产不出网的开发者来说这一点比省钱更值。第三个痛点是工作流零迁移。很多人并不是不喜欢 Claude 这个工具只是不想为它的 API 付费。这套方案把后端从云端换成本地之后工具本身、快捷键、提示词模板全部保留改一行环境变量就能切回去。这种“可回退”的设计对生产环境非常友好万一哪天本地模型解决不了问题你随时可以切回官方 API。1.3 预期管理免费能用不等于一模一样说实话“免费能用”这四个字里最重要的人是“能”不是“一模一样”。我实际用下来Qwen3-coder 在代码生成、结构化输出、单文件范围内修改这类任务上表现相当不错但遇到跨多个文件的重构、需要深度理解长文档、或者抽象程度很高的设计问题时跟顶级商业模型还是有可感知的差距。所以这套方案更适合高频但不重型的任务函数补全、单元测试生成、代码解释、简单脚本编写、批量格式化。真到了要处理复杂架构决策的时候把环境变量切回官方 API 就好这个切换成本很低。2. 组件选型深度拆解为什么是这四个2.1 LiteLLM 这个“格式翻译官”到底解决了什么LiteLLM 是一个开源 Python 库同时带了一个 proxy 服务。它的核心能力是“统一接口 协议转换”你可以把所有模型请求都发到同一个地址由它来决定路由到哪个后端。更重要的是它支持把 Anthropic 格式的消息转换成 OpenAI chat/completions 格式这在当前生态里非常实用。为什么不自己写转换脚本最直接的原因是协议转换的细节实在太多了。表面上看就是把 JSON 里的几个字段改个名字但实际涉及的内容包括流式输出的 SSE 事件拆分方式、tool_use 这种块状结构的映射、错误码和 HTTP 状态码的对应关系、系统提示词在不同格式里的嵌套规则。这些工作如果自己维护一开始可能觉得没什么等遇到边界情况就会非常痛苦。LiteLLM 把这些兼容问题集中处理等于帮你挡掉了一大片设计陷阱。我做过一个简单对比可以很直观地看出差别自己写转发脚本优点是自由可控缺点是所有格式兼容问题都要自己踩一遍前期开发量不算大但长期维护成本高直接魔改客户端源码让客户端生成 OpenAI 格式优点是少一层依赖缺点是你升级客户端软件时改动会被覆盖而 LiteLLM 的方案优点是配置即用、模型切换灵活、日志完整缺点是多跑一个进程。对我这种想快速搭起来跑业务的人来说LiteLLM 是明显最优解。2.2 LM Studio 和 Ollama 怎么选不要为了极客感选后者网上聊本地模型提到最多的除了 LM Studio 就是 Ollama。两者都能跑 GGUF 格式的量化模型也都提供 OpenAI 兼容的 API但从实际体验来看LM Studio 更适合作为这套方案的底座。选择 LM Studio 的理由有三个。第一图形化界面带来的试错成本低你可以在窗口里直接调节上下文长度、GPU 卸载层数、采样参数每次改动立刻生效不用改配置重启服务。第二它内置了模型市场搜索模型、选择量化版本、下载权重都可以在应用里完成不用自己去找模型托管平台对新手尤其友好。第三它的本地服务端功能做到了开箱即用点一个按钮就启动端口和模型都可以可视化配置。Ollama 当然也有它的优势命令轻量、适合脚本化部署、在服务器环境下很干净。但它对普通开发者并不友好模型源的配置、量化版本的选择、环境变量的设置都比 LM Studio 繁琐。如果你只是想在个人电脑上搭一个能用的服务LM Studio 会省下大量摸索时间。真正需要把模型部署到无桌面环境的服务器时再考虑 Ollama 也不迟。2.3 Qwen3-coder 模型选型对照显存选尺寸Qwen3-coder 是开源编码模型针对代码生成和结构化任务做了大量训练。它的参数规模覆盖了从轻量级到重量级的多个档位普通消费级显卡完全有得选。我的建议是按显存来定不要盲目追求大模型。如果你的显卡显存在 8GB 左右选择经过量化处理的 8B 级别编码模型比较合适编写脚本、代码补全、函数级修改都没有问题。如果显存达到 12GB 到 16GB可以考虑 14B 级别的量化版复杂指令的遵循能力、长文件内的局部重写会更好。如果显存到了 24GB 以上就可以尝试更大的模型接近商业服务的体验。这里还有一个容易被忽略的点上下文长度。Qwen3-coder 原生支持很长的上下文但在本地推理时上下文窗口开得越大占用的内存就越高首字延迟也会越慢。建议先以 16K 为起点如果显存占用紧张或者生成速度明显变慢就降到 8K。日常处理单文件级别的任务8K 到 16K 基本够用不要一上来就挑战最大上下文。2.4 保住 Claude 生态的价值最小变更原则这四个组件里最值得玩味的是为什么要保留 Claude 生态这一层。很多人会问我直接用 Qwen3-coder 的 IDE 插件或者独立界面不就行了可以但那就等于把整个工作流推倒重来。你之前调好的提示词模板、写好的自动化脚本、team 里统一使用的命令行工具全部要换。对于已经习惯了 Claude 生态的开发者来说换工具的隐性成本甚至比省下的 API 费用更高。这套方案的精髓在于“最小变更”客户端代码一行不改只是把环境变量里的 BASE_URL 指向本地 LiteLLM。从团队管理角度看这意味着部署和回滚都极其简单。今天用本地模型明天觉得某个任务还是官方模型更靠谱改两个环境变量再重启终端工具就完成切换。这种可迁移性让方案具备了很强的容错空间。3. 手把手部署从下载模型到打通客户端3.1 部署前先对照这份清单硬件方面我的建议是内存 16GB 起步显存尽量有 8GB 以上。如果你用的是 Mac只要内存达到 32GB 左右也能跑因为苹果芯片可以走 Metal 加速效果比同配置的纯 CPU 方案好很多。没有独立显卡的机器也能跑但速度会明显慢适合测试不适合日常高频使用。软件方面需要准备三样最新稳定版的 LM StudioPython 3.10 以上环境一个用来发 HTTP 请求的终端工具。第一次下载模型权重需要稳定网络建议根据自己显存选一个合适的量化版本不要为了追求质量去下超大文件下到一半失败会非常折磨人。在开始之前还要明确一点这套链路最终要提供的是两个本地服务一个是 LM Studio 的推理服务另一个是 LiteLLM 的网关服务。两个服务都要保持在后台运行任何一方挂了链路就断。3.2 LM Studio 加载 Qwen3-coder三个关键参数别改错第一步是打开 LM Studio在模型市场中搜索 Qwen3-coder根据你的显存选择合适的量化版本并下载。模型文件下载完成后点击加载。加载过程需要一点时间尤其是第一次需要把权重读入内存。第二步是启动本地服务。切到 Local Server 页面点击 Start ServerLM Studio 会开启一个默认监听 1234 端口的 HTTP 服务。这一步最常被忽略的是参数配置区真正影响体验的参数有三个。第一个是 GPU Offload也就是模型层数有多少放到显卡上。理想情况是全部加载到显卡显存不够时部分层会落到 CPU速度会断崖式下降。第二个是 Context Length。很多人喜欢把它拉到最大结果显存直接爆掉。正确做法是先设一个保守值比如 8192跑起来确认稳定之后再慢慢往上调。第三个是采样温度。代码生成是强确定性任务温度太高会让模型在条件分支上乱猜建议设在 0.2 到 0.4 之间。另外建议勾选 Keep in Memory防止模型在使用间隔中被清出内存否则每次调用都要重新加载。服务启动后先用 curl 打一下接口确认 LM Studio 本身没问题curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-model,messages:[{role:user,content:用一句话解释什么是递归}]}如果返回了正常的响应说明推理层已经就绪可以继续搭网关。3.3 LiteLLM 配置模型名映射是核心LiteLLM 的安装很简单执行 pip 命令装带 proxy 的版本就行。然后创建一个 config.yaml最核心的部分是模型映射。pip install litellm[proxy]配置文件示例model_list: - model_name: claude-sonnet-4-20250514 litellm_params: model: openai/qwen3-coder api_base: http://127.0.0.1:1234/v1 api_key: sk-no-key-needed - model_name: claude-3-5-sonnet-latest litellm_params: model: openai/qwen3-coder api_base: http://127.0.0.1:1234/v1 api_key: sk-no-key-needed litellm_settings: drop_params: true这段配置里有几个值得解释的点。model_name 是客户端请求时使用的名字你可以把它当作一个别名。因为很多 Claude 工具在启动时会预先请求一个默认的模型名比如 claude-sonnet-4-20250514如果你在 LiteLLM 里没有注册这个名字工具就会报模型不存在的错误。所以我建议把客户端可能请求的几个常见模型名都映射到同一个 Qwen3-coder这样无论它请求哪个都会落到本地模型上。litellm_settings 里的 drop_params 建议打开。它的作用是丢弃客户端传来但上游模型不支持的额外参数避免 LM Studio 因为收到不认识的字段而报错。api_key 写一个占位字符串就可以因为本地 LM Studio 并不校验密钥但你不能不写否则 LiteLLM 的校验逻辑会拦下请求。启动网关litellm --config config.yaml --port 9000启动后用一条 curl 命令验证网关到 LM Studio 的转发是否正常curl http://127.0.0.1:9000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-no-key-needed \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:写一个快速排序函数}]}请求经过 LiteLLM 转发给 LM Studio返回 Qwen3-coder 的输出就说明这一步打通了。3.4 把 Claude 客户端指向本地服务环境变量是关键以 Claude Code 这类命令行工具为例关键环境变量设置如下export ANTHROPIC_BASE_URLhttp://127.0.0.1:9000 export ANTHROPIC_AUTH_TOKENsk-any-string export ANTHROPIC_MODELclaude-sonnet-4-20250514ANTHROPIC_BASE_URL 是核心它让客户端把所有 Anthropic 格式请求发到本地 LiteLLM 而不是官方服务。ANTHROPIC_AUTH_TOKEN 只需要一个非空字符串用来过客户端自己的参数校验。ANTHROPIC_MODEL 必须和 LiteLLM 配置里的 model_name 对应上。设置完成之后随便给工具发一条指令比如“解释一下当前目录里的 Python 代码”。如果一切正常命令行的输出会像原来一样流式出现同时 LiteLLM 的日志里会显示请求被转发到了 1234 端口。到这一步一条“零 API 费用的本地 Claude 工作流”就正式跑起来了。有一个细节要提醒不同客户端对环境变量的要求有差异。有的认 ANTHROPIC_API_KEY有的认 ANTHROPIC_AUTH_TOKEN最稳妥的做法是两个都设置成同一个值。还有的客户端对 BASE_URL 末尾是否带 /v1 很敏感如果遇到 404试着把末尾的路径去掉或加上LiteLLM 对两种形式都能兼容。4. 实测效果与参数调优哪些地方真正影响体验4.1 三个真实使用场景的体感记录我日常用得最多的是代码补全与局部重构。比如把一个函数从循环改成列表推导式或者给一段逻辑加上边界检查Qwen3-coder 完成这类任务非常稳。在一台 16GB 内存加 8GB 显存的机器上短上下文的首字延迟大概在 1 到 3 秒长上下文会变慢到 5 秒以上但完全可以接受。第二个高频场景是生成单元测试。给定一个函数让模型生成 pytest 参数化用例效果整体不错能覆盖正常情况和边界情况。但有一点要留意它偶尔会引入一些并不存在的自定义模块导入生成后必须人工过一遍。还有一个我经常用的场景是解释代码读一段陌生祖传代码时直接把它丢给模型让它分段解释这个任务对本地编码模型来说几乎没有压力输出质量也高。4.2 工具调用与 Agent 场景能跑但别贪多LiteLLM 支持把 Anthropic 的 tool_use 结构转换成 OpenAI 的 function calling 格式再交给 LM Studio。Qwen3-coder 本身具备工具调用能力所以这条链路理论上能支撑简单的 Agent 任务。实际测试下来我的建议是控制工具调用的复杂度。一次对话里连续调用工具的步骤最好不要超过两到三步每步的工具参数尽量简单。因为消息在 Anthropic 格式和 OpenAI 格式之间来回转换工具调用块在二次转换时偶尔会出现字段丢失或 JSON 格式不严的问题。最稳的用法是“少步骤、窄范围”让模型先把单个动作做对再扩展到多步任务。4.3 影响体验最大的四个参数本地跑模型体验好坏往往不是模型决定而是参数配置决定。这几个月试下来四个参数最关键。温度是最直接的代码生成任务里0.2 到 0.4 是甜区再高就开始在 if 分支上自由发挥了。top_p 建议配合温度同步调整0.8 左右比较稳。上下文长度这个参数容易被忽略它对显存和速度的影响是立竿见影的不要贪大。最后是量化等级很多人执着于 Q8 而放弃更大的模型尺寸实际上在绝大多数编码任务里 Q4 和 Q8 的差距远小于模型尺寸带来的差距省下来的显存可以让模型上一个档次这个取舍更划算。流式输出也必须开启。关闭流式时长答案要全部生成完才会一次性返回体感会非常卡。开启流式后文字一个字一个字蹦出来虽然总时间没缩短但心理等待感完全不同。4.4 做一个简单的成本核算电费方面一张中端显卡满载功耗在两百多瓦算上整机大概三百多瓦。如果每天高强度使用六个小时一天的电费大概一两块钱一个月也就是几十块到一百块的水平。作为对比高频调用商业 API 一个月的费用会是它的几十倍不止。所以这块“免费”并不是零成本而是成本从按请求计费变成了固定电费你的调用次数越多越划算。5. 常见问题与避坑指南5.1 部署期最容易踩的连环坑部署阶段遇到问题最有价值的排查方式是分层隔离。先直接请求 LM Studio 的 1234 端口确认模型服务和参数都正常再请求 LiteLLM 的 9000 端口确认网关能转发最后才去检查客户端环境变量有没有指向对。很多人在第一步都没验证的情况下就去怀疑客户端配置浪费了大量时间。我把部署期常见问题整理成了一张表方便直接对照现象常见原因解决办法端口请求超时api_base 地址没写对或没带 http://先用 curl 手动测试两个端口客户端报 401认证头缺失或密钥不匹配设置 dummy 密钥环境变量统一报 model not foundLiteLLM 配置里没有客户端请求的模型名把该模型名加进 model_list上游返回非预期格式多余参数被转发给 LM Studio开启 litellm_settings.drop_params请求卡住没响应LM Studio 端 Keep in Memory 没开勾选后重新加载模型5.2 运行期体验问题慢、截断、复读运行期最常见的三个问题是慢、截断和复读。慢的原因基本集中在 GPU Offload 没生效、模型选得过大、上下文开得太长三个方向排查顺序也是从这三处开始。截断通常是因为上下文长度设得紧或者模型一次性生成内容太多被窗口截断这时要么扩大上下文要么把任务拆小。复读这个问题很多人遇过模型翻来覆去重复同一句话怎么也停不下来。最有效的解决方案是检查 sampling 参数温度过低有时反而会导致模型陷入重复循环适当调到 0.3 左右会有改善。另一个原因是 system prompt 写得太硬如果你给了一组非常死板的规则模型会不断强调规则而忽略真正要生成的代码。我实测下来精简后的 system prompt 对输出稳定性的提升非常明显。5.3 工具链兼容细节格式转换带来的隐性损失这条链路里所有消息都经历了 Anthropic 到 OpenAI 再到本地模型的二次转换虽然大部分场景都没有问题但个别能力会受到隐性损失。最典型的是多模态输入如果你希望模型理解图片在 Claude 格式里是 image content block转到 OpenAI 格式可能变成无效字段而 Qwen3-coder 本来就是纯文本编码模型所以这套方案只适合文本和代码任务不要期望它能看图。另一个细节是工具调用块里的参数描述可能被截断或重排。虽然 JSON 结构大体能保住但字段顺序一变模型有时候会对先调用哪个工具产生困惑。解决办法是控制工具数量不要在一条消息里塞十几个 function definition三到五个以内最稳妥。5.4 可以直接抄的避坑清单最后整理几件小事都是实践中总结出来的教训。第一LiteLLM 的 model_name 配置建议直接覆盖客户端可能请求的所有模型名宁可多配几个也不要遗漏关键的一个。第二环境变量里 BASE_URL 和认证信息一定要设置成全局变量写进 shell 配置文件不要只跑一条临时 export否则下次开终端就忘了。第三第一次启动成功后不要频繁切换模型文件LM Studio 每次重新加载模型都需要较长等待。第四不要开着其他占用显存的应用跟模型抢显存。第五LiteLLM 的日志是排错时最好的线索它会完整打印每次转发的目标 URL 和耗时遇到任何异常先翻日志。最后分享一点我的实际体会这套链路我前前后后跑了小半个月最大的感受是“免费能用”这四个字里的“能用”确实需要亲手调一遍才知道边界在哪。它最适合承载的是高频、低复杂度任务写点脚本、生成测试、解释陌生代码这些场景下体验非常舒服。而遇到跨文件重构、长上下文理解这类重型任务时我会毫不犹豫地把环境变量切回官方 API反正切换成本只是改个配置这套方案给了我随时在两种模式之间切换的自由。最后再留一个小技巧给 LiteLLM 设置一个随机字符串作为专用密钥不要用默认的明文。虽然本地模型不校验密钥但一个随机的 master key 能避免局域网内其他人蹭你的推理服务也能防止配置错误时误暴露端口。后续你还可以在 LiteLLM 的配置里不断增加新的 model 条目把本地模型和付费模型统一管理起来做成一个真正属于你自己的模型路由中心。