跳转到主要内容

​
文件上传集成

ACP的Product Feed文件上传采用SFTP推送模式（push-based）。商家主动将商品数据文件推送到OpenAI指定的SFTP服务器，而非由OpenAI来拉取。

​
3.1 SFTP推送模式

商家数据系统
  ↓ SFTP上传（商家主动推送）
OpenAI SFTP服务器
  ↓ 自动解析和索引
ChatGPT商品发现引擎
关键点: 这是单向推送。商家掌控上传时间和频率，OpenAI不会主动从商家系统拉取数据。 SFTP凭证在商家获得合作伙伴审批后由OpenAI提供。

​
3.2 支持的文件格式

格式压缩推荐度说明
Parquetzstd推荐列式存储，压缩效率最高
jsonl.gzgzip可选JSON Lines格式，每行一条记录
csv.gzgzip可选逗号分隔，需UTF-8编码
tsv.gzgzip可选Tab分隔，需UTF-8编码
编码要求: 所有文本文件必须使用UTF-8编码。 Parquet配合zstd压缩是首选方案，因为：
  • 列式存储天然支持高效的字段级读取
  • zstd压缩比高于gzip，解压速度更快
  • 内置schema信息，减少类型歧义

​
3.3 快照类型：全量覆盖

ACP文件上传采用**全量快照（Full Catalog）**模式，而非增量模式（delta）。 每次上传的文件代表商品目录的完整真实状态（complete source of truth）。这意味着：
  • 上传文件包含所有在售商品的完整信息
  • 每次上传会完全覆盖上一次的数据
  • 不需要标记”新增”、“修改”、“删除”等操作类型
  • 如果某个商品不在最新快照中，它会被视为已下架
Day 1 快照: [商品A, 商品B, 商品C]  → 目录 = A, B, C
Day 2 快照: [商品A, 商品C, 商品D]  → 目录 = A, C, D（B被移除，D被新增）

​
3.4 分片策略

大型商品目录需要分片上传。分片规则：
参数建议值
每个分片最大商品数500,000条
单个文件目标大小500MB以下
分片示例: 
# 100万商品的目录分片方案
products_shard_001.parquet  → 商品 1 - 500,000
products_shard_002.parquet  → 商品 500,001 - 1,000,000
分片时确保每个商品（包括其所有Variant）完整地在同一个分片文件中。不要将同一个Product的不同Variant拆分到不同文件。

​
3.5 上传频率

策略频率用途
SFTP全量快照至少每天一次商品目录基线同步
REST API增量全天实时价格、库存、促销等变化
推荐方案: 每日凌晨上传一次完整的SFTP全量快照，白天通过REST API推送实时变化（价格调整、库存变动、新品上架）。 这种双通道策略确保：
  • 全量快照提供数据一致性的基线
  • API增量更新保证数据时效性
  • 即使API出现短暂问题，全量快照也能在次日修正

​
3.6 文件命名规则

使用稳定一致的文件名。每次上传同名文件会覆盖上次的内容。 
# 正确：固定文件名，每次覆盖
products_shard_001.parquet
products_shard_002.parquet

# 错误：不要在文件名中加时间戳追加
products_20260411_001.parquet
products_20260412_001.parquet
不要追加（append）。ACP期望文件名稳定，内容覆盖。如果使用带时间戳的文件名，旧文件不会自动清理，可能导致数据混乱。

​
3.7 商品下架处理

在全量快照模式下，有两种方式下架商品： 方式1: 从快照中省略 最简单的方式。下次上传的快照中不包含该商品，它就自然消失。 方式2: 设置 is_eligible_search 为 false 在快照中保留商品记录，但将 is_eligible_search 字段设为 false。商品数据仍然存在，但不会在ChatGPT的商品发现中出现。 
{
  "id": "prod_discontinued_001",
  "is_eligible_search": false,
  "variants": [
    {
      "id": "var_001",
      "title": "Discontinued Product",
      "price": { "amount": 0, "currency": "USD" }
    }
  ]
}
方式2适用于需要保留商品记录但暂时不展示的场景（如季节性商品、临时缺货）。

​
3.8 Feed Header

每个上传文件必须包含Feed Header信息，标识数据来源和目标：
字段类型说明
feed_idstring数据源唯一标识
account_idstring商家账户ID
target_merchantstring目标商家标识
target_countrystring目标国家（ISO 3166-1 alpha-2）
{
  "feed_id": "feed_electronics_us",
  "account_id": "acct_merchant_123",
  "target_merchant": "merchant_xyz",
  "target_country": "US"
}

​
3.9 最佳实践清单

实践说明
使用Parquet + zstd压缩效率最高，解析最快
保持UTF-8编码避免字符集问题
每日全量 + API增量双通道确保数据新鲜度
固定文件名覆盖不要追加带时间戳的文件
单分片不超过50万条保持处理效率
单文件不超过500MB避免上传超时
完整商品在同一分片Product和Variant不跨文件
监控上传状态确认SFTP传输成功完成
下一章: 第4章：REST API集成 — Product Feed REST API完整参考