企业官网建设流程全解析

使用 ax CLI 在 Arize 上创建、运行与分析 LLM 实验：arize-experiment 技能实战指南

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

导读：本文聚焦 awesome-copilot 仓库中arize-experiment技能（skills/arize-experiment/SKILL.md），系统讲解如何基于 Arize 平台的数据集（Dataset）创建实验（Experiment）、导出实验运行结果、对比不同模型/提示词版本的表现，并完成评估（Evaluation）与回归分析。读完本文，你将掌握ax experiments系列命令的完整用法、Run 数据模型、REST 与 Arrow Flight 两种导出通道的取舍，以及一整套可直接落地执行的工作流与统计显著性判断方法。

arize-experiment是 awesome-copilot 仓库中 Arize AX 插件（plugins/arize-ax/plugin.json）提供的九大技能之一，与该插件的arize-dataset（数据集）、arize-prompt-optimization（提示词优化）、arize-trace（链路追踪）、arize-link（UI 深链）等技能协同，构成完整的「观测 → 建集 → 实验 → 优化」LLM 评测闭环。本文以该技能文档为主体，结合仓库中相关技能的源码文档与插件配置，逐层展开。

核心概念：实验、运行、数据集与评估

在使用任何命令之前，先建立四个相互关联的核心概念：

典型流程为：导出数据集 → 逐个处理示例 → 收集输出与评估 → 用 runs 创建实验。这一流程与arize-dataset技能（skills/arize-dataset/SKILL.md）中"数据集是可版本化、用于评估与实验的示例集合"的定义完全对应——实验永远建立在数据集之上。

前置条件与安全边界

arize-experiment的技能元数据声明其兼容性为"Requires the ax CLI and a configured Arize profile"（需要 ax CLI 与已配置的 Arize 配置文件）。技能明确要求：直接运行所需的ax命令，不要预先检查版本、环境变量或 profile；仅在命令失败时才按错误排查（对应 skills/arize-experiment/references/ax-setup.md 与 skills/arize-experiment/references/ax-profiles.md）。

两条必须严格遵守的红线：

• 安全：绝不读取.env文件或在文件系统中搜索凭据。Arize 凭据一律通过ax profiles管理，LLM 提供商密钥一律通过ax ai-integrations管理；若这些渠道不可用，直接询问用户。
• 绝不伪造输出（CRITICAL）：运行实验时，必须针对每个数据集示例调用用户指定的真实模型 API。严禁虚构、模拟或硬编码模型输出、延迟或评估分数。若无法调用 API（缺少 SDK、凭据、网络错误），必须停下并告知用户缺少什么。

SPACE 约定：所有--space标志与ARIZE_SPACE环境变量都接受 space名称（如my-workspace）或 base64 的 spaceID（如U3BhY2U6...），可用ax spaces list查询。

实验管理基础：列出、获取与删除

列出实验：ax experiments list

浏览实验，可按数据集过滤，输出到 stdout：

ax experiments list ax experiments list --dataset DATASET_NAME --space SPACE --limit 20 # DATASET_NAME 用名称或 ID（优先名称） ax experiments list --cursor CURSOR_TOKEN ax experiments list -o json

获取实验：ax experiments get

快速元数据查询——返回实验名称、关联的数据集/版本和时间戳：

ax experiments get NAME_OR_ID ax experiments get NAME_OR_ID -o json ax experiments get NAME_OR_ID --dataset DATASET_NAME --space SPACE # 使用实验名称而非 ID 时必填

响应字段：

注意experiment_traces_project_id字段揭示了实验与链路追踪的关联：实验中失败 run 的 trace 存储在该项目下，这正是arize-trace（skills/arize-trace/SKILL.md）技能可继续深挖的入口。

删除实验：ax experiments delete

ax experiments delete NAME_OR_ID ax experiments delete NAME_OR_ID --dataset DATASET_NAME --space SPACE # 使用实验名称而非 ID 时必填 ax experiments delete NAME_OR_ID --force # 跳过确认提示

导出实验：REST 与 Arrow Flight 双通道

ax experiments export将全部 runs 下载到文件。默认使用 REST API；传入--all改用 Arrow Flight 做批量传输。

# EXPERIMENT_NAME、DATASET_NAME 可用名称或 ID（优先名称） ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE # -> experiment_abc123_20260305_141500/runs.json ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --all ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --output-dir ./results ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[0]'

REST 与 Flight（--all）如何取舍

• REST（默认）：摩擦最小——无 Arrow/Flight 依赖，走标准 HTTPS 端口，可穿越任何企业代理或防火墙。每页限制 500 条 run。
• Flight（--all）：run 数超过 500 时必需。使用 gRPC+TLS 连接独立主机/端口（flight.arize.com:443），部分企业网络可能拦截。

Agent 自动升级规则：若 REST 导出恰好返回 500 条 run，结果很可能被截断，应改用--all重跑以获取完整数据集。

导出输出是 run 对象的 JSON 数组：

[ { "id": "run_001", "example_id": "ex_001", "output": "The answer is 4.", "evaluations": { "correctness": { "label": "correct", "score": 1.0 }, "relevance": { "score": 0.95, "explanation": "Directly answers the question" } }, "metadata": { "model": "gpt-4o", "latency_ms": 1234 } } ]

创建实验：ax experiments create

用数据文件中的 runs 创建新实验：

ax experiments create --name "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE --file runs.json ax experiments create --name "claude-test" --dataset DATASET_NAME --space SPACE --file runs.csv

通过 stdin 传入数据

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

echo '[{"example_id": "ex_001", "output": "Paris"}]' | ax experiments create --name "my-experiment" --dataset DATASET_NAME --space SPACE --file - # 或用 heredoc ax experiments create --name "my-experiment" --dataset DATASET_NAME --space SPACE --file - << 'EOF' [{"example_id": "ex_001", "output": "Paris"}] EOF

runs 文件必填列

其余列会作为additionalProperties透传到 run 上。

Experiment Run Schema 详解

每条 run 对应一个数据集示例：

{ "example_id": "required -- 关联数据集示例", "output": "required -- 该示例的模型/系统输出", "evaluations": { "metric_name": { "label": "可选字符串标签（如 'correct'、'incorrect'）", "score": "可选数值分数（如 0.95）", "explanation": "可选自由文本" } }, "metadata": { "model": "gpt-4o", "temperature": 0.7, "latency_ms": 1234 } }

评估字段（evaluations）

每个评估中label、score、explanation至少应存在一个。

从数据结构可以推断：evaluations以指标名为键的多值映射，天然支持在同一 run 上挂多个评估维度（如correctness与relevance并存），且每个维度独立拥有 label/score/explanation 三元组，这与arize-prompt-optimization技能（skills/arize-prompt-optimization/SKILL.md）中"性能信号列"的划分（eval.<name>.score、eval.<name>.explanation等）保持一致，即评估结果可直接回流为后续提示词优化的输入信号。

实战工作流一：对数据集运行实验

这是该技能文档给出的完整六步流程，也是最核心的落地路径：

1. 查找或创建数据集

ax datasets list --space SPACE ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'

2. 导出数据集示例

ax datasets export DATASET_NAME --space SPACE

3. 对每个示例调用真实模型 API 并收集输出

使用ax datasets export --stdout将示例直接管道送入推理脚本：

ax datasets export DATASET_NAME --space SPACE --stdout | python3 infer.py > runs.json

infer.py从 stdin 读取示例、调用目标模型、向 stdout 写 runs JSON。下面脚本为模板——先检查导出的数据集 JSON 找到正确的输入字段名，再按用户需求取消对应提供商代码块的注释：

import json, sys, time examples = json.load(sys.stdin) runs = [] for ex in examples: # 检查导出的 JSON 以找到正确字段（如 "input"、"question"、"prompt"） user_input = ex.get("input") or ex.get("question") or ex.get("prompt") or str(ex) start = time.time() # === 在此调用真实模型 API —— 绝不虚构或模拟 === # 取消并适配用户要求的提供商代码块： # # OpenAI（pip install openai —— 使用 OPENAI_API_KEY 环境变量）： # from openai import OpenAI # resp = OpenAI().chat.completions.create( # model="gpt-4o", # messages=[{"role": "user", "content": user_input}] # ) # output_text = resp.choices[0].message.content # # Anthropic（pip install anthropic —— 使用 ANTHROPIC_API_KEY 环境变量）： # import anthropic # resp = anthropic.Anthropic().messages.create( # model="claude-sonnet-4-6", max_tokens=1024, # messages=[{"role": "user", "content": user_input}] # ) # output_text = resp.content[0].text # # Google Gemini（pip install google-genai —— 使用 GOOGLE_API_KEY 环境变量）： # from google import genai # resp = genai.Client().models.generate_content( # model="gemini-2.5-pro", contents=user_input # ) # output_text = resp.text # # 自定义 / OpenAI 兼容代理（pip install openai —— 使用 CUSTOM_BASE_URL + CUSTOM_API_KEY 环境变量）： # 适用于 Azure OpenAI、NVIDIA NIM、本地 Ollama 或任何 OpenAI 兼容端点， # 包括测试集成代理。与 `ax ai-integrations create` 中的 `custom` 提供商对应。 # import os # from openai import OpenAI # resp = OpenAI( # base_url=os.environ["CUSTOM_BASE_URL"], # 如 https://my-proxy.example.com/v1 # api_key=os.environ.get("CUSTOM_API_KEY", "none"), # ).chat.completions.create( # model=os.environ.get("CUSTOM_MODEL", "default"), # messages=[{"role": "user", "content": user_input}] # ) # output_text = resp.choices[0].message.content latency_ms = round((time.time() - start) * 1000) runs.append({ "example_id": ex["id"], "output": output_text, "metadata": {"model": "MODEL_NAME", "latency_ms": latency_ms} }) print(f" {ex['id']}: {latency_ms}ms", file=sys.stderr) json.dump(runs, sys.stdout, indent=2)

运行前：安装提供商 SDK（pip install openai/anthropic/google-genai），并确保 API key 已在 shell 中设为环境变量。若无法访问 API，停下并告知用户所需条件。

注意该模板的通用输入提取逻辑（ex.get("input") or ex.get("question") or ex.get("prompt")）印证了arize-dataset技能中"示例（Example）是带有任意用户自定义字段的单条记录（如question、answer、context）"的定义——字段名由你建数据集时自定义，推理脚本必须适配。

4. 校验 runs 文件

python3 -c "import json; runs=json.load(open('runs.json')); print(f'{len(runs)} runs'); print(json.dumps(runs[0], indent=2))"

每条 run 必须包含example_id和output。可选字段：evaluations、metadata。

5. 创建实验

ax experiments create --name "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE --file runs.json

6. 验证

ax experiments get "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE

实战工作流二：对比两个实验

对比实验是模型选型（A/B 测试）、提示词迭代的核心手段，本质上是将两个实验的导出结果按example_id对齐后做分析：

1. 导出两个实验

ax experiments export "experiment-a" --dataset DATASET_NAME --space SPACE --stdout > a.json ax experiments export "experiment-b" --dataset DATASET_NAME --space SPACE --stdout > b.json

2. 按example_id对比评估分数

# 实验 A 的 correctness 平均分 jq '[.[] | .evaluations.correctness.score] | add / length' a.json # 实验 B 同理 jq '[.[] | .evaluations.correctness.score] | add / length' b.json

3. 找出结果有差异的示例

jq -s '.[0] as $a | .[1][] | . as $run | { example_id: $run.example_id, b_score: $run.evaluations.correctness.score, a_score: ($a[] | select(.example_id == $run.example_id) | .evaluations.correctness.score) }' a.json b.json

4. 每个评估器的分数分布（pass/fail/partial 计数）

# 统计实验 A 中按 label 分组的数量 jq '[.[] | .evaluations.correctness.label] | group_by(.) | map({label: .[0], count: length})' a.json

5. 找出回归（在 A 中通过但在 B 中失败）

jq -s ' [.[0][] | select(.evaluations.correctness.label == "correct")] as $passed_a | [.[1][] | select(.evaluations.correctness.label != "correct") | select(.example_id as $id | $passed_a | any(.example_id == $id)) ] ' a.json b.json

统计显著性提示

分数对比在每个评估器至少 30 个示例时最可靠。示例不足时，把差值仅视为方向性参考——n=10 时 5% 的差异可能只是噪声。报告分数时务必附带样本量：jq 'length' a.json。

实战工作流三：下载结果用于分析、并管道到其他工具

下载实验结果用于分析：

1. ax experiments list --dataset DATASET_NAME --space SPACE—— 查找实验
2. ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE—— 下载到文件
3. 解析：jq '.[] | {example_id, score: .evaluations.correctness.score}' experiment_*/runs.json

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

# 统计 run 数量 ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq 'length' # 提取所有输出 ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[].output' # 获取低分 run ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '[.[] | select(.evaluations.correctness.score < 0.5)]' # 转换为 CSV ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq -r '.[] | [.example_id, .output, .evaluations.correctness.score] | @csv'

--stdout+jq的组合让实验导出结果可以无缝融入任何下游分析管线（统计、可视化、CI 报告生成等），无需落盘中间文件。

与相关技能的协同链路

在 Arize AX 插件的技能矩阵中（见 plugins/arize-ax/README.md），arize-experiment处于评测环节的枢纽位置，其前后衔接关系如下：

• arize-dataset（前一步）：创建或导出实验所运行的数据集 → 先用arize-dataset
• arize-prompt-optimization（后一步）：利用实验结果改进提示词 → 下一步是arize-prompt-optimization
• arize-trace（排查失败 run）：检查失败实验 run 的单个 span trace → 用arize-trace
• arize-link（生成 UI 深链）：从实验 run 生成可点击的 trace UI 链接 → 用arize-link

这条链路揭示了实验在评测闭环中的位置：数据集定义评测输入，实验产出量化结果，结果驱动提示词优化，trace 与深链支撑人工排查与分享。

故障排查速查表

排查参考文档要点

两个参考文档均约定仅在命令失败时才查阅，不做主动检查：

• ax-setup.md：若ax已安装（非command not found），先运行ax --version，版本必须≥ 0.14.0（许多错误源于安装过旧）。command not found时按平台安装：macOS/Linux 优先uv tool install arize-ax-cli（备选pipx install arize-ax-cli、pip install arize-ax-cli），Windows 用pip install arize-ax-cli；过旧版本用uv tool install --force --reinstall arize-ax-cli（或pipx upgrade、pip install --upgrade）升级。SSL/证书错误可设置SSL_CERT_FILE指向系统证书或 certifi 路径。
• ax-profiles.md：先ax profiles show检查状态；修复用ax profiles update --api-key $ARIZE_API_KEY --region us-east-1b（仅修改指定字段，其余保留）；新建用ax profiles create work --api-key $ARIZE_API_KEY --region us-east-1b；使用命名 profile 时给命令加-p NAME。绝不以明文 flag 传 API key，一律通过$ARIZE_API_KEY环境变量引用，且绝不让用户把 key 粘贴进聊天、绝不记录/回显 key 值。space 没有 profile flag，保存为环境变量：macOS/Linux 在~/.zshrc或~/.bashrc中export ARIZE_SPACE="my-workspace"，Windows PowerShell 用[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE', 'my-workspace', 'User')。

会话结束时保存凭据

若本次会话中用户手动提供了任何凭据，且这些值并非来自已保存的 profile 或环境变量，在会话结束时提供保存选项（跳过场景：key 已来自现有 profile/ARIZE_API_KEY、space 已通过ARIZE_SPACE设置、用户仅用了 base64 project ID）。征得同意后：API key 用ax profiles create --api-key $ARIZE_API_KEY或ax profiles update --api-key $ARIZE_API_KEY（key 必须先导出为环境变量），space 按上文持久化为环境变量。

小结

arize-experiment技能把「对 LLM 模型/提示词做受控评测」沉淀为一套可复现的命令工作流：ax experiments list/get管理实验元数据，export双通道（REST 500 条上限 / Flight 批量）保证大规模实验的完整下载，create以 CSV/JSON/JSONL/Parquet 或 stdin 摄入 runs，Run Schema 用example_id + output + evaluations + metadata统一数据模型。结合六步实战流程（导出数据集 → 真实推理 → 校验 → 建实验 → 验证）与 jq 驱动的对比/回归分析，即可在 Arize 平台上完成模型选型与迭代评测；配合arize-dataset、arize-prompt-optimization、arize-trace、arize-link等兄弟技能，可打通从数据集构建到提示词优化的完整闭环。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot