arize-dataset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Arize Dataset Skill

Arize数据集Skill

Concepts

核心概念

Dataset = a versioned collection of examples used for evaluation and experimentation
Dataset Version = a snapshot of a dataset at a point in time; updates can be in-place or create a new version
Example = a single record in a dataset with arbitrary user-defined fields (e.g.,
```
question
```
,
```
answer
```
,
```
context
```
)
Space = an organizational container; datasets belong to a space

System-managed fields on examples (

id

created_at

updated_at

) are auto-generated by the server -- never include them in create or append payloads.

Dataset = 用于评估和实验的带版本控制的样本集合
Dataset Version = 数据集在某个时间点的快照；更新可以是原地更新或创建新版本
Example = 数据集中的单条记录，可包含任意用户自定义字段（如
```
question
```
、
```
answer
```
、
```
context
```
）
Space = 组织容器；数据集隶属于某个Space

样本的系统管理字段（

id

、

created_at

、

updated_at

）由服务器自动生成——在创建或追加请求的负载中绝对不要包含这些字段。

Prerequisites

前置条件

Three things are needed:

ax

CLI, an API key (env var or profile), and a space ID. A project name is also needed but usually comes from the user's message.

需要准备三件事：

ax

CLI、API密钥（环境变量或配置文件）、Space ID。还需要项目名称，通常可从用户的请求信息中获取。

Install ax

安装ax

Verify

ax

is installed and working before proceeding:

Check if
```
ax
```
is on PATH:
```
command -v ax
```
(Unix) or
```
where ax
```
(Windows)

If not found, check common install locations:

macOS/Linux:

test -x ~/.local/bin/ax && export PATH="$HOME/.local/bin:$PATH"

Windows: check

%APPDATA%\Python\Scripts\ax.exe

%LOCALAPPDATA%\Programs\Python\Scripts\ax.exe

If still not found, install it (requires shell access to install packages):
- Preferred:
```
uv tool install arize-ax-cli
```
- Alternative:
```
pipx install arize-ax-cli
```
- Fallback:
```
pip install arize-ax-cli
```

After install, if

ax

is not on PATH:

macOS/Linux:
```
export PATH="$HOME/.local/bin:$PATH"
```

Windows (PowerShell):

$env:PATH = "$env:APPDATA\Python\Scripts;$env:PATH"

ax --version

fails with an SSL/certificate error:

macOS:
```
export SSL_CERT_FILE=/etc/ssl/cert.pem
```

Linux:

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

Windows (PowerShell):

$env:SSL_CERT_FILE = "C:\Program Files\Common Files\SSL\cert.pem"

(or use

python -c "import certifi; print(certifi.where())"

to find the cert bundle)

```
ax --version
```
must succeed before proceeding. If it doesn't, stop and ask the user for help.

在继续操作前，请确认

ax

已安装并可以正常使用：

检查
```
ax
```
是否在系统PATH中：
```
command -v ax
```
（Unix系统）或
```
where ax
```
（Windows系统）

如果未找到，请检查常见安装路径：

macOS/Linux：

test -x ~/.local/bin/ax && export PATH="$HOME/.local/bin:$PATH"

Windows：检查

%APPDATA%\Python\Scripts\ax.exe

或

%LOCALAPPDATA%\Programs\Python\Scripts\ax.exe

如果仍未找到，请安装它（需要具备安装软件包的Shell权限）：
- 推荐方式：
```
uv tool install arize-ax-cli
```
- 替代方式：
```
pipx install arize-ax-cli
```
- 备用方式：
```
pip install arize-ax-cli
```

安装完成后，如果

ax

不在PATH中：

macOS/Linux：
```
export PATH="$HOME/.local/bin:$PATH"
```

Windows（PowerShell）：

$env:PATH = "$env:APPDATA\Python\Scripts;$env:PATH"

如果运行

ax --version

时出现SSL/证书错误：

macOS：
```
export SSL_CERT_FILE=/etc/ssl/cert.pem
```

Linux：

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

Windows（PowerShell）：

$env:SSL_CERT_FILE = "C:\Program Files\Common Files\SSL\cert.pem"

（或使用

python -c "import certifi; print(certifi.where())"

查找证书包路径）

必须确保
```
ax --version
```
可以成功运行后再继续。如果失败，请停止操作并向用户寻求帮助。

Verify environment

验证环境

Run a quick check for credentials:

macOS/Linux (bash):

bash

ax --version && echo "--- env ---" && echo "ARIZE_API_KEY: ${ARIZE_API_KEY:-(not set)}" && echo "ARIZE_SPACE_ID: ${ARIZE_SPACE_ID:-(not set)}" && echo "--- profiles ---" && ax profiles show 2>&1

Windows (PowerShell):

powershell

ax --version; Write-Host "--- env ---"; Write-Host "ARIZE_API_KEY: $env:ARIZE_API_KEY"; Write-Host "ARIZE_SPACE_ID: $env:ARIZE_SPACE_ID"; Write-Host "--- profiles ---"; ax profiles show 2>&1

Read the output and proceed immediately if either the env var or the profile has an API key. Only ask the user if both are missing. Resolve failures:

No API key in env and no profile → AskQuestion: "Arize API key (https://app.arize.com/admin > API Keys)"
Space ID unknown → AskQuestion, or run
```
ax projects list -o json --limit 100
```
and search for a match
Project unclear → ask, or run
```
ax projects list -o json --limit 100
```
and present as selectable options

快速检查凭据是否配置正确：

macOS/Linux（bash）：

bash

ax --version && echo "--- 环境变量 ---" && echo "ARIZE_API_KEY: ${ARIZE_API_KEY:-(未设置)}" && echo "ARIZE_SPACE_ID: ${ARIZE_SPACE_ID:-(未设置)}" && echo "--- 配置文件 ---" && ax profiles show 2>&1

Windows（PowerShell）：

powershell

ax --version; Write-Host "--- 环境变量 ---"; Write-Host "ARIZE_API_KEY: $env:ARIZE_API_KEY"; Write-Host "ARIZE_SPACE_ID: $env:ARIZE_SPACE_ID"; Write-Host "--- 配置文件 ---"; ax profiles show 2>&1

立即读取输出并继续：如果环境变量或配置文件中存在API密钥，则可直接操作。只有当两者都缺失时，才需要询问用户。解决失败情况：

环境变量和配置文件中均无API密钥 → 询问用户："请提供Arize API密钥（获取地址：https://app.arize.com/admin > API Keys）"
未知Space ID → 询问用户，或运行
```
ax projects list -o json --limit 100
```
并搜索匹配项
项目信息不明确 → 询问用户，或运行
```
ax projects list -o json --limit 100
```
并提供可选列表

Space ID and Project

Space ID与项目

Both are needed for most commands. Resolve each:

User provides it in the conversation -- use directly via
```
--space-id
```
/
```
--project
```
flags.
Env var is set (
```
ARIZE_SPACE_ID
```
,
```
ARIZE_DEFAULT_PROJECT
```
) -- use silently.
If missing, AskQuestion once. Tell the user:
- Space ID is in the Arize URL:
```
/spaces/{SPACE_ID}/...
```
- Project is the project name as shown in the Arize UI.
- For convenience, recommend setting env vars so they don't get asked again:
```
export ARIZE_SPACE_ID="U3BhY2U6..."
```
  and
```
export ARIZE_DEFAULT_PROJECT="my-project"
```

Prefer asking the user over searching or iterating through projects and API keys. If you get a

401 Unauthorized

, tell the user their API key may not have access to that space and ask them to verify.

大多数命令都需要这两个参数。获取方式如下：

用户在对话中提供 → 直接通过
```
--space-id
```
/
```
--project
```
参数使用
已设置环境变量（
```
ARIZE_SPACE_ID
```
、
```
ARIZE_DEFAULT_PROJECT
```
） → 自动使用
如果缺失，询问用户一次。告知用户：
- Space ID可在Arize的URL中找到：
```
/spaces/{SPACE_ID}/...
```
- 项目名称为Arize UI中显示的名称
- 为了方便后续操作，建议设置环境变量：
```
export ARIZE_SPACE_ID="U3BhY2U6..."
```
  和
```
export ARIZE_DEFAULT_PROJECT="my-project"
```

优先询问用户，而非遍历搜索项目和API密钥。如果收到

401 Unauthorized

错误，告知用户其API密钥可能无权访问该Space，请他们进行验证。

List Datasets:

ax datasets list

列出数据集：

ax datasets list

Browse datasets in a space. Output goes to stdout.

bash

ax datasets list
ax datasets list --space-id SPACE_ID --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

浏览指定Space中的数据集，输出结果将打印到标准输出。

bash

ax datasets list
ax datasets list --space-id SPACE_ID --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

Flags

选项

Flag	Type	Default	Description
`--space-id`	string	from profile	Filter by space
`--limit, -l`	int	15	Max results (1-100)
`--cursor`	string	none	Pagination cursor from previous response
`-o, --output`	string	table	Output format: table, json, csv, parquet, or file path
`-p, --profile`	string	default	Configuration profile

Flag	类型	默认值	说明
`--space-id`	string	来自配置文件	按Space过滤
`--limit, -l`	int	15	最大结果数（1-100）
`--cursor`	string	无	分页游标，来自上一次响应
`-o, --output`	string	table	输出格式：table、json、csv、parquet或文件路径
`-p, --profile`	string	default	配置文件名称

Get Dataset:

ax datasets get

获取数据集详情：

ax datasets get

Quick metadata lookup -- returns dataset name, space, timestamps, and version list.

bash

ax datasets get DATASET_ID
ax datasets get DATASET_ID -o json

快速查询元数据——返回数据集名称、所属Space、时间戳及版本列表。

bash

ax datasets get DATASET_ID
ax datasets get DATASET_ID -o json

Flags

选项

Flag	Type	Default	Description
`DATASET_ID`	string	required	Positional argument
`-o, --output`	string	table	Output format
`-p, --profile`	string	default	Configuration profile

Flag	类型	默认值	说明
`DATASET_ID`	string	必填	位置参数
`-o, --output`	string	table	输出格式
`-p, --profile`	string	default	配置文件名称

Response fields

响应字段

Field	Type	Description
`id`	string	Dataset ID
`name`	string	Dataset name
`space_id`	string	Space this dataset belongs to
`created_at`	datetime	When the dataset was created
`updated_at`	datetime	Last modification time
`versions`	array	List of dataset versions (id, name, dataset_id, created_at, updated_at)

字段	类型	说明
`id`	string	数据集ID
`name`	string	数据集名称
`space_id`	string	数据集所属的Space ID
`created_at`	datetime	数据集创建时间
`updated_at`	datetime	最后修改时间
`versions`	array	数据集版本列表（包含id、name、dataset_id、created_at、updated_at）

Export Dataset:

ax datasets export

导出数据集：

ax datasets export

Download all examples to a file. By default uses the REST API; pass

--all

to use Arrow Flight for bulk transfer.

bash

ax datasets export DATASET_ID

将所有样本下载到文件。默认使用REST API；传递

--all

参数可使用Arrow Flight进行批量传输。

bash

ax datasets export DATASET_ID

-> dataset_abc123_20260305_141500/examples.json

ax datasets export DATASET_ID --all ax datasets export DATASET_ID --version-id VERSION_ID ax datasets export DATASET_ID --output-dir ./data ax datasets export DATASET_ID --stdout ax datasets export DATASET_ID --stdout | jq '.[0]'

undefined

undefined

Flags

选项

Flag	Type	Default	Description
`DATASET_ID`	string	required	Positional argument
`--version-id`	string	latest	Export a specific dataset version
`--all`	bool	false	Use Arrow Flight for bulk export (see below)
`--output-dir`	string	`.`	Output directory
`--stdout`	bool	false	Print JSON to stdout instead of file
`-p, --profile`	string	default	Configuration profile

Flag	类型	默认值	说明
`DATASET_ID`	string	必填	位置参数
`--version-id`	string	latest	导出指定版本的数据集
`--all`	bool	false	使用Arrow Flight进行批量导出（详见下文）
`--output-dir`	string	`.`	输出目录
`--stdout`	bool	false	将JSON打印到标准输出而非保存到文件
`-p, --profile`	string	default	配置文件名称

REST vs Flight (

--all

)

REST与Flight（

--all

）对比

REST (default): Lower friction -- no Arrow/Flight dependency, standard HTTPS ports, works through any corporate proxy or firewall. Limited to 500 examples per page.
Flight (
```
--all
```
): Required for datasets with more than 500 examples. Uses gRPC+TLS on a separate host/port (
```
flight.arize.com:443
```
) which some corporate networks may block.

Agent auto-escalation rule: If a REST export returns exactly 500 examples, the result is likely truncated. Re-run with

--all

to get the full dataset.

Output is a JSON array of example objects. Each example has system fields (

id

created_at

updated_at

) plus all user-defined fields:

json

[
  {
    "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"
  }
]

REST（默认）：门槛更低——无需依赖Arrow/Flight，使用标准HTTPS端口，可通过任何企业代理或防火墙。限制：每页最多500条样本。
Flight（
```
--all
```
）：数据集样本超过500条时必须使用。使用gRPC+TLS协议，独立的主机/端口（
```
flight.arize.com:443
```
），部分企业网络可能会拦截此端口。

Agent自动升级规则：如果REST导出返回恰好500条样本，结果可能被截断。请使用

--all

参数重新运行以获取完整数据集。

输出为样本对象的JSON数组。每个样本包含系统管理字段（

id

、

created_at

、

updated_at

）及所有用户自定义字段：

json

[
  {
    "id": "ex_001",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "question": "2+2等于多少？",
    "answer": "4",
    "topic": "数学"
  }
]

Create Dataset:

ax datasets create

创建数据集：

ax datasets create

Create a new dataset from a data file.

bash

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

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

bash

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

Flags

选项

Flag	Type	Required	Description
`--name, -n`	string	yes (prompted)	Dataset name
`--space-id`	string	yes (prompted)	Space to create the dataset in
`--file, -f`	path	yes (prompted)	Data file: CSV, JSON, JSONL, or Parquet
`-o, --output`	string	no	Output format for the returned dataset metadata
`-p, --profile`	string	no	Configuration profile

Flag	类型	是否必填	说明
`--name, -n`	string	是（可提示用户输入）	数据集名称
`--space-id`	string	是（可提示用户输入）	数据集所属的Space ID
`--file, -f`	path	是（可提示用户输入）	数据文件：支持CSV、JSON、JSONL或Parquet格式
`-o, --output`	string	否	返回的数据集元数据的输出格式
`-p, --profile`	string	否	配置文件名称

Supported file formats

支持的文件格式

Format	Extension	Notes
CSV	`.csv`	Column headers become field names
JSON	`.json`	Array of objects
JSON Lines	`.jsonl`	One object per line
Parquet	`.parquet`	Column names become field names

格式	扩展名	说明
CSV	`.csv`	列标题将成为字段名称
JSON	`.json`	对象数组格式
JSON Lines	`.jsonl`	每行一个对象
Parquet	`.parquet`	列名将成为字段名称

Append Examples:

ax datasets append

追加样本：

ax datasets append

Add examples to an existing dataset. Two input modes -- use whichever fits.

向现有数据集添加样本。支持两种输入模式，可根据需求选择。

Inline JSON (agent-friendly)

内联JSON（适合Agent使用）

Generate the payload directly -- no temp files needed:

bash

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

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

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

bash

ax datasets append DATASET_ID --json '[{"question": "2+2等于多少？", "answer": "4"}]'

ax datasets append DATASET_ID --json '[
  {"question": "什么是引力？", "answer": "一种基本力..."},
  {"question": "什么是光？", "answer": "电磁辐射..."}
]'

From a file

从文件导入

bash

ax datasets append DATASET_ID --file new_examples.csv
ax datasets append DATASET_ID --file additions.json

bash

ax datasets append DATASET_ID --file new_examples.csv
ax datasets append DATASET_ID --file additions.json

To a specific version

追加到指定版本

bash

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

bash

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

Flags

选项

Flag	Type	Required	Description
`DATASET_ID`	string	yes	Positional argument
`--json`	string	mutex	JSON array of example objects
`--file, -f`	path	mutex	Data file (CSV, JSON, JSONL, Parquet)
`--version-id`	string	no	Append to a specific version (default: latest)
`-o, --output`	string	no	Output format for the returned dataset metadata
`-p, --profile`	string	no	Configuration profile

Exactly one of

--json

--file

is required.

Flag	类型	是否必填	说明
`DATASET_ID`	string	是	位置参数
`--json`	string	二选一	样本对象的JSON数组
`--file, -f`	path	二选一	数据文件（支持CSV、JSON、JSONL、Parquet）
`--version-id`	string	否	追加到指定版本（默认：最新版本）
`-o, --output`	string	否	返回的数据集元数据的输出格式
`-p, --profile`	string	否	配置文件名称

必须且只能选择

--json

或

--file

其中一种输入源。

Validation

验证规则

Each example must be a JSON object with at least one user-defined field
Fields
```
id
```
,
```
created_at
```
,
```
updated_at
```
are auto-generated -- do not include them
Maximum 100,000 examples per request

每个样本必须是JSON对象，且至少包含一个用户自定义字段
```
id
```
、
```
created_at
```
、
```
updated_at
```
字段由系统自动生成——请勿在请求中包含
单次请求最多支持100,000条样本

Delete Dataset:

ax datasets delete

删除数据集：

ax datasets delete

bash

ax datasets delete DATASET_ID
ax datasets delete DATASET_ID --force   # skip confirmation prompt

bash

ax datasets delete DATASET_ID
ax datasets delete DATASET_ID --force   # 跳过确认提示

Flags

选项

Flag	Type	Default	Description
`DATASET_ID`	string	required	Positional argument
`--force, -f`	bool	false	Skip confirmation prompt
`-p, --profile`	string	default	Configuration profile

Flag	类型	默认值	说明
`DATASET_ID`	string	必填	位置参数
`--force, -f`	bool	false	跳过确认提示
`-p, --profile`	string	default	配置文件名称

Workflows

工作流示例

Create a dataset from file for evaluation

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

Prepare a CSV/JSON/Parquet file with your evaluation columns (e.g.,
```
input
```
,
```
expected_output
```
)

ax datasets create --name "eval-set-v1" --space-id SPACE_ID --file eval_data.csv

Verify:
```
ax datasets get DATASET_ID
```
Use the dataset ID to run experiments

准备包含评估列的CSV/JSON/Parquet文件（如
```
input
```
、
```
expected_output
```
）

执行命令：

ax datasets create --name "eval-set-v1" --space-id SPACE_ID --file eval_data.csv

验证创建结果：
```
ax datasets get DATASET_ID
```
使用数据集ID运行实验

Add examples to an existing dataset

向现有数据集添加样本

bash

undefined

bash

undefined

Find the dataset

查找目标数据集

ax datasets list

Append inline (e.g., from an LLM-generated payload)

内联追加（例如从LLM生成的负载）

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

ax datasets append DATASET_ID --json '[ {"question": "什么是引力？", "answer": "一种基本力..."}, {"question": "什么是光？", "answer": "电磁辐射..."} ]'

Or append from a file

或从文件追加

ax datasets append DATASET_ID --file additional_examples.csv

undefined

ax datasets append DATASET_ID --file additional_examples.csv

undefined

Download dataset for offline analysis

下载数据集用于离线分析

```
ax datasets list
```
-- find the dataset
```
ax datasets export DATASET_ID
```
-- download to file

Parse the JSON:

jq '.[] | .question' dataset_*/examples.json

执行
```
ax datasets list
```
——找到目标数据集
执行
```
ax datasets export DATASET_ID
```
——下载到本地文件

解析JSON：

jq '.[] | .question' dataset_*/examples.json

Export a specific version

导出指定版本

bash

undefined

bash

undefined

List versions

列出所有版本

ax datasets get DATASET_ID -o json | jq '.versions'

Export that version

导出指定版本

ax datasets export DATASET_ID --version-id VERSION_ID

undefined

ax datasets export DATASET_ID --version-id VERSION_ID

undefined

Iterate on a dataset

迭代更新数据集

Export current version:
```
ax datasets export DATASET_ID
```
Modify the examples locally

Append new rows:

ax datasets append DATASET_ID --file new_rows.csv

Or create a fresh version:

ax datasets create --name "eval-set-v2" --space-id SPACE_ID --file updated_data.json

导出当前版本：
```
ax datasets export DATASET_ID
```
在本地修改样本

追加新行：

ax datasets append DATASET_ID --file new_rows.csv

或创建新版本：

ax datasets create --name "eval-set-v2" --space-id SPACE_ID --file updated_data.json

Pipe export to other tools

将导出结果管道到其他工具

bash

undefined

bash

undefined

Count examples

统计样本数量

ax datasets export DATASET_ID --stdout | jq 'length'

Extract a single field

提取单个字段

ax datasets export DATASET_ID --stdout | jq '.[].question'

Convert to CSV with jq

使用jq转换为CSV格式

ax datasets export DATASET_ID --stdout | jq -r '.[] | [.question, .answer] | @csv'

undefined

ax datasets export DATASET_ID --stdout | jq -r '.[] | [.question, .answer] | @csv'

undefined

Dataset Example Schema

数据集样本 Schema

Examples are free-form JSON objects. There is no fixed schema -- columns are whatever fields you provide. System-managed fields are added by the server:

Field	Type	Managed by	Notes
`id`	string	server	Auto-generated UUID. Required on update, forbidden on create/append
`created_at`	datetime	server	Immutable creation timestamp
`updated_at`	datetime	server	Auto-updated on modification
(any user field)	any JSON type	user	String, number, boolean, null, nested object, array

样本为自由格式的JSON对象，没有固定Schema——列由你提供的字段决定。系统管理字段由服务器自动添加：

字段	类型	管理方	说明
`id`	string	服务器	自动生成的UUID。更新时必填，创建/追加时禁止包含
`created_at`	datetime	服务器	不可变的创建时间戳
`updated_at`	datetime	服务器	修改时自动更新
（任意用户自定义字段）	任意JSON类型	用户	字符串、数字、布尔值、null、嵌套对象、数组均可

Troubleshooting

故障排除

Problem	Solution
`ax: command not found`	Check `~/.local/bin/ax` ; if missing: `uv tool install arize-ax-cli` (requires shell access to install packages)
`401 Unauthorized`	API key may not have access to this space. Verify the key and space ID are correct. Keys are scoped per space -- get the right one from https://app.arize.com/admin > API Keys.
`No profile found`	Run `ax profiles show --expand` to check; set `ARIZE_API_KEY` env var or write `~/.arize/config.toml`
`Dataset not found`	Verify dataset ID with `ax datasets list`
`File format error`	Supported: CSV, JSON, JSONL, Parquet
`platform-managed column`	Remove `id` , `created_at` , `updated_at` from create/append payloads
`reserved column`	Remove `time` , `count` , or any `source_record_*` field
`Provide either --json or --file`	Append requires exactly one input source
`Examples array is empty`	Ensure your JSON array or file contains at least one example
`not a JSON object`	Each element in the `--json` array must be a `{...}` object, not a string or number

问题	解决方案
`ax: command not found`	检查 `~/.local/bin/ax` 是否存在；如果不存在，执行 `uv tool install arize-ax-cli` （需要具备安装软件包的Shell权限）
`401 Unauthorized`	API密钥可能无权访问该Space。请确认密钥和Space ID是否正确。密钥按Space划分权限——请从https://app.arize.com/admin > API Keys获取对应Space的密钥。
`No profile found`	执行 `ax profiles show --expand` 检查配置；设置 `ARIZE_API_KEY` 环境变量或创建 `~/.arize/config.toml` 文件
`Dataset not found`	使用 `ax datasets list` 验证数据集ID是否正确
`File format error`	仅支持CSV、JSON、JSONL、Parquet格式
`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` 数组中的每个元素必须是 `{...}` 对象，不能是字符串或数字

Save Credentials for Future Use

保存凭据以便后续使用

At the end of the session, if the user manually provided any of the following during this conversation (via AskQuestion response, pasted text, or inline values) and those values were NOT already loaded from a saved profile or environment variable, offer to save them for future use.

Credential	Where it gets saved
API key	`ax` profile at `~/.arize/config.toml`
Space ID	macOS/Linux: shell config ( `~/.zshrc` or `~/.bashrc` ) as `export ARIZE_SPACE_ID="..."` . Windows: user environment variable via `[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE_ID', '...', 'User')`

Skip this entirely if:

The API key was already loaded from an existing profile or
```
ARIZE_API_KEY
```
env var
The space ID was already set via
```
ARIZE_SPACE_ID
```
env var
The user only used base64 project IDs (no space ID was needed)

How to offer: Use AskQuestion: "Would you like to save your Arize credentials so you don't have to enter them next time?" with options

"Yes, save them"

"No thanks"

If the user says yes:

API key — Check if

~/.arize/config.toml

exists. If it does, read it and update the

[auth]

section. If not, create it with this minimal content:

toml

[profile]
name = "default"

[auth]
api_key = "THE_API_KEY"

[output]
format = "table"

Verify with:

ax profiles show

Space ID — Persist the space ID as an environment variable:
macOS/Linux — Detect the user's shell config file (
```
~/.zshrc
```
for zsh,
```
~/.bashrc
```
for bash). Append:
bash
```
export ARIZE_SPACE_ID="THE_SPACE_ID"
```
Tell the user to run
```
source ~/.zshrc
```
(or restart their terminal) for it to take effect.
Windows (PowerShell) — Set a persistent user environment variable:
powershell
```
[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE_ID', 'THE_SPACE_ID', 'User')
```
Tell the user to restart their terminal for it to take effect.

在会话结束时，如果用户在本次对话中手动提供了以下任何凭据（通过问答响应、粘贴文本或内联值），且这些凭据未从已保存的配置文件或环境变量中加载过，则主动提供保存选项。

凭据	保存位置
API密钥	`ax` 配置文件： `~/.arize/config.toml`
Space ID	macOS/Linux： Shell配置文件（ `~/.zshrc` 或 `~/.bashrc` ），格式为 `export ARIZE_SPACE_ID="..."` ；Windows：用户环境变量，通过 `[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE_ID', '...', 'User')` 设置

以下情况请跳过此步骤：

API密钥已从现有配置文件或
```
ARIZE_API_KEY
```
环境变量加载
Space ID已通过
```
ARIZE_SPACE_ID
```
环境变量设置
用户仅使用了base64格式的项目ID（无需Space ID）

如何询问用户： 使用问答交互："是否需要保存你的Arize凭据，以便下次无需重复输入？"，提供选项

"是，保存凭据"

"不用了，谢谢"

。

如果用户选择"是"：

API密钥 — 检查
```
~/.arize/config.toml
```
是否存在。如果存在，读取并更新
```
[auth]
```
部分；如果不存在，创建包含以下内容的最小配置文件：
toml
```
[profile]
name = "default"

[auth]
api_key = "你的API密钥"

[output]
format = "table"
```
验证配置：
```
ax profiles show
```
Space ID — 将Space ID持久化为环境变量：
macOS/Linux — 检测用户的Shell配置文件（zsh使用
```
~/.zshrc
```
，bash使用
```
~/.bashrc
```
），在文件末尾追加：
bash
```
export ARIZE_SPACE_ID="你的Space ID"
```
告知用户执行
```
source ~/.zshrc
```
（或重启终端）使配置生效。
Windows（PowerShell） — 设置持久化用户环境变量：
powershell
```
[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE_ID', '你的Space ID', 'User')
```
告知用户重启终端使配置生效。

arize-dataset

Original

Translation

Arize Dataset Skill

Arize数据集Skill

Concepts

核心概念

Prerequisites

前置条件

Install ax

安装ax

Verify environment

验证环境

Space ID and Project

Space ID与项目

List Datasets: ax datasets list

列出数据集：ax datasets list

Flags

选项

Get Dataset: ax datasets get

获取数据集详情：ax datasets get

Flags

选项

Response fields

响应字段

Export Dataset: ax datasets export

导出数据集：ax datasets export

-> dataset_abc123_20260305_141500/examples.json

-> dataset_abc123_20260305_141500/examples.json

Flags

选项

REST vs Flight (--all)

REST与Flight（--all）对比

Create Dataset: ax datasets create

创建数据集：ax datasets create

Flags

选项

Supported file formats

支持的文件格式

Append Examples: ax datasets append

追加样本：ax datasets append

Inline JSON (agent-friendly)

内联JSON（适合Agent使用）

From a file

从文件导入

To a specific version

追加到指定版本

Flags

选项

Validation

验证规则

Delete Dataset: ax datasets delete

删除数据集：ax datasets delete

Flags

选项

Workflows

工作流示例

Create a dataset from file for evaluation

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

Add examples to an existing dataset

向现有数据集添加样本

Find the dataset

查找目标数据集

Append inline (e.g., from an LLM-generated payload)

内联追加（例如从LLM生成的负载）

Or append from a file

或从文件追加

Download dataset for offline analysis

下载数据集用于离线分析

Export a specific version

导出指定版本

List versions

列出所有版本

Export that version

导出指定版本

Iterate on a dataset

迭代更新数据集

Pipe export to other tools

将导出结果管道到其他工具

Count examples

List Datasets:
`ax datasets list`

列出数据集：
`ax datasets list`

Get Dataset:
`ax datasets get`

获取数据集详情：
`ax datasets get`

Export Dataset:
`ax datasets export`

导出数据集：
`ax datasets export`

REST vs Flight (
`--all`
)

REST与Flight（
`--all`
）对比

Create Dataset:
`ax datasets create`

创建数据集：
`ax datasets create`

Append Examples:
`ax datasets append`

追加样本：
`ax datasets append`

Delete Dataset:
`ax datasets delete`

删除数据集：
`ax datasets delete`