AI中转服务怎么配置API密钥和代理地址

文章导读
配置 AI 中转服务的密钥和代理地址,实际是两件需要分开处理的事:密钥决定「请求是否被认可」,代理地址决定「请求从哪条网络路径出去」。多数情况下,SDK 只需要 base_url 和 api_key 两个输入;只有当运行环境本身出网受限时,才需要额外设置 HTTP 代理。因此先判断中转服务是否已经替你完成出网,再决定是否叠加代理,能避免配置多一层导致排障困难。
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

配置 AI 中转服务的密钥和代理地址,实际是两件需要分开处理的事:密钥决定「请求是否被认可」,代理地址决定「请求从哪条网络路径出去」。多数情况下,SDK 只需要 base_url 和 api_key 两个输入;只有当运行环境本身出网受限时,才需要额外设置 HTTP 代理。因此先判断中转服务是否已经替你完成出网,再决定是否叠加代理,能避免配置多一层导致排障困难。

建议按「先定 base_url 与密钥来源,再定是否需要代理」的顺序处理:密钥通过环境变量或密钥管理注入,不写进代码仓库;代理只在出网受限的环境变量中设置,并用 NO_PROXY 排除内网域名。改完后分别验证网络可达性和鉴权结果,区分 401、403、404、407 四类信号再定位问题。共用中转服务的数据去向和稳定性需要结合环境确认,敏感数据不建议直接经第三方中转。

先确认当前场景和目标

先把场景归类,再动手改配置。常见有三类:第一类是客户端直接调用第三方 AI 服务,可以用中转域名替换官方地址,此时通常不需要代理;第二类是服务部署在内网或受限出网环境,需要经 HTTP 代理出网,中转地址和代理地址同时存在;第三类是在浏览器或移动端直连,这种场景下密钥一旦进入前端就等于公开,应当改成由自己的服务端转发。

动手前建议确认这几项判断条件:

  • 中转服务是否已经代为出网?如果是,本地再加代理可能造成多层转发,排障时要能被单独关闭。
  • 运行环境是本地终端、容器还是 CI?容器和 CI 通常不继承宿主机的环境变量,需要显式传入。
  • 代码中的 HTTP 客户端是否读取 HTTPS_PROXY 等环境变量?Python 的 requests 默认读取,httpx 需要 trust_env 相关设置,部分 SDK 会自建连接,需要显式传入代理参数。
  • 中转域名的路径规则:base_url 是到域名根还是已经包含 /v1,这一点直接影响后面是否出现 404。
  • 是否需要按环境区分密钥,避免测试流量和线上流量共用同一把 key。

按这个顺序处理

第一步是确定两个变量名,并把它们和代码解耦。下面这份写法可以作为通用配置示例,域名和 key 都要替换成你自己的内容,文件不要提交到仓库:

# .env 示例,仅本地使用
AI_BASE_URL=https://relay.example.com/v1
AI_API_KEY=sk-replace-with-your-key

# 仅在出网受限时启用
HTTPS_PROXY=http://10.0.0.10:3128
HTTP_PROXY=http://10.0.0.10:3128
NO_PROXY=127.0.0.1,localhost,.internal

第二步是确认 base_url 的拼接方式。多数兼容 OpenAI 协议的中转服务,请求路径由 base_url 加上 /chat/completions 组成,如果 base_url 末尾已经带 /v1,代码里就不要再拼一次;末尾多余的斜杠也建议统一去掉。

第三步是在服务端注入密钥。本地开发可以用环境变量或 .env;容器环境建议用编排层的环境变量或独立密钥文件挂载;CI 中使用平台提供的加密变量。密钥只放在请求头里,不要拼进 URL 查询参数,因为 URL 更容易被日志和中间链路记录。

AI中转服务怎么配置API密钥和代理地址

第四步是决定代理放在哪里。代理地址只影响出网,和鉴权无关,所以它应该配置在运行环境层面,而不是写死在业务代码里。下面这段请求骨架用于验证配置是否成立,可以放在本地或容器内执行:

import os
import httpx

base = os.environ['AI_BASE_URL'].rstrip('/')
key = os.environ['AI_API_KEY']

# trust_env=True 时会读取 HTTPS_PROXY / NO_PROXY
with httpx.Client(timeout=30.0, trust_env=True) as client:
    resp = client.post(
        base + '/chat/completions',
        headers={'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json'},
        json={'model': 'your-model', 'messages': [{'role': 'user', 'content': 'ping'}]},
    )
    print(resp.status_code)
    print(resp.text[:300])

如果使用的 SDK 不读取环境变量,可以在客户端初始化时显式传入代理参数,或者在进程启动前导出变量。model 取值需要按中转服务支持的模型名填写,不能照搬官方名称。分环境时,建议本地、测试、线上各用一套 key 和 base_url,改完一处只影响一处。

改完后怎么验证

验证要拆成两步,先看网络通不通,再看鉴权过不过。第一步用 curl -I 或 curl -o /dev/null -s -w '%{http_code}' 请求中转域名下的一个普通路径,观察是拿到 HTTP 响应还是连接超时、DNS 解析失败。拿到任何 HTTP 状态码,说明出网路径已经通,剩下的是业务层问题。

第二步发一条最小请求,按状态码判断:

AI中转服务怎么配置API密钥和代理地址
  • 200 且响应体里带正常的消息结构,说明 base_url 和密钥都生效。
  • 401 通常是密钥缺失、已失效或请求头格式不对,先检查是否漏了 Bearer 前缀和空格。
  • 403 多与中转服务的权限、来源限制或模型未开通有关,需要和提供方确认。
  • 404 优先怀疑路径拼接,检查 base_url 是否重复带 /v1 或末尾多余斜杠。
  • 407 表示代理需要认证,凭据同样不能写进仓库。
  • 连接超时或 DNS 失败,检查 HTTPS_PROXY 是否生效,以及 NO_PROXY 是否把内网域名误排除或误包含。

还需要做一个对照验证:临时取消代理设置,再发一次同样的请求。如果取消代理后反而成功,说明代理不是必需项,或者是 NO_PROXY 配置有问题;如果取消代理后失败,则确认代理确实是出网前提。最后检查应用日志,确认请求头中的密钥没有被打印出来。

容易忽略的边界

代理变量的兼容性需要留意:HTTPS_PROXY 和 https_proxy 的大小写在不同客户端里支持程度不一样,部分库只认其中一种;有的 SDK 使用自己的会话对象,完全不读取环境变量,此时必须在代码里显式传参,否则会出现「命令行 curl 通、程序里不通」的情况。

base_url 和密钥的绑定关系也容易出错。不同中转服务的域名、路径前缀和模型名往往不通用,把官方文档里的地址直接换域名而不改路径,出现 404 的概率很高。密钥轮换时,要同步更新所有环境,避免残留旧 key 的进程继续发出 401 请求。

数据边界同样不能忽略。共用或来源不明的中转服务,请求内容和返回结果会经过第三方链路,含个人信息、内部代码或商业数据的请求不建议走这类通道;对稳定性有明确要求的业务,需要结合自身环境确认是否可接受。

不适用与回退建议:如果运行环境本身无法出网,也无法配置代理,那么再调整密钥也无意义,此时应回到「让服务端具备可控出网路径」这个前置问题。临时把请求切回直连或换一个已知可用的中转地址,只适合用于排障对照,不适合长期作为配置方案,因为密钥和地址的散落会增加后续维护成本。