必须升级，因文心一言v1接口已于2026年7月15日强制降级；核心变更包括认证切换至OAuth 2.0（需动态获取并缓存Access Token）、请求路径与结构更新为/v2/chat/completions及JSON Body校验、错误响应结构化、TLS 1.3强制要求及PHP/OpenSSL版本卡点。
老项目 Symfony2 升级百度 API 接口，核心问题不是“能不能升”，而是“必须升”——文心一言 v1 接口已于 2026 年 7 月 15 日起强制降级，401 Unauthorized 或 422 Unprocessable Entity 错误已成常态。旧版 Authorization: Bearer <API_KEY> 直接失效，不改认证流程，请求必败。
认证方式从 API Key 切到 OAuth 2.0 Access Token
Symfony2 原有逻辑多基于静态 api_key 配置，新协议要求先调用 /oauth/2.0/token 换取短期 access_token，且需缓存并自动刷新（有效期仅 30 分钟）。不能简单替换 header。
- 旧写法（已失效）：
curl -H "Authorization: Bearer YOUR_API_KEY" https://aip.baidubce.com/v1/chat/completions - 新流程必须补两步：① 用
client_id+client_secret换 token；② 将 token 放入Authorization: Bearer <token>，且每次请求前校验是否过期 - Symfony2 中建议封装为服务类（如
BaiduOAuthTokenProvider），利用CacheBundle存 token 到 APCu 或 Redis，避免重复请求 token 接口 - 注意：
grant_type=client_credentials是唯一支持模式，scope参数可省略，但响应中expires_in必须用于刷新判断
请求体结构从 URL 参数迁移到 JSON Body
旧版靠 ?model=ernie-bot-4 指定模型，新版必须在 JSON body 中显式声明 model 字段，且整个 payload 需符合严格 Schema 校验。漏字段或类型错，直接返回 422。
百度热榜监控 | Baidu Hot Topics Monitor. 获取百度热搜榜、搜索趋势、关键词热度 | Get Baidu trending searches, trends, keyword popularity. 触发词：百度、热搜、baidu.
- 旧请求：
POST /v1/chat/completions?model=ernie-bot-4，body 只含messages - 新请求：
POST /v2/chat/completions（路径已变），body 必须为：{"model":"ernie-bot-4","messages":[{"role":"user","content":"hello"}]} -
messages不再是顶层数组，而是嵌套在对象内；role值限定为user/assistant/system，传bot会触发422 - Symfony2 的
HttpClient（若已升级）或GuzzleHttp\Client发送时，务必设Content-Type: application/json，否则服务端拒绝解析
错误响应格式变更导致异常处理逻辑失效
旧版错误返回纯文本或简单 JSON，新版统一返回结构化错误体，含 error.code、error.message 和 error.param，原先靠 response->getStatusCode() + 字符串匹配的兜底逻辑大概率漏判。
- 例如
422响应体示例：{"error":{"code":"invalid_parameter","message":"Missing required field 'model'","param":"model"}} - 需重写异常捕获：对非
2xx响应，先json_decode($response->getContent(), true)，再检查['error']['code']是否存在，而非只看状态码 - 特别注意
401不再只是“key 错”，也可能是 token 过期；429被细化为rate_limit_exceeded或quota_exhausted，需按error.code区分重试策略 - 旧项目若用
kernel.exception事件全局处理，建议新增针对BaiduApiException的专用监听器，避免污染其他 API 错误流
兼容性陷阱：TLS 1.3 强制启用与 PHP 版本卡点
百度新接口强制 TLS 1.3 握手，而 Symfony2 默认依赖的 PHP 版本（如 5.6/7.0）根本无法协商成功，cURL error 35 或空响应是典型表现，不是代码问题，是底层协议不支持。
- PHP 必须 ≥ 7.4（推荐 ≥ 8.1），且编译时启用
openssl扩展，并确认OPENSSL_VERSION_NUMBER ≥ 0x10101000L（即 OpenSSL 1.1.1+） - 执行
php -r "print_r(openssl_get_cipher_methods());"，若无aes-128-gcm等 TLS 1.3 密码套件，说明 OpenSSL 太旧，需系统级升级 - Symfony2 的
HttpClient若未显式配置ssl_version，会 fallback 到最低可用版本；必须手动设'ssl_version' => CURL_SSLVERSION_TLSv1_3（cURL 7.52+） - 别信“加个
verify_peer=false就行”——这只会掩盖 TLS 协商失败，实际请求仍超时或中断
最易被忽略的点：新协议要求每个响应带 request_id 和 trace_id，但 Symfony2 日志中间件默认不采集这两个 header。若没在日志里透出它们，线上排查失败请求时将失去关键追踪线索，相当于盲调。
