千问API调用错误需按五步排查：一查API Key有效性与配置；二验Base URL及接口路径准确性；三审请求体结构与Content-Type头；四核时间戳、签名及权限校验；五排服务端口占用与进程残留。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在调用千问大模型API时收到错误码，问题通常集中在认证、地址、参数、权限或服务状态等基础环节。以下是针对性的排查与解决步骤：
一、检查API Key有效性与配置方式
无效、过期或格式错误的API Key是触发401、403错误的最常见原因，需确认其来源、完整性及使用上下文是否匹配。
1、登录阿里云百炼控制台，核实该API Key处于“启用”状态且未被手动禁用。
2、复制API Key时确认是否完整包含sk-前缀，且末尾无不可见空格或换行符。
3、若在Unity、Dify或LangChain等平台中调用，检查Key是否通过环境变量、配置文件或安全资源对象注入，而非硬编码在源码中。
4、确认当前账号已开通所调用模型（如qwen-plus、qwen3-1.7B）的服务权限，并未超出调用配额上限。
二、验证Base URL与接口路径准确性
Base URL错误会导致连接拒绝、超时或404响应，本质是客户端无法定位到正确的服务入口，尤其在本地部署或镜像环境中极易出错。
1、对于CSDN星图等动态镜像服务，必须使用该会话实时生成的地址，不可复用他人截图中的URL。
2、运行命令curl -s http://localhost:8000/v1/models（端口依实际部署而定）验证本地服务是否正常响应。
3、确认Base URL结尾包含/v1路径，例如https://dashscope.aliyuncs.com/compatible-mode/v1，缺失将导致404。
4、若使用OpenAI兼容模式，确保URL协议为http（本地）或https（云端），且域名与模型ID严格对应。
三、审查请求体结构与Content-Type头
API对JSON格式、字段命名、嵌套层级和HTTP头有强校验，微小偏差即引发400或415错误，需逐项比对官方示例。
1、请求头中必须显式声明Content-Type: application/json，不可省略或拼写为application/json; charset=utf-8等变体。
2、请求体（payload）须为合法JSON，使用在线校验工具验证括号、引号、逗号是否闭合，避免Python字典直转导致的单引号问题。
3、核对model字段值是否为文档指定的模型ID（如qwen3-1.7B），而非中文名或界面显示名。
4、messages数组中每条消息必须含role（system/user/assistant）与content字段，且content为字符串类型，不可为null或对象。
四、确认时间戳、签名与权限校验逻辑
当错误码为403且参数齐全时，多因签名失效、时间偏移或权限策略拦截，需同步校验客户端与服务端时间及密钥一致性。
1、获取当前毫秒级时间戳（Date.now()或int(time.time() * 1000)），确保与服务端时差在±5分钟窗口内。
2、若使用HMAC-SHA256签名，确认签名基字符串（signature base）按顺序拼接requestId、timestamp、functionName及parameters的JSON序列化结果。
3、检查签名计算所用密钥是否为服务端配置的MIDDLEWARE_SECRET，而非API Key本身。
4、确认functionName与目标接口路径一致，例如调用重排序接口时应为rerank而非chat。
五、排查服务端口占用与进程残留
本地部署服务启动失败常表现为连接超时或拒绝连接，根本原因多为端口被占或后台残留进程干扰新实例运行。
1、执行lsof -i :7860（macOS/Linux）或netstat -ano | findstr :7860（Windows）查出占用7860端口的PID。
2、使用kill -9 [PID]（macOS/Linux）或taskkill /F /PID [PID]（Windows）强制终止该进程。
3、运行pkill -9 -f qwen或ps aux | grep "reranker"清理可能存在的隐性残留进程。
4、重启服务前，检查配置文件中绑定地址是否设为0.0.0.0:7860而非仅localhost:7860，否则外部客户端无法访问。
