接入只需改三处
接入自托管服务通常只需三处改动：把接口地址指向网关而不是直连引擎、使用下发的密钥、把超时按最长输出时长设置。再确认客户端库版本对所需参数的支持范围，避免出现参数写了却不生效的情况。团队里统一封装后，这些细节只需要维护一份。
基本信息
| 适用平台 | 各语言的 OpenAI 兼容客户端库 |
|---|---|
| 三处关键配置 | 接口地址、密钥、超时 |
| 版本要求 | 客户端库版本要与目标参数匹配 |
| 管理要求 | 密钥走配置或环境变量，不写进代码 |
Python 客户端
Python 客户端
from openai import OpenAI
client = OpenAI(base_url="http://<网关地址>/v1", api_key="<KEY>", timeout=600.0)
r = client.chat.completions.create(model="<别名>", messages=[{"role": "user", "content": "你好"}])
# 长输出场景超时给足，避免生成中途被客户端主动放弃典型使用场景
- 多项目接入：统一入口与密钥，便于审计与限流
- 长输出任务：超时按最长生成时长设置
- 重试策略：只对明确失败重试，避免重复计费
- 日志字段：统一记录请求标识，便于与网关日志对齐
- 版本对齐：客户端库与网关支持的参数范围要保持一致
- 联调自检：接入后先跑一条最小请求，确认整条链路通
三处配置的常见坑
| 配置项 | 常见错误 | 后果 |
|---|---|---|
| 接口地址 | 直连引擎或漏掉版本路径 | 绕过网关，鉴权与限流失效 |
| 密钥 | 硬编码或多人共用同一个 | 泄露难以定位，轮换成本高 |
| 超时 | 按平均耗时而不是最长耗时设置 | 长输出被客户端提前放弃 |
团队内固定客户端库版本与统一封装：超时、重试、日志字段集中管理，升级前先做回归。
密钥不要写进代码仓库：走环境变量或密钥服务，轮换时只改一处。
客户端超时、网关超时与引擎侧时间上限要逐层加长：任何一层先超时，链路就在那一层断开。
把请求标识写进客户端日志：排障时能直接拿它去网关与引擎日志里检索，不必再比对时间戳。