5.2 模型连接与配置类问题 - 人人都会AI编程

在实际项目里，模型服务连不上、参数配错是最常见的“卡住”环节。下面列出几种真实场景和对应的排查思路，帮你快速定位并解决问题。

现象：
调用接口时返回 401 Unauthorized 或 Invalid API Key。

可能原因与解决：

Key 复制错误：检查是否多复制了空格、换行符。建议用环境变量存放（如 export OPENAI_API_KEY="sk-..."），代码里直接读取。
Key 未激活或过期：去模型提供方后台确认 Key 状态，是否需要绑定信用卡、是否已过期或吊销。
头信息写错：标准 OpenAI 接口头为 Authorization: Bearer YOUR_KEY。有些代理或者自定义接口要求 Authorization: Token xxx 或 X-API-Key: xxx，请以服务商文档为准。
Base URL 错误：如果使用了代理或三方中转，base_url 必须以 /v1 结尾（如 https://your-proxy.com/v1），同时确认该 URL 支持你调用的接口路径。

现象：
请求长时间无响应，最后抛出 ConnectionTimeout 或 ConnectionRefusedError。

排查步骤：

测试网络基础连通性：在运行代码的环境里 curl 或 ping 目标 URL。如果完全不通，检查防火墙、安全组是否放行目标端口（通常 443）。
代理设置：公司网络可能需要 HTTP/HTTPS 代理。设置环境变量 HTTP_PROXY 和 HTTPS_PROXY，或在代码里为请求库指定代理。
服务端是否在线：用官方状态页确认服务是否宕机。如果自部署模型，检查服务进程是否存活、端口是否正确监听（netstat -an | grep 8080）。
增大超时时间：长文本生成或冷启动模型可能耗时较长，适当增加请求超时（如 timeout=60 秒），避免误判。

现象：
返回结果不符合预期、输出截断、报错“参数非法”。

重点检查：

模型名称：名称必须与提供方完全一致（如 gpt-4o，不是 gpt4o；qwen:7b 而非 qwen-7b）。自部署模型用 --model 指定的名称要与代码里一致。
max_tokens 设置：若限制了过小的值，会导致回答被截断。建议根据需要设置为 512 或以上，同时注意模型上下文窗口总长度。
temperature 与 top_p：用于控制随机性。想要稳定事实性回答用低温度（0~0.3），创意写作可到 0.7~1.0。注意不同模型默认值不同。
stop 序列：如果设置了自定义停止词，可能意外中止生成。检查生成文本是否恰好包含该词。
本地模型额外参数：如 num_gpu_layers、batch_size 等，参照模型要求设置，过高导致显存溢出，过低影响速度。

现象：
本地可以 localhost:8080 访问，但其他机器无法连接。

解决要点：

绑定地址：服务启动时一定要监听 0.0.0.0 而不是 127.0.0.1。例：python -m vllm.entrypoints.openai.api_server --host 0.0.0.0 --port 8000。
防火墙/安全组：云服务器需在控制台开放对应端口（比如 8000、7860）。
Docker 端口映射：使用 -p 8080:8080 正确映射容器端口到宿主机。

现象：
批量调用时出现 429 Too Many Requests。

应对方法：

查阅速率限制：OpenAI 等有每分钟请求数（RPM）和每分钟Token数（TPM）限制，升级套餐或按需排队。
使用重试与指数退避：代码中加入重试逻辑，遇到 429 时等待 Retry-After 头指定的秒数，或自定义退避策略（如先等 1 秒，失败等 2 秒、4 秒...）。
调整并发数：控制同时发起的请求数量，用信号量或队列平滑处理。

掌握以上几类典型问题的检查方法，绝大多数模型连接与配置的坑都能快速填平。关键是先排除最基础的网络和认证，再逐步检验参数与服务侧限制。