Object Storage Service:OSS ベクトル埋め込み CLI ： ベクトルの管理

アクセス認証情報の設定

アクセス認証情報を環境変数として設定してください。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. ベクターバケットの作成：[ベクターバケット] ページで、ベクターデータとインデックスを格納するバケットを作成してください。

2. ベクターインデックスの作成：新しいバケットでインデックスを作成し、そのベクターディメンションを、使用するベクターモデルの出力ディメンションと一致するように設定してください。

重要: ベクトルインデックスの次元は、使用する ベクトルモデル の出力次元と一致する必要があります。 例えば、text-embedding-v4 モデル (デフォルトは 1024 次元) を使用する場合、インデックスの次元も 1024 に設定する必要があります。

テキストファイルからの埋め込みの生成

text-embedding-v4 などのテキスト埋め込みモデルを使用してテキストを処理します。サポートされている入力ソースには、テキスト文字列、OSS オブジェクト、およびローカルテキストファイルが含まれます。

入力としてのテキスト文字列の使用

インラインのテキスト文字列から埋め込みを生成し、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 "Artificial intelligence is changing the way we live"

サンプルレスポンス：

{
  "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": "Artificial intelligence is changing the way we live",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

注: CLI は、埋め込みのソースを追跡するために、自動的に OSSVECTORS-EMBED-SRC-* フィールドをメタデータに追加します。

入力としてのローカルテキストファイルの使用

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

# パラメーターの説明：
# --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": "Artificial intelligence is changing the way we live. From being gently woken up by a smart alarm clock based on our sleep cycle in the morning, to having a voice assistant plan the best route for our commute; from a smart speaker at home playing personalized news summaries, to AI tools at work automatically generating reports, translating documents, and optimizing workflows—AI has quietly integrated into every corner of our daily lives.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "./documents/article.txt"
  }
}

入力としての OSS オブジェクトの使用

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>"

注: --region パラメーターを使用して、ソース OSS オブジェクトのリージョンを指定する必要があります。

サンプルレスポンス：

{
  "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": "This is an example file.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"
  }
}

画像ファイルからの埋め込みの生成

画像と動画を処理するには、マルチモーダル埋め込みモデル (たとえば qwen2.5-vl-embedding) を使用します。サポートされている入力ソースには、ローカルファイル、OSS オブジェクト、HTTP/HTTPS URL が含まれます。

入力としてのローカル画像の使用

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

# パラメーターの説明：
# --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 ベクターバケットに書き込みます。オブジェクトパスは、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 にある画像から埋め込みを生成し、OSS ベクターバケットに書き込みます：

# パラメーターの説明：
# --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 です。ビデオを処理する際、CLI はキーフレームを抽出し、フレームごとに個別の埋め込みを生成します。各埋め込みには一意のキーが必要なため、--key および --filename-as-key パラメーターはサポートされていません。CLI は、各フレームに対して一意のシーケンシャルキーを自動的に生成します。

入力としての OSS オブジェクトの使用

OSS の動画ファイルから埋め込みを生成し (アクセス用の署名付き URL の作成が含まれます) 、OSS ベクターバケットに書き込みます：

# パラメーターの説明：
# --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-3c156220ef54",
  "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 にある動画から埋め込みを生成し、OSS ベクターバケットに書き込みます：

# パラメーターの説明：
# --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 "Technical document content" \
  --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": "Technical document 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 "What is artificial intelligence" \
  --top-k 100

出力例 (ベクトルキーとメタデータを含む)：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "Artificial intelligence is changing our way of life",
        "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": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE",
        "OSSVECTORS-EMBED-SRC-LOCATION": "similar-product.jpg"
      }
    },
    ...
  ],
  "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 "Technical documentation" \
  --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": "Technical document content",
        "version": "1.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "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 Reference" \
  --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 Reference",
        "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

出力例：

                                 Query Results
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Rank ┃ Vector Key             ┃ Distance ┃ Metadata               ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1    │ doc:auth-setup         │ N/A      │ {"category": "docs"}   │
│ 2    │ doc:security-config    │ N/A      │ {"category": "docs"}   │
│ 3    │ doc:api-reference      │ N/A      │ {"category": "docs"}   │
└──────┴────────────────────────┴──────────┴────────────────────────┘
Query Summary:
  Model: text-embedding-v4
  Results Found: 3
  Query Dimensions: 1024

注意：コマンドに --return-distance パラメーターが含まれていないため、Distance 列には N/A が表示されます。距離の値を表示するには、このパラメーターを追加してください。

バッチ処理

CLI は、ワイルドカードを使用してディレクトリ内のすべてのファイルに対するバッチ処理をサポートしています。バッチモードでは、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 "Document content" \
  --key "doc-001" 

{
 "key": "doc-001",    // ベクターキーは "doc-001" です。
 "bucket": "my-vector-bucket",
 "index": "my-index",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "Document 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": "Artificial intelligence is changing the way we live. From being gently woken up by a smart alarm clock based on our sleep cycle in the morning, to having a voice assistant plan the best route for our commute; from a smart speaker at home playing personalized news summaries, to AI tools at work automatically generating reports, translating documents, and optimizing workflows—AI has quietly integrated into every corner of our daily lives.",
    "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 "Document content" \
  --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": "Document content",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

モデルパラメーターのカスタマイズ

--dashscope-inference-params パラメーターを使用して、さまざまなビジネスシナリオに合わせてベクターモデルを微調整できます。

カスタムパラメーターを使用した書き込み

データをベクトル化する際に、出力タイプや次元などのパラメーターを指定します。

# --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}' を使用して、モデルの出力タイプとベクターの次元をカスタマイズします。
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 "Technical document content" \
  --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": "Technical document content",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

カスタムパラメーターを使用したクエリ

ベクターをクエリする際に、テキスト切り捨てポリシーなどの動作を制御できます。

# --dashscope-inference-params '{"truncate": "END"}' を使用して、テキスト切り捨てポリシーを設定します。
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 "Technical documentation" \
  --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": "Technical documentation",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "qwen2.5-vl-embedding",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

テキスト埋め込みモデル

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

モデル選択の推奨事項：

• テキストのみを使用する場合は、text-embedding-v4 を使用します。

• テキストと画像の両方を使用する場合は、qwen2.5-vl-embedding を使用します。

• 低レイテンシーが求められる場合は、tongyi-embedding-vision-flash を検討してください。

グローバルパラメーター

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

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

フィルター構文