> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP商品数据SFTP文件上传指南

> ACP商品数据SFTP文件上传集成指南，详解SFTP推送模式的服务器连接与密钥认证配置、Parquet与JSON等文件格式选择与压缩方案、全量快照覆盖机制与50万条大文件分片上传策略、Feed Header数据源标识配置以及每日同步频率与文件命名规范的最佳实践

# 文件上传集成

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

## 3.1 SFTP推送模式

```
商家数据系统
  ↓ SFTP上传（商家主动推送）
OpenAI SFTP服务器
  ↓ 自动解析和索引
ChatGPT商品发现引擎
```

**关键点**: 这是单向推送。商家掌控上传时间和频率，OpenAI不会主动从商家系统拉取数据。

SFTP凭证在商家获得合作伙伴审批后由OpenAI提供。

## 3.2 支持的文件格式

| 格式          | 压缩   | 推荐度 | 说明                  |
| ----------- | ---- | --- | ------------------- |
| **Parquet** | zstd | 推荐  | 列式存储，压缩效率最高         |
| jsonl.gz    | gzip | 可选  | JSON Lines格式，每行一条记录 |
| csv.gz      | gzip | 可选  | 逗号分隔，需UTF-8编码       |
| tsv.gz      | gzip | 可选  | 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的商品发现中出现。

```json theme={null}
{
  "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_id`         | string | 数据源唯一标识                  |
| `account_id`      | string | 商家账户ID                   |
| `target_merchant` | string | 目标商家标识                   |
| `target_country`  | string | 目标国家（ISO 3166-1 alpha-2） |

```json theme={null}
{
  "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集成](/zh/book-4/ch4-api) — Product Feed REST API完整参考