必须严格遵循Kimii官方三步分片上传流程：先调用/upload_init获取upload_id和预签名URL，再逐块PUT上传字节范围数据，最后用ETag调用/upload_complete合并；PHP 7.4需精确控制分片大小（通常5MB）、禁用输出缓冲、手动读取文件流。
PHP 7.4 调用 Kimi 接口上传大文件，不能直接传整个文件——Kimi（由月之暗面提供）的 API 明确要求文件需先通过其指定的「分片上传流程」接入，不支持传统 multipart/form-data 一次性上传。核心不是 PHP 自己“拆”，而是严格遵循 Kimi 的预签名分片协议：先申请上传凭证，再分块上传，最后合并提交。
必须走 Kimi 官方分片上传流程
Kimi 的大文件上传（如 PDF、PPT、长音频等）强制使用三步式分片机制，PHP 7.4 只负责按其 API 规范调用，不能跳过或简化：
-
第一步：发起 upload_init 请求
向
https://api.kimi.ai/v1/upload_init（以实际文档为准）POST 文件元信息（文件名、大小、MIME 类型），获取upload_id和每个分片所需的presigned_urls数组（含有效期、HTTP 方法、headers、签名 URL）。 -
第二步：逐块上传分片
使用 cURL 或 Guzzle，对每个
presigned_urls[i]发起 PUT 请求（非 POST），上传对应字节范围的数据块（如 0–5242879 字节）。注意：必须严格按字节偏移切分，不可用 JavaScript 的slice()逻辑替代；PHP 需用fopen(..., 'rb')+fseek()+fread()精确读取每块。 -
第三步：提交合并请求
所有分片上传成功后，调用
/v1/upload_complete提交upload_id和各分片的 ETag（即响应头Etag值），Kimi 后端完成校验与合成，返回可用于后续推理的file_id。
PHP 7.4 实现关键点
避免常见踩坑，这些细节直接影响是否能成功上传：
Kimi Search
下载
使用 Moonshot Kimi API 的 $web_search 内置工具进行联网搜索。当需要进行网络搜索获取实时信息时使用，支持中文和英文搜索查询。需要配置 MOONSHOT_API_KEY。
-
禁用 output buffering 和超时干扰：上传过程可能耗时较长，开头加
ob_end_clean(); set_time_limit(0);，但不要依赖max_execution_time——分片是多次独立 HTTP 请求，每次应控制在 30 秒内完成。 -
分片大小必须与 Kimi 要求一致：官方通常要求 5MB/块（5242880 字节），最后一块可小于该值。PHP 计算方式：
$chunkSize = 5 * 1024 * 1024;，用ceil($fileSize / $chunkSize)得总块数。 -
手动构造字节范围，不依赖 $_FILES：Kimi 不接收表单上传，PHP 只需读本地文件流。示例片段：
for ($i = 0; $i < $totalChunks; $i++) { $start = $i * $chunkSize; $length = min($chunkSize, $fileSize - $start); $fp = fopen($filePath, 'rb'); fseek($fp, $start); $chunk = fread($fp, $length); fclose($fp); // 再用 cURL PUT $chunk 到 presigned_urls[$i] } -
检查并透传所有 presigned_url headers：比如
x-amz-date、content-type、content-md5（如有要求），缺失会导致 403 或 400 错误。
不需要调 PHP 或 Nginx 的上传限制参数
因为整个流程绕过了 PHP 的 $_FILES 机制和 Web 服务器的 body 解析层：文件不经过 upload_tmp_dir，不触发 upload_max_filesize、post_max_size、client_max_body_size 等限制。你只需确保 PHP 能发起外部 HTTPS 请求（cURL 启用、SSL 证书可信）、磁盘有读取权限、网络能直连 Kimi API（注意企业防火墙或代理拦截）。
立即学习“PHP免费学习笔记（深入）”；
失败时重点排查方向
上传中断或报错，优先查这四类问题：
- upload_init 返回的 presigned_urls 过期：Kimi 签名通常仅 10–30 分钟有效，上传需在此窗口内完成；建议分片上传逻辑不阻塞、不休眠。
-
ETag 不匹配：PUT 分片响应头中的
Etag必须原样传给upload_complete，大小写敏感，带引号与否需一致。 -
字节偏移错位或重复：例如第 2 块从 5242880 开始，但读了 5242881 字节，导致后续全部错位；可用
md5_file()对每个分片临时文件校验。 - 未处理 429 或 503 重试：Kimi 接口可能限频，对非 2xx 响应需指数退避重试（如 1s、2s、4s），而非直接报错退出。
