arize-dataset

Arize Dataset 技能

SPACE — --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 创建或更新配置文件。如果用户没有 API 密钥，请引导他们前往 https://app.arize.com/admin > API Keys
• 空间未知 → 参阅 Space
• 项目不明确 → 询问用户，或运行 ax projects list -o json --limit 100 并提供可选项
• 安全性： 切勿读取 .env 文件或搜索文件系统中的凭据。例外：非机密的 ARIZE_SPACE_ID 行（参阅 Space）。使用 ax profiles 获取 Arize 凭据，使用 ax ai-integrations 获取 LLM 提供商密钥。切勿让用户在聊天中粘贴机密信息。缺少凭据时，参阅 references/ax-profiles.md。

列出数据集：ax datasets list

浏览某个空间中的数据集。列表用于人工浏览；如果已知数据集名称或 ID，请直接调用 ax datasets get NAME_OR_ID --space SPACE -o json。

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

查看所有标志，请运行 ax datasets list --help。

获取数据集：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

查看所有标志，请运行 ax datasets get --help。

响应字段

字段	类型	说明
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

将示例下载到文件。默认情况下，导出会返回一页示例（--limit 设置页大小，--cursor 选择后续页面）。传入 --all 可导出完整数据集。使用 --filter 通过针对示例列、id 和 annotation.<name>.* 的类 SQL 表达式，在服务端缩小范围；--filter 不支持与 --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 --filter "annotation.Correctness.label = 'Correct'"
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

查看所有标志，请运行 ax datasets export --help。

Agent 规则： 任务需要所有示例时，务必传入 --all；不带 --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

从数据文件（--file）或内联 JSON（--json）创建新数据集。

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
ax datasets create --name "My Dataset" --space SPACE --json '[{"question": "What is 2+2?", "answer": "4"}]'

查看所有标志，请运行 ax datasets create --help。

通过 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

支持的文件格式

格式	扩展名	备注
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

查看所有标志，请运行 ax datasets append --help。

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

验证

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

追加前进行架构验证： 如果数据集已有示例，请先检查其架构，避免字段不匹配而未被察觉：

# 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 update-examples

ax datasets update-examples 按示例 id 修补行；ax datasets delete-examples 从一个版本中删除行，并且需要 --version-id 和作为示例 ID JSON 数组的 --example-ids。这类操作不常见——查看标志和输入格式，请运行 ax datasets update-examples --help 或 ax datasets delete-examples --help。

删除数据集：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

查看所有标志，请运行 ax datasets delete --help。

更新数据集：ax datasets update

重命名现有数据集。

ax datasets update NAME_OR_ID --name "new-dataset-name"
ax datasets update NAME_OR_ID --name "new-dataset-name" --space SPACE

查看所有标志，请运行 ax datasets update --help。

标注示例：ax datasets annotate-examples

从文件批量为数据集示例写入标注。采用 Upsert 语义——具有相同键的现有标注会被更新，新标注会被创建。每个请求最多 1000 个示例。每条记录都需要 record_id（数据集示例 ID）和 values；不匹配的记录 ID 会被悄悄忽略，因此请先根据导出结果确认 ID。

ax datasets annotate-examples NAME_OR_ID --file annotations.json
ax datasets annotate-examples NAME_OR_ID --file annotations.csv --space SPACE

查看所有标志，请运行 ax datasets annotate-examples --help。

工作流

按名称查找数据集

所有数据集命令都接受名称或 ID（传入名称时添加 --space SPACE）。要将名称解析为 ID，请从 get 的结果中读取：

ax datasets get "eval-set-v1" --space SPACE -o json | jq -r '.id'

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

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

向现有数据集添加示例

# 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 export DATASET_NAME --space SPACE --all——将每个示例下载到文件
2. 解析 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 --all
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 --all --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'

数据集示例架构

示例是自由格式的 JSON 对象。没有固定架构——列由你提供的字段决定。服务器会添加系统管理的字段：

字段	类型	管理方	说明
id	字符串	服务器	自动生成的 UUID。更新时必填，创建/追加时禁止提供
created_at	日期时间	服务器	创建时间戳，不可更改
updated_at	日期时间	服务器	修改时自动更新
(任意用户字段)	任意 JSON 类型	用户	字符串、数字、布尔值、null、嵌套对象、数组

相关技能

• arize-trace：导出生产环境中的 spans，了解要在数据集中放入哪些数据 → 使用 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 get NAME_OR_ID --space SPACE 检查名称或 ID；仅在查找正确名称时使用 ax datasets list --space SPACE
File format error	支持的格式：CSV、JSON、JSONL、Parquet。使用 --file - 从标准输入读取。
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 § 保存凭据以供后续使用。