Object Storage Service:OSS ベクトルデータの管理

認証情報の構成

認証情報を環境変数として構成します。CLI はこれらの環境変数を自動的に読み取り、各コマンド実行時に毎回指定する必要はありません。

# Alibaba Cloud アカウントの AccessKey
export OSS_ACCESS_KEY_ID="<your-access-key-id>"
export OSS_ACCESS_KEY_SECRET="<your-access-key-secret>"

# Model Studio API キー
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"

セキュリティに関するヒント： 認証情報をスクリプト内にハードコードしないでください。代わりに環境変数をご利用ください。

OSS Vectors Embed CLI のインストール

Python 3.9 以降が必要です。

オプション 1：pip を使用したインストール（推奨）

pip install oss-vectors-embed-cli

オプション 2：開発者モードでのインストール

git clone https://github.com/aliyun/oss-vectors-embed-cli.git
cd oss-vectors-embed-cli
pip install -e .

インストールの確認

oss-vectors-embed --version
# 出力例: oss-vectors-embed, version 0.1.0

ベクトルバケットの作成

ベクトルデータを書き込む前に、ベクトルバケットを作成し、ベクトルインデックスを構成する必要があります。

1. ベクトルバケットの作成： OSS コンソールの ベクトルバケット ページに移動し、ベクトルデータおよびインデックスを格納するためのベクトルバケットを作成します。

2. ベクトルインデックスの作成： 作成したベクトルバケット内でベクトルインデックスを作成し、そのベクトルディメンションを使用する埋め込みモデルの出力ディメンションに一致するよう構成します。

重要： ベクトルインデックスのベクトルディメンションは、埋め込みモデル の出力ディメンションと一致させる必要があります。たとえば、text-embedding-v4 モデル（デフォルト：1024 ディメンション）を使用する場合は、インデックスのベクトルディメンションも 1024 に設定する必要があります。

テキストファイルからのベクトル書き込み

テキスト埋め込みモデル（例：text-embedding-v4）を使用して、テキストから埋め込みを生成します。対応する入力ソースには、テキスト文字列、OSS オブジェクト、ローカルテキストファイルが含まれます。

インラインテキスト文字列からの書き込み

インラインのテキスト文字列から埋め込みを生成し、ベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --text-value:         入力テキスト文字列。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "人工知能は私たちの暮らし方を変革しています"

サンプル出力（ベクトルキー、バケット情報、メタデータを含む）：

{
  "key": "3d8935dd-6395-4c9c-a501-df902846ec80",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "人工知能は私たちの暮らし方を変革しています",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

注： CLI は、ベクトルの起源をトレースするために、メタデータに OSSVECTORS-EMBED-SRC-* で始まるソース情報フィールドを自動的に追加します。

ローカルのテキストファイルから

ローカルファイルから埋め込みを生成し、ベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --text:               ローカルファイルのパス。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "<./documents/article.txt>"

サンプル出力：

{
  "key": "415c108e-d653-4d54-a241-d3b70e996666",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "人工知能は私たちの暮らし方を変革しています。睡眠サイクルに基づいて最適なタイミングで起こしてくれるスマートアラームクロック、通勤時の最適ルートを計画する音声アシスタント、自宅のスマートスピーカーによるパーソナライズされたニュース要約の再生、仕事場での AI ツールによる自動レポート生成・文書翻訳・ワークフロー最適化など——AI は静かに私たちの日常生活の隅々に浸透しています。",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "./documents/article.txt"
  }
}

OSS オブジェクトから

OSS に保存されているオブジェクトから埋め込みを生成し、ベクトルバケットに書き込みます。パス形式は oss://bucket-name/object-key を使用します。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --region:             ソースバケットのリージョン。
# --text:               ソースファイルの OSS パス。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "oss://<your-source-bucket>/<your-file>"

注： ソース OSS オブジェクトのリージョンを指定するには、--region パラメーターを使用します。

サンプル出力：

{
  "key": "7ca24758-0d5b-46fe-ab90-db82be387650",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "これはサンプルファイルです。",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"
  }
}

画像ファイルからのベクトル書き込み

マルチモーダル埋め込みモデル（例：qwen2.5-vl-embedding）を使用して、画像および動画から埋め込みを生成します。画像の入力ソースには、ローカルファイル、OSS オブジェクト、HTTP/HTTPS URL が対応しています。

ローカルイメージから

ローカルの画像ファイルから埋め込みを生成し、ベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --image:              ローカル画像ファイルのパス。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "<./images/photo.jpg>"

サンプル出力：

{
  "key": "8fc8105b-d54f-464c-bf44-97b088d566ce",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "./images/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

OSS オブジェクトから

OSS に保存されている画像ファイルから埋め込みを生成し、ベクトルバケットに書き込みます。パス形式は oss://bucket-name/object-key を使用します。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --region:             ソースバケットのリージョン。
# --image:              ソース画像の OSS パス。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "oss://<your-source-bucket>/<your-image>"

サンプル出力：

{
  "key": "dbf57dfd-58be-4793-a484-a82eb86e0e08",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

画像 URL からの書き込み

画像の URL から埋め込みを生成し、ベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --image:              画像の URL。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "https://example.com/photo.jpg"

サンプル出力：

{
  "key": "f15cfe75-d4de-497f-b441-3b08243cfa5e",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

動画ファイルからのベクトル書き込み

マルチモーダルベクトルモデル（例：qwen2.5-vl-embedding）を使用して、画像および動画を処理します。動画の入力ソースには、OSS 動画ファイルおよび HTTP/HTTPS URL ファイルが対応しています。動画処理では、動画からキーフレームを抽出し、各フレームに対して個別の埋め込みを生成します。各埋め込みには一意のキーが必要であるため、--key および --filename-as-key パラメーターはサポートされていません。CLI は各フレームに対して一意の連番キーを自動的に生成します。

OSS オブジェクトから

OSS 内の動画ファイルを処理するには、CLI がオブジェクトの事前署名付き URL を生成し、埋め込みを作成してベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --region:             ソース動画のリージョン。
# --video:              ソース動画の OSS パス。
# --presign-url:        非公開バケットの場合に必要な、OSS オブジェクトの事前署名付き URL を生成します。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "oss://<your-source-bucket>/<your-video>" \
  --presign-url

サンプル出力：

{
  "key": "55606734-8275-4329-96a3-3c156220et54",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

動画 URL からの書き込み

動画の URL から埋め込みを生成し、ベクトルバケットに書き込みます。

# パラメーターの説明：
# --account-id:         ご利用の Alibaba Cloud アカウント ID。
# --vectors-region:     OSS ベクトルバケットのリージョン。
# --vector-bucket-name: OSS ベクトルバケットの名前。
# --index-name:         OSS ベクトルインデックスの名前。
# --model-id:           使用する埋め込みモデル。
# --video:              動画の URL。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "https://example.com/video.mp4"

サンプル出力：

{
  "key": "9157d87b-c44b-4c53-aceb-cd4be7fd8bd9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

スカラーメタデータの追加

書き込みコマンドにカスタムのスカラーメタデータを追加することで、ベクトル検索とスカラー検索のハイブリッド検索を有効化できます。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "技術文書の内容" \
  --metadata '{"category": "technology", "version": "1.0", "author": "admin"}' # ベクトルおよびスカラーのハイブリッド検索用にカスタムスカラーメタデータを追加します。

ユーザー定義のメタデータフィールドは、システムによって生成されたフィールドとマージされます。サンプル出力：

{
  "key": "c0ed4d9d-5301-49a5-82b7-eaf9d02b04a9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "category": "technology",  // 追加されたカスタムメタデータ
    "version": "1.0",          // 追加されたカスタムメタデータ
    "author": "admin",         // 追加されたカスタムメタデータ
    "OSSVECTORS-EMBED-SRC-CONTENT": "技術文書の内容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

テキスト類似性検索

テキストクエリを使用して、意味的に類似したベクトルを検索します。--top-k パラメーターで返す結果数を制御できます。次のコマンドは、my-index インデックス内で、「人工知能とは何か」と最も類似したベクトルを検索します。

# --text-value: クエリテキスト。
# --top-k:      返す最近傍の数。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "人工知能とは何か" \
  --top-k 100

サンプル出力（ベクトルキーおよびメタデータを含む）：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "人工知能は私たちの暮らし方を変革しています",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

注： デフォルトでは、類似性距離は返されません。結果に含めるには、--return-distance パラメーターを追加します。

画像類似性検索

画像クエリを使用して、最も類似したベクトルを検索し、画像間検索などのユースケースを実現します。

# --image: クエリ画像。
# --top-k: 返す最近傍の数。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "./query-images/similar-product.jpg" \   
  --top-k 100                                    

サンプル出力（ベクトルキーおよびメタデータを含む）：

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          // ベクトル検索結果（ベクトルキーおよびメタデータを含む）。
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "similar-product.png"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "image",
    "model": "qwen2.5-vl-embedding",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

ハイブリッド検索

--filter パラメーターを使用して、メタデータで結果をフィルター処理できます。これにより、より正確なクエリのために検索範囲を絞り込めます。OSS-Vectors-Embed-CLI は、単一のメタデータ条件によるシンプルなフィルタリングと、複数の条件による組み合わせフィルタリングをサポートします。

単一条件フィルタリング

category が technology であるベクトルをクエリします。

# --filter: メタデータフィルターを適用します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "技術文書" \
  --filter '{"category": {"$eq": "technology"}}' \
  --top-k 20 \
  --return-metadata

注： --return-metadata パラメーターは、ユーザー定義および CLI 生成の両方のフィールドを含むすべてのメタデータを結果に含めます。

サンプル出力：

{
  "results": [
    {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSSVECTORS-EMBED-SRC-CONTENT": "技術文書の内容",
        "version": "1.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "test1",
    "resultsFound": 4,
    "queryDimensions": 1024
  }
}

複数条件フィルタリング

OSS-Vectors-Embed-CLI は、フィルター構文 を使用して、AND や OR などの複数のフィルター条件を組み合わせます。次の例では AND 条件を使用しています。

AND クエリ： すべての条件に一致する必要があります。

# AND：両方の条件に一致する必要があります。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "API リファレンス" \
  --filter '{"$and": [{"category": "documentation"}, {"version": "3.0"}]}' \
  --top-k 5

サンプル出力：

{
  "results": [
  {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "documentation",
        "OSSVECTORS-EMBED-SRC-CONTENT": "API リファレンス",
        "version": "3.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 5,
    "queryDimensions": 1024
  }
}

検索結果を表形式で表示するには、--output table パラメーターを使用します。これにより、デフォルトの JSON 出力が読みやすい表形式に変換され、インタラクティブな探索およびデバッグに最適です。

# --output table: 出力形式を表形式で指定します。
oss-vectors-embed \
--account-id <your-account-id> \
--vectors-region cn-hangzhou \
query \
--vector-bucket-name <your-vector-bucket> \
--index-name <your-index> \
--model-id text-embedding-v4 \
--text "./queries/user-question.txt" \
--top-k 3 \
--output table

サンプル表形式出力：

                                 検索結果
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 順位 ┃ ベクトルキー           ┃ 距離   ┃ メタデータ             ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1    │ doc:auth-setup         │ N/A    │ {"category": "docs"}   │
│ 2    │ doc:security-config    │ N/A    │ {"category": "docs"}   │
│ 3    │ doc:api-reference      │ N/A    │ {"category": "docs"}   │
└──────┴────────────────────────┴──────────┴────────────────────────┘
検索まとめ：
  モデル: text-embedding-v4
  結果数: 3
  クエリディメンション: 1024

注： 距離列に「N/A」が表示されるのは、--return-distance パラメーターが省略されたためです。結果に距離を含めるには、このパラメーターをクエリに追加してください。

バッチ処理

CLI は、ワイルドカードを使用してディレクトリ内のファイルをバッチ処理します。このモードでは、並列リクエストを自動的に送信してスループットを向上させます。次の例では、OSS バケット内の指定されたプレフィックス配下にあるすべてのファイルを一括処理します。

# --text "oss://bucket/path/*": 指定されたプレフィックス配下のすべてのファイルを一括でベクトル化および書き込みます。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "oss://bucket/path/*"

{
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 2,
  "processedFiles": 2,
  "failedFiles": 0,
  "totalVectors": 2,
  "vectorKeys": [
    "1001dfcb-1e78-450b-8526-a9c92fa308c6",
    "b6aa1da0-adc7-489e-83e2-e39ff2e1fb9d"
  ]
}

# --max-workers: 同時実行数を設定します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "./documents/*.txt" \
  --max-workers 5

{
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 5,
  "processedFiles": 5,
  "failedFiles": 0,
  "totalVectors": 5,
  "vectorKeys": [
    "doc1.txt",
    "doc2.txt",
    "doc3.txt",
    "doc4.txt",
    "doc5.txt"
  ]
}

カスタムベクトルキー

CLI では、ベクトルキーを指定する柔軟な方法が提供されています。カスタム文字列、ソースファイル名、または各キーにプレフィックスを追加することができます。

# ベクトルキーを "doc-001" に設定します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "ドキュメントの内容" \
  --key "doc-001" 

{
 "key": "doc-001",    // ベクトルキーは "doc-001" に設定されます。
 "bucket": "my-test-2",
 "index": "test1",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "ドキュメントの内容",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

# ソースファイル名 "article.txt" をベクトルキーとして使用します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "article.txt" \
  --filename-as-key

{
  "key": "article.txt",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "人工知能は私たちの暮らし方を変革しています。睡眠サイクルに基づいて最適なタイミングで起こしてくれるスマートアラームクロック、通勤時の最適ルートを計画する音声アシスタント、自宅のスマートスピーカーによるパーソナライズされたニュース要約の再生、仕事場での AI ツールによる自動レポート生成・文書翻訳・ワークフロー最適化など——AI は静かに私たちの日常生活の隅々に浸透しています。",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "article.txt"
  }
}

# --key-prefix: ベクトルキーにプレフィックスを追加します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "ドキュメントの内容" \
  --key "doc-001" \
  --key-prefix "project-a/"

{
  "key": "project-a/doc-001",    // プレフィックス "project-a/" がベクトルキーに追加されます。
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "ドキュメントの内容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

カスタムモデルパラメーター

--dashscope-inference-params パラメーターを使用して、異なるシナリオに応じて埋め込みモデルの動作を微調整できます。

カスタムパラメーターによる書き込み

データのベクトル化時に、出力タイプやディメンションなどのパラメーターを指定できます。

# モデルの出力タイプおよびベクトルディメンションをカスタマイズします。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "技術文書の内容" \
  --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'

サンプル出力：

{
 "key": "73359c62-55a7-458a-a171-003755f3338e",
 "bucket": "my-vector-bucket",
 "index": "my-index",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "ドキュメントの内容",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

カスタムパラメーターによるクエリ

ベクトル検索時に、テキストの切り捨てポリシーなどの動作を制御できます。

# テキストの切り捨てポリシーを設定します。
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --text-value "技術文書" \
  --dashscope-inference-params '{"truncate": "END"}' \
  --top-k 10
  --return-distance

サンプル出力：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "技術文書",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

テキスト埋め込みモデル

マルチモーダル埋め込みモデル

モデル選択ガイド：

• テキストのみのユースケースには、text-embedding-v4 を使用します。

• テキストと画像を組み合わせるユースケースには、qwen2.5-vl-embedding を使用します。

• 高速処理を重視するアプリケーションには、tongyi-embedding-vision-flash を使用します。

グローバルパラメーター

put コマンドのパラメーター

query コマンドのパラメーター

フィルター構文