Business Export Cookbook / 业务库表导出 Cookbook

更新：2026-06-02
关联文档：业务 Manifest 与 Type-Role 规范 · 业务素材类型与 Bucket 指南

一页结论

下个 session 如果要从你们的业务库表真正导出训练/评测清单，建议直接按这个顺序：

1. 先从 SQL 导出音频资产基础字段
2. 用 type-role mapping 补 role / bucket
3. 落成 CSV 或 JSONL 中间文件
4. 再转成项目 manifest
5. 或直接先用仓库脚本转成 manifest-ready JSONL

仓库里已经补好以下参考物：

• ../acr-engine/configs/manifests/business_asset_manifest_template.json
• ../acr-engine/configs/manifests/business_type_role_mapping.json
• ../acr-engine/configs/manifests/examples/business_asset_export_example.csv
• ../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl

---

1. 推荐 SQL 导出字段

SELECT
  s.id              AS song_id,
  a.id              AS asset_id,
  a.type            AS type,
  a.file_path       AS audio_path,
  s.title           AS title,
  s.artist_name     AS artist,
  s.album_id        AS album_id,
  a.duration_sec    AS duration_sec,
  a.sample_rate     AS sample_rate,
  a.bitrate         AS bitrate,
  a.license_code    AS license,
  a.created_at      AS created_at
FROM music_asset a
JOIN song s ON s.id = a.song_id
WHERE a.type IN (1,7,8,9,10,11,16,18,2,12);

说明：

• 这不是强制 SQL，只是字段映射样例。
• 关键不是表名，而是把字段凑齐到 manifest 规范里。

---

2. 导出后要补什么字段

字段	来源	说明
role	business_type_role_mapping.json	由 type 映射
bucket	business_type_role_mapping.json	默认业务 bucket
split	导出脚本或后处理	train/val/test/holdout
source_dataset	固定值	如 internal_catalog
offset_sec	片段类素材可填	非片段可先置 0

---

3. 推荐中间格式

CSV

适合：

• 业务同学先导数据
• Excel / 表格工具核对

样例：

• ../acr-engine/configs/manifests/examples/business_asset_export_example.csv

JSONL

适合：

• 脚本流式处理
• 后续直接转 manifest

样例：

• ../acr-engine/configs/manifests/examples/business_asset_export_example.jsonl

---

4. 建议后处理规则

1. type=10/11 默认补成 reference
2. type=1/9 默认补成压缩域 reference
3. type=7/8/16 默认补成 query
4. type=18/2/12 默认先 excluded
5. 非音频资产直接过滤掉

---

5. 下个 session 最直接动作

1. 按 SQL 样例从业务库导一次真实数据
2. 存成 CSV 或 JSONL
3. 用仓库里的 mapping 规则补齐 role / bucket
4. 再转换成项目需要的 manifest

Sources

• See business-manifest-and-type-role-spec.md
• See business-music-bucket-and-type-guide.md

6. 轻量规范化脚本

仓库里已经补了一层可直接运行的转换脚本：

• ../acr-engine/scripts/normalize_business_export.py

示例：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/normalize_business_export.py \
  --input configs/manifests/examples/business_asset_export_example.csv \
  --output /tmp/business_asset_manifest_ready.jsonl

这个脚本会：

1. 读取 CSV 或 JSONL 导出
2. 应用 business_type_role_mapping.json
3. 自动补 role / bucket / source_dataset / split 默认值
4. 输出 manifest-ready JSONL

7. 拆分为角色清单

如果你已经拿到了 manifest-ready JSONL，还可以继续用：

• ../acr-engine/scripts/split_business_manifest_ready.py

示例：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/split_business_manifest_ready.py \
  --input /tmp/business_asset_manifest_ready.jsonl \
  --output-dir /tmp/business_asset_manifest_split

它会输出：

• reference.json
• query.json
• excluded.json

这样下个 session 可以更快把业务素材继续整形成训练/评测所需清单。