需要创建、管理或查询 Arize 数据集与示例时，用 ax…

当需要使用 Arize 数据集做评估/测试/黄金数据集，或进行创建、列出、获取、导出、追加、更新、删除、重命名、注释数据集与示例时适用。

适用场景

解决思路

1. 直接执行所需 `ax` 命令，不要预先检查版本、env vars 或 profiles；仅在命令失败时按错误排查。`--space` 可传空间名称（如 `my-workspace`）或 base64 空间 ID（如 `U3BhY2U6...`），用 `ax spaces list` 查找。Space 未知时运行 `ax spaces list` 按名称选择或询问；Project 不清楚时询问用户，或运行 `ax projects list -o json --limit 100` 展示为可选项。安全：不要读 `.env` 或搜索文件系统找凭据；用 `ax profiles` 管理 Arize 凭据、`ax ai-integrations` 管理 LLM provider keys；不要要求用户把 secret 粘贴到聊天；缺失凭据参考 `references/ax-profiles.md`。保存凭据供未来使用见 `references/ax-profiles.md` § Save Credentials for Future Use。
2. 列出数据集：运行 `ax datasets list`；可用 `--space SPACE`、`--limit 20`、`--cursor CURSOR_TOKEN`、`-o json`；`--name, -n` 对名称做子串过滤；`--limit, -l` 默认 15，范围 1-100；`-o, --output` 默认 table，支持 table、json、csv、parquet 或文件路径。
3. 获取数据集：运行 `ax datasets get NAME_OR_ID`；可用 `-o json`；当用数据集名称而非 ID 时需 `--space SPACE`；返回 `id`、`name`、`space_id`、`created_at`、`updated_at`、`versions`（每个版本含 id、name、dataset_id、created_at、updated_at）。用于快速查元数据。
4. 导出数据集：运行 `ax datasets export NAME_OR_ID`，默认生成 `dataset_abc123_20260305_141500/examples.json`；数据集超过 500 条示例时用 `--all` 做无限批量导出；可用 `--version-id VERSION_ID` 导出指定版本，`--output-dir ./data` 指定目录，`--stdout` 输出到标准输出，`--space SPACE`（用名称时必需）；可 `ax datasets export NAME_OR_ID --stdout | jq '.[0]'`。输出是示例对象 JSON 数组，每个含系统字段和所有用户字段。
5. 导出截断处理：如果导出恰好返回 500 条示例，结果很可能被截断，重新用 `--all` 获取完整数据集。
6. 验证导出完整性：从元数据取服务端计数 `ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'`；对比导出 `jq 'length' dataset_*/examples.json`；若计数不一致，用 `--all` 重新导出。
7. 创建数据集：运行 `ax datasets create --name "My Dataset" --space SPACE --file data.csv`，也可用 `data.json`、`data.jsonl`、`data.parquet`。Flags：`--name, -n` 必填，`--space` 必填，`--file, -f` 必填（CSV/JSON/JSONL/Parquet），`-o/--output` 可选。要追加到已有数据集，改用 `ax datasets append --json '[...]'`，不要重新 create。
8. 通过 stdin 创建：用 `--file -` 直接管道，无需临时文件：`echo '[{"question": "What is 2+2?", "answer": "4"}]' | ax datasets create --name "my-dataset" --space SPACE --file -`；或用 heredoc `ax datasets create --name "my-dataset" --space SPACE --file - << 'EOF'` 后接 `[{"question": "What is 2+2?", "answer": "4"}]` 和 `EOF`。
9. 文件格式与陷阱：CSV 列头变字段名，但丢失类型信息（日期变字符串，`null` 变空字符串），需保留类型用 JSON/Parquet；JSON 是对象数组；JSONL 每行一个对象，不能是 JSON 数组，数组放 `.jsonl` 会失败；Parquet 保列类型，本地读取需 `pandas`/`pyarrow`：`pd.read_parquet("examples.parquet")`。
10. 追加示例（内联 JSON）：运行 `ax datasets append DATASET_NAME --space SPACE --json '[{"question": "What is 2+2?", "answer": "4"}]'`；可一次传多个对象。
11. 追加示例（从文件）：运行 `ax datasets append DATASET_NAME --space SPACE --file new_examples.csv` 或 `--file additions.json`。
12. 追加到特定版本：运行 `ax datasets append DATASET_NAME --space SPACE --json '[{"q": "..."}]' --version-id VERSION_ID`。
13. 追加 flags/校验：`NAME_OR_ID` 位置参数必填，用名称时加 `--space`；`--json` 与 `--file` 互斥且必须恰好一个；`--version-id` 可选，默认最新版本；`-o/--output` 可选；每个示例必须是 JSON 对象且至少一个用户定义字段；每次请求最多 100,000 个示例。
14. 追加前 schema 验证：若数据集已有示例，先 `ax datasets export DATASET_NAME --space SPACE --stdout | jq '.[0] | keys'` 查看现有字段名；再 `echo '[{"question": "..."}]' | jq '.[0] | keys'` 检查新数据字段名；两者应显示相同用户定义字段。字段是自由格式：新示例可加额外字段，缺失字段变 null；但字段名拼写错误（如 `queston` vs `question`）会静默创建新列，追加前校验拼写。
15. 更新/删除示例：`ax datasets update-examples` 按 example `id` 补丁行；`ax datasets delete-examples` 从版本删除行；不常用，运行 `ax datasets update-examples --help` 或 `ax datasets delete-examples --help` 获取 flags 和输入格式。
16. 删除数据集：运行 `ax datasets delete NAME_OR_ID`；用名称时需 `--space SPACE`；`--force, -f` 跳过确认提示。
17. 重命名数据集：运行 `ax datasets update NAME_OR_ID --name "new-dataset-name"`；可加 `--space SPACE`；`NAME_OR_ID` 和 `--name` 必填。
18. 批量注释示例：运行 `ax datasets annotate-examples NAME_OR_ID --file annotations.json`，可 `--file annotations.csv --space SPACE`；`--file, -f` 必填，支持 JSON、JSONL、CSV、Parquet，`-` 表示 stdin；用名称时加 `--space`；upsert 语义：同 key 的现有注释更新，新注释创建；每次请求最多 1000 条注释。
19. 按名称查找数据集：所有数据集命令直接接受名称或 ID 作为位置参数；用名称时加 `--space SPACE`；如需 base64 ID，运行 `ax datasets list -o json | jq '.datasets[] | select(.name == "eval-set-v1") | .id'`（注意 `list -o json` 把数组放在 `datasets` key 下）。
20. 从文件创建评估数据集工作流：准备 CSV/JSON/Parquet，包含评估列（如 `input`、`expected_output`）；若内联生成数据，用 `--file -` 管道；运行 `ax datasets create --name "eval-set-v1" --space SPACE --file eval_data.csv`；验证 `ax datasets get DATASET_NAME --space SPACE`；用该数据集名称运行实验。
21. 向现有数据集添加示例工作流：运行 `ax datasets list --space SPACE` 查找；用 `ax datasets append DATASET_NAME --space SPACE --json '[{"question": "...", "answer": "..."}]'` 或 `--file additional_examples.csv` 追加。
22. 下载数据集离线分析工作流：运行 `ax datasets list --space SPACE` 找名称；运行 `ax datasets export DATASET_NAME --space SPACE` 下载到文件；用 `jq '.[] | .question' dataset_*/examples.json` 解析 JSON。
23. 导出特定版本工作流：列出版本 `ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions'`；导出 `ax datasets export DATASET_NAME --space SPACE --version-id VERSION_ID`。
24. 迭代数据集工作流：导出当前版本 `ax datasets export DATASET_NAME --space SPACE`；本地修改示例；追加新行 `ax datasets append DATASET_NAME --space SPACE --file new_rows.csv`；或者创建新版本/新数据集 `ax datasets create --name "eval-set-v2" --space SPACE --file updated_data.json`。
25. 将导出管道到其他工具：计数 `ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'`；提取单字段 `... --stdout | jq '.[].question'`；转 CSV `... --stdout | jq -r '.[] | [.question, .answer] | @csv'`。
26. 示例 schema 与系统字段：示例是自由格式 JSON 对象，无固定 schema，列由提供的字段决定；`id`、`created_at`、`updated_at` 由服务端管理，`id` 更新时必需、创建/追加时禁止；用户字段可为 string、number、boolean、null、嵌套对象、数组；创建/追加 payload 不要包含系统管理字段。
27. 保留列处理：创建/追加时移除 `time`、`count` 或任何 `source_record_*` 字段，否则报 `reserved column`。
28. 故障排查：`ax: command not found`/版本错误 → 参考 `references/ax-setup.md`；`401 Unauthorized` → 运行 `ax profiles show` 检查当前 profile，缺失或 API key 错误时按 `references/ax-profiles.md` 创建/更新；若用户没有 key，引导到 https://app.arize.com/admin > API Keys；`No profile found` → 按 `references/ax-profiles.md` 创建；`Dataset not found` → 用 `ax datasets list` 验证数据集 ID；`File format error` → 支持 CSV/JSON/JSONL/Parquet，用 `--file -` 从 stdin 读取；`platform-managed column` → 从 create/append payload 移除 `id`、`created_at`、`updated_at`；`Provide either --json or --file` → append 必须恰好提供 `--json` 或 `--file`；`Examples array is empty` → 确保 JSON 数组或文件至少一个示例；`not a JSON object` → `--json` 数组每个元素必须是 `{...}` 对象，不能是字符串或数字。
29. 关联技能：需要从生产 spans 理解数据放进数据集用 `arize-trace`；对数据集跑评估用 `arize-experiment`；用数据集+实验结果改进提示用 `arize-prompt-optimization`。

适用边界 · 注意事项

• 未安装 ax CLI（≥ 0.33.0）或未配置 Arize profile/API key 时不适用。
• 不使用 Arize 云平台或希望完全本地管理数据集时不适用。
• 需要严格 schema 且不能接受 CSV 丢失类型信息或自由字段静默新增列时，避免使用 CSV/自由字段模式，或改用 JSON/Parquet 并预先校验字段。