arize-dataset

Arize 数据集技能

SPACE — 所有 --space 标志和 ARIZE_SPACE 环境变量都接受空间名称（例如 my-workspace）或 base64 空间 ID（例如 U3BhY2U6...）。使用 ax spaces list 查找你的空间。

概念

• 数据集 = 用于评估和实验的示例的版本化集合
• 数据集版本 = 数据集在某一时间点的快照；更新可以就地完成，也可以创建新版本
• 示例 = 数据集中的单条记录，包含任意用户自定义字段（例如 question、answer、context）
• 空间 = 组织容器；数据集属于某个空间

示例上的系统管理字段（id、created_at、updated_at）由服务自动生成——切勿将它们包含在创建或追加负载中。

前置条件

直接执行任务——运行你需要的 ax 命令。不要预先检查版本、环境变量或配置文件。

如果 ax 命令失败，请根据错误进行排查：

• command not found 或版本错误 → 参见 references/ax-setup.md
• 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show 检查当前配置文件。如果配置文件缺失或 API 密钥错误，请按照 references/ax-profiles.md 创建/更新它。如果用户没有密钥，请引导他们访问 https://app.arize.com/admin > API Keys
• 空间未知 → 运行 ax spaces list 按名称选择，或询问用户
• 项目不明确 → 询问用户，或运行 ax projects list -o json --limit 100 并作为可选项呈现
• 安全： 切勿读取 .env 文件或在文件系统中搜索凭据。使用 ax profiles 获取 Arize 凭据，使用 ax ai-integrations 获取大模型提供商密钥。如果无法通过这些渠道获得凭据，请询问用户。

列出数据集：ax datasets list

浏览空间中的数据集。输出到 stdout。

ax datasets list
ax datasets list --space SPACE --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

标志

标志	类型	默认值	描述
--space	string	来自配置文件	按空间筛选
--limit, -l	int	15	最大结果数（1-100）
--cursor	string	无	来自上一个响应的分页游标
-o, --output	string	table	输出格式：table、json、csv、parquet 或文件路径
-p, --profile	string	default	配置配置文件

获取数据集：ax datasets get

快速元数据查询——返回数据集名称、空间、时间戳和版本列表。

ax datasets get NAME_OR_ID
ax datasets get NAME_OR_ID -o json
ax datasets get NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

标志

标志	类型	默认值	描述
NAME_OR_ID	string	必填	数据集名称或 ID（位置参数）
--space	string	无	空间名称或 ID（如果使用数据集名称而非 ID 则必填）
-o, --output	string	table	输出格式
-p, --profile	string	default	配置配置文件

响应字段

字段	类型	描述
id	string	数据集 ID
name	string	数据集名称
space_id	string	此数据集所属的空间
created_at	datetime	数据集的创建时间
updated_at	datetime	最后修改时间
versions	array	数据集版本列表（id、name、dataset_id、created_at、updated_at）

导出数据集：ax datasets export

将所有示例下载到文件。对于超过 500 个示例的数据集，使用 --all（无限批量导出）。

ax datasets export NAME_OR_ID
# -> dataset_abc123_20260305_141500/examples.json

ax datasets export NAME_OR_ID --all
ax datasets export NAME_OR_ID --version-id VERSION_ID
ax datasets export NAME_OR_ID --output-dir ./data
ax datasets export NAME_OR_ID --stdout
ax datasets export NAME_OR_ID --stdout | jq '.[0]'
ax datasets export NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

标志

标志	类型	默认值	描述
NAME_OR_ID	string	必填	数据集名称或 ID（位置参数）
--space	string	无	空间名称或 ID（如果使用数据集名称而非 ID，则必填）
--version-id	string	latest	导出特定的数据集版本
--all	bool	false	无限制批量导出（用于超过 500 条示例的数据集）
--output-dir	string	.	输出目录
--stdout	bool	false	将 JSON 打印到 stdout 而非文件
-p, --profile	string	default	配置 profile

Agent 自动升级规则： 如果导出恰好返回 500 条示例，结果很可能被截断——请使用 --all 重新运行以获取完整数据集。

导出完整性验证： 导出后，确认行数与服务报告的一致：

# Get the server-reported count from dataset metadata
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'

# Compare to what was exported
jq 'length' dataset_*/examples.json

# If counts differ, re-export with --all

输出是示例对象的 JSON 数组。每个示例都有系统字段（id、created_at、updated_at）以及所有用户定义的字段：

[
  {
    "id": "ex_001",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "question": "What is 2+2?",
    "answer": "4",
    "topic": "math"
  }
]

创建数据集：ax datasets create

从数据文件创建新数据集。

ax datasets create --name "My Dataset" --space SPACE --file data.csv
ax datasets create --name "My Dataset" --space SPACE --file data.json
ax datasets create --name "My Dataset" --space SPACE --file data.jsonl
ax datasets create --name "My Dataset" --space SPACE --file data.parquet

标志

标志	类型	必填	描述
--name, -n	string	是	数据集名称
--space	string	是	要在其中创建数据集的空间
--file, -f	path	是	数据文件：CSV、JSON、JSONL 或 Parquet
-o, --output	string	否	返回的数据集元数据的输出格式
-p, --profile	string	否	配置 profile

通过 stdin 传入数据

使用 --file - 直接管道传入数据——无需临时文件：

echo '[{"question": "What is 2+2?", "answer": "4"}]' | ax datasets create --name "my-dataset" --space SPACE --file -

# Or with a heredoc
ax datasets create --name "my-dataset" --space SPACE --file - << 'EOF'
[{"question": "What is 2+2?", "answer": "4"}]
EOF

要向现有数据集添加行，请改用 ax datasets append --json '[...]'——无需文件。

支持的文件格式

格式	扩展名	说明
CSV	.csv	列标题会成为字段名
JSON	.json	对象数组
JSON Lines	.jsonl	每行一个对象（不是 JSON 数组）
Parquet	.parquet	列名会成为字段名；保留类型

格式陷阱：

• CSV：会丢失类型信息——日期变成字符串，null 变成空字符串。请使用 JSON/Parquet 来保留类型。
• JSONL：每一行都是一个独立的 JSON 对象。在 .jsonl 文件中使用 JSON 数组（[{...}, {...}]）会失败——请改用 .json 扩展名。
• Parquet：保留列类型。需要 pandas/pyarrow 才能在本地读取：pd.read_parquet("examples.parquet")。

追加示例：ax datasets append

向现有数据集添加示例。有两种输入模式——选择适合的一种。

内联 JSON（对 Agent 友好）

直接生成载荷——无需临时文件：

ax datasets append DATASET_NAME --space SPACE --json '[{"question": "What is 2+2?", "answer": "4"}]'

ax datasets append DATASET_NAME --space SPACE --json '[
  {"question": "What is gravity?", "answer": "A fundamental force..."},
  {"question": "What is light?", "answer": "Electromagnetic radiation..."}
]'

从文件

ax datasets append DATASET_NAME --space SPACE --file new_examples.csv
ax datasets append DATASET_NAME --space SPACE --file additions.json

追加到特定版本

ax datasets append DATASET_NAME --space SPACE --json '[{"q": "..."}]' --version-id VERSION_ID

标志

标志	类型	必填	描述
NAME_OR_ID	string	是	数据集名称或 ID（位置参数）；使用名称时请添加 --space
--space	string	否	空间名称或 ID（如果使用数据集名称而非 ID，则必填）
--json	string	互斥	示例对象的 JSON 数组
--file, -f	path	互斥	数据文件（CSV、JSON、JSONL、Parquet）
--version-id	string	否	追加到特定版本（默认：latest）
-o, --output	string	否	返回的数据集元数据的输出格式
-p, --profile	string	否	配置 profile

--json 或 --file 必须且只能指定其中一个。

验证

• 每个示例必须是包含至少一个用户定义字段的 JSON 对象
• 每个请求最多 100,000 条示例

追加前进行 schema 验证： 如果数据集已经有示例，请在追加前检查其 schema，以避免字段静默不匹配：

# Check existing field names in the dataset
ax datasets export DATASET_NAME --space SPACE --stdout | jq '.[0] | keys'

# Verify your new data has matching field names
echo '[{"question": "..."}]' | jq '.[0] | keys'

# Both outputs should show the same user-defined fields

字段是自由形式的：新示例中的额外字段会被添加，缺失的字段会变为 null。但是，字段名中的拼写错误（例如 queston 与 question）会静默创建新列——追加前请核实拼写。

删除数据集：ax datasets delete

ax datasets delete NAME_OR_ID
ax datasets delete NAME_OR_ID --space SPACE   # required when using dataset name instead of ID
ax datasets delete NAME_OR_ID --force   # skip confirmation prompt

标志

标志	类型	默认值	描述
NAME_OR_ID	string	required	数据集名称或 ID（位置参数）
--space	string	none	空间名称或 ID（当使用数据集名称而非 ID 时必填）
--force, -f	bool	false	跳过确认提示
-p, --profile	string	default	配置档案

工作流

按名称查找数据集

所有数据集命令都直接接受名称或 ID。你可以将数据集名称作为位置参数传入（当不使用 ID 时添加 --space SPACE）：

# Use name directly
ax datasets get "eval-set-v1" --space SPACE
ax datasets export "eval-set-v1" --space SPACE

# Or resolve name to ID via list if you need the base64 ID
ax datasets list -o json | jq '.[] | select(.name == "eval-set-v1") | .id'

从文件创建数据集用于评估

1. 准备一个包含评估列的 CSV/JSON/Parquet 文件（例如 input、expected_output）
   • 如果内联生成数据，请通过 stdin 使用 --file - 管道传入（参见创建数据集部分）
2. ax datasets create --name "eval-set-v1" --space SPACE --file eval_data.csv
3. 验证：ax datasets get DATASET_NAME --space SPACE
4. 使用数据集名称来运行实验

向现有数据集添加示例

# Find the dataset
ax datasets list --space SPACE

# Append inline or from a file using the dataset name (see Append Examples section for full syntax)
ax datasets append DATASET_NAME --space SPACE --json '[{"question": "...", "answer": "..."}]'
ax datasets append DATASET_NAME --space SPACE --file additional_examples.csv

下载数据集用于离线分析

1. ax datasets list --space SPACE -- 找到数据集名称
2. ax datasets export DATASET_NAME --space SPACE -- 下载到文件
3. 解析 JSON：jq '.[] | .question' dataset_*/examples.json

导出特定版本

# List versions
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions'

# Export that version
ax datasets export DATASET_NAME --space SPACE --version-id VERSION_ID

迭代数据集

1. 导出当前版本：ax datasets export DATASET_NAME --space SPACE
2. 在本地修改示例
3. 追加新行：ax datasets append DATASET_NAME --space SPACE --file new_rows.csv
4. 或者创建全新版本：ax datasets create --name "eval-set-v2" --space SPACE --file updated_data.json

将导出管道传递给其他工具

# Count examples
ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'

# Extract a single field
ax datasets export DATASET_NAME --space SPACE --stdout | jq '.[].question'

# Convert to CSV with jq
ax datasets export DATASET_NAME --space SPACE --stdout | jq -r '.[] | [.question, .answer] | @csv'

数据集示例 Schema

示例是自由形式的 JSON 对象。没有固定 schema -- 列就是你提供的任何字段。由服务管理的字段由服务端添加：

字段	类型	管理方	备注
id	string	server	自动生成的 UUID。更新时必填，创建/追加时禁止提供
created_at	datetime	server	不可变的创建时间戳
updated_at	datetime	server	修改时自动更新
（任意用户字段）	任意 JSON 类型	user	字符串、数字、布尔值、null、嵌套对象、数组

相关技能

• arize-trace：导出生产环境 span 以了解应将哪些数据放入数据集 → 使用 arize-trace
• arize-experiment：针对此数据集运行评估 → 下一步是 arize-experiment
• arize-prompt-optimization：使用数据集 + 实验结果来改进提示词 → 使用 arize-prompt-optimization

故障排除

问题	解决方案
ax: command not found	参见 references/ax-setup.md
401 Unauthorized	API 密钥错误、已过期，或无权访问此空间。使用 references/ax-profiles.md 修复档案。
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	从创建/追加负载中移除 id、created_at、updated_at
reserved column	移除 time、count 或任何 source_record_* 字段
Provide either --json or --file	追加操作要求恰好一个输入源
Examples array is empty	确保你的 JSON 数组或文件包含至少一个示例
not a JSON object	--json 数组中的每个元素都必须是 {...} 对象，而不是字符串或数字

保存凭据以供将来使用

参见 references/ax-profiles.md § 保存凭据以供将来使用。