huawei-cloud-cloudrobo-dataset

Windows / PowerShell: 例では bash の構文を使用しています。Windows PowerShell で実行するには、次のようにします。

• \ による行継続を1行にまとめるか、行末にバッククォートを付けます。
• 環境変数は export NAME="value" ではなく $env:NAME="value" で設定します。
• シングルクォートで囲んだ JSON '{"a":"b"}' はそのまま使えます。

概要

cloudrobo-dataset スキルは、CloudRobo のデータ処理（proc-tasks）とデータ評価（eval-tasks）の全ライフサイクルを管理します。アルゴリズムの検索、タスクの CRUD 操作、ステータスのポーリング、ログの取得（システムログ＋ジョブログ）とダウンロード、出力データのプレビュー、フレームの抽出、アセットマーケットプレイスでのアルゴリズム検索、処理から評価へのパイプラインのオーケストレーション、バッチタスク管理、失敗の診断に対応します。

適用シナリオ： タスク管理（CRUD＋再起動）、トラブルシューティング（ログ取得＋エラー分析）、アルゴリズム検索、結果の確認（プレビュー＋フレーム）、パイプラインのオーケストレーション、バッチ管理、分析。

アーキテクチャ：

Agent / LLM
    │
    ├── CLI  →  cloudrobo dataset proc <command>     (proc-tasks)
    │           cloudrobo dataset eval <command>     (eval-tasks)
    ├── SDK  →  DatasetClient (Python)
                    │
                    ▼
              cloudrobo-service (REST API)
              /v1/data-eng/proc-tasks/*
              /v1/data-eng/eval-tasks/*

すべての操作は cloudrobo-service バックエンドを対象とし、workspace_id が必要です（--workspace-id で上書きしない限り、デフォルトのワークスペースが使用されます）。アルゴリズムとデータセットの検索はパッケージをまたぐ操作で、cloudrobo asset を介して cloudrobo-asset-manager サービスを呼び出します。

前提条件

CLI のインストール、AK/SK 認証、ワークスペース設定については、references/cli-installation-guide.md を参照してください。すべてのデータセット操作には、有効な workspace_id（デフォルトまたは明示的な --workspace-id）が必要です。

ワークフロー

対話型タスクの作成

すべての対話型作成ワークフローでは、対話ルールに従います。1ターンにつきツール呼び出しは最大1回とし、次の質問をする前に検索結果を表示します。

Proc-Task の作成（10ステップ）：タスク名 → 説明 → アルゴリズムの種類（PRESET_ASSETS/WORKSPACE_ASSETS/OBS_ASSETS）→ フィールドマッピングを含むアルゴリズム設定 → 環境変数 → ジョブの種類とリソース（CCE/K8S または CCE_RAY/RAY、リソースプール、インスタンス仕様）→ 動的ストレージ（パブリックプールのみ）→ 入力データセット（複数データセットのループ）→ 出力設定 → 確認して送信。詳細な手順については、references/interactive-workflow.md を参照してください。

Eval-Task の作成（7ステップ）：タスク名 → 説明 → リソースプールとインスタンス仕様 → 評価アルゴリズム → データセット（単一）→ ロボット設定 → 確認して送信。詳細な手順については、references/interactive-workflow.md を参照してください。

タスクのポーリングと結果の処理

1. ステータスをポーリング — dataset proc wait-task（推奨間隔は15秒）を実行し、終端状態（SUCCEEDED/FAILED/DELETED）になるまで、状態が変化するたびにユーザーへ報告します。
2. 完了時：
   • SUCCEEDED：get-preview で処理結果を表示し、システムログを出力します。
   • FAILED：ログを表示するかユーザーに確認し、システムログとジョブログを出力します。

Eval タスク： SUCCEEDED になったら、タスク詳細の target_report_path からレポートのパスを取得し、dataset eval get-preview --task-id <task-id> --file-name <obs-path-without-bucket> を使用して OBS の一時リンクを取得します。

パイプラインワークフロー（タスクのオーケストレーション）

シナリオ：データ変換 → データ評価 → アーティファクトのダウンロード

1. 処理タスクを実行し、SUCCEEDED になるまで待ちます。
2. タスク詳細から target_path と target_asset_id を取得します。
3. obs_path を target_path、asset_id を target_asset_id とする dataset_configs エントリーを作成します。
4. 評価タスクを作成し、SUCCEEDED になるまで待ちます。
5. レポートを取得します：dataset eval get-preview --file-name <path-from-target_report_path>（obs://<bucket>/ のプレフィックスを削除します）。
6. download-asset でアーティファクトをダウンロードします。

バッチワークフロー（バッチタスク）

シナリオ：複数のデータセットに同じアルゴリズムを実行

1. データセットの一覧を取得します（asset list-assets --type dataset）。
2. データセットごとに処理タスクを作成します（最初のタスクのアルゴリズムとリソース設定を再利用し、入力データセットのみ変更します）。
3. task_ids を収集し、ステータスをポーリングします。
4. 成功・失敗・処理中の件数を集計します。
5. 失敗したタスクについては、ログを表示するか再起動します。

診断ワークフロー（失敗の診断）

シナリオ：タスクが失敗 → ログを分析し、修正案を提示します

1. システムログとユーザーログを取得します
2. エラーパターンを分析します：OOM → worker_spec.memory を増やします。パスが見つからない → dataset_configs を確認します。イメージのプルに失敗 → image を確認します。パラメーターエラー → algo_entrance/envs を確認します。アクセス拒否 → catalog_id/権限を確認します
3. 診断結果と修正案を提示します
4. 確認後、update-task で変更するか、restart-task で再起動します

分析ワークフロー（データ分析）

ステータス別のタスク統計、アルゴリズムのランキング、時間的な傾向、失敗率を集計します。根本原因の提案を含む分析レポートを出力します。

長時間実行タスクのワークフロー

タイムアウトを指定して wait-task を開始します。タイムアウトした場合は、ステータスと経過時間を報告し、続行／ログの表示／終了のいずれにするかをユーザーに確認します。

CLI コマンド形式の標準

cloudrobo dataset proc <command> [OPTIONS]
cloudrobo dataset eval <command> [OPTIONS]

機能	説明	例
コマンドグループ	dataset proc（proc-tasks）、dataset eval（eval-tasks）	cloudrobo dataset proc
サブコマンド	ケバブケース	create-task、list-tasks、show-task
ワークスペースの上書き	--workspace-id <id>	--workspace-id abc-123
出力形式	標準出力への JSON	out(result)
ドライラン	--dry-run（サポートされている場合）	実行せずにプレビューします
ブール値フラグ	--is-system true	--is-system true
カンマ区切りリスト	--task-ids id1,id2,id3	--task-ids aaa,bbb

主なコマンド

タスク管理（proc-tasks）

データ処理タスクの作成

cloudrobo dataset proc create-task --name <task-name> --algo-type PRESET_ASSETS --task-config '<json-config>' [--workspace-id <id>] [--wait] [--timeout 1800] [--dry-run]

• SDK： client.create_task(task_config: dict)
• API： POST /v1/data-eng/proc-tasks

必須の task_config フィールド：name、algo_type（ステップ 3 の選択に基づく PRESET_ASSETS / WORKSPACE_ASSETS / OBS_ASSETS）、algo_name、algo_entrance、 image、algo_id、catalog_id（ワークスペースのもの）、resource_pool_type、cluster_type、 task_framework_type、dataset_configs（JSON 文字列の配列、複数データセットの入力）、 output_type、output_path、output_name、head_spec（cpu/memory/gpu/npu を含める必要があります）、worker_spec（cpu/memory/gpu/npu を含める必要があります）、worker_num、 evs_spec。全フィールドのマッピングについては、references/task-config-catalog.md を参照してください。

⚠️ 空でないことの検証： description を除き、すべてのパラメーターに空の値（空文字列 ""、None、空の辞書 {}）を指定できません。SDK は API に送信する前にこれを検証します。head_spec/worker_spec には 4 つすべてのキー（cpu、memory、gpu、npu）が必要です（値 0 は有効です）。dataset_configs には少なくとも 1 件のデータセットエントリーが必要です。空の配列 "[]" は無効です。

タスク一覧の取得

cloudrobo dataset proc list-tasks [--status RUNNING|SUCCEEDED|FAILED] [--algo-type <type>] [--name <name>] [--order-by start_at|update_at|finish_at] [--order DESC|ASC] [--offset <n>] [--limit <n>] [--user-id <id>] [--algo-name <name>] [--output-name <name>] [--workspace-id <id>]

• SDK： client.list_tasks(workspace_id=None, statuses=..., algo_type=..., name=..., order_by=..., ...)
• API： GET /v1/data-eng/proc-tasks?workspace_id=<id>&statuses=<status>

タスク詳細の表示

cloudrobo dataset proc show-task --task-id <task-id>

• SDK： client.get_task_detail(task_id)
• API： GET /v1/data-eng/proc-tasks/{task_id}

タスクの更新（SDK のみ）

• SDK： client.update_task(task_id, task_config: dict)
• API： PATCH /v1/data-eng/proc-tasks/{task_id}

タスクの削除（SDK のみ）

• SDK： client.delete_tasks([task_id_1, task_id_2])
• API： DELETE /v1/data-eng/proc-tasks?ids=id1,id2

タスクの再起動

cloudrobo dataset proc restart-task --task-id <task-id>

• SDK： client.restart_task(task_id)
• API： POST /v1/data-eng/proc-tasks/{task_id}/restart

タスクの監視

タスクが終了状態に達するまで待機

cloudrobo dataset proc wait-task --task-id <task-id> [--timeout 1800] [--interval 10]

終了状態：SUCCEEDED、FAILED、DELETED

• SDK： client.wait_task(task_id, timeout=1800, interval=10, on_status=callback)
• API： GET /v1/data-eng/proc-tasks/{task_id}（ポーリング）

タスクログの取得

# Step 1: List log files to get file_path
cloudrobo dataset proc get-log --task-id <id> --is-system true
cloudrobo dataset proc get-log --task-id <id> --is-system false

# Step 2: Get log content (default: latest 64KB tail)
cloudrobo dataset proc get-log --task-id <id> --file-name <name> --file-path <path>

# Get full log (not just tail)
cloudrobo dataset proc get-log --task-id <id> --file-name <name> --file-path <path> --all

• SDK: client.list_log_files(task_id, is_system=True) → client.get_task_log(task_id, file_name, file_path, start_byte, end_byte) または client.get_task_log_tail(task_id, file_name)
• API:
  • GET /v1/data-eng/proc-tasks/{task_id}/logs?is_system=true|false
  • GET /v1/data-eng/proc-tasks/{task_id}/logs/{file_name}?start_byte=&end_byte=&file_path=&job_id=

ログファイルのダウンロード

cloudrobo dataset proc download-log --task-id <id> --file-name <name> --file-path <path>

• SDK: client.download_task_log(task_id, file_name, file_path)
• API: GET /v1/data-eng/proc-tasks/{task_id}/logs/{file_name}/download

タスクのリソース使用状況の取得

cloudrobo dataset proc get-resource-usage --task-id <task-id> --metric CPU_UTIL|CPU_USED_CORE|MEM_UTIL|MEM_USED_MB|NETWORK_TX_RATE|NETWORK_RX_RATE|DISK_READ_KB|DISK_WRITE_KB --start <unix-ts-sec> --end <unix-ts-sec> --step <10-3600>

• SDK: client.get_task_resource_usage(task_id, metric, start, end, step)
• API: GET /v1/data-eng/proc-tasks/{task_id}/resource-usage?metric=&start=&end=&step=

データのプレビュー

タスク出力データのプレビュー

データセットファイルの OBS 一時ダウンロードリンクを取得します。file_name はバケット名を除いた OBS パスです（例：cloudrobo/f91cee72-.../1ddf1498-.../data/chunk-000/file-000.parquet）。

cloudrobo dataset proc get-preview --task-id <task-id> --file-name <obs-path-without-bucket>

• SDK: client.get_task_preview(task_id, file_name)
• API: GET /v1/data-eng/proc-tasks/{task_id}/preview?file_name=<file_name>

タスクのフレームの取得

タスクの入力／出力データセットのディレクトリ内にあるファイル一覧を照会します。prefix はバケット名を除いたデータセットの OBS パスです（例：cloudrobo/f91cee72-.../1ddf1498-.../）。

cloudrobo dataset proc get-frames --task-id <task-id> --prefix <obs-path-without-bucket>

• SDK: client.get_task_frames(task_id, prefix)
• API: GET /v1/data-eng/proc-tasks/{task_id}/frames?prefix=<prefix>

評価タスク（eval-tasks）

評価タスクは、フィールド名、削除の粒度、対応する操作が処理タスクと異なります。詳細な比較表については、references/task-config-catalog.md を参照してください。

評価タスクの作成

cloudrobo dataset eval create-task --name <task-name> --task-config '<json-config>' [--workspace-id <id>] [--wait] [--timeout 1800]

• SDK: client.create_eval_task(task_config: dict)
• API: POST /v1/data-eng/eval-tasks

task-config フィールドの説明：

eval-task の task-config では、2 組のデータセットフィールドが必要です。最上位の単一値フィールド（dataset_type、dataset_id、dataset_name、dataset_path）と、dataset_configs 配列（単一データセット、形式は proc-task と同じ）です。

必須フィールド：name、algo_type、algo_id、algo_name、algo_entrance、image、catalog_id（ワークスペースのもの）、cluster_type、task_framework_type、dataset_type／dataset_id／dataset_name／dataset_path（最上位）、dataset_configs、robot_config、resource_pool_type、head_spec、worker_spec、worker_num、evs_spec、output_type、output_path、output_name。

任意フィールド：description、resource_id、dedicated_pool_name。

⚠️ 重要な注意事項：

• 最上位のデータセットフィールドと dataset_configs 配列の両方が必要です
• dataset_name は空にできません（UDF_OBS_ASSET の場合は OBS パスの最後のディレクトリから取得します）
• dataset_type の値：BUILD_IN_ASSET／UDF_OBS_ASSET

フィールドの完全なマッピングと eval-task のフィールドの違いについては、references/task-config-catalog.md を参照してください。

評価タスクの一覧表示

cloudrobo dataset eval list-tasks [--status <status>] [--name <name>] [--workspace-id <id>]

• SDK: client.list_eval_tasks(workspace_id=None, **params)
• API: GET /v1/data-eng/eval-tasks?workspace_id=<id>

評価タスクの詳細表示

cloudrobo dataset eval show-task --task-id <task-id>

• SDK: client.get_eval_task_detail(task_id)
• API: GET /v1/data-eng/eval-tasks/{task_id}

評価タスクの更新（SDK のみ）

• SDK: client.update_eval_task(task_id, task_config: dict)
• API: PATCH /v1/data-eng/eval-tasks/{task_id}

評価タスクの削除（単一単位、SDK のみ）

• SDK: client.delete_eval_task(task_id)
• API: DELETE /v1/data-eng/eval-tasks/{task_id}

注記： eval-tasks の削除は単一タスク単位（delete-task）で、proc-tasks（delete-task）と同じです。eval-tasks は再起動に対応していません。

評価タスクのログを取得する

# Step 1: List log files
cloudrobo dataset eval get-log --task-id <id> --is-system true
cloudrobo dataset eval get-log --task-id <id> --is-system false

# Step 2: Get log content
cloudrobo dataset eval get-log --task-id <id> --file-name <name> --file-path <path>

• SDK： client.list_eval_log_files(task_id, is_system=True) + client.get_eval_task_log(task_id, file_name, ...)
• API：
  • GET /v1/data-eng/eval-tasks/{task_id}/logs?is_system=true|false
  • GET /v1/data-eng/eval-tasks/{task_id}/logs/{file_name}?file_path=&job_id=

評価タスクのプレビューを取得する

file_name はレポートファイルの OBS パス（バケット名を除く）です。タスク詳細の target_report_path から obs://<bucket-name>/ プレフィックスを削除して取得します。

例：target_report_path が obs://cloudrobo-test-203/eval_task/report/abc-123/diversity_evaluation_report.pdf の場合、file_name = eval_task/report/abc-123/diversity_evaluation_report.pdf です。

cloudrobo dataset eval get-preview --task-id <task-id> --file-name <obs-path-without-bucket> [--is-download]

• SDK： client.get_eval_task_preview(task_id, file_name, is_download=False)
• API： GET /v1/data-eng/eval-tasks/{task_id}/preview?file_name=<obs-path-without-bucket>&isDownload=

OBS の一時 URL が返されます。ダウンロードリンクには --is-download を使用し、プレビューリンクには指定しません。速やかに保存またはダウンロードしてください。

アルゴリズムの検索

利用可能なアルゴリズムを一覧表示する

cloudrobo asset list-publication-assets --type algorithm --tags "Data Processing" [--name <fuzzy-name>] [--limit 20]

• SDK（パッケージ横断）： asset_client.list_publication_assets(type="algorithm", sub_type="data_processing", limit=20)
• API： パッケージ横断です。データセットサービスではなく、アセットサービスを呼び出します。

各アルゴリズムには、タスク作成に必要な engine.image_url、command、environment_variables を含む ext_metadata があります。評価アルゴリズムを検索するには、--tags "Data Evaluation" を使用してください。

参考ドキュメント

• CLI インストールガイド — cloudrobo CLI のインストールと設定
• IAM ポリシー — 最小権限の認証情報モデル
• 検証方法 — 検証方法の詳細
• データフロー図 — Mermaid データフロー図
• 受け入れ基準 — 受け入れ基準
• タスク設定リファレンス — アルゴリズムのフィールドマッピング、必須フィールドのテンプレート、envs の形式、eval-tasks のフィールドの違い
• 対話型ワークフロー — proc-tasks と eval-tasks の対話型作成ワークフローの詳細な手順

エッジケース

シナリオ	対応
workspace_id がない	cloudrobo workspace use を実行するか、--workspace-id を使用します
タスクが終了状態ではない	wait-task は SUCCEEDED／FAILED／DELETED になるか、タイムアウトするまでポーリングします
ログファイルが見つからない	system-std-output.log／job-std-output.log にフォールバックします
ログファイルが大きい	デフォルトでは末尾 64KB を取得します。--all または download-log を使用してください
タスクの作成に失敗する	algo_type、JSON の妥当性、dataset_configs、リソースクォータを確認してください
AK／SK が設定されていない	HUAWEI_CLOUD_AK／HUAWEI_CLOUD_SK を設定してください
アルゴリズムが見つからない	--name によるあいまい検索、または sub_type フィルターを使用してください
eval-task の削除	個別削除のみ可能です。一括削除と再起動には対応していません
パイプラインの入力	target_path を dataset_configs のエントリーでラップします
評価レポートのリンク	OBS の一時 URL です。速やかに保存またはダウンロードしてください
envs の形式	オブジェクトではなく JSON 配列文字列です。task-config-catalog.md を参照してください
catalog_id の不一致	アルゴリズムのものではなく、ワークスペースのものを使用してください
list-assets のパラメーター	--catalog-id または --repository-id を指定してください。cloudrobo workspace current で取得できます
アルゴリズムのソース	組み込み：list-publication-assets、カスタム：list-assets
dataset_configs	アセットの url フィールドを使用してください。手動で連結しないでください
ログの照会	まずファイル一覧から file_path を取得し、その後、内容を取得してください
タスクの状態	終了状態：SUCCEEDED、FAILED、DELETED。未終了状態：CREATING、RUNNING、PENDING、FROZEN
タスクの削除	元に戻せません
アルゴリズムのフィールド	ext_metadata から抽出してください。作り出さないでください
オブジェクトストレージ	obs:// を使用する必要があります。s3:// は使用できません
API パス	推測せず、SDK の _url() 呼び出しから取得してください
スキル間の範囲	トレーニング／推論には対応しません。cloudrobo-train／infer を使用してください
データを変更する操作	create／update／delete／restart には確認が必要です
ワークフローのトリガー	パラメーターなしの場合は対話形式で進行します。すべてのパラメーターが指定されている場合は、確認へ進みます
省略可能なフィールドがない場合	environment_variables がなければ省略します。worker_spec はデフォルト値を使用します。eval の robot_config はプロンプトで確認します
空のフィールドの検証	description を除き、すべてのパラメーターは空でない必要があります。SDK は送信前に空文字列／None／空の辞書を拒否します
head_spec／worker_spec	cpu、memory、gpu、npu のキーを含める必要があります（値 0 は有効です）
dataset_configs が空	データセットのエントリーを 1 件以上含める必要があります。空の配列 "[]" は無効です
高度なリソース	DEDICATED_POOL：ID を照会します。Ray：クラスター／フレームワークの種類を組み合わせ、head_spec をゼロ以外にします

検証方法

仕様準拠の検証

bash scripts/test-cli-commands.sh -s . -e cli

機能テスト

# CLI / SDK
bash scripts/test-cli-commands.sh -s . -e {cli|sdk}

API レベルの検証は手動で行います。references/task-config-catalog.md に記載された API パスを API Explorer で再実行してください。

テストケース

proc-tasks、eval-tasks、アルゴリズムの検出、パイプラインのシナリオを網羅したテストケースの一覧は、templates/test-vars.json を参照してください。

検証チェックリスト

• タスクの作成後、状態を（推奨間隔 15 秒で）ポーリングし、状態が変わるたびにユーザーへ報告します
• SUCCEEDED の場合：get-preview と出力システムログで出力を確認します
• FAILED の場合：ログを表示するかユーザーに確認し、2 段階の手順（ファイル一覧 → 内容の取得）に従ってシステムログとジョブログを取得します
• パイプラインの場合：処理の target_path が eval タスクの dataset_configs にラップされていることを確認し、その後、eval が SUCCEEDED になったら get-preview が OBS リンクを返すことを確認します
• eval タスクの場合：SUCCEEDED 後にレポートのプレビューを確認します

ベストプラクティス

• タスクを作成する前に、必ずlist-algorithmsを実行して、利用可能なオペレーターを確認します
• 実際に実行する前に、create-taskで--dry-runを使用してタスク設定を検証します
• 無期限にポーリングしないよう、--timeoutを指定してwait-taskを使用し、ステータスが変わるたびに報告します
• タスクが失敗した場合は、システムログ（--is-system true）とジョブログ（--is-system false）の両方を取得し、 エラーのパターン（OOM／パスが見つからない／イメージのプル失敗／OBSへのアクセス）を分析して、再起動する前に修正方法を提案します
• パイプラインをオーケストレーションする場合は、評価タスクを作成する前に処理がSUCCEEDEDになるまで待ちます
• 一括削除の前に、タスクIDを確認して、取り消せない削除を防ぎます
• 完了または失敗したタスクをdelete-taskでクリーンアップして、リソースを解放します
• トラブルシューティング中に詳細なエラー出力を表示するには、CLOUDROBO_DEBUG=1を設定します
• 評価レポートへのリンクはOBSの一時URLです。速やかに保存またはダウンロードしてください