genai-hub-prompt-evaluation

步骤 0 — 首先索取凭据（必需）

运行任何其他步骤之前，请确认 AI Core 凭据已设置。调用 aicore-admin-resources 并运行 check_setup.py。

• 如果成功，请继续工作流。
• 如果失败（缺少变量、invalid_client 或凭据无效），请停止并询问用户 是否可以导出下方环境变量中列出的变量。不要继续，也不要在其他地方（笔记本、其他仓库、工作区文件）查找凭据或工作流步骤 — 此技能的 scripts/ 是唯一受支持的途径。

---

规则

1. 在此技能的根目录中运行所有脚本，命令为 uv run scripts/<name>.py。
2. 共享的生命周期/管理步骤由其他技能处理 — 请调用这些技能，而不是自行重新实现： 对象存储和资源组 → aicore-admin-resources；工件注册、执行、执行状态 → aicore-lifecycle-management。
3. 切勿打印或记录凭据值 — 脚本通过 SDK 从环境变量中读取这些值。
4. 评估场景 ID 为 genai-evaluations。始终使用可执行文件 ID genai-evaluations-simplified — 将其硬编码，不要使用任何带版本/用户后缀的变体。租户可能会列出许多此类自定义镜像；请忽略它们。只有当租户中完全不存在 genai-evaluations-simplified 时，才回退到发现流程（aicore-lifecycle-management get_executables.py --scenario-id genai-evaluations）。
5. 创建自定义指标或提示词注册表配置之前，请先列出现有项目，并按名称/场景/版本复用，以避免重复。create_evaluation_metric.py 已实现创建或获取。
6. 仅当执行状态为 COMPLETED 时才获取结果（get_evaluation_results.py）（UNKNOWN → PENDING → RUNNING → COMPLETED）。通过调用 aicore-lifecycle-management (get_executions.py --execution-id <id>) 检查状态。
7. 如果数据集没有参考/真实值列，请勿选择需要参考数据的指标。

---

环境变量

此技能中的所有脚本都从环境变量读取凭据 — 绝不从 CLI 参数读取。

AI Core 凭据（所有脚本都必需）

变量	说明	备注
AICORE_AUTH_URL	OAuth 令牌端点	必须以 /oauth/token 结尾
AICORE_CLIENT_ID	OAuth 客户端 ID	来自 BTP AI Core 服务密钥
AICORE_CLIENT_SECRET	OAuth 客户端密钥	来自 BTP AI Core 服务密钥
AICORE_BASE_URL	AI Core API 基础 URL	如果尚未包含 /v2，系统会自动追加
AICORE_RESOURCE_GROUP	要操作的资源组	默认值：default

来源：BTP cockpit → 你的子账户 → Instances & Subscriptions → AI Core 实例 → Service Keys。

通过 aicore configure 设置一次（保存到 ~/.aicore/config.json），或导出各个变量：

export AICORE_AUTH_URL=https://<subdomain>.authentication.<region>.hana.ondemand.com/oauth/token
export AICORE_CLIENT_ID=<client-id>
export AICORE_CLIENT_SECRET=<client-secret>
export AICORE_BASE_URL=https://api.ai.<region>.aws.ml.hana.ondemand.com
export AICORE_RESOURCE_GROUP=default

Shell 语法： AICORE_RESOURCE_GROUP='default' — = 前不能有空格。

对象存储凭据（仅 download_evaluation_results.py 必需）

每行 SQLite DB 都直接从 S3 下载 — 此处不会使用 AI Core 凭据。 请设置标准 AWS SDK 环境变量；脚本会直接使用 boto3 的凭据链：

变量	说明
AWS_ACCESS_KEY_ID	S3 访问密钥 ID
AWS_SECRET_ACCESS_KEY	S3 秘密访问密钥

存储桶名称通过命令行中的 --bucket <name> 传递（不会从环境变量读取）。 来源：在 aicore-admin-resources 中创建对象存储密钥时使用的同一组 AWS 凭据。

---

端到端工作流

完整的运行手册（包含所有命令以及各部分的连接方式）位于 references/WORKFLOW.md。以下是工作流概览，以及负责各步骤的技能：

#	步骤	负责方
1	注册 S3 对象存储密钥（输入源）	aicore-admin-resources create_object_store.py
2	将数据集上传到存储桶	用户 — data/ 中的示例数据集
3	将数据集文件夹注册为构件（使用提示词评估标签）	此技能 register_eval_artifact.py
4	确保编排部署正在运行（以获取部署 URL）	aicore-lifecycle-management + genai-hub-orchestration
5	选择系统指标 / 创建自定义指标	此技能 list_evaluation_metrics.py、create_evaluation_metric.py
6	创建待评估对象（请参见下方的评估类型）	此技能 create_prompt_template.py 或 create_orchestration_registry_config.py
7	创建评估配置	此技能 create_evaluation_configuration.py
8	启动执行	aicore-lifecycle-management create_execution.py
9	轮询状态，直到显示 COMPLETED	aicore-lifecycle-management get_executions.py
10	获取汇总结果	此技能 get_evaluation_results.py
11	（可选）下载原始 SQLite 数据库以进行逐行分析	此技能 download_evaluation_results.py

---

评估类型

选择一种类型——它决定了在步骤 6 中要创建的内容，以及在步骤 7 中传递给 create_evaluation_configuration.py 的绑定项：

类型	评估对象	使用以下工具创建	配置绑定项
提示词注册表	一个提示词模板和一个或多个模型	create_prompt_template.py	--prompt-template-id（以及 --models）
编排注册表	一个编排配置（prompt_templating）	create_orchestration_registry_config.py	--orchestration-registry-ids
Grounding 编排注册表	包含 grounding（RAG）模块的编排配置	create_orchestration_registry_config.py（grounding 模板）	--orchestration-registry-ids

这三种类型共用步骤 1–5 和 7–11；只有步骤 6 和配置绑定项不同。Grounding 类型 还需要 grounding 前提条件（启用了 grounding 的资源组、grounding 密钥、 document-grounding 流水线）——请参见 references/GROUNDING_SETUP.md。

---

评估指标

# Discover system metric names (use these verbatim in --metrics later)
uv run scripts/list_evaluation_metrics.py --kind system
uv run scripts/list_evaluation_metrics.py --kind system --name "Pointwise"

# List your custom metrics and their IDs
uv run scripts/list_evaluation_metrics.py --kind custom --json | jq '.[] | {id, name}'

# Create (or reuse) custom LLM-as-a-judge metrics from a definition file (idempotent).
# See templates/custom-metric.json. Prints the resulting metric ID(s).
uv run scripts/create_evaluation_metric.py --file templates/custom-metric.json

常见系统指标：Pointwise Conciseness、Pointwise Answer Relevance、 Pointwise Instruction Following、Pointwise Correctness、Pointwise RAG Context Relevance、 Pointwise RAG Groundedness、Pointwise RAG Context Precision、Pointwise RAG Completeness。 使用 list_evaluation_metrics.py --kind system 确认租户的确切名称。

---

步骤 6 — 创建待评估对象

类型 1 — 提示词注册表

在提示词注册表中创建（或复用）一个提示词模板，然后对多个模型进行基准测试。

uv run scripts/list_prompt_templates.py --scenario genai-evaluations          # reuse?
uv run scripts/create_prompt_template.py --file templates/prompt-template.json \
  --name prompt-registry-eval-demo --version 1.0.0

返回提示词模板 ID → 在步骤 7 中将其与 --models 一起传递给 --prompt-template-id （例如 "gpt-4o:2024-05-13"）。

类型 2 — 编排注册表

创建（或复用）一个编排配置（prompt_templating，不含 grounding）。

uv run scripts/list_orchestration_registry_configs.py --scenario genai-evaluations   # reuse?
uv run scripts/create_orchestration_registry_config.py \
  --file templates/orchestration-registry-config.json \
  --name genai-eval-prompt-config --version 0.0.1

返回配置 ID → 在步骤 7 中将其传递给 --orchestration-registry-ids。

类型 3 — Grounding 编排注册表（RAG）

先完成 references/GROUNDING_SETUP.md 中的 grounding 前提条件，然后使用 grounding 模板创建 配置（添加一个 grounding 模块）：

uv run scripts/create_orchestration_registry_config.py \
  --file templates/orchestration-registry-grounding-config.json \
  --name genai-eval-grounding-config --version 0.0.1

返回配置 ID → 在步骤 7 中将其传递给 --orchestration-registry-ids。此类型请选择 RAG 指标 （Pointwise RAG Groundedness、Pointwise RAG Context Relevance 等）。

---

第 7 步 — 评估配置与执行

直接使用可执行项 ID genai-evaluations-simplified（根据规则 4 — 不要使用带版本或用户后缀的变体）。然后使用此技能的脚本创建配置：

# 2a. Create the evaluation configuration — ORCHESTRATION / GROUNDING types
uv run scripts/create_evaluation_configuration.py \
  --executable-id genai-evaluations-simplified \
  --dataset-artifact-id <artifact-id> \
  --test-dataset-path testdata/full_dataset.csv \
  --test-dataset-type csv \
  --metrics "Pointwise Correctness,Pointwise Answer Relevance" \
  --orchestration-registry-ids <registry-config-id> \
  --orchestration-deployment-url <orchestration-deployment-url> \
  --repetitions 1

# 2b. Create the evaluation configuration — PROMPT REGISTRY type
uv run scripts/create_evaluation_configuration.py \
  --executable-id genai-evaluations-simplified \
  --dataset-artifact-id <artifact-id> \
  --test-dataset-path testdata/full_dataset.csv \
  --metrics "Pointwise Correctness" \
  --prompt-template-id <prompt-template-id> \
  --models "gpt-4o:2024-05-13" \
  --orchestration-deployment-url <orchestration-deployment-url>

自定义指标 ID（来自 create_evaluation_metric.py）可以追加到 --metrics。使用 --test-row-count N 限制行数。使用 --variable-mapping '{"all_metrics/reference":"data/ground_truth"}' 将变量映射到数据集列。

然后将执行本身交由 aicore-lifecycle-management 处理：

• 启动执行 — create_execution.py --configuration-id <config-id>
• 轮询直到 COMPLETED — get_executions.py --execution-id <execution-id> （状态依次为 UNKNOWN → PENDING → RUNNING → COMPLETED）

---

结果

# Aggregate metrics per model/prompt run (only once COMPLETED)
uv run scripts/get_evaluation_results.py --execution-id <execution-id>
uv run scripts/get_evaluation_results.py --execution-id <execution-id> --json

如需获取实例级结果（逐行评分、延迟、日志），请从对象存储下载 SQLite DB（<execution-id>/tmp/results.db）。在环境中设置 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY，然后通过 --bucket 传入存储桶名称：

uv run scripts/download_evaluation_results.py --execution-id <execution-id> --bucket <bucket> --show-tables

完整的下载和本地检查流程（表架构、逐行指标查询）请参阅 references/RESULTS_ANALYSIS.md。

---

交接

• 凭据、资源组或对象存储密钥尚未设置？ → 调用 aicore-admin-resources
• 需要启动／停止／检查执行、发现可执行项或管理部署？ → 调用 aicore-lifecycle-management
• 需要正在运行的编排部署，或想要设计提示词／RAG 流水线？ → 调用 genai-hub-orchestration
• 为 grounding 类型设置 grounding（RAG）？ → 请参阅 references/GROUNDING_SETUP.md（使用 aicore-admin-resources 设置资源组和密钥）
• 通过离线服务评估 Agent（而非提示词／LLM）？ → 调用 aeval-offline-evaluation

---

何时加载参考文件

触发条件	加载
运行完整的端到端评估，或不确定下一步该运行哪个命令	references/WORKFLOW.md
为 grounding 编排类型设置 grounding（RAG）先决条件	references/GROUNDING_SETUP.md
下载并检查原始逐行结果（来自对象存储的 SQLite DB）	references/RESULTS_ANALYSIS.md