Alibabacloud Oss Manage Metaquery

OSS Vector Search & AI Content Awareness

Leverage multimodal AI models to extract semantic descriptions and concise summaries from images, videos, audio, and documents stored in OSS Buckets. Build searchable vector indexes to enable advanced retrieval capabilities such as text-to-image and text-to-video search.

Prerequisites

1. Aliyun CLI (>= 3.3.3)

Pre-check: Aliyun CLI >= 3.3.3 required

This skill uses Aliyun CLI for all OSS operations except opening MetaQuery.

If Aliyun CLI is already installed, ossutil does not need to be installed separately.

Run the following command to verify the version: aliyun version

If not installed or the version is below 3.3.3,

run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update,

or refer to references/cli-installation-guide.md for installation instructions.

>

Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

[MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

2. Update the aliyun ossutil plugin

Troubleshooting: `--user-agent` unknown flag error

If you encounter Error: unknown flag: --user-agent when running a command, the ossutil plugin version is too old. Run the following command to update to the latest version:

```bash

aliyun ossutil update

```

After the update, re-run the original command.

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

Notes:

- Required: Aliyun CLI, Python dependencies oss2 and alibabacloud-credentials

- Not required: ossutil

- The only operation that requires Python: opening MetaQuery (AI Content Awareness + semantic search)

Security Rules:

- NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

- NEVER ask the user to input AK/SK directly in the conversation or command line

At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

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

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

Architecture

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)

Core Components: OSS Bucket + Data Index + Vector Search + AI Content Awareness

Usage Restrictions

Supported Regions

Note: If the user's Bucket is in a region not listed above, vector-mode MetaQuery and content awareness cannot be enabled, and an EC Code 0037-00000001 error will be returned. Guide the user to create a new Bucket in a supported region.

File Types

• Supported: Images, videos, audio, documents
• Multipart uploads: Only objects that have been assembled via CompleteMultipartUpload are shown

---

Performance Reference

OSS Internal Bandwidth and QPS

This bandwidth and QPS is provided exclusively for vector search and does not consume the Bucket's QoS quota.

Existing File Index Build Time

Incremental Updates and Search Latency

• Incremental updates: When QPS < 1250, latency is typically minutes to hours
• Search response: Sub-second, default timeout 30 seconds

---

Dangerous Operation Confirmation

Before executing any of the following dangerous operations, you MUST confirm with the user first and obtain explicit consent before proceeding:

• Delete Bucket: aliyun ossutil rm oss://<bucket-name> -b --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery -- Deletes the entire Bucket, irreversible
• Delete Object: aliyun ossutil rm oss://<bucket-name>/<object-key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery -- Deletes a specific file
• Batch Delete Objects: aliyun ossutil rm oss://<bucket-name>/ --recursive --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery -- Recursively deletes all files in the Bucket
• Close MetaQuery: aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery -- Closes the metadata index; all indexed data will be cleared
• Open MetaQuery: python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint> -- Opens the metadata index; existing data will start being indexed. If the bucket has more than 1000 objects, confirm with the user first.
• Create Bucket: aliyun ossutil api put-bucket --bucket <bucket> --region <region-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery -- Creates a Bucket

When confirming, explain the following to the user: 1. The specific operation to be performed 2. The scope of impact (which files/resources will be deleted or closed) 3. Whether the operation is reversible (most delete operations are irreversible)

RAM Permissions

See references/ram-policies.md

---

Critical Rules (Must Follow)

Rule 1: Opening MetaQuery MUST use the Python script

PROHIBITED:

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

REQUIRED:

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

Reason: Only the Python script or SDK can correctly configure WorkflowParameters to enable AI Content Awareness (ImageInsightEnable and VideoInsightEnable). Without this, semantic search quality will be severely degraded.

Rule 2: Must ask the user when Bucket name conflicts

When creating a Bucket and encountering a BucketAlreadyExists error: 1. Immediately stop all subsequent operations 2. Inform the user: "The Bucket name is already taken" 3. Ask the user to choose:

• Option 1: Use the existing bucket (requires explicit user confirmation)
• Option 2: Choose a new bucket name (user provides the new name)

4. Wait for the user's response before continuing PROHIBITED:

• Automatically modifying the bucket name (e.g., appending -2, -new, etc.)
• Using an existing bucket without asking the user

Rule 3: Use Aliyun CLI by default for all operations except opening MetaQuery

The following operations should use Aliyun CLI by default:

• Create Bucket
• Query Bucket info
• Query Bucket statistics
• Upload files
• Query MetaQuery status
• Execute semantic search
• Close MetaQuery
• Delete Object / Bucket

Goal: Use the `aliyun` command uniformly, minimizing dependency on ossutil.

Rule 4: If Aliyun CLI is installed, ossutil is not needed

This skill does not require ossutil to be installed by default. As long as Aliyun CLI >= 3.3.3 is installed and the following has been executed:

aliyun configure set --auto-plugin-install true

It can be used as the default execution tool.

Core Workflows

Task 1: Create Bucket and Upload Files

Always confirm with the user before creating a bucket. Proceed only after the user agrees.

# 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

Task 2: Enable Vector Search & AI Content Awareness (Python script or SDK only)

WARNING: You MUST use python scripts/open_metaquery.py to open MetaQuery. Using aliyun ossutil api open-meta-query is STRICTLY PROHIBITED (it cannot configure WorkflowParameters, which prevents enabling AI Content Awareness features ImageInsightEnable and VideoInsightEnable, severely degrading semantic search quality).

Using the Python Script (Mandatory)

Before executing the Python script, complete the following environment setup:

1. Install Python dependencies:

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

2. Configure credentials: The Python script uses the alibabacloud-credentials default credential chain to automatically discover credentials (supporting environment variables, ~/.aliyun/config.json, ECS instance roles, etc.). No explicit AK/SK handling is needed in the code. Ensure credentials are configured via the aliyun configure command.

3. Verify RAM permissions: Users must have the minimum RAM permissions required for MetaQuery. See references/ram-policies.md. If the user encounters an AccessDenied error, check that RAM permissions are correctly configured.

Enablement Process: 1. Prepare the Bucket: a. If the user requests creating a new Bucket:

• Run aliyun ossutil api put-bucket --bucket examplebucket --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery with the user-specified bucket name
• If creation fails with a BucketAlreadyExists error:
• Immediately stop the operation
• Inform the user: "The Bucket name <bucket-name> is already taken (it may have been created by you or another user)"
• You MUST ask the user: "Would you like to: 1) Use this existing bucket? or 2) Choose a new bucket name?"
• Wait for the user's explicit response before continuing. Do not modify the bucket name or use the existing bucket without permission.

b. If the user provides an existing bucket:

• First verify the bucket exists using aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
• If it does not exist, ask the user whether to create it

2. Verify Bucket object count: After the user provides a bucket, check the object count. If it exceeds 1000, warn the user that enabling MetaQuery will incur costs. Use the following command to get the bucket's object count:

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

The ObjectCount field in the response indicates the number of objects.

• If the object count exceeds 1000, warn the user that enabling MetaQuery will incur costs and confirm whether to proceed.
• If the object count is 0, ask the user which files to upload. Upload command:

     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. Run the Python script: After the above steps are complete, attempt to open MetaQuery using the Python script. Python script example:

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

Troubleshooting MetaQuery Enablement Issues

Use the get-meta-query-status command to check MetaQuery status:

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

Based on the returned status:

• Status is `Deleted`: MetaQuery is being closed. The user should retry later.
• Status is `Running` or `Ready`: MetaQuery has already been created. Check the following two conditions:
• Whether MetaQueryMode is semantic
• Whether WorkflowParameters contains the following configuration:

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

If MetaQueryMode=semantic and both VideoInsightEnable and ImageInsightEnable are True, the user has successfully enabled MetaQuery in vector mode with content awareness (which greatly improves semantic search quality). No further action is needed. If these conditions are not met, recommend the user switch to a different bucket and start over.

Task 3: Execute Semantic Search

Prerequisites for MetaQuery Search

Before using MetaQuery for search, confirm the following: 1. Verify MetaQuery is enabled:

   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](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>

Example of scalar search where file size > 30B and file modification time > 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. Execute the search command:**
This example uses semantic vector search. The `meta-query.xml` file defines the query conditions, and search results return the most similar files.

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

For scalar search, use `--meta-query-mode basic`
> For detailed command parameters, see the DoMetaQuery section in [references/related-apis.md](references/related-apis.md).

**3. Optimizing search result display:**
After search completes, when displaying results to the user, use the `x-oss-process` parameter to generate preview images or cover frames for image and video files, making it easier for the user to visually review search results. If the user's current channel supports multimedia files, send them directly to the user.

**Video files -- Get video cover snapshot:**

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

Parameters: `t_0`: Capture frame at 0ms as cover; `f_png`: Output format PNG; `w_0,h_0`: Width/height 0 means original resolution.

**Image files -- Get image preview link:**

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

> **Note**: The `aliyun ossutil presign` command generates a signed temporary access URL that can be opened directly in a browser for preview during its validity period. For image files, you can also add image processing parameters via `x-oss-process` (e.g., resize, crop):
> ```bash
> 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
> ```
> This generates a thumbnail preview to reduce loading time.

### Troubleshooting MetaQuery Search Issues
#### User asks "Why wasn't a specific file found?"
When a user reports that a specific uploaded file is missing from search results, troubleshoot based on the MetaQuery configuration:

**a. Content awareness is NOT enabled:**
If the user's MetaQuery does not have content awareness enabled (i.e., `VideoInsightEnable` or `ImageInsightEnable` is not `True` in `WorkflowParameters`), possible reasons include:
- The file's metadata index has not been fully built yet. Wait for the index scan to complete (check the `Phase` field via `aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery`).
- Without content awareness, search is based only on basic file metadata (filename, size, type, etc.) and cannot perform semantic understanding of file contents, resulting in limited search effectiveness.
- **Recommendation**: Suggest the user enable content awareness to improve search quality. Since existing MetaQuery configurations cannot be directly modified, recommend the user switch to a new bucket and re-enable MetaQuery with content awareness following the Task 2 process.

**b. Content awareness IS enabled:**
If the user's MetaQuery has content awareness enabled but a specific file still cannot be found, possible reasons include:
- **File is still being processed**: Content awareness requires deep analysis of files (e.g., image recognition, video understanding), which takes longer, especially for video files. Check the `Phase` field via `aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery`:
  - `FullScanning`: The overall index is still in full scan mode. Wait patiently.
  - `IncrementalScanning`: Newly uploaded files are being processed incrementally. Usually wait a few minutes.
- **Unsupported file format**: Some file formats may not be supported by content awareness. In this case, search can only use basic metadata.
- **Search keywords don't match**: The user's search keywords may not semantically match the file content. Suggest the user try adjusting their search keywords to use descriptions closer to the actual file content.

### Task 4: Query Data Index Status (aliyun ossutil)

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

> For detailed descriptions of returned fields (State, Phase, MetaQueryMode, etc.), see the GetMetaQueryStatus section in [references/related-apis.md](references/related-apis.md).

## Verification
See [references/verification-method.md](references/verification-method.md)

## Resource Cleanup

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

> **Warning**: After closing the data index, all indexed data will be cleared. (Dangerous operation -- confirm with the user first)

## Alternative Python Scripts for OSS Operations
When aliyun ossutil is unavailable, you can use Python scripts as alternatives. See the Python SDK Scripts section in [references/related-apis.md](references/related-apis.md).

---

Acceptance Criteria: OSS Vector Search & AI Content Awareness

Scenario: OSS Vector Search & AI Content Awareness Semantic Search Purpose: Skill test acceptance criteria

Table of Contents

• Operation Dependencies
• Correct aliyun ossutil Command Patterns
• Correct Python SDK Code Patterns
• Correct Java SDK Code Patterns
• Operation Checklist
• Acceptance Test Cases
• Common Errors and Troubleshooting

---

Operation Dependencies

+---------------------------------------------------------------------+
|                    Operation Dependency Flow                         |
+---------------------------------------------------------------------+
|                                                                     |
|  1. Create Bucket -----------------------------------------------+  |
|     (CLI/SDK/Console)                                            |  |
|           |                                                      |  |
|           v                                                      |  |
|  2. Upload Files ----------------------------------------+       |  |
|     (CLI/SDK/Console)                                    |       |  |
|           |                                              |       |  |
|           v                                              |       |  |
|  3. Initial Role Authorization (Console only)            |       |  |
|     AliyunMetaQueryDefaultRole                           |       |  |
|           |                                              |       |  |
|           v                                              |       |  |
|  4. Enable Vector Search + AI Content Awareness <--------+       |  |
|     (SDK/Console)                                                |  |
|     - mode: semantic                                             |  |
|     - WorkflowParameters: VideoInsightEnable, ImageInsightEnable |  |
|     - Filters: File filtering rules (optional)                   |  |
|           |                                                      |  |
|           v                                                      |  |
|  5. Wait for Index Build <---------------------------------------+  |
|     Query status: GetMetaQueryStatus                                |
|     State: Ready -> Running (FullScanning -> IncrementalScanning)   |
|           |                                                         |
|           v                                                         |
|  6. Execute Semantic Search                                         |
|     (CLI/SDK/Console)                                               |
|     DoMetaQuery (mode=semantic)                                     |
|                                                                     |
+---------------------------------------------------------------------+

Dependency Table

---

Correct Command Patterns

For correct aliyun ossutil command patterns and core rules, refer to the "Critical Rules" and "Core Workflows" sections in SKILL.md.

---

Correct Python SDK Code Patterns

For correct and incorrect Python SDK code patterns (import, credential initialization, enabling vector search, semantic search, scalar search), refer to the code examples and script usage in the "Critical Rules" and "Core Workflows" sections of SKILL.md, as well as the verification scripts in verification-method.md.

---

Correct Java SDK Code Patterns

1. Dependency Version

CORRECT

<!-- Java SDK 3.18.2+ supports vector search -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.18.2</version>
</dependency>

2. Client Initialization

CORRECT

EnvironmentVariableCredentialsProvider credentialsProvider = 
    CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

ClientBuilderConfiguration clientConfig = new ClientBuilderConfiguration();
clientConfig.setSignatureVersion(SignVersion.V4);  // Must use V4 signature

OSS ossClient = OSSClientBuilder.create()
    .endpoint(endpoint)
    .credentialsProvider(credentialsProvider)
    .clientConfiguration(clientConfig)
    .region(region)
    .build();

3. Semantic Search Request

CORRECT

DoMetaQueryRequest request = new DoMetaQueryRequest(
    bucketName, maxResults, query, sort, 
    MetaQueryMode.SEMANTIC,  // Semantic mode
    mediaTypes, simpleQuery
);
DoMetaQueryResult result = ossClient.doMetaQuery(request);

---

Operation Checklist

Prerequisite Checks

• [ ] Valid credentials configured (via aliyun configure in ~/.aliyun/config.json)
• [ ] Bucket region supports vector search functionality
• [ ] Correct SDK version installed (Java >= 3.18.2, Python oss2)

Role Authorization (First time only, Console only)

• [ ] AliyunMetaQueryDefaultRole role authorization completed in Console

Enable Vector Search & AI Content Awareness (SDK/Console)

• [ ] Vector search enabled (mode=semantic)
• [ ] Image content awareness configured (ImageInsightEnable=True)
• [ ] Video content awareness configured (VideoInsightEnable=True)
• [ ] (Optional) File filtering rules configured

Index Status Check

• [ ] State = Running (operational)
• [ ] Phase = FullScanning (full scan) or IncrementalScanning (incremental scan)

---

Acceptance Test Cases

For specific commands and code for the following test cases, refer to the corresponding "Core Workflows" Task sections in SKILL.md.

Test Case 1: Bucket Creation and File Upload

Corresponds to: SKILL.md Task 1

Prerequisites: Valid credentials configured (via aliyun configure in ~/.aliyun/config.json)

Expected Results:

• Bucket created successfully
• Files uploaded successfully

---

Test Case 2: Enable Vector Search & AI Content Awareness

Corresponds to: SKILL.md Task 2

Prerequisites:

• Bucket created
• Role authorization completed (Console required for first time)
• Bucket object count verified (confirm costs if exceeding 1000 objects)

Expected Results:

• Successful status code returned (200)
• Index build started
• Content awareness features enabled (VideoInsightEnable and ImageInsightEnable are True)

---

Test Case 3: Query Index Status

Corresponds to: SKILL.md Task 4

Prerequisites: Vector search enabled

Expected Results:

• State: Ready -> Running
• Phase: FullScanning or IncrementalScanning
• MetaQueryMode: semantic

---

Test Case 4: Execute Semantic Search

Corresponds to: SKILL.md Task 3

Prerequisites:

• Index state is Running
• Files have been indexed

Expected Results:

• Matching file list returned
• Each file contains AI metadata (description, summary)

---

Test Case 5: AI Content Awareness Result Verification

Prerequisites: Test Case 4 completed

Expected Results:

• oss_ai_meta.description: Approximately 100 characters describing the file content
• oss_ai_meta.summary: No more than 20 characters, concise summary

---

Test Case 6: Close Data Index

Corresponds to: SKILL.md Resource Cleanup

Prerequisites: Vector search enabled

Expected Results:

• Successful status code returned
• Index status changes to Deleted

---

Common Errors and Troubleshooting

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Table of Contents

• Installation
• macOS
• Linux
• Windows
• Configuration
• Quick Start
• Configuration Modes
• Environment Variables
• Managing Multiple Profiles
• Credential Priority
• Verification
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Next Steps
• References

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli
# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz
# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz
# Move to PATH
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"
# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli
# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)
# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts. Where to Get Access Keys 1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached. Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou
aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA
export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins): 1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions
# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "China East 1 (Hangzhou)"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get
# Test with debug logging
aliyun ecs describe-regions --log-level=debug
# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

• Don't: Use Aliyun root account credentials
• Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore
# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun
# Check PATH
echo $PATH
# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get
# Test with debug
aliyun ecs describe-regions --log-level=debug
# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM
# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired
# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region
# Check available regions
aliyun ecs describe-regions
# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30
# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration: 1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds
   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

MetaQuery Query Condition Reference

This document provides query condition formats and examples for MetaQuery scalar and semantic queries.

For script command formats, refer to the Python SDK Scripts section in related-apis.md. For the complete workflow and environment setup, refer to SKILL.md.

---

Scalar Query Conditions

This condition performs an exact match query by filename:

{
  "SubQueries":[
    {
      "Field":"Filename",
      "Value":"video_1.mov",
      "Operation":"eq"
    }
  ],
  "Operation":"and"
}

Condition Description:

• Field: "Filename" - Specifies the query field as filename
• Value: "video_1.mov" - The specific filename to search for, can be replaced with any filename
• Operation: "eq" - Equals operator, for exact matching

query_time - Time-Based Query Configuration

This configuration queries based on file creation time and modification time:

{
  "SubQueries":[
    {
      "Field":"OSSTagging.CreateTime",
      "Value":"1672588800000000000",
      "Operation":"eq"
    },{
      "Field":"FileModifiedTime",
      "Value":"2025-11-21T14:50:13.011643661+08:00",
      "Operation":"eq"
    }
  ],
  "Operation":"and"
}

Configuration Description:

• First sub-query - Creation time:
• Field: "OSSTagging.CreateTime" - File creation time tag. The CreateTime tag can be optionally attached when uploading files via upload.py.
• Value: "1672588800000000000" - Nanosecond timestamp corresponding to the CreateTime tag added during upload
• Operation: "eq" - Exact match for this creation time
• Second sub-query - Modification time:
• Field: "FileModifiedTime" - File modification time
• Value: "2025-11-21T14:50:13.011643661+08:00" - Time in RFC3339Nano format
• Operation: "eq" - Exact match for this modification time
• Operation: "and" - Both conditions must be satisfied simultaneously
• Use case: Filter files by time range, such as finding files uploaded or modified during a specific period
• Usage tips:
• Creation time uses nanosecond timestamp format
• Modification time must use RFC3339Nano format, or alternatively, you can use OSS Tags to carry the modification time during upload and search using the OSSTagging.{TagName} format
• Either time condition can be used independently or in combination
• Supports other operators like "gt" (greater than), "lt" (less than), etc. for range queries

Fields supported by scalar index: For more supported fields and operators, refer to the official documentation: Fields and Operators Supported by Scalar Index

Semantic Query Conditions

Pure Vector Semantic Query Configuration

This configuration is used for intelligent search based on content semantics:

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

Configuration Description:

• MediaTypes: <MediaType>video</MediaType> - Restricts search to video-type media files
• Available values: video, image, audio, document
• Query: person - Semantic search keyword. The system analyzes video content to find videos containing "person"
• Can be descriptive terms for objects, scenes, actions, etc.

query_body_with_basic - Combined Vector + Scalar Query Configuration

This configuration combines semantic search with attribute filtering for composite queries:

<MetaQuery>
<MediaTypes><MediaType>video</MediaType></MediaTypes>
<Query>person</Query>
<SimpleQuery>{
  "SubQueries":[
    {
      "Field":"Size",
      "Value":"30",
      "Operation":"gt"
    },
    {
      "Field":"OSSTagging.CreateTime",
      "Value":"1763722586691406000",
      "Operation":"eq"
    }
  ],
  "Operation":"and"
}</SimpleQuery>
</MetaQuery>

Configuration Description:

• MediaTypes: Restricted to video type (same as pure vector query)
• Query: person - Semantic search keyword (same as pure vector query)
• SimpleQuery: Adds scalar query conditions for further filtering
• First condition - File size:
• Field: "Size" - File size (bytes)
• Value: "30" - 30 bytes
• Operation: "gt" - Greater than operator, filters files larger than 30 bytes
• Second condition - Creation time:
• Field: "OSSTagging.CreateTime" - Creation time tag. The CreateTime tag can be optionally attached when uploading files via upload.py.
• Value: "1763722586691406000" - Specific nanosecond timestamp
• Operation: "eq" - Exact match for this creation time
• Operation: "and" - All conditions must be satisfied simultaneously
• Use case: Precise queries that need to satisfy both content semantics and file attribute conditions
• Usage tips:
• Scalar query conditions can include file size, creation time, modification time, etc.
• Operators can be adjusted based on actual needs (eq, gt, lt, gte, lte, etc.)
• Suitable for scenarios requiring precise control over search results

Fields supported by vector index: For more supported fields and operators, refer to the official documentation: Fields and Operators Supported by Vector Index

---

Query Result Response Fields: Query results contain rich field information. For detailed descriptions, refer to the official documentation: DoMetaQuery Response Field Descriptions

ossutil Installation Guide

Overview

ossutil is a command-line tool for managing Alibaba Cloud OSS resources. This guide provides installation instructions for ossutil v2.2.1.

Download Links

Current latest version: 2.2.1

Linux

macOS

Windows

Installation Steps

Linux/macOS

# 1. Download (example for Linux x86_64)
wget https://gosspublic.alicdn.com/ossutil/v2/2.2.1/ossutil-2.2.1-linux-amd64.zip

# 2. Extract
unzip ossutil-2.2.1-linux-amd64.zip

# 3. Move to PATH directory
chmod +x ossutil
sudo mv ossutil /usr/local/bin/

# 4. Verify installation
ossutil version

Windows

1. Download the appropriate version from the links above 2. Extract the zip archive 3. Add the extracted directory to your system PATH 4. Or copy the ossutil.exe file to a directory that's already in your PATH 5. Verify installation by running ossutil version in Command Prompt

Configuration

After installation, ossutil automatically obtains authentication information through the default credential chain without manual AK/SK configuration. The default credential chain looks for credentials in the following order:

1. Environment variables (ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET) 2. Credentials in configuration file (set via aliyun configure) 3. ECS instance RAM role (automatically obtained in ECS environments)

It is recommended to use instance RAM roles in cloud environments such as ECS, and use environment variables or aliyun configure for local development environments.

Configure endpoint information:

ossutil config --endpoint oss-cn-hangzhou.aliyuncs.com

RAM Permission Policies

Required Permissions

The following RAM permissions are required for each feature of this project:

Bucket Basic Operations

• oss:GetBucketInfo -- Query Bucket basic information (region, storage class, etc.)
• oss:ListObjects -- List files in the Bucket (V1)
• oss:ListObjectsV2 -- List files in the Bucket (V2)

File Upload and Download

• oss:GetObject -- Download (read) file content
• oss:PutObject -- Upload (write) files to the Bucket
• oss:DeleteObject -- Delete files from the Bucket

Data Index and Semantic Search

• oss:OpenMetaQuery -- Enable metadata management (includes AI content awareness configuration)
• oss:DoMetaQuery -- Execute metadata queries (scalar search / vector semantic search)
• oss:GetMetaQueryStatus -- Query data index status
• oss:CloseMetaQuery -- Close data index

Minimum Permission Policy

The following is the minimum RAM permission policy JSON required for OSS vector search and AI content awareness features:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetBucketInfo",
        "oss:ListObjects",
        "oss:ListObjectsV2",
        "oss:GetObject",
        "oss:PutObject",
        "oss:OpenMetaQuery",
        "oss:DoMetaQuery",
        "oss:GetMetaQueryStatus",
        "oss:CloseMetaQuery"
      ],
      "Resource": [
        "acs:oss:*:*:your-bucket-name",
        "acs:oss:*:*:your-bucket-name/*"
      ]
    }
  ]
}

Read-Only Query Permissions

If the application only needs to perform semantic searches, the following minimum read-only permissions can be used:

• oss:DoMetaQuery -- Execute metadata queries
• oss:GetMetaQueryStatus -- Query data index status
• oss:GetObject -- Download retrieved files

Corresponding policy JSON:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:DoMetaQuery",
        "oss:GetMetaQueryStatus"
      ],
      "Resource": "acs:oss:*:*:your-bucket-name"
    },
    {
      "Effect": "Allow",
      "Action": "oss:GetObject",
      "Resource": "acs:oss:*:*:your-bucket-name/*"
    }
  ]
}

Service Role Authorization

When using the data index feature for the first time, you need to authorize the OSS service role AliyunMetaQueryDefaultRole:

1. The OSS Console will automatically prompt for authorization when enabling data index 2. This role allows the OSS service to manage data indexes in the Bucket

Service Role Permission Scope:

• Read file content in the Bucket for AI analysis
• Build and manage vector indexes
• Process incremental file updates

Important Notes

1. Resource Scope: It is recommended to replace your-bucket-name with the specific Bucket name to avoid over-authorization 2. Region Restrictions: OSS resources are region-level; you can specify region restrictions in the Resource field 3. Regular Audits: Regularly review and clean up permissions that are no longer needed 4. Use STS: For temporary access scenarios, it is recommended to use STS temporary credentials instead of long-term AccessKeys

Reference Links

• OSS Access Control Overview
• RAM Policy Syntax

Related APIs and CLI Commands

Table of Contents

• ossutil Commands
• SDK API
• API Details
• OpenMetaQuery (Enable Metadata Management)
• GetMetaQueryStatus (Get Index Status)
• DoMetaQuery (Execute Query)
• CloseMetaQuery (Close Index)
• SDK Version Requirements
• Reference Links

---

ossutil Commands

do-meta-query Query Conditions

The --meta-query parameter of do-meta-query requires an XML-formatted query condition file.

For detailed format, field descriptions, and complete examples (including semantic and scalar queries), see metaquery.md.

Python SDK Scripts (Alternative to aliyun ossutil)

When aliyun ossutil is unavailable, you can use the following Python scripts as alternatives. For the complete usage workflow, refer to the "Core Workflows" section in SKILL.md.

API Details

OpenMetaQuery (Enable Metadata Management)

Request Parameters:

WorkflowParameters - AI Content Awareness Configuration:

Filters - File Filtering Rules:

Note: Filename and OSSTagging values must be URL-safe Base64 encoded

---

GetMetaQueryStatus (Get Index Status)

Request Parameters:

Response Fields:

State Values:

Phase (Scan Phase):

---

DoMetaQuery (Execute Query)

Vector Search Mode (mode=semantic)

Request Parameters:

Supported MediaType Values:

SimpleQuery Examples:

// File size greater than 30 bytes
{"Operation": "gt", "Field": "Size", "Value": "30"}

// Combined conditions
{
  "Operation": "and",
  "SubQueries": [
    {"Operation": "gt", "Field": "Size", "Value": "1000"},
    {"Operation": "prefix", "Field": "Filename", "Value": "videos/"}
  ]
}

Scalar Search Mode (mode=basic)

Request Parameters:

Query Operators:

Aggregation Operations:

Response Fields:

---

CloseMetaQuery (Close Index)

Request Parameters:

---

Opening MetaQuery via Python Script

Opening MetaQuery must use the Python script. For detailed usage, WorkflowParameters XML configuration, and the enablement process, refer to "Rule 1" and "Task 2: Enable Vector Search & AI Content Awareness" sections in SKILL.md.

SDK Version Requirements

Reference Links

• OpenMetaQuery API Documentation
• GetMetaQueryStatus API Documentation
• DoMetaQuery API Documentation
• OSS Vector Search User Guide
• OSS Java SDK Vector Search
• OSS Python SDK Vector Search
• OSS Go SDK Vector Search
• ossutil Command-Line Tool

Verification Methods

Table of Contents

• 1. Verify Bucket Creation
• 2. Verify File Upload
• 3. Verify Data Index Status
• 4. Verify Semantic Search Functionality
• 5. Verify AI Content Awareness Results
• 6. Complete Verification Flow
• Common Issue Troubleshooting

---

1. Verify Bucket Creation

CLI Verification

# Check if Bucket exists
aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

# View detailed Bucket information
aliyun ossutil api get-bucket-stat --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

Success Indicators:

• Command returns Bucket information without errors
• Displays Bucket creation time, region, storage class, and other information

---

2. Verify File Upload

CLI Verification

# List files in the Bucket
aliyun ossutil ls oss://<bucket-name>/<prefix>/ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

# View individual file information
aliyun ossutil api head-object --bucket <bucket-name> --key <object-key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

Success Indicators:

• File list contains the uploaded files
• File size and last modification time are correct

---

3. Verify Data Index Status

CLI Verification

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

Success Indicators:

• Command returns JSON result without errors
• State is Running
• Phase is FullScanning (full scan in progress) or IncrementalScanning (incremental scan, searchable)
• MetaQueryMode is semantic

---

4. Verify Semantic Search Functionality

CLI Verification

1. Create query condition file `meta-query.xml`:

<MetaQuery>
<MediaTypes>
<MediaType>video</MediaType>
<MediaType>image</MediaType>
</MediaTypes>
<Query>a yard with parked cars</Query>
</MetaQuery>

2. Execute semantic search:

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

Success Indicators:

• Command returns XML result without errors
• Result contains a <Files> list
• File entries contain <OSSAIMeta> fields (with description and summary)

---

5. Verify AI Content Awareness Results

Check Returned AI Metadata

In the semantic search results (XML) from Step 4, check whether each file entry contains the <OSSAIMeta> field:

<File>
  <Filename>test_medias/example.jpg</Filename>
  ...
  <OSSAIMeta>
    <Description>A yard with several parked cars, surrounded by walls and green plants...</Description>
    <Summary>Yard with cars</Summary>
  </OSSAIMeta>
</File>

Success Indicators:

• Returned files contain the <OSSAIMeta> field
• <Description> content is approximately 100 characters describing the file content
• <Summary> content is no more than 20 characters, a concise summary

---

6. Complete Verification Flow

Execute the following CLI commands in order for end-to-end verification:

# [1/4] Verify Bucket exists
aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

# [2/4] Verify files are uploaded
aliyun ossutil ls oss://<bucket-name>/<prefix>/ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

# [3/4] Verify data index status (confirm State=Running, MetaQueryMode=semantic)
aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

# [4/4] Execute semantic search (create meta-query.xml first, refer to Step 4)
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

Verification Pass Criteria: 1. Bucket information returns successfully 2. File list contains uploaded files 3. Index status State is Running, Phase is IncrementalScanning 4. Semantic search results contain <OSSAIMeta> (with Description and Summary)

---

Common Issue Troubleshooting