先知平台API调用必须使用HTTPS+JSON格式，禁止表单提交；需严格匹配字段名、顺序及嵌套结构，携带有效valid_token和model_id，并正确解析嵌套的trend字段。
先知平台 API 调用必须走 HTTPS + JSON，不能直接 POST 表单
第四范式「先知」平台不接受 application/x-www-form-urlencoded 或表单提交，所有预测请求必须是 POST 到指定 URL，Content-Type 设为 application/json，且 body 是标准 JSON 对象。常见错误是用 curl -d "a=1&b=2" 直接传参，结果返回 400 Bad Request 或 "invalid json format"。
实操建议：
- 用
json_encode()构造请求体，别拼字符串 - 务必设置
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json'])
- 启用
CURLOPT_SSL_VERIFYPEER（设为false仅限测试环境；生产必须配好 CA 证书）
特征数据要按模型训练时的字段名和顺序组织成 array
先知模型对输入字段名极其敏感：字段名大小写、下划线/驼峰风格、是否带前缀（如 feat_）、甚至空格都必须和训练时完全一致。字段顺序也需匹配——不是按 key 排序，而是按模型元信息里定义的 schema 顺序。错一个字段名或漏一个必填字段，会直接返回 "missing required field: xxx" 或 "type mismatch for field yyy"。
实操建议：
- 从先知平台「模型详情 → 输入 Schema」页面复制原始字段列表，不要靠记忆或日志反推
- PHP 中用索引数组保持顺序：
$features = [ 'user_age' => 28, 'city_level' => 'A', 'last_order_days' => 3.5 ];
- 若模型要求嵌套结构（如
{"profile": {"age": 28}}），必须严格按 schema 深度构造，不能扁平化
调用 predict 接口需携带
先知不走 OAuth2，而是用短期有效的 valid_token 鉴权。该 token 由平台「应用管理」中创建应用后生成，不是用户登录 token，也不能复用其他接口的 token。过期时间通常为 24 小时，过期后请求返回 401 Unauthorized 或 "invalid or expired token"。
实操建议：
- 把
valid_token存在配置文件或环境变量中，禁止硬编码进 PHP 文件 - 请求头必须带：
Authorization: Bearer -
model_id是字符串（如"mdl-abc123xyz"），不是数字 ID，需从模型详情页 URL 或 API 文档中准确提取 - 生产环境建议加 token 自动刷新逻辑（调用
/v1/app/token/refresh，需额外权限）
返回结果里的 trend 字段不在顶层，而在 data.predictions[0].trend
很多人以为响应 JSON 直接有 trend 字段，实际结构是嵌套的：
{
"status": "success",
"data": {
"predictions": [
{
"trend": "up",
"score": 0.92,
"raw_output": {...}
}
]
}
}直接访问 $resp['trend'] 会得到 null，导致后续逻辑出错。
实操建议：
- 始终做多层判空：
isset($resp['data']['predictions'][0]['trend']) - 先知返回的
trend值是字符串（如"up"、"down"、"stable"），不是数字或布尔，别用== true判断 - 若批量预测（多个样本），
predictions是数组，需遍历取每个的trend
curl -v 抓包比对 header 和 body 的每个字符，再查 schema。
