データのインポート（SDK）

このガイドでは、bulk-writer API と bulk-import API を使用して SDK でコレクションにデータをインポートする方法を説明します。

あるいは、データの準備と Zilliz Cloud コレクションへのデータのインポートの両方を扱う 当社の fast-track エンドツーエンドコース も参照してください。

Notes

Zilliz Cloud では、クラスターをホストしているクラウドプロバイダーに関係なく、任意のオブジェクトストレージサービスから任意の Zilliz Cloud クラスターにデータをインポートできるようになりました。たとえば、AWS S3 バケットから GCP 上にデプロイされた Zilliz Cloud クラスターにデータをインポートできます。

低レイテンシで安定したエクスペリエンスを確保するには、ターゲットクラスターと同じプロバイダー、同じリージョンにあるバケットまたは BLOB コンテナーを使用することをお勧めします。

依存関係をインストールする

Python

ターミナルで次のコマンドを実行し、pymilvus と minio をインストールするか、最新バージョンにアップグレードします。

shell

python3 -m pip install --upgrade pymilvus minio

Java

• Apache Maven の場合は、pom.xml の依存関係に以下を追加します。

java

<dependency>
  <groupId>io.milvus</groupId>
  <artifactId>milvus-sdk-java</artifactId>
  <version>3.0.10</version>
</dependency>

<dependency>
  <groupId>io.milvus</groupId>
  <artifactId>milvus-sdk-java-bulkwriter</artifactId>
  <version>3.0.10</version>
</dependency>

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.9</version>
</dependency>

• Gradle/Grails, の場合は、次を実行します。

shell

implementation 'io.milvus:milvus-sdk-java:3.0.10'
implementation 'io.milvus:milvus-sdk-java-bulkwriter:3.0.10'
implementation 'io.minio:minio:8.5.9'

準備済みデータを確認する

BulkWriter ツール を使用してデータを準備し、準備したファイルのパスを取得したら、それらを Zilliz Cloud コレクションにインポートする準備が整います。準備ができているかどうかを確認するには、次のようにします。

Python

python

from minio import Minio

# Third-party constants
ACCESS_KEY = "YOUR_ACCESS_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
BUCKET_NAME = "YOUR_BUCKET_NAME"
REMOTE_PATH = "YOUR_REMOTE_PATH"

client = Minio(
    endpoint="storage.googleapis.com", # use 's3.amazonaws.com' for AWS S3
    access_key=ACCESS_KEY,
    secret_key=SECRET_KEY,
    secure=True
)

objects = client.list_objects(
    bucket_name=BUCKET_NAME,
    prefix=REMOTE_PATH,
    recursive=True
)

print([obj.object_name for obj in objects])

# Output
#
# [
#     "folder/1/claps.npy",
#     "folder/1/id.npy",
#     "folder/1/link.npy",
#     "folder/1/publication.npy",
#     "folder/1/reading_time.npy",
#     "folder/1/responses.npy",
#     "folder/1/title.npy",
#     "folder/1/vector.npy"
# ]

Java

java

import io.minio.MinioClient;
import io.minio.Result;
import io.minio.ListObjectsArgs;
import io.minio.messages.Item;
import java.util.Iterator;

// Third-party constants
String ACCESS_KEY = "YOUR_ACCESS_KEY";
String SECRET_KEY = "YOUR_SECRET_KEY";
String BUCKET_NAME = "YOUR_BUCKET_NAME";
String REMOTE_PATH = "YOUR_REMOTE_PATH";

MinioClient minioClient = MinioClient.builder()
        .endpoint("storage.googleapis.com") // use 's3.amazonaws.com' for AWS S3
        .credentials(ACCESS_KEY, SECRET_KEY)
        .build();

Iterable<Result<Item>> results = minioClient.listObjects(
    ListObjectsArgs.builder().bucket(BUCKET_NAME).prefix(REMOTE_PATH).build()
);

for (Result<Item> result : results) {
    System.out.println(result.get().objectName());
}

// Output
// [[1.parquet]]

データをインポートする

データとコレクションの準備ができたら、オブジェクトストレージのバケットやブロックストレージの BLOB コンテナーなどの外部ストレージを介して、特定のコレクションにデータをインポートできます。

データをインポートする

外部ストレージを介してデータをインポートする場合は、次のようにします。

Python

python

from pymilvus.bulk_writer import bulk_import

# Bulk-import your data from the prepared data files
CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com"
CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx"
API_KEY = ""
STORAGE_URL = ""
ACCESS_KEY = ""
SECRET_KEY = ""

res = bulk_import(
    api_key=API_KEY,
    url=CLOUD_API_ENDPOINT,
    cluster_id=CLUSTER_ID,
    collection_name="medium_articles",
    object_url=STORAGE_URL,
    access_key=ACCESS_KEY,
    secret_key=SECRET_KEY
)

print(res.json())

# Output
#
# {
#     "code": 0,
#     "data": {
#         "jobId": "9d0bc230-6b99-4739-a872-0b91cfe2515a"
#     }
# }

Java

java

private static String bulkImport() throws InterruptedException {
    /**
     * The value of the URL is fixed.
     */
    String CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com";
    String CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx";
    String API_KEY = "";
    String STORAGE_URL = "";
    String ACCESS_KEY = "";
    String SECRET_KEY = "";
    CloudImportRequest cloudImportRequest = CloudImportRequest.builder()
            .apiKey(API_KEY)
            .clusterId(CLUSTER_ID)
            .collectionName("medium_articles")
            .objectUrl(STORAGE_URL)
            .accessKey(ACCESS_KEY)
            .secretKey(SECRET_KEY)
            .build();
    String bulkImportResult = BulkImportUtils.bulkImport(CLOUD_API_ENDPOINT, cloudImportRequest);
    System.out.println(bulkImportResult);
    JsonObject bulkImportObject = new Gson().fromJson(bulkImportResult, JsonObject.class);
    String jobId = bulkImportObject.getAsJsonObject("data").get("jobId").getAsString();
    System.out.println("Create a bulkImport task, job id: " + jobId);
    return jobId;
}

public static void main(String[] args) throws Exception {
    String jobId = bulkImport();
}

// 0f7fe853-d93e-4681-99f2-4719c63585cc

Go

go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/milvus-io/milvus/client/v3/bulkwriter"
)

func main() {
    ctx := context.Background()

    opt := bulkwriter.NewCloudBulkImportOption(
        "https://api.cloud.zilliz.com",
        "medium_articles",
        "YOUR_API_KEY",
        "YOUR_OBJECT_URL",
        "inxx-xxxxxxxxxxxxxxx",
        "YOUR_ACCESS_KEY",
        "YOUR_SECRET_KEY",
    )
    resp, err := bulkwriter.BulkImport(ctx, opt)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.Data.JobID)
}

Rust

rust

use milvus::v2::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // The value of the URL is fixed.
    let config = BulkImportConfig::new()
        .url("https://api.cloud.zilliz.com")
        .api_key("YOUR_API_KEY");
    let bulk_import = BulkImport::new(&config)?;

    let request = BulkImportRequest::builder()
        .collection_name("medium_articles")
        .cluster_id("inxx-xxxxxxxxxxxxxxx")
        .object_url("YOUR_OBJECT_URL")
        .access_key("YOUR_ACCESS_KEY")
        .secret_key("YOUR_SECRET_KEY")
        .build()?;

    let resp = bulk_import.bulk_import(request).await?;
    println!("{:?}", resp.job_id());
    Ok(())
}

C++

c++

// Note: milvus::BulkImport::CreateImportJobs() implements the import REST API,
// but as of v3.0.3 it does not accept the cloud object-storage parameters
// (objectUrl/accessKey/secretKey/clusterId) used in this section.

NodeJS

javascript

// Note: Cloud object-storage import is not supported in milvus-sdk-node as of v3.0.6.

cURL

bash

curl --request POST \
     --url "https://api.cloud.zilliz.com/v2/vectordb/jobs/import/create" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     -d '{
        "clusterId": "inxx-xxxxxxxxxxxxxxx",
        "collectionName": "medium_articles",
        "objectUrl": "YOUR_OBJECT_URL",
        "accessKey": "YOUR_ACCESS_KEY",
        "secretKey": "YOUR_SECRET_KEY"
    }'

Notes

データインポートを成功させるには、ターゲットコレクションの実行中または保留中のインポートジョブが 10,000 件未満であることを確認してください。

インポートの進行状況を確認する

指定した bulk-import ジョブの進行状況を確認できます。

Python

python

import json
from pymilvus.bulk_writer import get_import_progress

## Zilliz Cloud constants
CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com"
CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx"
API_KEY = ""

# Get bulk-insert job progress
resp = get_import_progress(
    api_key=API_KEY,
    url=CLOUD_API_ENDPOINT,
    cluster_id=CLUSTER_ID,
    job_id="job-01fa0e5d42cjxudhpuehyp",
)

print(json.dumps(resp.json(), indent=4))

Java

java

private static void getImportProgress(String jobId) {
    /**
     * The value of the URL is fixed.
     */
    String CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com";
    String CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx";
    String API_KEY = "";
    CloudDescribeImportRequest request = CloudDescribeImportRequest.builder()
        .apiKey(API_KEY)
        .clusterId(CLUSTER_ID)
        .jobId(jobId)
        .build();
    String getImportProgressResult = BulkImportUtils.getImportProgress(CLOUD_API_ENDPOINT, request);
    System.out.println("Get import progress, result: " + getImportProgressResult);
}

public static void main(String[] args) throws Exception {
    getImportProgress("job-xxxx");
}

Go

go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/milvus-io/milvus/client/v3/bulkwriter"
)

func main() {
    ctx := context.Background()

    opt := bulkwriter.NewCloudGetImportProgressOption(
        "https://api.cloud.zilliz.com",
        "job-01fa0e5d42cjxudhpuehyp",
        "YOUR_API_KEY",
        "inxx-xxxxxxxxxxxxxxx",
    )
    resp, err := bulkwriter.GetImportProgress(ctx, opt)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%+v\n", resp.Data)
}

Rust

rust

use milvus::v2::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // The value of the URL is fixed.
    let config = BulkImportConfig::new()
        .url("https://api.cloud.zilliz.com")
        .api_key("YOUR_API_KEY");
    let bulk_import = BulkImport::new(&config)?;

    let request = GetImportProgressRequest::builder()
        .job_id("job-01fa0e5d42cjxudhpuehyp")
        .cluster_id("inxx-xxxxxxxxxxxxxxx")
        .build()?;

    let resp = bulk_import.get_import_progress(request).await?;
    println!("{:?}", resp);
    Ok(())
}

C++

c++

// Note: milvus::BulkImport::GetImportJobProgress() implements the progress API,
// but as of v3.0.3 it does not send the cloud clusterId used in this section.

NodeJS

javascript

// Note: Cloud import progress is not supported in milvus-sdk-node as of v3.0.6.

cURL

bash

curl --request POST \
     --url "https://api.cloud.zilliz.com/v2/vectordb/jobs/import/get_progress" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     -d '{
        "clusterId": "inxx-xxxxxxxxxxxxxxx",
        "jobId": "job-01fa0e5d42cjxudhpuehyp"
    }'

すべてのインポートジョブを一覧表示する

すべての bulk-import タスクについても把握したい場合は、次のように list-import-jobs API を呼び出します。

Python

python

import json
from pymilvus.bulk_writer import list_import_jobs

## Zilliz Cloud constants
CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com"
CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx"
API_KEY = ""

# List bulk-insert jobs
resp = list_import_jobs(
    api_key=API_KEY,
    url=CLOUD_API_ENDPOINT,
    cluster_id=CLUSTER_ID
)

print(json.dumps(resp.json(), indent=4))

Java

java

private static void listImportJobs() {
    /**
     * The value of the URL is fixed.
     */
    String CLOUD_API_ENDPOINT = "https://api.cloud.zilliz.com";
    String CLUSTER_ID = "inxx-xxxxxxxxxxxxxxx";
    String API_KEY = "";
    CloudListImportJobsRequest listImportJobsRequest = CloudListImportJobsRequest.builder()
            .apiKey(API_KEY)
            .clusterId(CLUSTER_ID).build();
    String listImportJobsResult = BulkImportUtils.listImportJobs(CLOUD_API_ENDPOINT, listImportJobsRequest);
    System.out.println(listImportJobsResult);
}

public static void main(String[] args) throws Exception {
    listImportJobs();
}

Go

go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/milvus-io/milvus/client/v3/bulkwriter"
)

func main() {
    ctx := context.Background()

    opt := bulkwriter.NewListImportJobsOption("https://api.cloud.zilliz.com", "")
    opt.APIKey = "YOUR_API_KEY"
    opt.ClusterID = "inxx-xxxxxxxxxxxxxxx"

    resp, err := bulkwriter.ListImportJobs(ctx, opt)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.Data.Records)
}

Rust

rust

use milvus::v2::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // The value of the URL is fixed.
    let config = BulkImportConfig::new()
        .url("https://api.cloud.zilliz.com")
        .api_key("YOUR_API_KEY");
    let bulk_import = BulkImport::new(&config)?;

    let request = ListImportJobsRequest::builder()
        .cluster_id("inxx-xxxxxxxxxxxxxxx")
        .build()?;

    let resp = bulk_import.list_import_jobs(request).await?;
    println!("{:?}", resp);
    Ok(())
}

C++

c++

// Note: milvus::BulkImport::ListImportJobs() implements the list-jobs API,
// but as of v3.0.3 it does not send the cloud clusterId used in this section.

NodeJS

javascript

// Note: Cloud import-jobs listing is not supported in milvus-sdk-node as of v3.0.6.

cURL

bash

curl --request POST \
     --url "https://api.cloud.zilliz.com/v2/vectordb/jobs/import/list" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     -d '{
        "clusterId": "inxx-xxxxxxxxxxxxxxx"
    }'

関連トピック

• ストレージオプション

• フォーマットオプション

• RESTful API によるデータのインポート

• ゼロから学ぶデータインポート