genai-hub-tabular-orchestration

规则

1. 从技能根目录运行所有脚本：uv run scripts/<name>.py。
2. 切勿打印或记录凭据值——SDK 会从环境中读取。
3. 发送预测请求前，务必确认 TCR 前置条件（数据目标 → 表格化工件 → 场景配置）均已就绪。
4. 预测请求中的 rows 和 columns 互斥——切勿同时包含两者。
5. 遇到凭据或身份验证错误时，先调用 aicore-admin-resources。
6. 修改脚本需要 --confirm；执行删除操作时务必显式传入该参数。
7. 用户未指定 --resource-group 时，不要传入该参数；SDK 将使用默认值。
8. 执行任何 btp update services/instance 命令前，必须：(a) 运行 btp get services/instance --id <id>，获取完整的当前 parameters 块；(b) 向用户展示完整的当前参数和准确的差异——包括将添加、更改或移除的内容——以及将要发送的完整结果载荷；(c) 要求用户明确确认所展示的参数和拟议更改。在用户于同一轮中确认之前，任何情况下都不得执行 btp update services/instance。

---

概念

上下文注册表（TCR）通过三个分层资源向 AI Core 场景公开结构化数据：

Data Destination  →  Tabular Artifact  →  Scenario Configuration
(HDL connection)      (file + schema)       (named bundle of TAs)

• 数据目标：存储 HDL（HANA Data Lake）端点的连接凭据。
• 表格化工件（TA）：指向数据目标上的特定文件，并包含架构元数据 （CSN）。支持 CSV、Parquet 和 Delta 格式。架构可以内联提供（DOCUMENT）、 通过路径引用（REFERENCE），也可以自动派生（AUTO）。
• 场景配置：由表格化工件名称组成的命名可复用列表——在推理时由 AI Core 场景使用。

所有资源均限定在某个资源组（AI-Resource-Group 标头）内。请先使用 aicore-admin-resources 技能验证凭据并获取当前活动资源组。

---

快速开始

# 1. Check setup
uv run scripts/check_setup.py    # from aicore-admin-resources, or verify env vars

# 2. List all three resource types
uv run scripts/list_data_destinations.py
uv run scripts/list_tabular_artifacts.py
uv run scripts/list_scenario_configs.py

# 3. Register a new HDL data destination
uv run scripts/create_data_destination.py --name my-hdl --host <hdl-hostname>

# 4. Register a tabular artifact (AUTO schema, CSV)
uv run scripts/create_tabular_artifact.py \
  --name customer-ta \
  --data-destination my-hdl \
  --path /data/customer.csv \
  --type CSV

# 5. Create a scenario configuration
uv run scripts/create_scenario_config.py \
  --name my-scenario \
  --tabular-artifacts customer-ta,orders-ta

---

数据目标

数据目标用于存储 HDL 主机名和凭据；系统会在创建时验证连接，并安全地存储凭据。

创建数据目标前，请向用户询问：

1. 名称 — kebab-case，1–127 个字符（例如 my-hdl）
2. HDL 主机名 — 不带 https:// 前缀（例如 abc123.files.hdl.eu10.hanacloud.ondemand.com）
3. （可选） 标签 — 遵循 (ext|int).ai.sap.com/<suffix> 模式的键值对
4. （可选） 描述 — 自由文本描述

uv run scripts/list_data_destinations.py               # list all
uv run scripts/list_data_destinations.py --json        # pipe-friendly JSON

uv run scripts/get_data_destination.py --name <name>   # get details of one destination
uv run scripts/get_data_destination.py --name <name> --json

uv run scripts/create_data_destination.py \
  --name <name> \
  --host <hdl-hostname>
  # hostname only — no https:// prefix, e.g. abc123.files.hdl.eu10.hanacloud.ondemand.com
  # optional: --labels ext.ai.sap.com/env=prod --description "Production HDL"

# Update labels (replaces the entire label set)
uv run scripts/patch_data_destination.py --name <name> --labels ext.ai.sap.com/env=prod
uv run scripts/patch_data_destination.py --name <name> --labels ext.ai.sap.com/env=prod ext.ai.sap.com/team=data

# Search by labels
uv run scripts/search_data_destinations.py --labels ext.ai.sap.com/env=prod
uv run scripts/search_data_destinations.py --labels ext.ai.sap.com/env=prod --json

uv run scripts/delete_data_destination.py --name <name> --confirm
# Note: deletes cascade to all tabular artifacts that reference this destination.

名称约束：小写字母、数字和连字符；1–127 个字符；必须以字母数字字符开头和结尾。

标签遵循 (ext|int).ai.sap.com/<suffix> 模式，可用于通过搜索端点进行筛选（参见 references/API.md）。

创建后的必要步骤 — 在 HDL 中注册主题模式：create_data_destination.py 成功运行后，响应中会包含一个或多个 X.509 主题 DN（subjectPatterns）。必须将这些 DN 添加为 HDL Files 服务实例配置中的 authorizations。请引导用户完成以下步骤：

0. 验证 BTP CLI 登录状态

运行任何 btp 命令前，请确保已安装 BTP CLI 并已登录。安装和登录说明请参见 references/SETUP.md。

1. 查找 HDL Files 实例 ID

btp target --subaccount <subaccount-id>
btp list services/instance

查找名称或类型与此数据目标所用 HDL Files 服务对应的实例。

2. 获取并显示当前实例参数

btp get services/instance --id <hdl-instance-id>

从输出中提取完整的 parameters 块，并原样显示给用户。注意任何现有的 authorizations 条目——更新载荷中必须保留这些条目。

3. 构建并确认更新载荷

构建完整的 parameters 载荷，在保留所有现有 authorizations 条目的基础上，添加新的主题模式。向用户显示：

• 当前 authorizations 数组（来自步骤 2）
• 要添加的新条目
• 将要发送的完整结果载荷

如果 AI Core 返回多个模式，则为每个模式添加一个条目，并按顺序设置 rank。authorizations 数组会替换现有数组——务必包含所有现有条目。

请用户明确确认当前参数和拟议载荷后再继续。在同一轮对话中收到确认前，不得继续。

4. 应用更新

仅在用户确认后：

btp update services/instance \
  --id <hdl-instance-id> \
  --parameters '{
    "data": {
      "fileContainer": {
        "authorizations": [
          {
            "pattern": "<subject-pattern-from-ai-core>",
            "rank": 1,
            "roles": ["user"]
          }
        ]
      }
    }
  }'

你拥有此角色吗？ 需要拥有 HDL 实例所属子账户的子账户管理员或服务管理员角色。如果没有，请将主题模式告知 BTP 管理员，并请他们执行此步骤。

传播延迟：更改可能需要 1–2 分钟才能生效。如果更新后立即创建表格工件仍返回 403，请等待后重试。

在用户确认主题模式已注册（或 BTP 管理员已完成注册）之前，不要继续创建表格工件。

---

表格制品

表格制品会将数据目标上的文件注册为可查询的虚拟表。有三种架构定义模式：

definitionType	适用场景	所需内容
AUTO	让系统从文件中推导架构	仅需 definitionType: AUTO
DOCUMENT	内联提供列名和类型——推荐	--csn-columns col:cds.Type,...
REFERENCE	指向数据目标上的 CSN 文件	documentReference.path 中的路径

创建表格制品前，请向用户询问：

1. 名称 — kebab-case，1–80 个字符（例如 customer-data）
2. 数据目标名称 — 必须已存在（如不确定，请使用 list_data_destinations.py 列出）
3. 文件路径 — HDL 上文件的绝对路径（例如 /data/customer.csv）
4. 文件类型 — CSV、PARQUET 或 DELTA
5. （仅限 DOCUMENT 模式） 实体名称 — 表的 PascalCase 标签（例如 Customer）
6. （仅限 DOCUMENT 模式） 列名 — 与文件标题行中的名称完全一致
7. （仅限 DOCUMENT 模式） 每列的类型 — 使用完整的 cds.* 类型名称（例如 cds.String、cds.Integer）

然后使用 --csn-columns 内联传入这些内容：

uv run scripts/list_tabular_artifacts.py               # list all
uv run scripts/list_tabular_artifacts.py --json

uv run scripts/get_tabular_artifact.py --name <name>   # get details of one artifact
uv run scripts/get_tabular_artifact.py --name <name> --json

# AUTO schema (simplest — works well for CSV with a header row)
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.csv \
  --type CSV

# DOCUMENT schema — supply column names and types explicitly
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.csv \
  --type CSV \
  --csn-columns "id:cds.Integer,name:cds.String,score:cds.Decimal,active:cds.Boolean" \
  --entity-name MyEntity

# REFERENCE schema (CSN file lives on the HDL)
uv run scripts/create_tabular_artifact.py \
  --name <name> \
  --data-destination <dd-name> \
  --path /data/file.parquet \
  --type PARQUET \
  --csn-reference /data/metadata/schema.json \
  --entity-name MyEntity

uv run scripts/delete_tabular_artifact.py --name <name> --confirm
# Deletion is async (202 Accepted); the artifact transitions to DELETING status.

--csn-columns 格式：以逗号分隔的 name:cds.Type 对。 支持的类型：cds.UUID、cds.Boolean、cds.Integer、cds.Int16、cds.Int32、cds.Int64、 cds.UInt8、cds.Decimal、cds.Double、cds.Date、cds.Time、cds.DateTime、cds.Timestamp、 cds.String、cds.Binary、cds.LargeBinary、cds.LargeString、cds.Map、cds.Vector。 列名必须与文件的标题行完全一致。

名称限制：小写字母、数字和连字符；1–80 个字符；必须以字母或数字开头和结尾。

---

场景配置

场景配置是一组具名且稳定的表格制品名称列表，AI Core 场景会在推理时通过名称引用这些名称。

uv run scripts/list_scenario_configs.py
uv run scripts/list_scenario_configs.py --json

uv run scripts/get_scenario_config.py --name <name>    # get details of one config
uv run scripts/get_scenario_config.py --name <name> --json

uv run scripts/create_scenario_config.py \
  --name <name> \
  --tabular-artifacts ta1,ta2,ta3

# Update the TA list (replaces the entire list)
uv run scripts/patch_scenario_config.py \
  --name <name> \
  --tabular-artifacts ta1,ta2,ta3,ta4

uv run scripts/delete_scenario_config.py --name <name> --confirm

名称限制：与数据目标相同（小写字母、连字符，1–127 个字符）。

---

表格预测（predict.py）

使用 predict.py 向已部署的表格 RPT 模型（sap-rpt-1-small 或 sap-rpt-1-large）发送推理请求。模型会从 TCR 读取上下文行，并为查询行预测值。

uv run scripts/predict.py --deployment-id <id> --body '<json>'
# optional: --json  --main-tenant <uuid>  --resource-group <rg>

规则

1. 必须满足 TCR 前置条件 — 发送预测请求前，必须已注册表格制品、场景配置和 数据目标（参见上文各章节）。

2. rows 和 columns 互斥 — 同一请求中绝不能同时包含二者。

3. 预测目标必须包含 "[PREDICT]" — 查询行中目标列的每个条目都必须是占位字符串 "[PREDICT]"。

---

交互式构建流程

按顺序完成以下步骤。跳过用户已回答的步骤。

步骤 1 — 确认 TCR 前置条件

询问：

Before we proceed, please confirm you have already set up the following in TCR:
  ✓ Tabular artifact (context dataset uploaded)
  ✓ Scenario configuration (scenarioConfigName you want to use)
  ✓ Data destination

If any of these are missing, I can help you set them up first.

如果尚未设置，请使用上述 TCR 脚本帮助用户注册，然后返回预测流程。

---

步骤 2 — 确认 scenarioConfigName 和 deploymentId

uv run scripts/list_scenario_configs.py

获取 deployment ID（表格型 RPT 部署可能不会显示在已知场景中）：

uv run ../aicore-lifecycle-management/scripts/get_deployments.py --status RUNNING

确认这两项后，还要在一条消息中询问以下内容：

参数	询问内容
deploymentId	“你的部署 ID 是什么？”
modelName	“要使用哪个模型：sap-rpt-1-small（速度更快）还是 sap-rpt-1-large（准确度更高）？”
目标列	“你想预测哪一列？”
任务类型	“这是分类任务（预测类别）还是回归任务（预测数值）？（可选 — 模型可以自动检测）”
数据格式	“你将如何提供数据 — 按列（数组组成的对象）还是按行（对象组成的数组）？”

---

步骤 3 — 收集并整理数据

请用户提供查询数据。接受任何格式：

• 粘贴的表格 / CSV 文本
• JSON 行 [{...}, {...}]
• 键值对
• 类似电子表格的格式

根据步骤 2 中选择的格式转换数据：

如果选择按列格式：

"columns": {
  "Col A": ["val1", "val2", "val3"],
  "Col B": [10, 20, 30],
  "Target": ["[PREDICT]", "[PREDICT]", "[PREDICT]"]
}

如果选择按行格式：

"rows" : [
  {"Col A": "val1", "Col B": 10, "Target": "[PREDICT]"},
  {"Col A": "val2", "Col B": 20, "Target": "[PREDICT]"}
]

整理数据的规则：

• 将所有查询行中目标列的值替换为 "[PREDICT]"
• 确保所有数组长度相同
• 完全保留用户提供的列名

还要询问用户是否有上下文数据（包含已知答案、供模型学习的行）。如果有，请收集并将其整理为 contextColumns — 保留实际目标值（上下文数据中不要使用 "[PREDICT]"）。

---

步骤 4 — 构建 predictionConfig

"predictionConfig": {
  "targetColumns": [
    {
      "name": "<target column name>",
      "predictionPlaceholder": "[PREDICT]",
      "taskType": "<classification | regression>"
    }
  ]
}

---

步骤 5 — 构建 contextSelectionConfig

请用户选择如何从数据目标位置采样上下文行，以及要包含多少行。：

How should context rows be sampled?
  A) random    — default, good general purpose
  B) heuristic — scoring-based, finds similar rows
  C) none      — take from HEAD or TAIL of the table
How many context rows? (default: 50)

根据用户的选择，参照 references/PREDICT.md 中的 contextSelectionConfig 部分来构建 JSON 对象。如果用户选择启发式采样，请询问或确认所需的唯一行 ID 列，将其作为 indexColumn。询问用户是否要自定义 strategyConfig，否则使用合理的默认值。

---

步骤 6 — 组装并发送

向用户展示完整的 JSON 请求体，然后运行：

uv run scripts/predict.py \
  --deployment-id <deploymentId> \
  --body '<assembled-json>'

---

常见错误

TCR / Context Registry

错误	可能原因	修复方法
401 Unauthorized	令牌 / 凭据无效	重新运行 aicore configure
404 Not Found	名称或资源组错误	检查 --name 和 AI-Resource-Group
409 Conflict	已存在同名资源	选择其他名称或先删除现有资源
400 Bad Request	名称格式不符合要求或缺少字段	查看上方的名称限制
创建 TA 时出现 403 Access Denied	尚未在 HDL 实例中注册主题模式	按照上方“注册主题模式”步骤操作；更新后等待 1–2 分钟
HDL 连接被拒绝	主机名错误或无法访问网络	省略 https://，检查连接
TA 卡在 DELETING 状态	后台清理仍在进行	运行 cleanup 端点；参见 references/API.md

有关端点详情、字段架构和分页参数，请参见 references/API.md。

预测

HTTP	错误代码	描述	修复方法
400	VALIDATION_ERROR	请求验证失败	检查必填字段——modelName、scenarioConfigName、predictionConfig.targetColumns；确保只提供 rows/columns 其中之一；确认所有数组长度相同
401	—	身份验证失败	检查 --main-tenant 和 --resource-group 请求头
404	MODEL_NOT_FOUND	模型不可用	确认 modelName 是 sap-rpt-1-small 或 sap-rpt-1-large，并且部署正在运行
404	SCENARIO_CONFIG_NOT_FOUND_ERROR	未找到场景配置	通过上方的“场景配置”部分创建配置
500	CONTEXT_SELECTOR_ERROR	上下文选择器故障	检查 TCR 设置——表格工件和数据目标必须运行正常
500	SAP_RPT1_SMALL_ERROR	SAP RPT-1 Small 故障	检查部署状态；重试或切换到 sap-rpt-1-large
500	SAP_RPT1_LARGE_ERROR	SAP RPT-1 Large 故障	检查部署状态；重试或切换到 sap-rpt-1-small
502	BAD_GATEWAY	外部服务故障	检查部署状态；TFM 或上下文选择器无法访问
504	GATEWAY_TIMEOUT	请求超时	减少 numRows 或批次大小

---

交接

情况	使用技能
凭据或身份验证错误、资源组管理	aicore-admin-resources
检查部署状态、创建或停止部署	aicore-lifecycle-management
查找可执行 ID 或浏览基础模型	genai-hub-foundation-models

---

何时加载参考文件

触发条件	加载
任何凭据或身份验证错误	aicore-admin-resources 技能
未安装 BTP CLI 或尚未登录	references/SETUP.md
即将引导用户执行 BTP 步骤（注册主体模式）	references/API.md
需要完整字段参考或预测请求的完整示例	references/PREDICT.md
用户提供不常见的数据格式，需要转换指导	references/PREDICT.md