> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/ja/toappurdo/upload-a-dataset.md).

# データセットをアップロードする

Python SDK を使って、画像と注釈からなる構造化データセットを Roboflow プロジェクトにアップロードします。

このページでは、既存のラベル付きデータセット（画像とそのアノテーション）を Python SDK、HTTP API、または CLI で一括インポートする方法を説明します。API を使って画像を個別にアップロード・管理する方法については、 [画像の管理](https://docs.roboflow.com/datasets/ja/guan-li/manage-images.md).

## Python SDK

`Workspace.upload_dataset()` は、構造化データセット（画像と対応するアノテーション）を Roboflow プロジェクトにアップロードします。プロジェクトが存在しない場合は作成され、すでに存在する場合は新しい画像がそのプロジェクトに追加されます。

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

workspace.upload_dataset(
    "./dataset/",                  # 構造化データセットのディレクトリへのパス
    "my-detector",                 # プロジェクト ID（存在しない場合は作成）
    num_workers=10,
    project_license="MIT",
    project_type="object-detection",
    batch_name=None,
    num_retries=0,
    is_prediction=False,           # レビュー待ちのモデル生成アノテーションには True
)
```

### パラメーター

* `dataset_path` (str) - データセットのルートへのパス。
* `project_name` (str) - アップロード先プロジェクトの ID。存在しない場合は作成されます。
* `num_workers` (int、デフォルト `10`) - 並列アップロード数。25を超えないことをおすすめします。
* `project_license` (str、デフォルト `"MIT"`) - 新規作成するプロジェクトのライセンス。非公開プロジェクトの場合は `"Private"` に設定します。
* `project_type` (str、デフォルト `"object-detection"`) - 新規作成するプロジェクトの種類。プロジェクトがすでに存在する場合は無視されます。
* `batch_name` (str、任意) - アップロードを名前付きバッチにまとめます。ラベリング作業のソースを追跡するのに便利です。
* `num_retries` (int、デフォルト `0`) - 一時的なアップロード失敗時の再試行回数。
* `is_prediction` (bool、デフォルト `False`) - 正解データではなく、レビュー待ちのモデル予測としてアノテーションをアップロードするには `True` に設定します。

### 予測の保存先

アップロードバッチにまだ含まれている画像の予測を保存すると、Roboflow はその画像をバッチのレビュータスクに移動します。タスクを開き、ラベルを承認または修正してから正解データにします。

画像がすでにアノテーションタスクに割り当てられている場合は、そのタスクにとどまります。

### 想定されるディレクトリ構成

COCO データセットの場合：

```
my_dataset/
├── train/
│   ├── image1.jpg
│   └── _annotations.coco.json
├── valid/
│   ├── image2.jpg
│   └── _annotations.coco.json
└── test/
    ├── image3.jpg
    └── _annotations.coco.json
```

各画像を格納するフォルダーによって、その画像のデータセット分割が決まります。次の完全一致するフォルダー名のみが対象です： `train`, `training`, `valid`, `validation`, `val`, `test`、および `testing`。大文字と小文字は区別されず、ファイル名は無視されます。そのため、 `test_image.jpg` という名前の画像はテスト分割に分類されず、 `train2017` という名前のフォルダーも分割を設定しません。一致するフォルダーがない場合、画像にはアップロードのデフォルトの分割が適用されます。ZIP アップロードの場合、これはリクエストの `split` 値で、デフォルトは `train`.

VOC の場合は、各画像と同じ場所に対応する `.xml` ファイルを配置します。YOLO の場合は、対応する `.txt` ファイルと、クラス一覧を記述した `data.yaml` を配置します。

### SHA-256 による重複排除について（v1.3.6 以降）

バージョン `roboflow` 1.3.6 以降、SDK は Pillow で再エンコードせず、元の画像バイト列をアップロードします。これによりウェブアップローダーと同じ動作になり、Roboflow サーバーが SHA-256 でアップロードの重複を排除できるようになります。同じ画像を再アップロードしても（たとえば別のバッチにアップロードする場合）、追加のストレージクレジットを消費することなく成功します。

## HTTP API

### データセット ZIP をアップロードする

データセット全体を 1 つの ZIP ファイルとしてアップロードします。Roboflow はバックグラウンドで処理するため、処理中に接続を維持する必要はありません。ZIP には、サポートされている任意の形式（例：COCO、YOLO、Pascal VOC）の画像とアノテーションを格納できます。分類の場合、フォルダー名がクラスラベルになります。

アップロードは次の 3 ステップで行います：

1. アップロードを開始します。レスポンスには署名付き URL と `taskId`.
2. が含まれます。署名付き URL に `Content-Type: application/zip`を指定して ZIP を PUT します。アップロードが完了すると処理が開始されます。
3. タスクのステータスが `completed` または `failed`.

{% openapi src="/files/8136d030d5405d34dcfdf641aecc1994741fd3b3" path="/{workspace}/{project}/upload/zip" method="post" %}
[dataset-zip-upload.yaml](https://2416768182-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-25a53c9e468fe23c13da4395e49bc7a5287c5a12%2Fdataset-zip-upload.yaml?alt=media)
{% endopenapi %}

になるまでタスクの状態をポーリングします。

```bash
署名付き URL は Roboflow API ではなく Google Cloud Storage 上にあるため、API キーを付けずにファイルを送信します：
  -H "Content-Type: application/zip" \
  --upload-file ./my-dataset.zip
```

デフォルトでは、プロジェクト内にすでにある画像のアノテーションは保持され、その画像に対する ZIP 内のアノテーションはスキップされます。置き換えるには、 `annotationOverwrite` を `true` に設定します。

アップロード時のスクリーニングで保留されなかった画像のアノテーションは、直接データセットに登録されます。または、 [レビュー モード](https://docs.roboflow.com/datasets/ja/zhu-shi/zhu-shi/team-collaboration.md#review-mode) が有効な場合はレビュー ジョブに登録されます。アノテーションのない画像はラベリング用のバッチに追加されます。保留された画像のアノテーションは、スクリーニングで承認された場合は保存され、承認されなかった場合は破棄されます。

{% openapi src="/files/8136d030d5405d34dcfdf641aecc1994741fd3b3" path="/{workspace}/upload/zip/{taskId}" method="get" %}
[dataset-zip-upload.yaml](https://2416768182-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-25a53c9e468fe23c13da4395e49bc7a5287c5a12%2Fdataset-zip-upload.yaml?alt=media)
{% endopenapi %}

ZIPタスクが完了していても、アップロード時のスクリーニングで保留中の画像が含まれていることがあります。その `result.screening` の数は `result.uploaded`に含まれます。これらの画像は、まだプロジェクトやデータセットで利用できません。審査に合格した画像、または修正された画像は後で利用可能になりますが、却下された画像や審査に失敗した画像は利用できません。ZIPの結果から画像ごとの最終判定はわかりません。アップロードの応答で保留中の画像IDが返された場合は、 [スクリーニング判定を確認する](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data.md#check-image-upload-screening)か、MCP経由で `images_screening_status` を使用してください。スクリーニング判定だけでは、データセットで利用可能になったことは確認できません。

ZIP内のPDFは、サポートされていない形式であることを示す警告とともにスキップされます。動画も同様にスキップされますが、アクション認識プロジェクトの場合は除きます。

アクション認識プロジェクトでは、ZIP内の3 GB以下の各MP4またはMOV動画が、 [動画のアップロード](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data.md#upload-a-video)と同様に動画として追加されます。ZIP内の画像は警告とともにスキップされます。動画にはアップロード時のタグ、バッチ、分割が適用されます。また、 `train`, `valid`または `test` フォルダーによって、画像の場合と同じ方法で分割が設定されます。 `result.videoIds` 内の各IDを使って、 [動画のステータスを確認](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data.md#upload-a-video)してください。ZIP内の動画ラベルはインポートされません。

## CLI

Roboflow CLIを使用して、画像やアノテーションを含むデータセットをアップロードできます。

データセットのアップロード方法を解説する動画をご用意しました。

{% embed url="<https://www.loom.com/share/19637984033a466b831af56f9404fa89>" %}

### ディレクトリをアップロードする

ディレクトリのパスを指定して `roboflow image upload` を使うと、画像ごとに並列アップロードしてデータセットを一括アップロードできます。

```bash
roboflow image upload /path/to/dataset/folder -p PROJECT_ID
```

または、短縮エイリアスを使用します。

```bash
roboflow upload /path/to/dataset/folder -p PROJECT_ID
```

CLIは、パスがファイル、ディレクトリ、または `.zip` ファイルのいずれかを自動判定します。ディレクトリを指定すると、 `--zip-upload`.

#### オプション

| フラグ                   | 説明                            |
| --------------------- | ----------------------------- |
| `-p`, `--project`     | プロジェクトID（必須）                  |
| `-c`, `--concurrency` | 並列アップロード数（デフォルト: 10）          |
| `-b`, `--batch`       | アップロードをまとめるバッチ名               |
| `-r`, `--retries`     | 失敗したアップロードを再試行する回数N（デフォルト: 0） |
| `-s`, `--split`       | アップロードするすべての画像の分割先を上書きします     |

オプションを指定した例:

```bash
roboflow upload ./my-dataset -p my-project -c 20 -b "april-batch" -r 3
```

### Zipファイルをアップロードする

大規模なデータセットをアップロードする場合や、データセットがすでに `.zip` ファイルとしてパッケージ化されている場合は、ZIPアップロードを使用します。ZIPアップロードでは、Roboflowの非同期ZIPアップロードフローが使用されます。デフォルトでは、CLIはZIPファイルをアップロードし、処理が完了するまで待機します。

これは、上記の [HTTP API](#http-api) で説明されているものと同じフローです。署名付きURLを使ったアップロードとタスクのポーリングは、CLIが代わりに処理します。

既存のZIPファイルをアップロードするには:

```bash
roboflow image upload /path/to/dataset.zip -p PROJECT_ID
```

ローカルディレクトリをクライアント側でZIP化し、非同期ZIPアップロードフローでアップロードするには、主要コマンドに `--zip-upload` を指定します:

```bash
roboflow image upload /path/to/dataset/folder -p PROJECT_ID --zip-upload
```

#### ZIPアップロードのオプション

| フラグ               | 説明                                             |
| ----------------- | ---------------------------------------------- |
| `-p`, `--project` | プロジェクトID（必須）                                   |
| `--zip-upload`    | ディレクトリをクライアント側でZIP化し、非同期ZIPアップロードフローでアップロードします |
| `--no-wait`       | 処理の完了を待たず、ZIPのアップロード後すぐに戻ります                   |
| `-b`, `--batch`   | アップロードをまとめるバッチ名                                |
| `-s`, `--split`   | 分割先: train、valid、またはtest                       |
| `-t`, `--tag`     | カンマ区切りのタグ名                                     |

ZIPアップロードのオプションを指定した例:

```bash
roboflow image upload ./my-dataset.zip -p my-project -s train -t "outdoor,daytime" -b "april-batch"
```

処理を開始して、タスクIDをすぐに返すには:

```bash
roboflow image upload ./my-dataset.zip -p my-project --no-wait --json
```

JSONレスポンスには、非同期タスクIDが含まれます:

```json
{
  "status": "pending",
  "task_id": "task-123",
  "path": "./my-dataset.zip",
  "project": "my-project",
  "result": {
    "task_id": "task-123",
    "status": "pending"
  }
}
```

ZIPアップロードでは `--is-prediction`はサポートされていません。予測データをアップロードする場合は、通常の画像ごとのアップロードフローを使用してください。

### サポートされているプロジェクトタイプ

次のプロジェクトタイプのデータをアップロードできます:

* 物体検出
* シングルラベル分類
* マルチラベル分類
* インスタンスセグメンテーション
* セマンティックセグメンテーション
* キーポイント検出

### サポートされているdata.yaml形式

CLIは、データセットのアップロード時に `data.yaml` ファイル内のリスト形式とキーと値のペア形式のクラス名マッピングの両方をサポートしています:

```yaml
nc: 3
names: ['Paper', 'Rock', 'Scissors']
```

または

```yaml
nc: 3
names:
  0: 紙
  1: 岩
  2: はさみ
```

### JSON出力

自動化には、次を使用します。 `--json`:

```bash
roboflow upload ./my-dataset -p my-project --json
```

```json
{"status": "uploaded", "path": "./my-dataset", "project": "my-project"}
```

## MCPサーバー

AIエージェントを [MCPサーバー](https://docs.roboflow.com/agents/mcp-server) に接続して、画像と任意のアノテーションファイルをZIPでアップロードします。アップロードタスクの状態をポーリングし、スクリーニングのために保留された画像があれば個別に報告します。トレーニングを開始する前に、データセットの準備状況を確認してください。

<table data-search="false"><thead><tr><th width="290">ツール</th><th>説明</th></tr></thead><tbody><tr><td><code>image_upload</code></td><td>画像と任意のアノテーションファイルを含むZIPアップロードを準備します。</td></tr><tr><td><code>image_upload_status</code></td><td>画像ZIPアップロードタスクのステータスを確認します。</td></tr><tr><td><code>annotations_save</code></td><td>アップロード済みの画像にアノテーションを保存します。</td></tr><tr><td><code>images_screening_status</code></td><td>保留中の画像IDについて、スクリーニング結果を読み取ります。</td></tr></tbody></table>

## 次のステップ

* アノテーションのない画像にラベルを付けて、トレーニングに使用できるようにします。詳しくは、 [Roboflow Annotateの概要](https://docs.roboflow.com/datasets/ja/zhu-shi/zhu-shi/annotation-tools.md).
* 画像をトレーニング可能なスナップショットに変換します。詳しくは、 [データセットバージョンを作成する](https://docs.roboflow.com/datasets/ja/bjon/dataset-versions/create-a-dataset-version.md).
