企业官网建设流程全解析

在 Arize 中使用 ax CLI 打造 LLM-as-judge 评估体系：Evaluator、Task 与持续监控实战指南

【免费下载链接】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

本文以 arize-evaluator 技能 为核心，系统讲解如何基于 Arize 的ax命令行工具完成LLM-as-judge 评估的完整闭环：从理解 Evaluator 与 Task 的概念模型，到创建评估器、配置列映射（column mappings）、触发回填/持续评估运行，再到调试取消的运行任务。读完本文，你将能够独立为一个线上 trace 项目或一个离线 experiment 实验设计、创建并运维可靠的自动评估流水线，并掌握排查"运行取消""0 span 被评分"等高频故障的系统化方法。

前置概念：Evaluator 与 Task 的分工

在 Arize 的评估体系中，两个核心概念需要首先厘清：

• Evaluator（评估器）：一个LLM-as-judge 定义。它描述"用什么提示词、让哪个模型、按哪些可选标签去评判"，本身不触碰任何真实数据。
• Task（任务）：把评估器运行到真实数据上的载体。Task 挂接在project（实时 traces/spans）或dataset（实验运行结果）上，负责把评估器模板里的变量映射到实际字段，并控制评分范围与运行方式。

这种"定义与运行分离"的设计，让同一个 Evaluator 可以跨项目、跨实验复用，而项目特有的数据路径只存在于 Task 的列映射中。

Evaluator 的组成字段

Evaluator 是版本化的——每次修改提示词或模型都会产生一个新的不可变版本，最新版本处于激活状态。任何create操作都会同时创建评估器及其第一个版本。

Task 的组成字段

环境准备与排障约定

本技能要求axCLI（版本0.14.0 或更高）和一个已配置好 AI integration 的 Arize profile。运行环境问题参考 ax-setup 排障文档 与 ax-profile 配置文档：

• ax未安装时，macOS/Linux 可用uv tool install arize-ax-cli（首选）、pipx install arize-ax-cli或pip install arize-ax-cli安装；Windows 用pip install arize-ax-cli。
• 版本低于 0.14.0 时用uv tool install --force --reinstall arize-ax-cli升级，很多"子命令不存在"错误源于版本过旧。
• 401 Unauthorized或缺失 API key 时，运行ax profiles show检查当前 profile，按需用ax profiles create --api-key $ARIZE_API_KEY创建或用ax profiles update --api-key $ARIZE_API_KEY修正（始终通过环境变量引用 key，绝不内联明文）。
• 找不到 space 时运行ax spaces list按名称挑选。

关于SPACE参数有两条贯穿全文的约定：所有--space标志和ARIZE_SPACE环境变量都接受 space名称（如my-workspace）或 base64 的 spaceID（如U3BhY2U6...）；此外，ai-integrations create不接受--space——AI integrations 是账户级的，--space只用于list、get、update、delete。

两条不可逾越的安全与诚信红线

• 凭据安全：绝不读取.env文件或在文件系统中搜索凭据。Arize 凭据走ax profiles，LLM 提供商 key 走ax ai-integrations。这些渠道拿不到凭据时直接询问用户。
• 绝不伪造评估结果：如果评估任务失败、被取消或未产出分数，必须如实报告失败原因，禁止"手动评估"、编造质量分数、估算百分比，或把任何 agent 生成的分析伪装成 Arize 评估系统的输出。正确做法是：(1) 修复问题后重试；(2) 尝试从 Arize UI 运行；(3) 用ax ai-integrations list核实集成凭据；(4) 联系 https://arize.com/support。

数据粒度（Data Granularity）：span、trace 与 session

--data-granularity标志决定评估器对哪个数据单元打分，默认span，且只对 project 任务生效（dataset/experiment 任务直接评估实验运行，不适用此标志）。

trace 与 session 的聚合机制

• trace 粒度：共享同一context.trace_id的 spans 被分到一组，评估器模板用到的列值会被逗号拼接成单个字符串（每个值截断到 100K 字符）再交给评判模型。
• session 粒度：先做 trace 级分组，再按start_time排序、按attributes.session.id分组；session 级值总计上限为 100K 字符。

特殊的{conversation}模板变量

在 session 粒度下，{conversation}会被渲染为一个 JSON 数组，包含 session 内所有 trace 的{input, output}轮次——input 侧来自attributes.input.value/attributes.llm.input_messages，output 侧来自attributes.output.value/attributes.llm.output_messages。而在 span 或 trace 粒度下，{conversation}就是一个普通模板变量，按常规列映射解析。

多评估器任务

一个 Task 可以包含不同粒度的评估器。运行时系统按最高粒度（session > trace > span）拉取数据，并自动为每个评估器拆分成一个子运行。每个评估器 JSON 里独立的query_filter可进一步收窄包含哪些 spans（例如只评估 session 内的 tool-call spans）。

基础 CRUD 操作

AI Integrations（LLM 提供商凭据）

AI integration 存储评估器调用评判模型所需的 LLM 提供商凭据。完整的增删改查（OpenAI、Anthropic、Azure、Bedrock、Vertex、Gemini、NVIDIA NIM、custom 等全部提供商）请参考 arize-ai-provider-integration 技能。最常见的 OpenAI 场景速查：

# 先检查是否已有集成 ax ai-integrations list --space SPACE # 没有则创建 ax ai-integrations create \ --name "My OpenAI Integration" \ --provider openAI \ --api-key $OPENAI_API_KEY

记下返回的 integration ID——ax evaluators create --ai-integration-id必须要用到它。注意各提供商要求的额外标志不同：azureOpenAI需要--api-key加--base-url；awsBedrock走 IAM 角色，用--provider-metadata '{"role_arn": "..."}'；vertexAI用--provider-metadata '{"project_id": "...", "location": "..."}'；nvidiaNim和custom需要--base-url。

Evaluators

# 列表 / 查询 ax evaluators list --space SPACE ax evaluators get ID # 接受名称或 ID ax evaluators get NAME --space SPACE # 用名称时必须带 --space ax evaluators list-versions NAME_OR_ID ax evaluators get-version VERSION_ID # 创建（同时创建评估器及其第一个版本） ax evaluators create \ --name "Answer Correctness" \ --space SPACE \ --description "Judges if the model answer is correct" \ --template-name "correctness" \ --commit-message "Initial version" \ --ai-integration-id INT_ID \ --model-name "gpt-4o" \ --include-explanations \ --use-function-calling \ --classification-choices '{"correct": 1, "incorrect": 0}' \ --template 'You are an evaluator. Given the user question and the model response, decide if the response correctly answers the question. User question: {input} Model response: {output} Respond with exactly one of these labels: correct, incorrect' # 创建新版本（版本不可变，提示词或模型变更即新版本） ax evaluators create-version NAME_OR_ID \ --commit-message "Added context grounding" \ --template-name "correctness" \ --ai-integration-id INT_ID \ --model-name "gpt-4o" \ --include-explanations \ --classification-choices '{"correct": 1, "incorrect": 0}' \ --template 'Updated prompt... {input} / {output} / {context}' # 仅更新元数据（名称、描述——不含提示词） ax evaluators update NAME_OR_ID \ --name "New Name" \ --description "Updated description" # 删除（永久，移除所有版本） ax evaluators delete NAME_OR_ID

create的关键标志：

Tasks

PROJECT_NAME、DATASET_NAME和evaluator_id都接受名称或 base64 ID。

# 列表 / 查询 ax tasks list --space SPACE ax tasks list --project PROJECT_NAME ax tasks list --dataset DATASET_NAME --space SPACE ax tasks get TASK_ID # 创建（project——持续评估） ax tasks create \ --name "Correctness Monitor" \ --task-type template_evaluation \ --project PROJECT_NAME \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \ --is-continuous \ --sampling-rate 0.1 # 创建（project——一次性 / 回填） ax tasks create \ --name "Correctness Backfill" \ --task-type template_evaluation \ --project PROJECT_NAME \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \ --no-continuous # 创建（experiment / dataset） ax tasks create \ --name "Experiment Scoring" \ --task-type template_evaluation \ --dataset DATASET_NAME --space SPACE \ --experiment-ids "EXP_ID_1,EXP_ID_2" \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \ --no-continuous # 触发运行（project 任务——使用数据窗口） ax tasks trigger-run TASK_ID \ --data-start-time "2026-03-20T00:00:00" \ --data-end-time "2026-03-21T23:59:59" \ --wait # 触发运行（experiment 任务——使用 experiment IDs） ax tasks trigger-run TASK_ID \ --experiment-ids "EXP_ID_1" \ --wait # 监控 ax tasks list-runs TASK_ID ax tasks get-run RUN_ID ax tasks wait-for-run RUN_ID --timeout 300 ax tasks cancel-run RUN_ID --force

注意：--experiment-ids需要的是 base64 ID，可从ax experiments list --space SPACE -o json获取；代码中的#注释仅为说明，实际命令行中不要带上。trigger-run的时间格式为2026-03-21T09:00:00——不要带结尾的Z。

更多 trigger-run 标志：

运行状态速查：

工作流 A：为 project 创建评估器

适用场景："为我的 Playground Traces 项目创建一个评估器"。

Step 1：确认项目名

ax spans export直接接受项目名，无需查 ID。不知道项目名时先列出：

ax projects list --space SPACE -o json

找到"name"字段大小写不敏感匹配的条目，后续命令用该名称作为PROJECT。若名称触发校验错误，改用该项目的"id"（base64 字符串）。

Step 2：明确要评估什么

如果用户指定了评估器类型（幻觉、正确性、相关性等）→ 跳到 Step 3。否则先抽样最近的 spans，基于真实数据设计评估器：

ax spans export PROJECT --space SPACE -l 10 --days 30 --stdout

检查attributes.input、attributes.output、span kinds 及已有标注，识别失败模式（如幻觉事实、离题回答、缺失上下文），提出1–3 个具体评估器方案让用户挑选。每个方案必须包含：评估器名称（加粗）、一句话描述其评判内容、括号内的二分类标签对。格式如下：

1. Response Correctness— 评判 agent 的回复是否正确回答了用户的金融问题。（correct/incorrect）
2. Hallucination— 评判回复是否捏造了检索上下文中没有的事实。（factual/hallucinated）

Step 3：确认或创建 AI integration

ax ai-integrations list --space SPACE -o json

有合适的集成就记下其 ID；没有则用arize-ai-provider-integration技能创建。向用户确认评判模型用哪个提供商/模型。

Step 4：创建评估器

遵循下文"模板设计最佳实践"。评估器名称和变量保持通用——项目相关的接线由 Step 6 的column_mappings负责：

ax evaluators create \ --name "Hallucination" \ --space SPACE \ --template-name "hallucination" \ --commit-message "Initial version" \ --ai-integration-id INT_ID \ --model-name "gpt-4o" \ --include-explanations \ --use-function-calling \ --classification-choices '{"factual": 1, "hallucinated": 0}' \ --template 'You are an evaluator. Given the user question and the model response, decide if the response is factual or contains unsupported claims. User question: {input} Model response: {output} Respond with exactly one of these labels: hallucinated, factual'

Step 5：询问回填、持续还是两者都要

推荐路径：先用小规模回填（约 100 条历史 spans）验证评估器，再开启持续监控。这样能在已知数据上尽早发现列映射错误、span kind 不匹配和模板问题，避免给后续所有生产 spans 错误评分。创建任务前务必向用户确认：

"您希望： (a) 对历史 spans 做一次回填（一次性）？ (b) 对未来新 spans 设置持续评估？ (c)两者都要——先回填验证，再自动持续评分？（推荐）"

Step 6：从真实 span 数据确定列映射

不要凭空猜测路径，先拉样本检查实际存在的字段：

ax spans export PROJECT --space SPACE -l 5 --days 7 --stdout

为每个模板变量（{input}、{output}、{context}）找到匹配的 JSON 路径。以下为常见起点——使用前务必在你的真实数据上验证：

两个关键陷阱：

• 验证 span kind 对齐：如果评估器提示词假设的是 LLM 最终文本，而任务却指向 CHAIN spans（或反之），运行会取消或评分到错误的文本。确保任务的query_filter与你映射的 span kind 一致。
• query_filter只作用于已索引属性：评估器 JSON 里的query_filter是针对评估索引（eval index）求值的，不是原始 span 存储。attributes.metadata.*或自定义 key 下的属性可能未被索引，会静默匹配不到任何东西。优先用span_kind或attributes.llm.model_name这类公认的已索引属性过滤。若加了过滤器返回 0 spans 但数据明明存在，试着移除过滤器做诊断。

完整的--evaluatorsJSON 示例：

[ { "evaluator_id": "EVAL_ID", "query_filter": "span_kind = 'LLM'", "column_mappings": { "input": "attributes.input.value", "output": "attributes.llm.output_messages.0.message.content", "context": "attributes.retrieval.documents.contents" } } ]

模板引用的每个变量都必须有对应的映射——漏掉任何一个都会导致运行产不出有效分数。

Step 7：创建任务

仅回填 (a)：

ax tasks create \ --name "Hallucination Backfill" \ --task-type template_evaluation \ --project PROJECT \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \ --no-continuous

仅持续 (b)：

ax tasks create \ --name "Hallucination Monitor" \ --task-type template_evaluation \ --project PROJECT \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \ --is-continuous \ --sampling-rate 0.1

两者都要 (c)：创建时用--is-continuous，然后在 Step 8 再触发一次回填运行。

Step 8：触发回填运行（如需要）

评估索引滞后：评估索引从主 trace 存储异步构建，可能滞后1–2 小时。首次测试运行的时间窗口终点至少要落在 2 小时之前。如果把--data-end-time设为"现在"而 spans 是最近一小时内摄入的，运行会"成功完成"但只评分 0 个 spans。

先确认哪个时间范围有数据：

ax spans export PROJECT --space SPACE -l 100 --days 1 --stdout # 先试最近 24h ax spans export PROJECT --space SPACE -l 100 --days 7 --stdout # 为空就扩大

用真实 spans 的start_time/end_time字段设置窗口。首次验证运行把--max-spans限制在约 100，快速获得反馈：

ax tasks trigger-run TASK_ID \ --data-start-time "2026-03-20T00:00:00" \ --data-end-time "2026-03-21T23:59:59" \ --max-spans 100 \ --wait

在扩大到完整回填或开启持续评估之前，先审阅分数和解释说明。

工作流 B：为 experiment 创建评估器

适用场景："为我的实验创建一个评估器"或"评估我的 dataset 运行"。

如果用户说"dataset"但没有 experiment：任务必须针对 experiment（不是裸 dataset）运行。此时应询问："评估任务运行在实验运行上，而不是直接针对数据集。需要我先帮你在该数据集上创建一个实验吗？"如果用户同意，用arize-experiment技能创建实验，然后回到本流程。

Step 1：找到 dataset 和 experiment 名称

ax datasets list --space SPACE ax experiments list --dataset DATASET_NAME --space SPACE -o json

记下 dataset 名称和要评分的 experiment 名称。后续命令中名称和 ID 都接受——优先用名称。

Step 2：明确要评估什么

用户指定了评估器类型就跳到 Step 3；否则先检查一条最近的实验运行：

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

查看output、input、evaluations、metadata字段，找出用户关心但尚未覆盖的指标缺口，提出1–3 个评估器方案（格式同工作流 A 的 Step 2）。

Step 3–4：确认 integration 并创建评估器

同工作流 A 的 Step 3 与 Step 4，变量保持通用。

Step 5：从真实运行数据确定列映射

运行数据的形状与 span 数据不同。常见映射：

• output→"output"（每条运行上的顶层字段）
• input→ 检查它是在运行上还是嵌在关联的 dataset examples 中

若运行 JSON 上没有input，导出 dataset examples 找路径：

ax datasets export DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; ex=json.load(sys.stdin); print(json.dumps(ex[0], indent=2))"

Step 6：创建任务

ax tasks create \ --name "Experiment Correctness" \ --task-type template_evaluation \ --dataset DATASET_NAME --space SPACE \ --experiment-ids "EXP_ID" \ --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \ --no-continuous

Step 7：触发并监控

ax tasks trigger-run TASK_ID \ --experiment-ids "EXP_ID" \ --wait ax tasks list-runs TASK_ID ax tasks get-run RUN_ID

模板设计最佳实践

1. 使用通用、可移植的变量名

使用{input}、{output}、{context}，不要用绑定到特定项目或 span 属性的名字（比如不要用{attributes_input_value}）。评估器本身保持抽象，任务的column_mappings才是把它接到具体项目或实验字段的地方。这样同一个评估器无需修改即可跨多个项目、多个实验运行。

2. 默认使用二分类标签

使用恰好两个清晰的字符串标签（如hallucinated/factual、correct/incorrect、pass/fail）。二分类的优势：

• 评判模型最容易稳定产出
• 业界最常用
• 在仪表盘中解释最简单

如果用户坚持要多于两个选项也没问题——但先推荐二分类并解释权衡（标签越多 → 歧义越多 → 评分者间一致性越低）。

3. 明确告诉模型必须返回什么

模板必须要求评判模型只输出标签字符串，除此之外别无他物。提示词中的标签字符串必须与--classification-choices中的标签完全一致（拼写、大小写都一样）。

好的写法：

Respond with exactly one of these labels: hallucinated, factual

不好的写法（过于开放）：

Is this hallucinated? Answer yes or no.

4. 保持低 temperature

传入--invocation-params '{"temperature": 0}'以获得可复现的评分。更高的温度会给评估结果引入噪声。

5. 用--include-explanations辅助调试

初始搭建阶段始终开启解释说明，这样在大规模信任标签之前，可以验证评判模型推理是否正确。

6. bash 中模板用单引号传递

单引号防止 shell 插值{variable}占位符。双引号会出问题：

# 正确 --template 'Judge this: {input} → {output}' # 错误——shell 可能解析 { } 或直接失败 --template "Judge this: {input} → {output}"

7.--classification-choices必须与模板标签匹配

--classification-choices里的标签必须与--template引用的标签完全一致（拼写、大小写）。省略--classification-choices会导致任务运行报 "missing rails and classification choices" 错误。

故障排查

诊断已取消的运行（cancelled）

当任务运行状态为cancelled时，按下述顺序排查：

1. 检查集成凭据

ax ai-integrations list --space SPACE -o json

确认评估器使用的 integration ID 存在且凭据有效。如果集成被删除或 API key 过期，运行会在约 1 秒内取消。

2. 核实模型名

ax evaluators get EVALUATOR_NAME --space SPACE -o json

检查model_name字段。拼写错误或已弃用的模型会导致 LLM 调用失败，运行约 3 分钟后取消。

3. 导出样本 span/run 并与 column_mappings 对比路径

project 任务：

ax spans export PROJECT --space SPACE -l 1 --days 7 --stdout | python3 -m json.tool

experiment 任务：

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2)) if runs else print('No runs')"

将导出的 JSON 路径与任务的column_mappings对比。对每个模板变量，确认映射路径真实存在。常见不匹配：

• 在 experiment 运行上把output映射到attributes.output.value（应该只是output）
• 在 CHAIN span 上把input映射到attributes.input.value，而真实路径是attributes.llm.input_messages
• 把context映射到被过滤 span kind 上不存在的路径

4. 检查data_start_time不是 epoch

如果trigger-run的起始时间是0、1970-01-01或空字符串，时间窗口就无效。务必从真实 span 时间戳推导：

ax spans export PROJECT --space SPACE -l 5 --days 30 --stdout | python3 -c " import sys, json spans = json.load(sys.stdin) for s in spans: print(s.get('start_time', 'N/A'), s.get('end_time', 'N/A')) "

5. 核实 span kind 与评估器范围一致

如果评估器用--data-granularity trace创建，但任务的query_filter是span_kind = 'LLM'，运行可能找不到合格数据而取消。确保粒度和过滤器一致。

6. 检查所有模板变量都能解析

模板中的每个{variable}都必须有对应的column_mappings条目且解析为非空值。用真实 span 测试解析：

ax spans export PROJECT --space SPACE -l 3 --days 7 --stdout | python3 -c " import sys, json spans = json.load(sys.stdin) # 把下面的路径换成你实际的 column_mappings 值 mappings = {'input': 'attributes.input.value', 'output': 'attributes.output.value'} for i, span in enumerate(spans): print(f'--- Span {i} ---') for var, path in mappings.items(): parts = path.split('.') val = span for p in parts: val = val.get(p) if isinstance(val, dict) else None status = 'FOUND' if val else 'MISSING' print(f' {var} ({path}): {status} — {str(val)[:80] if val else \"null\"}') "

如果某个变量在所有 spans 上都显示 MISSING，修正列映射或调整query_filter指向其他 span kind。

关联技能生态

本技能在 Arize 的 ax 技能族中处于中心位置，与其他技能协同使用：

• arize-ai-provider-integration：LLM 提供商集成的完整 CRUD（SKILL.md），是创建评估器前的凭据前提；
• arize-trace：导出 spans 以发现列路径与时间范围（SKILL.md），其中 OpenInference 语义约定下的attributes.llm.input_messages、attributes.retrieval.documents.contents、annotation.<name>.label等列参考与本文的列映射直接相关；
• arize-experiment：创建实验并导出运行，用于 experiment 任务的列映射；
• arize-dataset：导出 dataset examples，当运行数据缺少input时定位字段；
• arize-link：生成指向 Arize UI 中评估器与任务的深链。

此外，ax-profile 配置文档 提供了凭据持久化的完整指引（profile 创建、region 修正、ARIZE_SPACE环境变量设置，以及会话结束时"保存凭据供下次使用"的规范流程）；ax-setup 文档 覆盖了版本检查、安装升级与 SSL 证书问题的处理。

结语

基于 Arize 的 LLM-as-judge 评估体系，核心是把"评判定义"（Evaluator）与"运行绑定"（Task）解耦：用通用的{input}/{output}/{context}变量写模板、用--classification-choices固定标签集、用column_mappings完成项目级接线。回填先行验证、持续监控跟进，配合"评估索引滞后 1–2 小时""query_filter仅作用于已索引属性"等运行机制认知，就能把幻觉检测、回答正确性、相关性等评估从一次性脚本升级为可维护、可复现、可扩展的自动化质量防线。

【免费下载链接】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