本地跑大模型的坑多半不在模型本身而在接入层。模型下载好了、推理服务也起来了结果客户端要连的时候发现一团乱麻Ollama 一个端口、vLLM 一个端口、Embedding 模型又一个服务每个的 API 格式还不完全一样代码里写死了一堆 base_url 和适配逻辑换个环境又得改一遍。我自己折腾过几轮之后最直接的解法就是上一个本地大模型网关然后用 CLI 来管理它。这篇文章就把我实操下来的完整过程写清楚本地大模型网关解决什么问题、CLI 怎么装怎么配、日常怎么用、出了坑怎么排查。适合已经在本地部署了 LLM、想统一管理多个模型入口的开发者也适合团队里准备搭一套共享推理服务的同学参考。1. 为什么本地部署大模型需要网关1.1 单模型直连的痛点先说说我踩过的实际场景。最开始我只是在笔记本上用 Ollama 跑 Llama 3那时候不需要网关客户端直接指向http://localhost:11434就行。但随着项目深入问题开始冒出来团队里其他人也要用这个模型我不可能把自己终端开着当服务器更不可能把本机 IP 直接甩给他们。同时跑了好几个模型有的在 Ollama 上有的用 vLLM 部署端口和 API 路径全都不一样。有些内部工具只认 OpenAI 格式的接口Ollama 原生接口虽然兼容但字段总有细微差别联调时反复出问题。想给不同的人分配不同密钥、限制调用频率完全没有现成机制。这些问题单独看都不算大凑在一起就是灾难。每次接入一个新客户端都要去查这个模型跑在哪个端口、用什么格式效率极低。1.2 网关在本地部署里的定位网关本质上就是一个流量入口把所有后端推理服务的差异屏蔽掉对外暴露一套统一的 API。你可以把它理解成公司前台你不需要知道某个部门在第几层哪个工位只要把需求告诉前台前台帮你转达。在本地大模型的场景里网关承担这几个核心职责统一入口所有模型都通过一个地址访问客户端只配一个 base_url。协议转换后端可以是 Ollama、vLLM、TGI 等任意推理框架网关统一转成 OpenAI 兼容格式。路由转发根据请求里的 model 字段把流量转发给对应的后端服务。认证鉴权给不同用户或应用分配不同 API Key控制谁能用哪个模型。负载均衡与限流同一个模型部署了多个副本时做分发防止单个实例被打爆。简单说网关解决的是“模型多了以后怎么管”的问题。单模型单用户阶段完全不需要一旦跨过这个阶段它就是刚需。1.3 为什么用 CLI 而不是 Web UI现在很多网关工具都带 Web 控制台点鼠标就能配。那为什么我推荐 CLI首先CLI 可以脚本化。我的网关配置是要跟着项目走的用配置文件加命令行的方式整个配置可以放进 Git 里做版本管理改了什么一目了然出问题也能回滚。Web 界面点点点别人问你“上次改了啥”你根本说不清楚。其次CLI 适合自动化。比如 CI/CD 流程里要临时起一个网关实例跑测试一条命令搞定Web 界面做不到。包括批量生成密钥、批量刷新配置CLI 的效率远高于鼠标操作。最后CLI 的调试体验更好。配完之后直接用 curl 验证输出干净直接不会有浏览器那堆干扰信息。我自己日常 90% 的操作都在终端里完成CLI 是最贴合这种习惯的方式。2. 环境准备与网关安装2.1 硬件与系统要求先说结论网关本身不挑配置它就是一层代理主要消耗是内存和少量 CPU。真正吃资源的是后端推理服务。我的参考配置网关节点2 核 CPU、4GB 内存即可跑 Docker 或直接裸装都行。后端推理节点取决于模型大小。7B 模型量化版大概需要 8GB 显存13B 需要 16GB 左右70B 就别想单卡了。系统Ubuntu 22.04 / Debian 12 都试过macOS 也能跑Windows 建议用 WSL2。如果你只是本地单机测试网关和推理服务放同一台机器完全没问题端口错开就行。2.2 网关软件选型市面上的选择其实不少我把自己实际用过的几类列出来对比方案定位优点缺点LiteLLMAI 原生网关轻量、纯 Python、OpenAI 格式原生支持、CLI 友好高并发场景性能不如 C 系网关APISIX / Kong通用 API 网关性能强、插件生态丰富、适合大规模生产配置复杂AI 场景要自己写插件Higress云原生网关有 AI 插件和 K8s 集成好偏云环境本地部署略重自研 Nginx 反代最简单方案零依赖纯转发没有鉴权、限流、路由能力只是个壳我自己主推 LiteLLM原因很直接它就是为“把各种模型统一成 OpenAI 兼容接口”这个场景设计的模型路由、密钥管理、限流都是开箱即用而且提供了完整的 CLI。这篇文章的实操部分也以它为主线。如果你后续流量很大、需要极致性能可以再加一层 APISIX 做流量入口LiteLLM 做 AI 网关层各司其职。但这是后话别一上来就整太复杂。2.3 安装 LiteLLM 与初始化配置LiteLLM 是 Python 包安装很简单建议用虚拟环境隔离python3 -m venv litellm-env source litellm-env/bin/activate pip install litellm[proxy]安装完确认版本litellm --version然后创建一个工作目录和配置文件。我的习惯是建一个/opt/litellm放配置和日志目录结构如下mkdir -p /opt/litellm/config mkdir -p /opt/litellm/logs cd /opt/litellm初始配置文件config.yaml长这样model_list: - model_name: llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434 - model_name: deepseek-coder litellm_params: model: vllm/deepseek-coder-6.7b api_base: http://localhost:8000/v1 general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db这里model_name是对外暴露的模型名客户端请求时用的就是这个名字litellm_params里面写后端的真实地址和框架类型。master_key是网关的管理员密钥所有管理操作都要用它认证。3. 核心配置实操从零接入本地模型3.1 配置 Ollama 模型作为上游服务我先把最简单的场景讲清楚Ollama 跑在localhost:11434网关对外暴露成 OpenAI 兼容接口。配置文件里已经写好了llama3这一段现在启动网关litellm --config config.yaml --port 4000启动成功后终端会输出当前监听的地址和可用模型列表。用 curl 直接测试curl http://localhost:4000/v1/models \ -H Authorization: Bearer sk-your-master-key能看到返回的模型列表里有llama3说明网关已经把 Ollama 的模型接管了。接下来测试对话接口curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { model: llama3, messages: [{role: user, content: 你好介绍一下自己}] }如果一切正常返回的就是 OpenAI 格式的响应。到这里你的客户端已经可以完全忽略 Ollama 的存在只用 OpenAI SDK 就能调用本地模型。3.2 接入 vLLM 高并发服务如果模型并发量上来Ollama 顶不住通常会用 vLLM 部署。vLLM 本身已经提供 OpenAI 兼容接口为什么还要过一层网关因为直接暴露 vLLM 的端口有几个问题一是没有鉴权谁拿到端口谁就能用二是多模型场景下每个 vLLM 实例一个端口客户端要维护多个地址三是没法做精细的流量控制。配置方式一样在model_list里加一项- model_name: qwen2.5-14b litellm_params: model: vllm/qwen2.5-14b-instruct api_base: http://localhost:8000/v1 api_key: dummy注意api_key这里填dummy是因为 vLLM 默认不校验密钥但 LiteLLM 内部要求这个字段存在。如果 vLLM 那边配了真实的 API Key这里就填真的。改完配置重启网关kill $(pgrep -f litellm --config) litellm --config config.yaml --port 4000这里我偷了个懒直接用kill杀进程。正规做法是用 systemd 管理后面第 4 章会讲。3.3 API Key 管理与访问控制现在网关已经能转发多个模型了但有个问题master_key权限太大了发给谁都危险。实际使用中需要给不同的人或应用生成独立的 Key。LiteLLM 提供了专门的接口生成子 Key。启动网关后在另一个终端执行curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { duration: 30d, models: [llama3], max_budget: 10.0 }这条命令的意思是生成一个有效期 30 天、只能访问llama3这个模型、总预算 10 美元的 Key。返回结果里key字段就是你要发给使用者的 Key。提示预算单位是美元但本地部署没有实际计价你可以把它当成一个配额数字来理解。比如max_budget: 1000就表示允许消耗 1000 个单位的配额。用生成的 Key 调用curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-generated-key-xxxx \ -H Content-Type: application/json \ -d {model: llama3, messages: [{role: user, content: hi}]}如果尝试访问没被授权的模型比如curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-generated-key-xxxx \ -H Content-Type: application/json \ -d {model: deepseek-coder, messages: [{role: user, content: hi}]}网关会直接返回401或403提示没有权限。这个机制在多人共享一台推理服务器时特别有用。3.4 客户端代码接入示例服务端配好了客户端接入非常简单。用 OpenAI 的 Python SDK只改两个地方base_url和api_key。from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-generated-key-xxxx, ) response client.chat.completions.create( modelllama3, messages[{role: user, content: 讲个冷笑话}], ) print(response.choices[0].message.content)代码量没有变化只是把原来指向https://api.openai.com的地址换成局域网内的网关地址。这就是网关的价值接入方完全无感该干嘛干嘛。其他语言也一样只要是 OpenAI 兼容的 SDK改base_url就能用。包括 TypeScript、Java、Go原理完全相同。4. 日常运维与进阶玩法4.1 用 systemd 管理网关进程刚才启动网关用的litellm --config config.yaml这种方式终端一关进程就没了。真实场景下必须把网关注册成系统服务让它开机自启、崩溃自动拉起。在/etc/systemd/system/litellm.service写入[Unit] DescriptionLiteLLM Proxy Afternetwork.target [Service] Userubuntu WorkingDirectory/opt/litellm EnvironmentPATH/opt/litellm-env/bin ExecStart/opt/litellm-env/bin/litellm --config /opt/litellm/config.yaml --port 4000 Restartalways RestartSec3 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable litellm sudo systemctl start litellm查看状态和日志sudo systemctl status litellm sudo journalctl -u litellm -f用 systemd 管理之后改配置只需要执行sudo systemctl restart litellm比手动杀进程干净得多。4.2 负载均衡与多副本配置当模型流量大到单实例撑不住时vLLM 可能会在同一台机器或多个机器上起多个副本。LiteLLM 可以对同一个模型配置多个上游地址自动做负载均衡。配置方式model_list: - model_name: qwen2.5-14b litellm_params: model: vllm/qwen2.5-14b-instruct api_base: http://192.168.1.10:8000/v1 api_key: dummy model_info: weight: 1 - model_name: qwen2.5-14b litellm_params: model: vllm/qwen2.5-14b-instruct api_base: http://192.168.1.11:8000/v1 api_key: dummy model_info: weight: 2这里model_name相同但api_base不同。LiteLLM 会按照weight的比例分发请求第二个实例配置了权重 2理论上会承担两倍流量。提示负载均衡的前提是多个副本加载的是同一个模型并且状态是独立无依赖的。如果你的应用依赖对话历史或者会话状态负载均衡可能会导致上下文丢失。4.3 限流与配额控制多人共享网关时最怕的就是某个人跑了个死循环脚本把资源全占了。LiteLLM 的限流配置在general_settings里general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db rate_limit: rpm: 60 tpm: 100000rpm是每分钟最多请求数tpm是每分钟最多 token 数。超过限制的请求会返回429 Too Many Requests。你也可以针对单个 Key 设置更严格的限制创建 Key 时加参数curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { models: [llama3], rpm: 10, tpm: 20000 }这样这个 Key 每分钟最多 10 个请求、2 万 token适合给测试环境或者临时接入的同事用。4.4 日志与监控网关的日志是排查问题的第一手资料。LiteLLM 默认在控制台输出请求日志但如果用 systemd 管理日志会进 journald用journalctl查看。更实用的是把请求日志写到单独的文件里。在配置里加general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db log_file: /opt/litellm/logs/access.log log_level: INFO重启后每个请求的模型名、响应时长、状态码都会记录到文件里。我通常用这条命令统计每个模型的调用量awk {print $model} /opt/litellm/logs/access.log | sort | uniq -c具体字段格式可能随版本变化但思路一样先看日志确认字段再做统计。4.5 配置热加载与版本管理CLI 最大的好处是配置即代码。我把config.yaml、systemd 服务文件、初始化脚本都放进 Git 仓库改了配置提交 MR、review 通过再部署。如果不想每次改配置都重启网关LiteLLM 还支持配置热加载。启动时加--reload参数litellm --config config.yaml --port 4000 --reload这样修改config.yaml后网关会自动重新加载配置不需要手动重启。我在本地开发环境一直开这个参数生产环境不开——生产环境追求稳定可控改动必须显式走 restart。5. 常见问题与排查技巧实录5.1 网络类问题连不上网关这是最先遇到的坑。网关启动正常但客户端从另一台机器访问不到先按这个顺序排查端口监听确认网关监听的是0.0.0.0而不是127.0.0.1。LiteLLM 默认应该是全网卡但如果用了 Docker 就要注意端口映射参数。防火墙Ubuntu 上我经常遇到 ufw 拦着放行端口sudo ufw allow 4000/tcp同一网段如果网关和客户端跨网段检查路由和网关配置确保网络连通。用curl -v看详细连接过程能区分是 TCP 层不通还是应用层报错。5.2 认证问题401 Unauthorized密钥相关的报错排查思路相对固定确认请求头是Authorization: Bearer key不是api_key之类的自定义头。检查 Key 是否过期。生成的 Key 带有效期过期后需要重新生成。如果是刚改过master_key旧 Key 会全部失效需要重新生成。在日志里看具体报错正常会明确提示是 Key 不存在还是权限不足。我自己踩过的坑是把master_key直接发给别人用了后来要回收权限很麻烦。正确做法是master_key只留给自己管理对外一律生成子 Key。5.3 后端连接问题上游服务无响应网关返回502 Bad Gateway或503说明网关本身是通的但后端推理服务连不上。排查步骤先跳过网关直接 curl 后端地址确认服务正常curl http://localhost:8000/v1/models确认配置文件里的api_base是否正确端口有没有写错。如果后端是 vLLM可能还在加载模型阶段此时请求会排队或拒绝等模型加载完成再试。如果后端机器和网关不在同一台机器检查后端机器的防火墙是否放行了对应端口。这类问题我遇到最多的是地址写错配了localhost但网关和后端是两台机器。localhost永远指向本机跨机器必须写实际 IP。5.4 模型相关报错Model Not Found请求时返回404提示模型不存在原因基本是这两种客户端传的model字段和配置里的model_name不一致。检查配置文件里model_list中的名字一字不差地复制过去。配置改了没重启或者没用--reload。确认网关加载的是最新配置可以请求/v1/models接口查看实际生效的模型列表。有一个小技巧配置model_name时不要用太绕的名字否则客户端容易拼错。保持简单直观比如llama3、qwen-14b这种。5.5 性能问题响应慢或超时同样的请求直连后端很快过网关就慢。可能的原因网关内存不足LiteLLM 默认会有一些缓存和统计功能内存太小会导致 GC 频繁。看日志是否有内存相关告警。SQLite 锁竞争如果用 SQLite 做数据库高频写入时会有锁竞争。请求量大时换成 PostgreSQL 或 MySQL。超时设置不当大模型的推理时间本来就长默认超时时间可能不够。在配置里调大general_settings: request_timeout: 600单位是秒600 秒足够覆盖绝大多数场景。别调太小否则长上下文生成任务会被误杀。5.6 日志排查实战最后分享一个实战案例。有一次同事反馈说某个 Key 调用偶尔失败我直接看日志sudo journalctl -u litellm -f找到一条429 rate limit exceeded的记录原来是这个 Key 的rpm设为 10但同事写了个并发脚本瞬间打满限额。把限额改成 50 并通知他控制并发问题解决。日志的价值就在这问题发生时有据可查不用瞎猜。所以从第一天起就要把日志管好别等出了事再补。6. 我的一点实操感悟网关这东西单机单模型阶段确实用不上但一旦开始搞多模型、多人协作它就是性价比最高的投资。CLI 管理配合 Git 版本控制整个网关配置可以做到完全可追溯这在团队协作里太重要了。我自己实操下来的心得很简单先拿 Ollama 跑通一条链路再加 vLLM再上密钥和限流一步步来别一口吃成胖子。配置文件的每个字段都搞清楚含义再改别从网上复制一大段就跑出了问题你根本不知道从哪排查。最后再分享一个小技巧把常用的网关操作封装成几个 shell 脚本比如gw-start.sh、gw-restart.sh、gw-logs.sh放仓库里共享。团队其他人不需要记住 systemd 命令直接执行脚本就行。省心也少踩坑。