Adobe Stock 元数据 CSV 表头被秒拒的原因与修复方法

手工拼凑的 CSV 文件往往在第一行就被平台拒绝，而错误信息却指向数据本身，这让排查变得异常困难。一位向量素材创作者在第一批 40 个文件全部被拒后，总结出表头格式才是元数据上传的真正门槛。

表头是 Adobe 的第一道过滤网

Adobe Stock 的上传器要求 CSV 恰好包含五列，顺序固定为 Filename,Title,Keywords,Category,Releases。作者最初凭直觉加入了 Description 列，结果整个批次在解析阶段就被拒绝，没有任何人工审核介入。

这不是 Adobe 独有的严格。据该作者在多个平台的实测，Vecteezy 要求 4 列格式，Dreamstime 要求 15 列。三个平台、三套表头、零容忍。手工维护电子表格的人迟早会写错列名或列数，而失败模式之所以令人困惑，是因为错误提示通常指向数据行，而不是真正的表头问题。

这种设计逻辑其实很直白：平台解析器在读取第一行时就建立了结构契约。列名不匹配或列数不对，后续所有字段映射都会错位，与其产生不可靠的导入结果，不如在入口处直接拒绝。没有部分得分，也没有“差不多就行”。

CSV（Comma-Separated Values，逗号分隔值）是一种以纯文本存储表格数据的格式，每行代表一条记录，各字段之间用逗号分隔，首行通常作为表头（header）声明列名。它本身没有强制的模式定义，也没有类型校验，因此对结构错误极其敏感。

在素材平台的上传场景中，CSV 是一种“契约式”输入：平台解析器会先读取表头，建立列名到内部字段的映射关系。一旦列名拼写、大小写或顺序与规范不符，后续每一行的数据都会被错误地归位，甚至完全无法解析。这与数据库的 schema 约束类似——如果表结构不对，插入的数据就没有意义。

也正因为 CSV 不带自描述的类型信息，平台无法像 JSON 或 XML 那样通过字段名容错，只能选择“要么全对，要么全拒”的严格策略。这就是为什么表头错误往往在第一行就被拦截，而错误信息却经常指向数据行，造成排查困难。

用脚本生成表头，而非手工填写

作者的解决方案是彻底放弃手工编写 CSV，改用 make_metadata.py 按平台规范生成表头。该脚本只依赖 Python 标准库，无需安装额外依赖：

python make_metadata.py ./my-assets --platform adobe --out metadata.csv --ext .jpg
python make_metadata.py ./my-assets --platform vecteezy --out vecteezy.csv --ext .jpg
python make_metadata.py ./my-assets --platform dreamstime --out dreamstime.csv --ext .jpg

三条命令对应三套正确表头，从源头消除了拼写错误的可能。默认情况下脚本会把文件名转成标题格式，适合第一轮快速过审，但正式提交前应通过 --titles titles.json 替换为预先准备的标题和关键词。

关键设计原则是：脚本写出的表头来自平台官方规范并经过审核行为验证，而不是创作者自己发明的列名。这一点比脚本本身的实现更重要——工具的价值在于把“我记得应该是这几列”变成“平台要求就是这几列”。

重复上传：第二个秒拒陷阱

表头修好之后，作者紧接着踩中了另一个坑。为了修复一个坏文件，他重跑了整个批次的上传命令，结果同一批素材被重复提交。重复上传是导致账号被标记的最快途径之一，而批量工具让这种误操作变得极其容易。

于是流水线里增加了账本机制。upload_tracker.py 用纯文本文件记录已经发布过的资产：

python upload_tracker.py pending items.txt   # 尚未完成的条目
python upload_tracker.py done "asset-001.jpg"
python upload_tracker.py status

重跑时，已标记完成的条目会被自动跳过。这个工具只是几十行标准库 Python 加一个纯文本文件，但作者称它至少避免了两次达到账号标记级别的失误。对于任何批量提交场景，幂等性都不是可选项——重复提交的代价远高于多花十分钟做去重检查。

幂等性（idempotency）是分布式系统和批处理中的核心概念，指同一操作执行一次与执行多次对系统状态产生的效果相同。在素材上传场景中，幂等意味着无论重跑多少次上传命令，同一资产都不会被重复提交。

批量脚本天然容易破坏幂等性：为了修复某个失败文件而重跑整个批次，会让已经成功的文件再次进入队列。平台通常将重复上传视为滥用行为，因为它占用审核资源、干扰库存管理，并可能触发账号风控。

实现幂等的常见手段是维护一份“已处理账本”（ledger），也就是文中 upload_tracker.py 所做的事：用纯文本文件记录已完成资产，重跑时先查询账本并跳过已存在条目。这种思路与数据库的 upsert、消息队列的去重 ID、以及 CI/CD 中的增量构建完全一致。对任何批量提交任务而言，幂等设计都是防止不可逆副作用的第一道防线。

为什么元数据必须用代码构建

有同行认为电子表格足够用。作者承认，在单批 10 个文件的规模下确实如此。但当批次达到 100 个文件、同时面向三个平台时，手工 CSV 就不再是效率问题，而是可靠性问题。

他的父项目约 19000 行流水线代码，已打包 39 个成品，输出 856 MB。如果每次上传都需要打开电子表格祈祷不出错，这些产出不可能实现。

整套系统跑在 1 vCPU、2 GB 内存、无 GPU 的服务器上。元数据生成的计算开销几乎为零，因此可以放在任何环境运行。真正吃资源的是图像处理，作者的习惯做法包括：一次只跑一个进程、资产之间调用 gc.collect()、用 resource.getrusage 测量峰值内存，以及按实际需要的分辨率渲染。用 60 dpi 而非 300 dpi 检查预览图，就是能否在 2 GB 内存内完成工作与陷入交换死亡之间的区别。

上传前的检查清单

作者目前每次上传前都会执行以下四项检查：

1. 表头与平台完全匹配——Adobe 5 列，Vecteezy 4 列，Dreamstime 15 列。
2. 标题和关键词是真实内容，而非文件名转标题的默认值。
3. upload_tracker.py status 确认当前批次没有已发布过的资产。
4. 文件位于 output/ 目录，元数据 CSV 从该目录重新生成，之后绝不手工编辑。

这份清单来自三次本可避免的拒绝。作者在笔记里积累了 300 多页关于平台规则的研究，但元数据表头是第一个咬到所有人的问题——因为它在作品被看到之前就让上传失败了。

从这次经历沉淀出的工具集

上述内容已被打包进 Pipeline Starter Kit，包含四个可运行脚本（make_metadata.py、upload_tracker.py、md2pdf.py、pack_product.py）、目录结构说明和微型服务器注意事项。作者强调这些是产出那 39 个产品的同一批脚本，而非为教程重写的版本。对于正在搭建自己流水线的创作者来说，这套工具的价值在于省去那些本可避免的拒绝邮件。

素材上传的自动化不是炫技，而是把重复性的人为错误从流程中移除。表头、去重、内存管理，每一个环节的失误都会在某个时刻变成账号风险或时间浪费。代码化处理这些环节，换来的是可预测的产出节奏。