给一个多人协作的 AI 应用团队搭过接口的朋友都知道，最麻烦的往往不是模型效果本身，而是每个成员各自存了一堆 API Key：模型供应商不同、Base URL 不同、调用地址散落各处，密钥一旦提交到 Git 仓库，就有被盗刷的风险。把这个场景抽象一下，其实团队需要的是一个统一 AI API 网关：把多个模型供应商的接口收拢到一个入口，所有成员只从网关拿独立的虚拟 Key，由网关负责路由、鉴权、限流和用量统计。这篇文章会从零开始，用开源项目 LiteLLM 搭建这样一套网关，并把它接入到 OpenAI 客户端 SDK 中，让朋友或队友用统一地址调用不同厂商的模型。需要提前说明的是，这里说的“共享”只覆盖一个合规前提：使用团队自己从官方渠道合法购买的 API Key，通过网关集中管理；不涉及共享订阅会员、转售密钥或绕过任何付费限制。
1. 先搞清楚统一 AI API 网关到底解决什么问题
1.1 多人协作时，密钥分散带来的三个风险
很多小团队一开始是让每个人自己去注册模型服务商，自己保存 API Key。这种方式在一个人写 Demo 时没问题，但一旦变成多人协作，问题就会慢慢暴露出来。
第一个风险是密钥泄露面变大。API Key 会出现在环境变量、IDE 配置、命令行历史、部署服务器的.env文件甚至聊天记录里。只要有一处被提交到公开仓库，整个账号都等于暴露了，别人可以拿着这个 Key 直接调用模型，费用却记在你的账单上。
第二个风险是调用入口不统一。A 成员的项目调用 OpenAI，B 成员的项目调用 DeepSeek，C 成员又用通义千问。每个项目的base_url和api_key都不一样，哪天想换模型供应商，就得逐个项目改配置，非常容易漏改。
第三个风险是成本无法归属。几个人共用同一个 Key 时，没有独立的用量统计，月底看账单只能知道总花费，谁也说不清每个模型、每个功能模块分别花了多少。预算一旦失控，定位成本也很困难。
1.2 网关的四个职责：路由、鉴权、限流、审计
统一 AI API 网关本质上是一个轻量级代理服务，客户端请求先发给网关，网关再转发给上游模型供应商。
第一个职责是路由。网关维护一张模型映射表，把客户端请求的model_name映射到上游真实模型 ID。比如客户端请求deepseek-chat，网关转发给 DeepSeek 的官方接口；客户端请求gpt-4o-mini，网关转发给 OpenAI 的官方接口。对调用方来说，只需要知道网关的地址和网关定义的模型名，不需要关心上游细节。
第二个职责是鉴权。网关向团队成员分发虚拟 Key，每个虚拟 Key 可以绑定一组允许使用的模型。成员调用时只能使用自己的虚拟 Key，管理员可以随时吊销某个 Key，而不需要更换上游供应商密钥。
第三个职责是限流。网关可以按虚拟 Key 设置每分钟请求数上限、每分钟 Token 数上限和总预算，避免某个成员误用死循环直接耗尽账户余额。
第四个职责是审计。每次请求的模型、Token 数、费用、调用来源都会记录到日志里，管理员可以通过接口查询，做到成本可追溯。
1.3 合规前提：只共享 API 入口，不共享账号会员
这一条必须单独说明。日常交流中，有人会把“和朋友分享服务”理解成把某个会员账号转发给朋友使用，或者建立一个接口转发服务，让没有购买额度的人绕过官网限制使用模型。这类做法通常违反模型供应商的服务条款，还可能导致账号封禁、Key 泄露、费用纠纷，不展开做教程也不建议尝试。
本文的方案是另一条合法路径：你和朋友在同一个项目或技术小组里，各自通过官方渠道购买 API 额度，然后把密钥统一放到自己的网关服务器上。网关只解决“多人如何安全地共用一套模型调用入口”的问题，所有人使用的仍然是合法购买的额度，没有绕过任何官方限制。
2. 技术选型和环境准备：用 LiteLLM 从零搭建
2.1 为什么选择 LiteLLM
市面上的 LLM Gateway 工具不少，但对零基础用户来说，LiteLLM 有几个明显的优势。
首先，它是开源项目，采用宽松的开源许可证，可以免费部署在自己的服务器上，数据不会经过第三方中转平台。其次，它支持大量主流模型供应商，包括 OpenAI、Anthropic、DeepSeek、通义、Kimi、Azure OpenAI 等，基本覆盖国内技术团队常用的选择。第三，它对外提供 OpenAI 兼容接口，也就是说 OpenAI SDK、LangChain 等生态里的工具可以直接把base_url指向 LiteLLM，代码改动量很小。第四，它内置虚拟 Key 管理、预算控制、请求日志等能力，不需要自己从零实现一套鉴权和统计系统。
需要说明的是，LiteLLM 版本更新比较快，具体接口和字段在不同版本可能有一些差异。本文以当前主流用法为例，落地前建议去官方仓库查看对应版本文档。
2.2 环境要求和部署方式
搭建 LiteLLM 有两种常见方式：直接使用 Python 虚拟环境安装，或者使用 Docker 部署。
对于零基础场景，最推荐的是用 Docker Compose 部署，因为环境隔离彻底、启动简单、日志查看也方便。本地只需要安装 Docker 和 Docker Compose，不需要关心 Python 版本和依赖冲突。
如果本机还没有 Docker，需要先安装 Docker Engine。Linux 服务器可以参考 Docker 官方安装文档，Windows 和 macOS 可以安装 Docker Desktop。安装完成后，通过下面命令确认环境可用：
docker --version docker compose version如果不想用 Docker，也可以使用 Python 虚拟环境：
python -m venv .venv source .venv/bin/activate pip install 'litellm[proxy]'2.3 准备合规 API Key 和端口规划
在开始部署前，需要准备以下内容：
一是上游模型服务的 API Key。例如 DeepSeek 的 Key、OpenAI 的 Key，具体从各官方平台申请。这些都是你或团队自己购买的额度，后续统一放到网关配置中。
二是服务器地址和端口。LiteLLM 默认监听 4000 端口，如果部署在云服务器上，需要在安全组或防火墙中放行 4000 端口。建议先只用 HTTP 在测试环境验证，后续上线再加 Nginx 和 HTTPS。
三是管理端密钥。LiteLLM 的管理员调用接口需要 master key，这个 Key 只保存在服务器环境变量里，不能写进代码仓库。
学习环境可以直接在本机验证；如果要在团队中使用，建议准备一台内存至少 1GB 的云服务器，因为 LiteLLM 本身占用资源不高，主要吃内存用于缓存和日志。
3. 最小可运行配置：用 config.yaml 把第一个模型跑起来
3.1 项目目录和 config.yaml
建议新建一个独立目录管理网关配置，以ai-gateway为例，目录结构如下：
ai-gateway/ ├── config.yaml ├── .env └── docker-compose.yml其中config.yaml是 LiteLLM 的核心配置，示例内容如下：
model_list: - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: os.environ/DEEPSEEK_API_KEY - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY general_settings: master_key: os.environ/LITELLM_MASTER_KEY.env文件保存敏感信息，内容如下：
DEEPSEEK_API_KEY=sk-你的deepseek密钥 OPENAI_API_KEY=sk-你的openai密钥 LITELLM_MASTER_KEY=sk-master-123456注意.env不要提交到 Git，建议加入.gitignore。
3.2 配置逐行拆解
model_list是路由表，每一项定义一个对外暴露的模型。model_name是客户端请求时使用的模型名称，建议命名简单直观；litellm_params.model是上游真实模型 ID，DeepSeek 使用deepseek/deepseek-chat这种“服务商/模型名”的写法，OpenAI 直接写gpt-4o-mini，LiteLLM 会根据前缀识别服务商。
api_key设置为os.environ/DEEPSEEK_API_KEY，表示从环境变量读取密钥，而不是直接写在 YAML 里。这样即使配置文件被误传，也不会泄露密钥。
general_settings.master_key是管理员密钥，用于调用/key/generate、/spend/logs等管理接口。换到生产环境时，这个密钥至少要改成随机长字符串。
3.3 用 Docker Compose 启动
在docker-compose.yml中写入：
services: litellm: image: ghcr.io/berriai/litellm:main-stable container_name: ai-gateway restart: unless-stopped env_file: - .env ports: - "4000:4000" volumes: - ./config.yaml:/app/config.yaml command: ["--config", "/app/config.yaml", "--port", "4000"]然后启动：
docker compose up -d首次启动会拉取镜像，需要一点时间。启动完成后查看日志：
docker compose logs -f litellm看到类似“Uvicorn running on http://0.0.0.0:4000”的日志，说明服务已经正常启动。
3.4 验证网关是否存活
用 curl 检查健康接口：
curl http://127.0.0.1:4000/health/liveliness正常返回：
{"status": "ok"}如果是云服务器，可以换成公网 IP 测试，但必须先确认防火墙和安全组放行 4000 端口。这一步没跑通，后面所有调用都会失败，所以建议作为第一个验收点。
4. 配置详解：模型路由、Master Key 和虚拟 Key
4.1 模型路由的映射关系
理解 LiteLLM 的配置，最关键的是搞清楚两层模型名。
第一层是客户端可见的model_name，第二层是上游服务商的真实模型 ID。客户端请求到达网关时，LiteLLM 根据model_name查表，找到对应的litellm_params.model，再带着该模型的上游 API Key 去请求供应商。
这种设计的好处是：上游模型可以在不改动客户端代码的情况下切换。比如把deepseek-chat指向另一个同类型模型，客户端代码仍保持model="deepseek-chat"，只需要调整配置并重启网关。
配置字段速查如下：
| 配置字段 | 作用 | 示例 |
|---|---|---|
model_name | 客户端请求时使用的模型名 | deepseek-chat |
litellm_params.model | 上游真实模型 ID | deepseek/deepseek-chat |
litellm_params.api_key | 上游供应商 API Key | os.environ/DEEPSEEK_API_KEY |
general_settings.master_key | 管理端 Master Key | os.environ/LITELLM_MASTER_KEY |
4.2 Master Key 和虚拟 Key 的分工
这里需要区分两类 Key。
Master Key 是管理员密钥，权限最大，可以调用管理接口，也可以生成和注销其他 Key。这个 Key 绝对不能发给普通成员。
虚拟 Key 是给普通成员使用的调用凭据，由管理员通过 Master Key 生成。虚拟 Key 可以绑定指定模型、设置预算和限流。朋友或团队成员只拿到虚拟 Key，拿不到上游供应商的 Key。
这样做的好处很明显：即使某个虚拟 Key 泄露，管理员可以单独注销它，不需要更换上游供应商密钥；同时由于虚拟 Key 绑定了模型范围和预算，即使被滥用，损失也可控。
4.3 限流与预算参数速查
LiteLLM 在生成虚拟 Key 时支持多个控制参数，常用字段如下：
| 参数 | 含义 | 示例值 |
|---|---|---|
models | 允许该 Key 使用的模型列表 | ["deepseek-chat"] |
max_budget | 该 Key 的累计费用上限 | 10表示 10 美元 |
budget_duration | 预算周期 | 30d表示 30 天 |
rpm_limit | 每分钟最多请求数 | 60 |
tpm_limit | 每分钟最多 Token 数 | 100000 |
字段大小写和具体格式在不同 LiteLLM 版本可能略有差异，生产环境要以当前官方文档为准。原则是：能设置预算就设置预算，宁可先收紧再放开。
5. 让朋友接入：OpenAI SDK、requests 和 curl 都能调用
5.1 给朋友生成一个独立虚拟 Key
使用 Master Key 调用生成接口：
curl -X POST 'http://服务器IP:4000/key/generate' \ -H 'Authorization: Bearer sk-master-123456' \ -H 'Content-Type: application/json' \ -d '{ "models": ["deepseek-chat", "gpt-4o-mini"], "max_budget": 20, "budget_duration": "30d", "info": {"note": "friend-a"} }'返回结果会包含生成的虚拟 Key，类似：
{ "key": "sk-新生成的虚拟Key", "models": ["deepseek-chat", "gpt-4o-mini"], "max_budget": 20, "budget_duration": "30d" }把返回的key值单独发给对应的朋友，不要发到群共享。
5.2 用 OpenAI SDK 接入
因为 LiteLLM 对外提供 OpenAI 兼容接口，朋友的项目只需要把base_url改成你的网关地址，把api_key改成虚拟 Key。
Python 示例：
from openai import OpenAI client = OpenAI( api_key="sk-虚拟Key", base_url="http://服务器IP:4000/v1", ) resp = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": "你好，请用三句话介绍微积分"}], ) print(resp.choices[0].message.content)需要注意，base_url末尾的/v1不能省略，因为 OpenAI SDK 会在后面拼接/chat/completions。
5.3 用 requests 直接调用
如果不依赖 SDK，也可以直接用 Python requests 发送请求：
import requests url = "http://服务器IP:4000/v1/chat/completions" headers = { "Authorization": "Bearer sk-虚拟Key", "Content-Type": "application/json", } payload = { "model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}], } resp = requests.post(url, headers=headers, json=payload, timeout=30) print(resp.status_code) print(resp.json()["choices"][0]["message"]["content"])这个方式适合 JavaScript、Go 等语言，只要 HTTP 客户端支持 POST JSON 就可以。
5.4 用 curl 快速验证
在服务器本机或任意能访问网关的机器上执行：
curl 'http://服务器IP:4000/v1/chat/completions' \ -H 'Authorization: Bearer sk-虚拟Key' \ -H 'Content-Type: application/json' \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}] }'正常返回是 OpenAI 格式的 JSON，choices[0].message.content就是模型回复内容。如果返回 401，先检查虚拟 Key 是否正确；如果返回 404，先检查model_name是否和配置一致。
6. 用量查询和费用管理
6.1 查看每个虚拟 Key 的用量
管理员可以通过 Master Key 查询每个虚拟 Key 的消耗：
curl 'http://服务器IP:4000/user/info' \ -H 'Authorization: Bearer sk-master-123456'返回内容里会包含当前 Key 的花费、请求数、Token 数等信息。这样当朋友反馈“我的请求被拒了”，你可以快速看到是不是预算已经用完。
6.2 查看请求日志
LiteLLM 提供了请求日志查询接口，可以查看每次请求的模型、Token 消耗和费用明细：
curl 'http://服务器IP:4000/spend/logs' \ -H 'Authorization: Bearer sk-master-123456'这个接口在生产环境非常有用，能帮助团队定位“某个功能突然费用变高”的问题。建议在接入网关后，立即让朋友跑通一次请求，然后在日志里确认这条记录是否存在，这样后面查问题就有据可依。
6.3 预算保护配置
除了在生成虚拟 Key 时设置max_budget，还可以在config.yaml中配置全局预算：
general_settings: master_key: os.environ/LITELLM_MASTER_KEY max_budget: 100这只是一种基础保护。更稳妥的做法是给每个朋友单独设置预算，目的是隔离风险，避免一个人消耗掉整个团队的额度。预算设置过低会导致请求频繁失败，设置过高则失去保护意义。建议先按每 30 天一个周期设置，观察一周后再调整。
7. 常见问题排查：从现象到根因
7.1 错误现象速查表
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 网关启动失败，端口被占用 | 4000 端口已被占用 | ss -lntp | grep 4000 | 更换端口或停止占用进程 |
| curl 健康检查不通 | 服务未启动、防火墙未放行 | docker compose ps/ 安全组规则 | 启动容器并放行端口 |
| 返回 401 | 虚拟 Key 错误或已注销 | 检查请求头 Authorization | 重新生成虚拟 Key |
| 返回 404 或模型不存在 | 请求的model_name不在配置中 | 对比 config.yaml 和请求体 | 统一模型名 |
| 上游报 401 | 供应商 API Key 错误或账户欠费 | 查看网关日志中的上游响应 | 检查环境变量和账户状态 |
| 调用超时 | 网络问题或上游服务不稳定 | 检查服务器网络、上游状态页 | 增加超时时间并重试 |
| 请求被拒绝但费用接近上限 | 虚拟 Key 预算用尽 | 查询/user/info | 提高预算或续期 |
7.2 模型访问不了怎么排查
先确认请求头里的虚拟 Key 是网关生成的，不是上游供应商的 Key。然后确认请求体里的model和config.yaml中的model_name完全一致，大小写和连字符都不能差。
接着查看网关日志。Docker 部署时执行：
docker compose logs -f litellm日志中会显示请求路由到了哪个上游地址，以及上游返回的原始错误。这一步能区分问题是出在“网关层面”还是“上游服务商层面”。
7.3 Docker 场景下的日志排查
如果容器启动后立即退出，先看日志：
docker compose logs常见原因包括：config.yaml路径错误、环境变量未加载、YAML 语法错误。YAML 对缩进非常敏感，粘贴配置时尤其要注意。
如果改了.env后不生效，需要重新创建容器：
docker compose up -d --force-recreate修改配置后也建议重启容器，让它重新加载 config.yaml。
8. 从单机 Demo 到生产环境的最佳实践
8.1 安全加固清单
把网关暴露在公网之前，至少完成以下检查：
- Master Key 使用强随机字符串，只保存在服务器环境变量中。
- 所有虚拟 Key 都设置了模型白名单和预算上限。
- 没有对外开放管理接口的默认权限，
/key/generate等接口必须带 Master Key。 - 确认 Docker 容器没有被映射到
/key/generate等危险端口之外的地址。 .env、config.yaml中不包含真实密钥的明文提交到 Git。- 定期查看
/spend/logs，发现异常消耗立即吊销对应虚拟 Key。
这一条值得反复强调：不要图省事把 Master Key 直接发给朋友，也不要关闭鉴权让所有人匿名访问。匿名访问一旦被扫描到，会出现被刷账单的风险。
8.2 Nginx 与 HTTPS 部署
生产环境不建议直接暴露 4000 端口给外部。更常见的做法是用 Nginx 做反向代理，并通过 Let’s Encrypt 配置 HTTPS。
Nginx 配置示例：
server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:4000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这样外部地址变成https://api.example.com/v1，数据链路走 TLS 加密，密钥不会以明文形式在公网传输。
8.3 合规提醒和审计建议
网关集中管理了模型访问权限，事实上也是团队的合规边界。建议做好三件事：一是只接入有正规 API 额度且允许合法调用的模型服务；二是保留调用日志，方便核对费用；三是当有人离开团队时，及时吊销对应虚拟 Key，而不是让 Key 继续留在对方手里。
如果团队人数变多，开始涉及费用分摊，可以让每个成员绑定自己的独立虚拟 Key，并通过/spend/logs定期导出账单。这样既清晰，也能避免因为共用同一个 Key 导致的费用纠纷。
8.4 后续扩展路线
这套方案跑通之后，可以根据团队需要继续扩展。
一是接入更多模型。在model_list中新增节点，给每个模型配置独立的上游 Key 即可。客户端代码不用改，只改网关配置。
二是增加负载均衡和故障转移。LiteLLM 支持把同一个模型配置多个上游 Key，或将请求路由到多个供应商，形成高可用。这个适合对稳定性要求更高的场景。
三是基于网关日志做成本报表。把/spend/logs的结果同步到数据库或 BI 工具，按项目、按成员、按模型统计费用。
对于零基础用户，这个项目最大的价值在于：你亲手建起了一个包含“路由、鉴权、限流、审计”四个能力的小型基础设施。以后无论团队接入多少模型，入口永远是那一个地址，密钥管理也有了一条清晰的边界。这就是搭建统一 AI API 网关相比直接发 Key 给朋友最本质的差别。
