alibabacloud-oss-manage-metaquery

OSS ベクトル検索と AI コンテンツ認識

マルチモーダル AI モデルを活用し、OSS バケットに保存された画像、動画、音声、ドキュメントから、意味的な説明と簡潔な要約を抽出します。検索可能なベクトルインデックスを構築し、テキストから画像、テキストから動画を検索するなどの高度な検索機能を実現します。

前提条件

1. Aliyun CLI（>= 3.3.3）

事前確認：Aliyun CLI >= 3.3.3 が必要です このスキルでは、MetaQuery を開く操作を除き、すべての OSS 操作に Aliyun CLI を使用します。 Aliyun CLI がすでにインストールされている場合、ossutil を別途インストールする必要はありません。 次のコマンドを実行してバージョンを確認します：aliyun version インストールされていない場合、またはバージョンが 3.3.3 未満の場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

続いて、プラグインの自動インストールを有効にするため、[必須] aliyun configure set --auto-plugin-install true を実行してください。 ローカルマシンにある既存のプラグインを常に最新の状態に保つため、[必須] aliyun plugin update を実行してください。

2. aliyun ossutil プラグインを更新する

トラブルシューティング：--user-agent が不明なフラグというエラー コマンドの実行時に Error: unknown flag: --user-agent が発生した場合、ossutil プラグインのバージョンが古すぎます。次のコマンドを実行して最新バージョンに更新してください：

aliyun ossutil update

更新後、元のコマンドを再実行してください。

# Python SDK dependencies
pip install oss2==2.19.1 alibabacloud-credentials==1.0.8

注意：

• 必須：Aliyun CLI、Python の依存関係 oss2 と alibabacloud-credentials
• 不要：ossutil
• Python が必要な操作は、MetaQuery（AI コンテンツ認識＋セマンティック検索）を開く操作のみです セキュリティルール：
• AK/SK の値を絶対に読み取ったり、エコーしたり、出力したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 会話やコマンドラインで AK/SK を直接入力するよう、ユーザーに絶対に求めないでください

Core Workflow の開始時（CLI を呼び出す前）： [必須] AI-Mode を有効にする — Agent Skill の実行には AI-mode が必要です。 CLI を呼び出す前に、次のコマンドを実行してください：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery"

[必須] すべての終了時に AI-Mode を無効にする — どのような理由であっても最終回答を返す前に、必ず最初に AI-mode を無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、その他 CLI コマンドをこれ以上実行しないすべての状況に適用されます。 AI-mode は Agent Skill の呼び出しシナリオでのみ使用し、スキルの実行停止後に有効なままにしてはなりません。

aliyun configure ai-mode disable

[必須] CLI User-Agent — aliyun CLI コマンドを呼び出すたびに、次を含める必要があります： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

アーキテクチャ

User Request -> OSS Bucket -> AI Content Awareness Engine -> Semantic Feature Extraction -> Vector Index -> Semantic Search
                    |
         Images/Videos/Audio/Docs -> Detailed Description (~100 chars) + Concise Summary (<=20 chars)

コアコンポーネント：OSS Bucket + Data Index + Vector Search + AI Content Awareness

使用制限

対応リージョン

リージョンカテゴリ	リージョン一覧
中国東部	cn-hangzhou, cn-shanghai
中国北部	cn-qingdao, cn-beijing, cn-zhangjiakou
中国南部	cn-shenzhen, cn-guangzhou
中国西南部	cn-chengdu
その他	cn-hongkong, ap-southeast-1 (Singapore), us-east-1 (Virginia)

注意：ユーザーの Bucket が上記に記載されていないリージョンにある場合、ベクトルモードの MetaQuery とコンテンツ認識を有効にできず、EC Code 0037-00000001 エラーが返されます。対応リージョンに新しい Bucket を作成するようユーザーに案内してください。

ファイル形式

• 対応：画像、動画、音声、ドキュメント
• マルチパートアップロード：CompleteMultipartUpload で組み立てが完了したオブジェクトのみが表示されます

---

パフォーマンスの参考情報

OSS 内部帯域幅と QPS

リージョン	内部帯域幅	デフォルト QPS
cn-beijing, cn-hangzhou, cn-shanghai, cn-shenzhen	10Gbps	1250
その他のリージョン	1Gbps	1250

この帯域幅と QPS はベクトル検索専用であり、Bucket の QoS クォータを消費しません。

既存ファイルのインデックス作成時間

ファイルの種類	1,000 万ファイル	1 億ファイル	10 億ファイル
構造化データと画像	2～3 時間	1 日	約 10 日
動画、ドキュメント、音声	2～3 日	7～9 日	-

増分更新と検索レイテンシ

• 増分更新：QPS が 1250 未満の場合、通常、レイテンシは数分から数時間です
• 検索レスポンス：1 秒未満、デフォルトのタイムアウトは 30 秒です

---

危険な操作の確認

以下の危険な操作を実行する前に、必ず先にユーザーに確認し、明示的な同意を得てください。

• Bucket の削除：aliyun ossutil rm oss://<bucket-name> -b --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery — Bucket 全体を削除します。元に戻せません
• オブジェクトの削除：aliyun ossutil rm oss://<bucket-name>/<object-key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery — 特定のファイルを削除します
• オブジェクトの一括削除：aliyun ossutil rm oss://<bucket-name>/ --recursive --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery — Bucket 内のすべてのファイルを再帰的に削除します
• MetaQuery の終了：aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery — メタデータインデックスを終了します。インデックス化されたデータはすべて消去されます
• MetaQuery の開始：python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint> — メタデータインデックスを開始します。既存のデータのインデックス化が始まります。Bucket 内のオブジェクトが 1000 個を超える場合は、必ず先にユーザーに確認してください
• Bucket の作成：aliyun ossutil api put-bucket --bucket <bucket> --region <region-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery — Bucket を作成します

確認の際は、以下の内容をユーザーに説明してください。

1. 実行する具体的な操作
2. 影響範囲（削除または終了されるファイル／リソース）
3. 操作を元に戻せるかどうか（ほとんどの削除操作は元に戻せません）

RAM 権限

references/ram-policies.md を参照してください

---

重要なルール（必ず遵守）

ルール 1：MetaQuery の開始には必ず Python スクリプトを使用する

禁止：

aliyun ossutil api open-meta-query oss://my-bucket --mode semantic

必須：

python scripts/open_metaquery.py --region cn-hangzhou --bucket my-bucket

**理由：**AI Content Awareness（ImageInsightEnable と VideoInsightEnable）を有効にする WorkflowParameters を正しく設定できるのは、Python スクリプトまたは SDK だけです。これを設定しないと、セマンティック検索の品質が大幅に低下します。

ルール 2：Bucket 名が競合した場合は必ずユーザーに確認する

Bucket の作成時に BucketAlreadyExists エラーが発生した場合：

1. 直ちに停止し、それ以降の操作をすべて中止します
2. ユーザーに「Bucket 名はすでに使用されています」と伝えます
3. ユーザーに以下から選択するよう依頼します。
   • オプション 1：既存の Bucket を使用する（ユーザーの明示的な確認が必要です）
   • オプション 2：新しい Bucket 名を選択する（ユーザーが新しい名前を指定します）
4. 続行する前に、ユーザーの回答を待ちます 禁止：

• Bucket 名を自動的に変更すること（例：-2、-new などを追加する）
• ユーザーに確認せず既存の Bucket を使用すること

ルール 3：MetaQuery の開始以外のすべての操作では、デフォルトで Aliyun CLI を使用する

以下の操作では、デフォルトで Aliyun CLI を使用してください。

• Bucket の作成
• Bucket 情報の照会
• Bucket 統計情報の照会
• ファイルのアップロード
• MetaQuery のステータス照会
• セマンティック検索の実行
• MetaQuery の終了
• オブジェクト／Bucket の削除 目標：aliyun コマンドを統一して使用し、ossutil への依存を最小限に抑えます。

ルール 4：Aliyun CLI がインストールされている場合、ossutil は不要

このスキルでは、ossutil のインストールはデフォルトで必要ありません。 Aliyun CLI >= 3.3.3 がインストールされ、以下が実行されていれば、

aliyun configure set --auto-plugin-install true

デフォルトの実行ツールとして使用できます。

中核となるワークフロー

タスク 1：バケットを作成してファイルをアップロードする

バケットを作成する前に、必ずユーザーに確認してください。ユーザーの同意を得てから続行してください。

# 1.1 Create Bucket
aliyun ossutil api put-bucket --bucket examplebucket --region <region-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
# 1.2 Download files
aliyun ossutil cp oss://example-bucket/test_medias/ /tmp/test_medias_download/ -r --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
# 1.3 Upload files
aliyun ossutil cp /tmp/test_medias_download/ oss://example-bucket/test_medias/ -r --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

タスク 2：ベクトル検索と AI コンテンツ認識を有効にする（Python スクリプトまたは SDK のみ）

WARNING: MetaQuery を開くには、必ず python scripts/open_metaquery.py を使用してください。aliyun ossutil api open-meta-query の使用は厳禁です（WorkflowParameters を設定できないため、AI コンテンツ認識機能の ImageInsightEnable と VideoInsightEnable を有効にできず、セマンティック検索の品質が著しく低下します）。

Python スクリプトを使用する（必須）

Python スクリプトを実行する前に、次の環境設定を完了してください。

1. Python の依存関係をインストールする：

pip install oss2==2.19.1 alibabacloud-credentials==1.0.8

2. 認証情報を設定する： Python スクリプトは alibabacloud-credentials のデフォルト認証情報チェーンを使用して、認証情報を自動的に検出します（環境変数、~/.aliyun/config.json、ECS インスタンスロールなどに対応）。コード内で AK/SK を明示的に扱う必要はありません。aliyun configure コマンドで認証情報が設定されていることを確認してください。

3. RAM 権限を確認する： ユーザーには MetaQuery に必要な最小限の RAM 権限が必要です。references/ram-policies.md を参照してください。 ユーザーに AccessDenied エラーが発生した場合は、RAM 権限が正しく設定されていることを確認してください。

有効化の手順：

1. バケットを準備する： a. ユーザーが新しいバケットの作成をリクエストした場合：

   • ユーザー指定のバケット名を使用して、aliyun ossutil api put-bucket --bucket examplebucket --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery を実行します
   • BucketAlreadyExists エラーで作成に失敗した場合：
     • 直ちに操作を中止します
     • ユーザーに次のように伝えます：「バケット名 <bucket-name> はすでに使用されています（ユーザー自身または別のユーザーが作成した可能性があります）」
     • 必ずユーザーに確認します：「次のどちらにしますか？ 1）この既存のバケットを使用する、または 2）新しいバケット名を選択する」
     • 続行する前に、ユーザーから明確な回答を得るまで待ちます。許可なくバケット名を変更したり、既存のバケットを使用したりしないでください。 b. ユーザーが既存のバケットを指定した場合：
   • まず、aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery を使用して、バケットが存在することを確認します
   • 存在しない場合は、作成するかどうかをユーザーに確認します

2. バケット内のオブジェクト数を確認する：ユーザーからバケットの指定を受けた後、オブジェクト数を確認します。1000 を超える場合は、MetaQuery の有効化によって費用が発生することをユーザーに警告してください。 次のコマンドを使用して、バケット内のオブジェクト数を取得します。

   aliyun ossutil api get-bucket-stat --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
   

   応答の ObjectCount フィールドがオブジェクト数を示します。

   • オブジェクト数が 1000 を超える場合は、MetaQuery の有効化によって費用が発生することをユーザーに警告し、続行するか確認してください。
   • オブジェクト数が 0 の場合は、アップロードするファイルをユーザーに確認します。アップロードコマンド：

     aliyun ossutil api put-object --bucket <your-bucket-name> --key <object-key> --body file://<local-file-path> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
     

3. Python スクリプトを実行する：上記の手順が完了したら、Python スクリプトを使用して MetaQuery を開きます。 Python スクリプトの例：

python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint>

MetaQuery の有効化に関する問題のトラブルシューティング

get-meta-query-status コマンドを使用して、MetaQuery のステータスを確認します：

aliyun ossutil api get-meta-query-status --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

返されたステータスに応じて、次のように対応します：

• ステータスが Deleted の場合：MetaQuery は終了処理中です。後でもう一度お試しいただくようユーザーに案内してください。
• ステータスが Running または Ready の場合：MetaQuery はすでに作成されています。次の 2 つの条件を確認してください：
  • MetaQueryMode が semantic であること
  • WorkflowParameters に次の設定が含まれていること

    <WorkflowParameters>
      <WorkflowParameter><Name>ImageInsightEnable</Name><Value>True</Value></WorkflowParameter>
      <WorkflowParameter><Name>VideoInsightEnable</Name><Value>True</Value></WorkflowParameter>
    </WorkflowParameters>
    

  MetaQueryMode=semantic で、VideoInsightEnable と ImageInsightEnable がどちらも True の場合、ユーザーはベクトルモードでコンテンツ認識を有効にして MetaQuery の設定に成功しています（これにより、セマンティック検索の品質が大幅に向上します）。これ以上の対応は不要です。 これらの条件を満たしていない場合は、別のバケットに切り替えて最初からやり直すようユーザーに案内してください。

タスク 3：セマンティック検索の実行

MetaQuery 検索の前提条件

MetaQuery を使用して検索する前に、次の点を確認してください：

1. MetaQuery が有効になっていることを確認します：

   aliyun ossutil api get-meta-query-status --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
   

2. If MetaQuery is not enabled: Complete the enablement process first. Refer to Task 2 to enable it using the Python script.
3. Check index scan status: The Phase field from get-meta-query-status indicates the current scan phase:
   • FullScanning: Full scan in progress. Search is not available yet. Wait for the full scan to complete.
   • IncrementalScanning: Incremental scan in progress. The index has been largely built and search can be performed normally.
4. Verify MetaQuery state is Running: MetaQuery is only available when State is Running. If the state is Ready or any non-Running state, you may need to wait or re-enable it.

1. Prepare the meta-query.xml file: Create a meta-query.xml file to define query conditions. For detailed format, field descriptions, and complete examples, see references/metaquery.md. Example of semantic vector search for video files containing "person" (MediaTypes can only be one of: video, image, audio, document):

<MetaQuery>
<MediaTypes><MediaType>video</MediaType></MediaTypes>
<Query>person</Query>
</MetaQuery>

ファイルサイズが 30B を超え、ファイルの更新時刻が 2025-06-03T09:20:47.999Z より後である場合のスカラー検索例：

<MetaQuery>
<Query>{"SubQueries":[{"Field":"Size","Value":"30","Operation":"gt"},{"Field":"FileModifiedTime","Value":"2025-06-03T09:20:47.999Z","Operation":"gt"}],"Operation":"and"}</Query>
</MetaQuery>

2. 検索コマンドを実行します： この例では、セマンティックベクトル検索を使用しています。meta-query.xml ファイルでクエリ条件を定義し、検索結果として最も類似したファイルが返されます。

aliyun ossutil api do-meta-query --bucket <bucket-name> --meta-query file://meta-query.xml --meta-query-mode semantic --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

スカラー検索の場合は、--meta-query-mode basic を使用します。

詳細なコマンドパラメーターについては、references/related-apis.md の DoMetaQuery セクションを参照してください。

3. 検索結果の表示を最適化します： 検索が完了したら、結果をユーザーに表示する際に x-oss-process パラメーターを使用して、画像ファイルのプレビュー画像や動画ファイルのカバーフレームを生成すると、検索結果を目で確認しやすくなります。ユーザーが現在利用しているチャネルでマルチメディアファイルをサポートしている場合は、そのままユーザーに送信してください。

動画ファイル -- 動画のカバー画像を取得します：

aliyun ossutil presign oss://<bucket-name>/<video-object-key> --query-param x-oss-process=video/snapshot,t_0,f_png,w_0,h_0 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

パラメーター：t_0：0ms のフレームをカバー画像としてキャプチャします。f_png：出力形式は PNG です。w_0,h_0：幅と高さが 0 の場合は元の解像度です。

画像ファイル -- 画像のプレビューリンクを取得します：

aliyun ossutil presign oss://<bucket-name>/<image-object-key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

注：aliyun ossutil presign コマンドは、ブラウザーで直接開いて有効期間中にプレビューできる、一時的な署名付きアクセス URL を生成します。画像ファイルの場合は、x-oss-process を使用して画像処理パラメーター（サイズ変更、切り抜きなど）を追加することもできます：

aliyun ossutil presign oss://<bucket-name>/<image-object-key> --query-param x-oss-process=image/resize,w_200 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

これにより、読み込み時間を短縮するサムネイルプレビューが生成されます。

MetaQuery 検索に関する問題のトラブルシューティング

ユーザーから「特定のファイルが見つからない」と質問された場合

特定のアップロード済みファイルが検索結果に表示されないとユーザーから報告された場合は、MetaQuery の設定に基づいてトラブルシューティングを行います。

a. コンテンツ認識が有効になっていない場合： ユーザーの MetaQuery でコンテンツ認識が有効になっていない場合（つまり、WorkflowParameters 内の VideoInsightEnable または ImageInsightEnable が True ではない場合）、次の理由が考えられます。

• ファイルのメタデータインデックスがまだ完全に作成されていません。インデックスのスキャンが完了するまで待ちます（aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery を使って Phase フィールドを確認します）。
• コンテンツ認識が無効な場合、検索は基本的なファイルメタデータ（ファイル名、サイズ、種類など）のみを対象とし、ファイルの内容を意味的に理解できないため、検索精度が限られます。
• 推奨事項：検索品質を向上させるため、コンテンツ認識を有効にするようユーザーに提案します。既存の MetaQuery 設定は直接変更できないため、Task 2 の手順に従って、新しいバケットに切り替え、コンテンツ認識を有効にして MetaQuery を再設定することを推奨します。

b. コンテンツ認識が有効になっている場合： ユーザーの MetaQuery でコンテンツ認識が有効になっているにもかかわらず、特定のファイルが見つからない場合、次の理由が考えられます。

• ファイルの処理中：コンテンツ認識では、ファイルの詳細な分析（画像認識、動画の理解など）が必要であり、特に動画ファイルでは時間がかかります。aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery を使って Phase フィールドを確認します。
  • FullScanning：インデックス全体のスキャンがまだ進行中です。完了までお待ちください。
  • IncrementalScanning：新しくアップロードされたファイルが増分処理されています。通常は数分お待ちください。
• 未対応のファイル形式：コンテンツ認識でサポートされていないファイル形式があります。この場合、基本的なメタデータのみを使って検索できます。
• 検索キーワードが一致しない：ユーザーの検索キーワードがファイルの内容と意味的に一致していない可能性があります。実際のファイル内容に近い表現を使うよう、検索キーワードを調整することを提案します。

Task 4：データインデックスのステータスを照会する（aliyun ossutil）

aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

返されるフィールド（State、Phase、MetaQueryMode など）の詳細については、references/related-apis.md の GetMetaQueryStatus のセクションを参照してください。

検証

references/verification-method.md を参照してください。

リソースのクリーンアップ

# Close the data index. (Dangerous operation -- confirm with the user first)
aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

警告：データインデックスを閉じると、インデックス化されたデータはすべて消去されます。（危険な操作です。必ず事前にユーザーに確認してください）

OSS 操作に使える Python スクリプト

aliyun ossutil を使用できない場合は、代替手段として Python スクリプトを使用できます。references/related-apis.md の Python SDK Scripts のセクションを参照してください。

---