016、第三方 API 提供商配置中转 API、Azure OpenAI 的接入与调试一、从一次诡异的 401 错误说起上周五凌晨两点我盯着终端里那行401 Unauthorized反复刷新CodeX 的对话窗口一片空白。明明 API Key 是从 Azure 门户复制粘贴的环境变量也设对了为什么就是不行后来发现问题出在api_base的路径上——Azure OpenAI 的终结点末尾多了一个/而 CodeX 在拼接请求时又自动加了一个最终变成了https://xxx.openai.azure.com//openai/deployments/...。这种双斜杠的坑我踩了整整三个小时。如果你正在用中转 API 或者 Azure OpenAI 作为 CodeX 的后端这篇文章就是为你准备的。我会把调试过程中遇到的典型问题、配置细节、以及一些“别这样写”的教训全部摊开来讲。二、中转 API 的配置别被“代理”两个字骗了很多团队为了绕过网络限制或降低成本会使用第三方中转 API比如国内的 API2D、AIProxy 等。CodeX 默认只支持 OpenAI 官方接口但通过修改环境变量可以轻松对接中转服务。2.1 核心配置项打开你的.env文件或者直接在系统环境变量里设置重点关注这几个变量# 这里踩过坑很多中转服务要求 api_base 末尾不带斜杠OPENAI_API_BASEhttps://your-proxy-domain.com/v1OPENAI_API_KEYsk-your-proxy-keyOPENAI_API_TYPEopenai关键点OPENAI_API_TYPE必须设为openai即使你用的是非官方服务。CodeX 通过这个字段判断请求格式。如果设成azure它会用 Azure 的认证逻辑去请求中转 API结果就是 400 Bad Request。2.2 中转 API 的常见调试问题问题一请求超时或连接重置中转服务通常有速率限制。CodeX 默认的超时时间是 30 秒如果中转服务响应慢比如排队就会报TimeoutError。解决办法# 在 .env 中增加超时配置单位秒OPENAI_TIMEOUT60问题二模型名称不匹配中转 API 可能把gpt-4映射成gpt-4-0613或自定义名称。CodeX 在初始化时会请求模型列表如果返回的模型名和配置的不一致就会报ModelNotFoundError。建议先手动测试curl-XGEThttps://your-proxy-domain.com/v1/models\-HAuthorization: Bearer sk-your-proxy-key看看返回的id字段是什么然后在 CodeX 的配置里用那个名字。问题三流式输出Streaming不工作有些中转 API 不支持流式响应或者实现有 bug。CodeX 默认开启流式输出如果遇到输出卡顿、只返回第一个 token 就停止可以尝试关闭流式# 别这样写直接设成 false 会导致某些功能异常# 正确做法在 CodeX 的 UI 设置里关闭“流式输出”选项STREAMING_MODEfalse不过关闭流式后长对话的响应速度会明显变慢这是取舍。三、Azure OpenAI 的接入认证方式不止一种Azure OpenAI 的配置比中转 API 复杂因为它的认证方式有两种API Key 和 Azure ADMicrosoft Entra ID。CodeX 默认支持 API Key 方式但如果你所在的企业强制使用 Azure AD就需要额外配置。3.1 API Key 方式最简单OPENAI_API_TYPEazureOPENAI_API_KEYyour-azure-api-keyOPENAI_API_BASEhttps://your-resource-name.openai.azure.comOPENAI_API_VERSION2024-02-15-preview# 这里踩过坑deployment_name 必须和 Azure 门户里的部署名称完全一致包括大小写AZURE_OPENAI_DEPLOYMENT_NAMEgpt-4-32k注意OPENAI_API_BASE不要带/openai后缀CodeX 会自动拼接。如果你在 Azure 门户复制终结点时带了/openai一定要去掉。3.2 Azure AD 认证企业环境常见如果你的组织要求使用托管身份或服务主体CodeX 需要额外配置AZURE_OPENAI_AD_TOKEN。这个 token 可以通过 Azure CLI 获取# 先登录 Azureaz login# 获取 token别这样写不要直接复制到 .envtoken 会过期az account get-access-token--resourcehttps://cognitiveservices.azure.com然后在.env中设置OPENAI_API_TYPEazureOPENAI_API_BASEhttps://your-resource-name.openai.azure.comAZURE_OPENAI_AD_TOKENeyJhbGciOiJSUzI1NiIs...坑点Azure AD token 有效期通常只有 1 小时过期后 CodeX 会报 401。解决方案有两个写一个定时任务每小时刷新 token 并重启 CodeX 服务不优雅但能用改用 API Key 方式如果安全策略允许3.3 部署名称与模型版本的匹配Azure OpenAI 的部署名称和模型版本是两回事。比如你部署了gpt-4但版本可能是0613或1106-preview。CodeX 在请求时只认部署名称不认模型版本。如果你在代码里写modelgpt-4-1106-preview而部署名称是gpt-4就会报DeploymentNotFound。正确做法在 CodeX 的配置中model字段填部署名称而不是模型 ID。四、调试技巧从日志里挖真相无论用哪种 API 提供商调试的第一步都是看日志。CodeX 默认日志级别是 INFO很多关键信息被隐藏了。建议开启 DEBUG 级别# 在 .env 中设置LOG_LEVELDEBUG然后重启 CodeX观察终端输出。你会看到类似这样的信息[DEBUG] Sending request to https://your-proxy-domain.com/v1/chat/completions [DEBUG] Headers: {Authorization: Bearer sk-xxx, Content-Type: application/json} [DEBUG] Request body: {model: gpt-4, messages: [...]} [DEBUG] Response status: 200 [DEBUG] Response body: {id: chatcmpl-xxx, ...}重点关注请求的 URL 是否正确有没有双斜杠、路径是否完整返回的 HTTP 状态码401 是认证问题404 是终结点或模型不存在429 是限流错误信息中的code和message字段Azure 的返回格式和 OpenAI 不同五、个人经验别让配置成为瓶颈我见过太多团队花了两周时间调 API 配置最后发现只是环境变量名拼写错误。这里分享几个我自己的习惯先裸测再集成不要直接让 CodeX 去连 API。先用 curl 或 Postman 手动发一个请求确认 API 本身是通的。这一步能排除 90% 的配置问题。环境变量统一管理不要手动改.env文件。用direnv或dotenv工具每个项目一个独立的.envrc避免不同项目之间的变量冲突。版本锁定Azure OpenAI 的 API 版本更新频繁CodeX 可能不支持最新的预览版。我一般锁定一个稳定版本比如2024-02-15-preview直到确认新版本兼容再升级。限流处理中转 API 和 Azure 都有速率限制。CodeX 默认没有重试机制建议在.env中开启自动重试OPENAI_MAX_RETRIES3OPENAI_RETRY_MIN_WAIT1OPENAI_RETRY_MAX_WAIT30不要迷信“一键配置”网上很多教程说“复制粘贴就能用”但实际环境千差万别。你的网络代理、防火墙、DNS 解析都可能影响连接。遇到问题先检查网络再检查配置。最后如果你用的是 Azure OpenAI强烈建议在 Azure 门户的“网络”选项卡里把“允许来自公共网络的访问”打开如果安全策略允许。否则即使配置完全正确CodeX 也会因为 IP 限制而无法连接。这个坑我帮三个同事排查过每次都是这个原因。配置搞定之后CodeX 的体验会非常丝滑。下一篇我会讲如何用 CodeX 对接本地模型比如 Ollama 和 llama.cpp那又是另一套完全不同的玩法了。