如果你的代码现在调用的是 OpenAI，迁移到阿里云百炼这件事，官方文档的说法是「您只需调整 API Key、BASE_URL 和模型名称」。这句话是真的，但它省略了一个前提：BASE_URL 已经不是 dashscope.aliyuncs.com 了。
2026 年 10 月 16 日晚，我们把百炼「API 参考（模型）→ 工具包/框架 → OpenAI兼容-Chat」这条路径完整读了一遍，并对照官方文档实拍核对了 BASE_URL、地域、参数、错误码四张表。结论是：迁移的代码改动确实只有 3 行，但这 3 行踩中的任何一个陷阱，都会以「401」「404」或者「连不上」的形式出现，而且没有一个是代码逻辑问题。
一、先说结论：BASE_URL 已经不是 dashscope.aliyuncs.com 了
这是本次核验里最值得单独拎出来的一条。百炼文档在「兼容 OpenAI 需要信息 → BASE_URL」一节写得很明确：为华北 2（北京）、新加坡、中国香港三个地域推出了业务空间专属域名，官方建议迁移过去。
| 地域 | OpenAI SDK 形式（BASE_URL） |
|---|---|
| 华北 2（北京） | https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 |
| 美国（弗吉尼亚） | https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1 |
| 新加坡 | https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 |
| 日本（东京） | https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1 |
其中 {WorkspaceId} 是你的业务空间 ID，在百炼控制台的「业务空间详情」页面可以查到。它不是你的账号 ID，也不是 API Key 的一部分——填错同样会 401。
如果通过 HTTP 直连，endpoint 则是：
- 北京：
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions - 弗吉尼亚：
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions - 新加坡：
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions - 东京：
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
官方对旧域名的态度是：「现有域名仍可正常使用」——所以 dashscope.aliyuncs.com 和 dashscope-intl.aliyuncs.com 并没有下线。但文档明确写了「建议优先使用业务空间专属域名」，理由是为推理请求提供「卓越的性能和更高的稳定性」。这意味着新旧域名会长期并存，迁移是渐进式的，不是截止日期式的。
二、陷阱 1：跨地域调用返回 401，而错误信息极具误导性
这是四个陷阱里最容易让人排查半天的一个。
百炼 API Key 是按地域绑定的。文档在「调用失败排查 → 跨地域调用」一节写得很清楚：调用某个地域的 base_url 时，必须使用在同一地域创建的 API Key；用其他地域的 API Key 调用该地域 endpoint 会被鉴权拒绝。这条规则适用于所有提供 endpoint 的地域，包括华北 2（北京）、美国（弗吉尼亚）、新加坡和日本（东京）。
文档给出的具体现象是：使用北京地域 API Key 调用弗吉尼亚地域 endpoint 时，返回 HTTP 401，错误信息为 Incorrect API key provided，错误码为 invalid_api_key。
麻烦的地方在于，这个提示和「你的 Key 真的失效了」「你的账号欠费了」「你的权限不够」几乎长得一模一样。一个多地域部署的服务，只要有一个 Key 放错了地域，监控面板上看到的就是一片 invalid_api_key，而实际上 Key 是好的、地域是错的。
排查顺序建议就按官方给的来：先确认 BASE_URL 的地域，再确认 API Key 的创建地域，两者必须一致；如果 Key 本身没问题，再查权限和额度。这是本文四个陷阱里唯一一个「配置对了就完全消失」的坑——代价是你得知道它存在。
三、陷阱 2：Qwen-Audio 不支持 OpenAI 兼容协议
这条被放在「支持的模型列表」章节的末尾，位置很靠后，但它决定了你的音频链路能不能走兼容层。
文档原话：「Qwen-Audio 不支持 OpenAI 兼容协议，仅支持 DashScope 协议。」
换句话说，如果你现在有一套 OpenAI 风格的统一客户端，里面混了文本模型和 Qwen-Audio，那么切到兼容模式之后，文本部分会正常工作，音频部分会失败——而这个失败和模型能力无关，纯粹是协议层不匹配。这类问题在灰度切换时特别隐蔽，因为同一份代码、同一个 SDK，只是 model 字段不同。
更值得注意的是，兼容层支持的模型范围比很多人以为的宽。文档列出的支持清单包括：Qwen 大语言模型（商业版、开源版）、Qwen-VL、Qwen-Coder、Qwen-Omni、Qwen-Math，以及 DeepSeek、Kimi、GLM、MiniMax 等三方直供模型。但三方直供模型仅在中国站的华北 2（北京）地域可用，调用前需要在控制台先开通对应服务。文档以 SiliconFlow DeepSeek 为例说明了流程：搜索 deepseek → 找到 SiliconFlow DeepSeek 模型卡片 → 单击立即开通 → 确认授权。
四、陷阱 3：tools 和 stream=True 不能同时用
这一条藏在参数表 tools 那一行的说明里，属于典型的「不看就会撞」型限制。
文档在 tools 参数下写明：「tools 暂时无法与 stream=True 同时使用。」并且在 function call 流程中，无论是发起 function call 的轮次，还是向模型提交工具函数的执行结果，均需设置 tools 参数；当前支持的模型包括 qwen-plus 和 qwen-max。
这条限制的实际影响是：如果你从 OpenAI 迁移过来的代码是「流式 + 工具调用」的组合（这在 Agent 类应用里很常见，因为要边生成边执行），在百炼兼容层上会直接失效。可选的处理路径只有两条——要么关掉流式，要么把工具调用拆成非流式的多轮（文档给出的 function call 示例正是这种 while 循环多轮结构）。
顺带把参数表里另外几处容易看漏的限制一起列出来：
| 参数 | 限制 |
|---|---|
presence_penalty |
目前仅在千问商业模型和 qwen1.5 及以后的开源模型上支持 |
n |
取值 1-4；当前仅支持 qwen-plus，且传入 tools 时固定为 1；不增加输入 Token 消耗，只增加输出 Token 消耗 |
enable_search |
需通过 extra_body={"enable_search": True} 配置；qwen-long 暂不支持 |
stop |
为 array 类型时，不可将 token_id 和字符串混用（如不可写 ["你好",104307]） |
system_fingerprint（返回） |
当前暂不支持，返回为空字符串 |
五、陷阱 4：第三方客户端里 Base URL 要填「不含 /chat/completions」的地址
最后一条关于第三方客户端配置，文档给了很具体的填法。
以智谱客户端为例：在「服务商设置」中选择自定义服务商，然后 Base URL 填写以 /compatible-mode/v1 结尾、不含 /chat/completions 的地址。文档特别提醒：各地域的 Base URL 不同，需与 API Key 所属地域保持一致。
为什么强调「不含 /chat/completions」，因为大多数第三方客户端会在这个 Base URL 后面自动拼接路径。如果你在 Base URL 里手写了 /chat/completions，最终请求就会变成 .../chat/completions/chat/completions，返回 404——而 404 在百炼的排查清单里被归到「配置问题」，很容易和 BASE_URL 写错地域混在一起。
文档还给出了两个第三方客户端特有的错误判别：
- 返回 HTTP 400，且
error.message为current user api does not support http call、error.type为invalid_request_error—— 说明当前填写的模型不支持通过 OpenAI 兼容接口进行 HTTP 调用，需更换为「支持的模型列表」中的模型后重试。 - 文档在模型名称一栏也补了一句提示：例如 qwen3.7-plus 仅作为模型名称示例，不表示免费额度承诺。这句话值得单独拎出来——很多迁移文档里的模型名会被读者误读成价格承诺。
六、状态码速查：同一个 429 挂了两条完全不同的原因
百炼兼容层的状态码表不长，但有一个细节值得注意：429 出现了两次，而两条的含义完全不同。
| 状态码 | 错误码 / 提示 | 含义 |
|---|---|---|
| 400 | Invalid Request Error | 输入请求错误，看具体报错信息 |
| 401 | Invalid API-key provided | API Key 不正确（很可能是跨地域） |
| 429 | Rate limit reached for requests | QPS、QPM 等超限 |
| 429 | You exceeded your current quota… | 额度超限或者欠费 |
| 500 | The server had an error… | 服务端错误 |
| 503 | The engine is currently overloaded… | 服务端负载过高，可重试 |
一个反直觉的工程结论是：你的重试策略不能只看状态码。两个 429 一个该退避重试（限流），一个重试也没用（额度/欠费），必须读 body 里的 message 区分。如果限流逻辑只判断 status == 429 就退避重试，在欠费场景下会陷入无限重试。
七、完整迁移检查清单
把上面四个陷阱和参数表约束合起来，一次迁移可以按这个顺序走：
- 确认业务空间 ID → 百炼控制台「业务空间详情」页面，拿到
{WorkspaceId}。 - 选地域 → 国内用户默认华北 2（北京）；需要三方直供模型（DeepSeek/Kimi/GLM/MiniMax）则只能选北京。
- 建对应地域的 API Key → 就在你要用的那个地域的控制台里创建，不要复用其他地域的 Key。
- 改 BASE_URL → 用
{WorkspaceId}专属域名，以/compatible-mode/v1结尾；第三方客户端不要手动补/chat/completions。 - 改 model 名 → 换成千问支持列表里的模型名，注意工具调用当前只支持 qwen-plus 和 qwen-max。
- 排查流式 + 工具调用组合 → 百炼兼容层不支持同时开启，二选一。
- 确认没有混用 Qwen-Audio → 它只支持 DashScope 协议，不走兼容层。
- 重试策略按 body 分流 → 429 要区分限流与欠费，不要只看状态码。
- API Key 放环境变量 → 文档反复推荐
DASHSCOPE_API_KEY环境变量方式，并提示写在代码里「泄露风险会提高」。
八、本次核验的证据与口径
本文只使用官方文档作为事实来源，所有参数名、错误码、状态码、限制条件均为文档原文，不做推断。补充说明：
- 文档来源：阿里云帮助中心「大模型服务平台百炼 → API参考（模型）→ 工具包/框架 → OpenAI兼容-Chat」等页面，本文外链均指向官方地址。
- 截图：2026-10-16 使用无头 Chrome 实拍阿里云帮助中心官方页面，非占位图；文中 5 张配图分别对应 BASE_URL 段、模型列表段、参数表段、第三方客户端配置段。
- 口径：本文统计的参数与状态码数量，以本次抓取的页面内容为准；文档更新后条目可能变化，请以官方页面为准。
- 未知项：本文未对各地域的延迟、吞吐做实测，官方文档也未提供这类对比数据，因此不做性能排名类结论。
如果你正在做这次迁移，最值得先确认的一件事是：你的 BASE_URL 是不是还在用 dashscope.aliyuncs.com。如果还在用，它现在能跑，但你在新旧域名并存的过渡期里；如果你已经换了专属域名，那 401 大概率不是 Key 的问题，是地域的问题。
