最近小半年我身边越来越多的人开始把项目从“只用云端 API”改成“本地模型 云端 API 混着用”。原因其实很简单天天调用云端模型token 账单哗哗涨可一旦换成纯本地小模型遇到稍微复杂一点的推理又明显拉胯。于是大家不约而同走到一个岔路口——本地跑着一个 Ollama云端配着 DeepSeek、通义、Kimi 好几个 key代码里一会儿写ollama.chat一会儿写openai.ChatCompletion再想接 Claude Code、Trae 这些工具时又是一套新的协议……整个工程被接口差异撕得粉碎。这篇文章想把我在这个坑里摸爬滚打几个月的经验讲清楚本地模型和云端 API 完全可以收敛到一套接口下统一调度而且不需要很复杂的架构。你只需要理解“OpenAI 兼容协议”这个事实标准再选一个合适的转发层网关或 SDK就能让所有业务代码、IDE 插件、智能体框架用同一套请求格式访问本地和云端模型按成本、按优先级甚至按模型能力自动切换。适合正在做 AI 应用开发、搭 RAG 管线、或者整天在各类 AI 工具里折腾本地模型的朋友参考。1. 先想清楚本地模型和云端 API 到底差在哪1.1 从调用方式看两者的本质差异本地模型和云端 API底层都是“用 HTTP 发 JSON 过去再收 JSON 回来”这点没有任何神秘。真正的差异在于三点终端地址不同、鉴权方式不同、消息结构不同。终端地址云端是https://api.xxx.com/v1/...本地是http://localhost:11434/...。鉴权云端要带Authorization: Bearer sk-xxx本地无所谓随便填。消息结构OpenAI 把 system 放在 messages 数组里统一传Anthropic 把 system 单独拎出来还要带x-api-key和anthropic-version两个头Ollama 原生接口又有自己的一套/api/chat。我说几个实际例子你就明白了。同样是“问模型一句话”OpenAI 风格是POST /v1/chat/completionsbody 里是{model: ..., messages: [{role: user, content: 你好}]}Anthropic 风格是POST /v1/messagesbody 里多了独立的system字段Ollama 原生风格则是POST /api/chat需要显式传stream: false才不流式。长得都很像但就是“差一点点”。如果每接一个模型就写一套适配代码会被 if-else 塞满。最要命的是 Claude Code、Trae、CodeGeeX 这类工具它们只认自己那套协议你本地模型再好它们也不认识。所以业内逐渐形成默契不管底层是谁对外尽量暴露成 OpenAI 兼容接口这就是“统一接口”得以成立的地基。维度本地模型云端 API延迟无网络开销首字快受网络波动影响成本一次性硬件投入 电费按 token 持续计费隐私数据不出本机数据上传到服务商能力上限受显存、算力限制可调用超大模型并发单机受限弹性扩容可用性依赖本机运行状态依赖服务商稳定性1.2 统一调度要解决的四类实际问题把这个问题拆开看你会发现大家嘴里说的“统一调度”其实涵盖四个完全不同的诉求。很多时候你觉得自己没思路是因为没搞清楚到底要解决哪一个。第一业务代码只写一套 client。你不想在产品代码里同时维护 openai、anthropic、ollama 三套 SDK希望在代码里只出现一个 OpenAI 客户端换模型只是改一个字符串。这是最基础、也是被提得最多的一层诉求。第二工具类软件只认一个 base_url。Claude Code 要通过环境变量指定 API 地址Trae 添加模型时要填 Base URLCodeGeeX 配置时要填地址。这类工具大多只认 OpenAI 兼容协议你得给它们一个统一的入口否则本地模型和这些工具永远无缘。第三成本和性能的自动权衡。笨办法是人在代码里判断“这个任务简单走本地那个任务难走云端”。自动化的做法是让调度层配置好 fallback本地模型超时或质量不够自动切到云端或者本地模型能答就不花钱答不了再升级到云端。这一层是“调度”二字的真正价值所在。第四团队共享与模型纳管。一个人折腾无所谓几个人共用时你希望能有一个入口、一套 key 管住所有模型还能看每个模型消耗了多少 token。这就从“接口问题”升级成了“网关问题”。我接触到的绝大多数项目最终都落在这四个诉求里。把这四件事一件一件解决掉你对“统一接口”的理解就算到位了。2. 为什么“OpenAI 兼容接口”成了事实标准2.1 一套接口的约定URL、鉴权、请求和响应长什么样先给没接触过的朋友补个基础所谓 OpenAI 兼容接口就是实现了下面几个约定的 HTTP 服务GET /v1/models返回当前服务可用的模型列表。POST /v1/chat/completions多轮对话这是最核心的接口。POST /v1/embeddings文本向量化做 RAG 检索时用。POST /v1/completions补全接口现在用得比较少了。其中chat/completions的请求体关键字段就几个。model是模型名messages是消息数组每个元素有rolesystem/user/assistant/tool和contenttemperature控制随机性max_tokens限制最大生成长度stream决定是否流式返回tools是函数调用工具列表。响应体则统一是choices数组套message再带上usage统计 token 消耗。这套约定简单到没朋友所以大家愿意往它靠。现在国内能直接买到服务的云 API比如 DeepSeek、通义、智谱、Kimi基本都提供了 OpenAI 兼容地址你只需要换base_url和 key。给你看一个最直观的对比同一句“你好”请求云端 DeepSeek 和请求本地 Ollama代码几乎是复制粘贴import requests def ask(base_url, api_key, model, message): resp requests.post( f{base_url}/v1/chat/completions, headers{Authorization: fBearer {api_key}}, json{ model: model, messages: [{role: user, content: message}], stream: False, }, timeout120, ) return resp.json()[choices][0][message][content] # 云端 print(ask(https://api.deepseek.com, sk-你的key, deepseek-chat, 你好)) # 本地 Ollamaapi_key 随便填 print(ask(http://localhost:11434, ollama, deepseek-r1:7b, 你好))看到没有除了base_url、key、model三个参数不同其余一模一样。这就是“一套接口”的全部秘密。你只要能找到一个层把这两类服务都翻译成同一种格式调度问题就解决了一大半。2.2 本地推理框架如何暴露 OpenAI 兼容接口本地模型本身没有“API 概念”它是一堆权重文件需要推理框架加载后对外提供服务。好在主流推理框架现在都内置了 OpenAI 兼容端点不需要额外造轮子。Ollama启动后默认监听 11434自带/v1路径curl http://localhost:11434/v1/models就能看到模型列表用法和 OpenAI 几乎一样。vLLM生产级推理服务启动时加--served-model-name指定对外暴露的模型名默认就是 OpenAI 兼容协议适合高并发场景。LM Studio图形界面工具内置本地服务器端口默认 1234地址是http://localhost:1234/v1适合不爱敲命令的 Mac 用户。llama.cpp 的 server 子命令也会暴露/v1/chat/completions纯 C 实现资源占用低。XinferenceXorbits Inference聚合式推理平台支持把本机模型和远端模型都纳管起来对外提供 OpenAI 兼容接口。框架特点典型端口适合场景Ollama安装简单模型管理方便11434个人开发、Mac 用户vLLM高吞吐PagedAttention8000生产、高并发LM Studio图形界面开箱即用1234不熟命令行的用户llama.cpp纯 C低资源消耗8080老机器、嵌入式场景Xinference模型市场 推理管理9997多模型统一管理所以“本地模型怎么提供 API”这个问题答案已经非常统一框架帮你做兼容你只需要告诉框架模型路径和端口。真正需要你自己动手的是把多个这样的服务和一个或多个云 API 再往上层并成一个入口。3. 三条落地路线网关转发、SDK 封装、框架路由3.1 路线一部署一个 API 网关把所有模型收编成一个入口网关方案就是单独跑一个常驻服务比如 LiteLLM Proxy、One API、new-api把本地 Ollama 和各家云端 API 都配成它的“上游”。你所有的调用方只认这一个网关网关替你转发到实际模型。这个方案的好处有三个。一是调用方不需要装任何额外依赖随便一个 HTTP 客户端就能用二是可以顺带做鉴权、计费、限流团队共用很省心三是 Claude Code、Trae 这类工具只接受一个 base_url你直接把它们指向网关就行不用挨个去适配。我自己最推荐的组合是本地模型用 Ollama云端 API 用 LiteLLM Proxy 统一纳管。因为 LiteLLM 的模型配置是纯 YAML加一个供应商就是加一段配置不需要写代码。One API 和 new-api 则更偏“管理平台”界面里能可视化配渠道、发 token、看统计适合给团队当基础设施用。如果你是一两个人折腾LiteLLM 的轻量程度刚好。3.2 路线二在代码里封装一个 Provider 层如果你不想为了调度单独跑一个服务也可以在代码里做封装。最简单的做法是用 OpenAI 的 Python SDK 创建多个 client每个 client 指向不同 base_url然后写一个工厂函数按需返回。再讲究一点直接用 LiteLLM 的 Python 库它本身就是一个“代码里的路由器”。from openai import OpenAI clients { local: OpenAI(base_urlhttp://localhost:11434/v1, api_keyollama), deepseek: OpenAI(base_urlhttps://api.deepseek.com/v1, api_keysk-xxx), qwen: OpenAI(base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1, api_keysk-xxx), } def chat(provider, model, messages): return clients[provider].chat.completions.create( modelmodel, messagesmessages, )这种方案的好处是零额外组件、部署简单适合产品代码里只有你自己这一个调用方。缺点也很明显如果你把调用方写成十几个不同的服务每个服务都要维护一份这种代码那就该上网关方案了。我的建议是代码封装适合“起步阶段”和“验证想法”阶段等你真的要把模型能力做成产品卖出去网关迟早要补上。3.3 路线三让推理框架自带的路由逻辑替你转发严格来说本地推理框架很少做“转发到云”这件事真正做协议翻译的是另一类工具。比如 Claude Code 说的是 Anthropic 协议而你手头是 OpenAI 兼容的模型就需要一个“协议翻译层”对外暴露 Anthropic 的/v1/messages接口内部把请求翻译成 OpenAI 格式再路由到本地 Ollama 或某个云端 API。这类工具包括社区里的 claude-code-router以及 LiteLLM Proxy 自带的/v1/messages兼容端点。它们的本质都是“一个服务把一种协议翻译成另一种协议”。这个思路要特别记住因为你的调用方不一定都听 OpenAI 的有时候你得去迁就它们。三条路线其实不是互斥的。我的经验是本地个人折腾用路线二要给 IDE 和团队用路线一最省事遇到 Claude Code 这类特殊协议的调用方路线三必须补上。很多成熟项目是 1 3 的组合——网关对内统一 OpenAI 协议对外再暴露一个 Anthropic 兼容端点。4. 实操用一套 OpenAI 兼容接口统一调度本地 云端4.1 准备环境Ollama 部署和本地模型加载先说本地这半边。安装 Ollama 之后拉模型和起服务只需要几条命令# 启动服务Mac 上安装完默认在后台跑Linux 上一般用 systemctl start ollama ollama serve # 拉取对话模型 ollama pull deepseek-r1:7b ollama pull qwen2.5:7b # 拉取向量模型做 RAG 用体积很小 ollama pull qwen3-embedding:0.6b # 确认模型列表 ollama list验证 Ollama 的 OpenAI 兼容接口通不通直接 curl 一行命令curl http://localhost:11434/v1/models如果返回一个 JSON 数组里面包含你拉过的模型说明本地这半边已经就绪。注意 Ollama 的模型名是带 tag 的比如deepseek-r1:7b后面配网关时必须一字不差。Mac 用户要注意一点Ollama 默认会把模型放在~/.ollama/models7B 模型 Q4 量化后大约 4.7GB下载前确认磁盘余量。如果你用 M 系列芯片Metal 加速默认开启跑 qwen2.5:7b 大概能到每秒 20~40 token体感还可以。如果ollama pull qwen3-embedding:0.6b拉不到可以去 ModelScope 下权重再用 Modelfile 导入 Ollama或者直接换 ollama 官方库里的 bge-m3 这类向量模型效果差不多。4.2 用 LiteLLM 搭建统一网关配置全解LiteLLM 的安装很简单一行命令pip install litellm[proxy]然后写一个 config.yaml。下面这个配置我实际用过可以直接抄model_list: # 本地模型通过 Ollama 的 OpenAI 兼容接口接入 - model_name: local-r1 litellm_params: model: ollama/deepseek-r1:7b api_base: http://localhost:11434 # 本地 Qwen做工具调用更稳 - model_name: local-qwen litellm_params: model: ollama/qwen2.5:7b api_base: http://localhost:11434 # 云端 DeepSeek - model_name: cloud-deepseek litellm_params: model: deepseek/deepseek-chat api_key: os.environ/DEEPSEEK_API_KEY # 云端通义DashScope 的 OpenAI 兼容地址 - model_name: cloud-qwen litellm_params: model: openai/qwen-max api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: os.environ/DASHSCOPE_API_KEY # 云端 OpenAI - model_name: cloud-gpt litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY启动网关export DEEPSEEK_API_KEYsk-xxx export DASHSCOPE_API_KEYsk-xxx litellm --config config.yaml --port 4000然后随便用一个 HTTP 工具测curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-any \ -H Content-Type: application/json \ -d {model:local-r1,messages:[{role:user,content:你好}],stream:false}能正常返回内容说明本地模型已经通过网关暴露成一个 OpenAI 兼容接口。现在把 model 改成cloud-deepseek不用改任何请求结构就切到了云端。这里有个关键点要解释config.yaml 里的model_name是“对外暴露的虚拟模型名”可以随便起litellm_params.model才是真实模型。这样做的好处是业务代码永远只认local-r1这种稳定的名字底层模型升级、换供应商改配置就行代码不用动。4.3 业务代码里只用一套 client 调用网关起来了业务代码干净到令人感动。不管底层是本地还是云端你只需要一个 OpenAI SDK clientfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-any-liteLLM-key, ) def chat(model: str, user_message: str) - str: resp client.chat.completions.create( modelmodel, messages[{role: user, content: user_message}], streamFalse, ) return resp.choices[0].message.content # 先走本地失败自动切云端 try: print(chat(local-r1, 用一句话介绍你自己)) except Exception: print(chat(cloud-deepseek, 用一句话介绍你自己))流式输出也是同一套。把streamTrue然后遍历响应拿 deltastream client.chat.completions.create( modellocal-r1, messages[{role: user, content: 写一首五言绝句}], streamTrue, ) for chunk in stream: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)向量接口同理。本地用qwen3-embedding:0.6b生成 embedding云端用openai/text-embedding-3-small请求格式都是POST /v1/embeddings只是 model 名字不同。这意味着你的 RAG 管线可以先用本地向量模型把数据全部算一遍成本为零等精度不够再换云端大向量模型代码几乎不用改。4.4 模型名映射与 fallback 策略设置只有“手动选模型”还不够我理解中的“统一调度”得让系统自动做决策。这个决策逻辑一般分成两层。第一层是“同名路由”。在 LiteLLM 的 model_list 里你可以把多个真实模型配成同一个 model_name网关会按负载均衡转发。比如让local-main同时指向本地 qwen 和云端 deepseek调用方永远请求local-main网关优先把请求打到本地。第二层是“失败降级”。本地模型毕竟依赖本机资源内存不够、服务没起、生成超时都是常见故障。理想状态是本地失败自动切云端。LiteLLM 的 Router 支持配置 fallbacks在 Python 代码里可以这样写from litellm import Router router Router( model_list[ {model_name: local-main, litellm_params: {model: ollama/qwen2.5:7b, api_base: http://localhost:11434}}, {model_name: cloud-backup, litellm_params: {model: deepseek/deepseek-chat, api_key: sk-xxx}}, ], fallbacks[{local-main: [cloud-backup]}], ) resp router.completion(modellocal-main, messages[{role: user, content: 你好}])这段配置的含义是local-main这个虚拟模型名下的本地后端失败后自动切换到cloud-backup。你在业务代码里不用写任何 try-except调度层自己就把兜底做完了。等你真遇到“本地 OOM 导致整个 Agent 崩溃”的时候就知道这个能力有多救命。5. 工具链实战Claude Code、Trae、CodeGeeX 怎么接本地模型5.1 Claude Code 通过网关接入本地模型Claude Code 默认调用 Anthropic 官方 API它说的是 Anthropic 的/v1/messages协议。但 Claude Code 留了三个环境变量让你改指向ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。要让 Claude Code 用上本地模型思路就是找一个“Anthropic 协议翻译层”挡在中间对外暴露 Anthropic 接口对内转发到你的 OpenAI 兼容网关或 Ollama。社区里常用的 claude-code-router 就是干这个的LiteLLM Proxy 也提供/v1/messages兼容端点二选一即可。操作流程大概是# 1. 启动 LiteLLM 网关用前面配好的 config litellm --config config.yaml --port 4000 # 2. 设置环境变量让 Claude Code 指向网关 export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-any export ANTHROPIC_MODELlocal-qwen # 3. 启动 Claude Code claude这样 Claude Code 的对话、代码修改、文件读写都会走本地 Qwen 模型。如果你想让复杂任务走云端把ANTHROPIC_MODEL改成cloud-deepseek再启动就行。我个人习惯装一个 CC Switch 这类配置切换小工具把“本地模式”和“云端模式”存成两套 preset一键切换省得每次敲 export。需要提醒的是Claude Code 的很多高级能力依赖模型的工具调用能力本地 7B 模型在工具调用上明显弱于 Claude 官方模型。简单任务比如读文件、改配置没问题复杂的多文件重构建议还是切回云端大模型否则你会发现它在每个文件里都若有所思地改出一点小问题。5.2 Trae 添加本地模型Trae 这类 AI IDE 的做法更直接。在设置里找到模型供应商或自定义模型入口添加一个 OpenAI 兼容供应商填几样东西供应商名称随便写比如 “MyLocal”。Base URL如果是本地 Ollama填http://127.0.0.1:11434/v1如果走网关填http://localhost:4000/v1。API Key本地填ollama或任意字符串网关填你网关的 key。模型名对应你配置里的模型名。之后在对话面板里把模型切到你新加的模型就能看到本地模型开始回复。Trae 面向云端模型优化得更多接本地模型后补全速度、上下文长度和云端有明显差距但这不妨碍你用本地模型做敏感代码的本地分析。像 QClaw、WorkBuddy 这类细分工具配置本地模型的原理也完全一样找到设置里的模型供应商填 base_url 和模型名报错就按下一章的方法查。5.3 VSCode CodeGeeX 配置本地模型常见报错CodeGeeX 在 VSCode 里配置自定义模型时最容易撞见的就是那句“连接错误请确认模型配置”。根据我踩坑的经验90% 是以下三个原因。第一Base URL 写错了。CodeGeeX 要求的是完整地址如果你只写了http://localhost:11434而漏掉/v1就会在握手阶段失败。检测方法是先在浏览器或 curl 里打开http://localhost:11434/v1/models能看到 JSON 才算对。第二模型名和实际不一致。CodeGeeX 配置时模型名必须和 Ollama 的完全一致包括 tag。你写deepseek-r1而实际是deepseek-r1:7b就会报 model not found。第三Ollama 服务没起来。这个看起来低级但排查永远优先考虑它——先 curl 一下端口通不通再排查配置。把这三个点按顺序查一遍基本能解决九成问题。剩下的一成可能是 CodeGeeX 旧版本对自定义模型的协议实现有 bug建议升级插件或者换 Continue、Cline 这类协议支持更成熟的开源插件。顺便说一句Gradio 这种 Demo 框架本身不是模型服务你在 Gradio 的回调函数里调用前面那个统一 client 就行它并不参与模型调度。6. 常见问题与排查技巧实录6.1 “连接错误请确认模型配置”的排查路径这类报错本质上就是“调用方没能从你的模型服务拿到预期响应”。我建议所有遇到这种问题的朋友按下面这条链路去排查比在网上乱搜有效得多。第一步直接 curl 原始服务。“原始服务”指的不是调用方比如 CodeGeeX而是你配置里写的那个地址。先 curl 本地 Ollama再 curl 网关逐层缩小范围curl http://localhost:11434/v1/models curl http://localhost:4000/v1/models第二步curl 对话接口。确认 models 能通后再用最小请求测一次chat/completions看能不能真的生成内容。如果 curl 能通而工具报错问题基本在配置细节路径、key、模型名。第三步看日志。LiteLLM 启动时的控制台会打印每一次请求的转发目标和状态码Ollama 的日志在 Mac 上可以通过ollama serve前台启动时直接看到。状态码 404 是模型名问题401 是 key 问题500 是服务内部问题。把状态码拿出来对着查比瞎猜快得多。6.2 模型名不一致导致 404 / model not found这是统一调度场景里出现频率最高的坑而且特别隐蔽。Ollama 的模型名比如deepseek-r1:7b冒号后面的 tag 必须原样保留。但很多人配置时嫌麻烦只写deepseek-r1或者写成了deepseek-r1-7b。网关收到请求后拿着这个名字去 Ollama 查查不到就直接 404。排查方法很简单在 Ollama 里跑ollama list把你看到的模型名逐字复制到配置里。如果你用 LiteLLM 的ollama/前缀它内部会用 model 字段去调 Ollama用 OpenAI 兼容方式接入时请求体里的 model 也必须等于 Ollama 的模型名。在统一接口的世界里“模型名”就是不同服务之间的寻址 ID马虎不得。6.3 Function Calling 兼容性差异大这个话题我要单独拎出来说因为“本地模型 function calling”是很多人栽跟头的地方。OpenAI 协议里的tools参数本质上是把函数描述塞给模型让模型输出一个结构化的tool_calls结果。云端大模型训练充分基本都能稳定输出本地模型就参差不齐了。以deepseek-r1:7b为例它是推理模型蒸馏版强项是链式思考工具调用并不是它的主场经常出现“该输出 tool_calls 却输出了一堆散文”的情况。如果你要做 Agent 工具调用我实测下来 Qwen 系指令模型qwen2.5:7b、qwen3 系列更稳。这也是为什么我在前面的配置里专门加了一个local-qwen入口就是给 function calling 场景留的后路。如果你的场景必须用某个不支持工具调用的本地模型还有一个土办法不让模型做结构化输出而是把工具说明写进 system prompt让模型“用一句话告诉我你想调用哪个工具、参数是什么”然后在代码里用正则把结果解析出来。丑是丑了点但能干活应急完全够用。6.4 mac 本地部署的性能与内存踩坑Mac 是本地模型的重灾区因为 M 系列芯片用 Unified Memory跑推理确实快代价是显存和内存是同一块。7B 模型 Q4 量化后大概占 4.7GB加上系统开销16GB 内存的机器跑一个 7B 模型已经有点紧你要同时跑对话模型和向量模型或者把上下文拉得很长分分钟触发 swap 和 OOM。我的建议是对话模型和向量模型不要同时驻留。Ollama 默认会把模型 keep-alive 一段时间如果频繁换模型内存会堆积。可以设置环境变量OLLAMA_KEEP_ALIVE0再启动ollama serve让模型用完立即卸载给对话模型腾内存。另一个坑是上下文长度。同样的模型上下文从 4k 拉到 32k内存占用几乎翻倍。本地跑长上下文任务前先想想这个任务是不是真的需要那么长别上来就max_tokens拉满。还有一点如果 Ollama 速度奇慢检查一下是不是 Metal 加速没生效或者系统正在跑别的重负载任务。最后分享一个我自己的习惯。我现在写任何接模型的代码哪怕只是临时脚本也统一走网关而不是直接连 Ollama 或云 API。因为一旦习惯了“业务代码只认一个 base_url”后面加模型、换供应商、做 fallback 都是改配置的事代码基本不动。有一次我把项目从 DeepSeek 切到通义只改了 config.yaml 里两行业务代码一行没碰那种感觉确实很爽。统一接口这事儿技术难度真的不高难的是想清楚你到底要解决哪个层面的问题——是给 IDE 一个入口还是给业务代码一个抽象还是给团队一个统一网关。把这层想明白再回来选工具你会发现答案自己就浮出来了。我的建议是从 LiteLLM Ollama 这个组合开始试成本最低见效最快等跑通了再往团队级网关升级也不迟。