Alibabacloud Pds Multimodal Search

PDS Multimodal Search

Please read this entire skill document carefully

Features

• For getting drive/drive_id, querying enterprise space, team space, personal space -> read references/drive.md
• For uploading local files to enterprise space, team space, personal space → read references/upload-file.md
• For downloading files from enterprise space, team space, personal space to local → read references/download-file.md
• For searching or finding files → read references/search-file.md
• For document/audio/video analysis, quick view, summarization on cloud drive → read references/multianalysis-file.md
• For image search, similar image search, image-text hybrid retrieval → read references/visual-similar-search.md

Agent Execution Guidelines

• Must execute steps in order: Do not skip any step, do not proceed to the next step before the previous one is completed.
• Must follow documentation: The aliyun pds cli commands and parameters must follow this document's guidance, do not fabricate commands.
• [MUST] CLI User-Agent — Every aliyun CLI command invocation must include:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

• Must determine the target space before file operations: Before search, upload, download, or analysis, first decide whether the user explicitly means enterprise space, team space, personal space, or all spaces.
• Space scope must not be broadened silently: If the user explicitly says "enterprise space", only use the enterprise space drive_id. If the user explicitly says "team space", only use the matching team space drive_id. If the user explicitly says "personal space", only use the personal space drive_id. Only search across multiple spaces when the user did not restrict the scope.
• Enterprise space and team space are not interchangeable: Even though both are returned by list-my-group-drive, root_group_drive is the enterprise space and items are team spaces. Never substitute one for the other.
• If the requested space is missing, stop and explain: For example, if the user asks for enterprise space but root_group_drive is empty, do not fall back to a team space search.

Core Concepts:

• Domain: PDS instance with a unique domain_id, data is completely isolated between domains
• User: End user under a domain, has user_id
• Group: Team organization under a domain, divided into enterprise group and team group
• Drive: Storage space, can belong to a user (personal space) or group (enterprise space or team space)
• File: File or folder under a space, has file_id
• Mountapp: PDS mount app plugin, used to mount PDS space to local, allowing users to access and manage files in PDS space conveniently

Space Selection Rules

Apply the following rules before choosing a drive_id:

Before continuing, perform a brief self-check: 1. Did the user explicitly name the target space type? 2. Does the selected drive_id come from the correct response field for that space type? 3. If multiple team spaces exist and the user only said "team space", do I need to disambiguate which team space?

If any answer is uncertain, do not guess.

---

Installation Requirements

Prerequisites: Requires Aliyun CLI >= 3.3.3

>

Verify CLI version:

```bash

aliyun version # requires >= 3.3.3

```

>

If not installed or version too low,

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

or see references/cli-installation-guide.md for installation instructions.

>

Verify PDS plugin version:

```bash

aliyun pds version # requires >= 0.1.4

```

>

After installation, must enable auto plugin installation:

```bash

aliyun configure set --auto-plugin-install true

```

>

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

---

CLI Initialization (MUST run before Core Workflow)

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-pds-multimodal-search"

[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

---

Authentication Configuration

Prerequisites: Alibaba Cloud credentials must be configured

>

Security Rules:

- Forbidden to read, output, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is forbidden)

- Forbidden to ask users to input AK/SK directly in conversation or command line

- Forbidden to use aliyun configure set to set plaintext credentials

- Only allowed to use aliyun configure list to check credential status

>

Check credential configuration:

```bash

aliyun configure list

```

>

Confirm the output shows a valid profile (AK, STS, or OAuth identity).

>

If no valid configuration exists, stop first.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside this session (run aliyun configure in terminal or set environment variables)

3. Run aliyun configure list to verify after configuration is complete

# Install Aliyun CLI (if not installed)
curl -fsSL --max-time 10 https://aliyuncli.alicdn.com/install.sh | bash
aliyun version  # confirm >= 3.3.3

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Install Python dependencies (for multipart upload script)
pip3 install requests

PDS-Specific Configuration

Before executing any PDS operations, you must first configure domain_id, user_id, and authentication type -> read references/config.md

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

>

Examples:

```bash

aliyun pds get-user --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

aliyun pds list-my-drives --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

aliyun pds upload-file --drive-id <id> --local-path <path> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

```

References

Error Handling

1. If file search fails, please read references/search-file.md and strictly follow the documented process to re-execute file search.

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

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 --timeout=600 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 --timeout=600 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 --timeout=600 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 --timeout=600 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": "华东 1（杭州）"
      },
      ...
    ]
  },
  "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

PDS Aliyun CLI Configuration Guide (Important)

Scenario: Required configuration when using aliyun pds cli for the first time Purpose: Configure domain_id, user_id, and authentication type for aliyun pds cli

---

Before executing any PDS operations, you must first configure domain_id, user_id, and authentication type:

Step 1: Verify if configuration already exists (only needs to be configured once during initialization)

aliyun pds get-user --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

If already configured successfully, it will return the current logged-in user information, and you can skip the subsequent steps.

Step 2: Query domain list using aliyun pds list-domains (skip this step if you already have the domain_id to configure)

aliyun pds list-domains --service-code edm --limit 100 --region cn-beijing --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

The returned JSON structure is as follows. Extract the domain list from the response and display it to the user in a table format with columns domain_id and domain_name, prompting the user to select one domain. (If there is only one domain, use it directly without asking)

{
	"items": [{
      "domain_id": "bj322",
      "domain_name": "beijing-31216",
      "region_id": "cn-beijing",
      "service_code": "edm"
    }],
	"next_marker": ""
}

This step requires obtaining the selected domain_id before proceeding to the next step.

Step 3: Query user list under the domain using aliyun pds list-user (skip this step if you already have the user_id to configure)

# First configure domain_id with ak authentication type
aliyun pds config --domain-id <domain_id> --authentication-type ak --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search
# Then list users under this domain
aliyun pds list-user --limit 100 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

The returned JSON structure is as follows. Extract the user list from the response and display it to the user in a table format with columns user_id, nick_name, phone, email, and role, prompting the user to select one user. (If there is only one user, use it directly without asking)

{
	"items": [
		{
			"nick_name": "SuperAdmin",
			"role": "superadmin",
			"status": "enabled",
			"updated_at": 1774159173066,
			"phone": "123",
            "email": "test@example.com",
			"user_id": "a34527bd247e48b6b7e48d5c381b23f3"
		}
	],
	"next_marker": ""
}

This step requires obtaining the selected user_id before proceeding to the next step.

Step 4: Configure domain_id, user_id, and authentication type to aliyun pds cli using aliyun pds config

aliyun pds config \
  --domain-id <domain_id> \
  --user-id <user_id> \
  --authentication-type token \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Parameter Description:

• --domain-id: PDS domain ID (e.g., bj31216), provided by PDS user, check if included in the prompt
• --user-id: PDS user ID (e.g., a34527bd247e48b6b7e48d5c381b23f3), provided by PDS user, check if included in the prompt
• --authentication-type: Must be set to `token` if user_id parameter is provided, indicating access with user identity

Effect After Configuration:

• No need to pass --domain-id parameter for subsequent PDS API calls
• CLI will automatically use the configured domain_id and user_id

Verify Configuration:

# Test if configuration is effective, get-user API without parameters returns current logged-in user information in token scenario
aliyun pds get-user --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Extract the current logged-in user information from the returned JSON: domain_id: domain_id, user_id: user_id, nick_name: nick_name.

After successful configuration, notify the user: Current PDS DomainID: <domain_id>, logged-in user: <nick_name>(<user_id>)

Notes:

• Domain_id and user_id will be preset in CLI configuration
• User's token will be preset in Aliyun CLI configuration file
• After configuring once, no need to repeat configuration for subsequent operations

---

PDS File Download Guide

Scenario: When you have obtained the drive_id and file_id of the file to download and need to download that file Purpose: Download file to local

---

Get File ID from File Path

If you want to download a file from a PDS drive but only have the file path (e.g., /Photos/2026/04/vacation.jpg), you need to traverse each level of the path to find the corresponding file's file_id. The steps are as follows: For example, to download the file /Photos/2026/04/vacation.jpg from a personal space:

1. First, use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id root --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search command to list all directories under the root directory (parent-file-id=root) and find the file_id of the Photos directory: a. If the Photos directory exists, note down its file_id b. If the Photos directory does not exist, the file path is invalid 2. Use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id <parent_file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search command to list all directories under the parent directory (parent-file-id=<Photos directory's file_id>) and find the file_id of the 2026 directory: a. If the 2026 directory exists, note down its file_id b. If the 2026 directory does not exist, the file path is invalid 3. Use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id <2026 directory's file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search command to list all directories under the parent directory (parent-file-id=<2026 directory's file_id>) and find the file_id of the 04 directory: a. If the 04 directory exists, note down its file_id b. If the 04 directory does not exist, the file path is invalid 4. Use the aliyun pds list-file --drive-id <drive_id> --type file --parent-file-id <04 directory's file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search command to list all files under the parent directory (parent-file-id=<04 directory's file_id>) and find the file_id of the vacation.jpg file: a. If the vacation.jpg file exists, note down its file_id b. If the vacation.jpg file does not exist, the file path is invalid 5. After obtaining the file_id of vacation.jpg, you can use this file_id to download the file

Note: When executing the aliyun pds list-file command, if there are no valid items returned and the next_marker is not empty, it means that the query is not complete and the next_marker needs to be used as the --marker parameter for the next list query until next_marker is empty.

---

Download File

Step 1: Get Download URL

Get the download link for the file:

aliyun pds get-download-url \
  --drive-id <drive_id> \
  --file-id <file_id> \
  --expire-sec 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Parameter Description:

• --drive-id: The drive_id of the space where the file is located (obtained from search results)
• --file-id: The file_id of the file to download (obtained from search results)
• --expire-sec: Download link validity period (seconds), default 900, maximum 115200 (32 hours)

Output: Returns a JSON object containing url (download link), expiration, method, size, and other information.

Example Output:

{
  "url": "https://pds-data.aliyuncs.com/...",
  "expiration": "2024-01-15T11:30:00Z",
  "method": "GET",
  "size": 1048576
}

---

Step 2: Download File

Use the obtained download URL to download the file:

curl -L --max-time 3600 --max-redirs 10 -o <output_filename> '<download_URL>'

Parameter Description:

• -L: Follow redirects automatically (when download_URL returns a redirect URL, curl will continue downloading from the new location)
• --max-redirs 10: Maximum number of redirects to follow (prevents infinite redirect loops)
• --max-time 3600: Maximum time for the entire download operation (seconds)

Note: The -L parameter is critical because PDS download URLs often return a redirect to the actual OSS storage URL. Without this parameter, curl will fail with a 3xx redirect response.

Or use wget:

wget --timeout=3600 --max-redirect=10 -O <output_filename> '<download_URL>'

Parameter Description:

• --max-redirect=10: Maximum number of redirects to follow
• --timeout=3600: Timeout for the download operation (seconds)

---

Step 3: Verify Local File Exists

PDS Drive Concepts and API Reference

Scenario: Used when querying user's drive list (including personal space, enterprise space, team space, all spaces) Purpose: Get drive_id for user's personal space, team space, and enterprise space

---

Drive Concept Introduction

A PDS drive is a cloud storage space that can store files. A drive must have an owner, which can be either a user or a group.

• When a drive belongs to a user, it is that user's personal space.
• When a drive belongs to an enterprise group, it is an enterprise space.
• When a drive belongs to a team group, it is a team space.

Users have three types of spaces in a domain:

• Enterprise space
• Team space
• Personal space

When referring to "my PDS drive" without specifying which type of space, it should be understood as all spaces: including enterprise space, team space, and personal space

Mandatory Space Mapping Rules

This section is critical when the user explicitly specifies a space type.

• root_group_drive represents the enterprise space. There is at most one.
• items returned by list-my-group-drive represent team spaces only. There may be multiple.
• list-my-drives.items represent personal spaces.
• Enterprise space and team space are both group-owned drives, but they are different scopes and must never be mixed.
• If the user says "enterprise space", you must read drive_id from root_group_drive only.
• If the user says "team space", you must read drive_id from items only.
• If the user says "personal space", you must read drive_id from list-my-drives.items only.
• If the user does not specify any space, then and only then can you consider all spaces together.
• If the requested space does not exist in the corresponding field, stop and report that the requested space is unavailable. Do not silently switch to another space type.
• If the user asks for "team space" and multiple team spaces exist, do not arbitrarily choose one unless the request already identifies which team space to use.

Quick Decision Table

Drive Query API Reference

Query Method for Enterprise Space and Team Space

You can query using the list group drives API. The items field in the response contains the user's team space list, and the root_group_drive field contains the enterprise space object.

aliyun pds list-my-group-drive --limit 100 --marker "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Output: Returns JSON containing enterprise space and team space, including items, root_group_drive, next_marker, etc. Detailed explanation:

• items: Contains team space list. There may be multiple team spaces. If not all displayed on one page, next_marker will be returned. If there are no team spaces, this field returns empty.
• root_group_drive: Contains enterprise space object. There is at most one enterprise space. If none exists, this field returns empty.
• next_marker: Used for pagination, indicates the marker for next page. Pass the returned next_marker to the marker parameter to query the next page. If no next page, this field returns empty.

The JSON objects returned in items and root_group_drive are Drive objects. Important attributes of Drive objects include:

• drive_id: Unique space ID, commonly used in API parameters to identify a drive (important parameter for identifying a space, other APIs may require this field as input)
• drive_name: Space name, commonly used for display
• total_size: Total space size in bytes
• used_size: Used space size in bytes
• owner_type: Owner type, either user or group
• owner: Owner ID

Example Output:

{
  "items": [
    {
      "category": "",
      "created_at": "2026-03-22T06:00:12.951Z",
      "creator": "a34527b***c381b23f3",
      "description": "",
      "domain_id": "bj12",
      "drive_id": "100",
      "drive_name": "Test Team Space 1",
      "drive_type": "normal",
      "encrypt_data_access": false,
      "encrypt_mode": "none",
      "owner": "e71ce9***c5862d5",
      "owner_type": "group",
      "permission": null,
      "relative_path": "",
      "status": "enabled",
      "store_id": "fb651***943990a",
      "total_size": 107374182400,
      "updated_at": "2026-03-22T06:00:12.952Z",
      "used_size": 138194
    },
    {
      "category": "",
      "created_at": "2026-03-22T06:00:12.951Z",
      "creator": "a34527***81b23f3",
      "description": "",
      "domain_id": "bj12",
      "drive_id": "101",
      "drive_name": "Test Team Space 2",
      "drive_type": "normal",
      "encrypt_data_access": false,
      "encrypt_mode": "none",
      "owner": "e71ce9***b7fc5862d5",
      "owner_type": "group",
      "permission": null,
      "relative_path": "",
      "status": "enabled",
      "store_id": "fb6516****45c943990a",
      "total_size": 107374182400,
      "updated_at": "2026-03-22T06:00:12.952Z",
      "used_size": 138194
    }
  ],
  "next_marker": "",
  "root_group_drive": {
    "category": "",
    "created_at": "2026-03-22T05:55:03.280Z",
    "creator": "system",
    "description": "",
    "domain_id": "bj12",
    "drive_id": "103",
    "drive_name": "Test Space",
    "drive_type": "normal",
    "encrypt_data_access": false,
    "encrypt_mode": "none",
    "owner": "9c251e****b9f952f",
    "owner_type": "group",
    "permission": null,
    "relative_path": "",
    "status": "enabled",
    "store_id": "fb651****43990a",
    "total_size": 107374182400,
    "updated_at": "2026-03-23T07:08:40.098Z",
    "used_size": 240062520
  }
}

In the above example output, team space drive_ids are: 100 and 101, enterprise space drive_id is: 103

Important interpretation rule for the example above:

• If the user asked for enterprise space, only 103 is eligible.
• If the user asked for team space, only 100 or 101 are eligible.
• It is incorrect to use 100 or 101 as enterprise space, and incorrect to use 103 as a team space.

Query API for Personal Space

You can query using the list my drives API. The items field in the response contains the user's personal space list.

aliyun pds list-my-drives --limit 100 --marker "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

The JSON array in the items field returned by the personal space query API contains personal space Drive objects. Important attributes of Drive objects include:

• drive_id: Unique space ID, commonly used in API parameters to identify a drive (important parameter for identifying a space, other APIs may require this field as input)
• drive_name: Space name, commonly used for display
• total_size: Total space size in bytes
• used_size: Used space size in bytes
• owner_type: Owner type, either user or group
• owner: Owner ID

{
    "items": [
        {
            "category": "",
            "created_at": "2026-03-22T05:59:33.037Z",
            "creator": "a34527b***81b23f3",
            "description": "",
            "domain_id": "bj31216",
            "drive_id": "108",
            "drive_name": "SuperAdmin (Test)",
            "drive_type": "normal",
            "encrypt_data_access": false,
            "encrypt_mode": "none",
            "owner": "a34527b***81b23f3",
            "owner_type": "user",
            "permission": null,
            "relative_path": "",
            "status": "enabled",
            "store_id": "fb6516***c943990a",
            "total_size": 107374182400,
            "updated_at": "2026-03-23T08:45:35.541Z",
            "used_size": 950709133
        }
    ],
    "next_marker": ""
}

In the above example output, personal space drive_id is 108

PDS Document and Audio/Video Analysis

Scenario: When you have obtained the drive_id, file_id, and revision_id of the file to analyze and need to perform analysis on that file Purpose: Perform analysis on files and get structured analysis results ---

Core Workflow

Flow 1: Submit Analysis Task and Poll for Results

Use Python script to automatically submit analysis task and poll until processing is complete.

# Document analysis polling
python scripts/pds_poll_processor.py \
  --drive-id "1" \
  --file-id "66e7e860a2360204b9414d5c866dd3a20af1974e" \
  --revision-id "123" \
  --x-pds-process "doc/analysis" \
  -o doc_result.json

# Audio/Video analysis polling
python scripts/pds_poll_processor.py \
  --drive-id "1" \
  --file-id "66e7e860a2360204b9414d5c866dd3a20af1974e" \
  --revision-id "123" \
  --x-pds-process "video/analysis" \
  -o video_result.json

Parameter Description:

• --drive-id: The space drive_id where the analysis file is located
• --file-id: The file_id of the file to analyze
• --revision-id: The revision_id of the file to analyze
• --x-pds-process: Processing type, doc/analysis (document) or video/analysis (audio/video). Since analysis is a synchronous API, x-pds-process must be used, not x-pds-async-process
• -o: Save raw JSON result to file (contains signed URLs)

Document Analysis Result Structure

{
  "summary": ["https://bucket/summary.json?sign=xxx"],
  "chapter_summaries": ["https://bucket/chapter_summaries.json?sign=xxx"],
  "keywords": ["https://bucket/keywords.json?sign=xxx"],
  "guiding_questions": ["https://bucket/guiding_questions.json?sign=xxx"],
  "method_description": ["https://bucket/method_description.json?sign=xxx"],
  "experiment_description": ["https://bucket/experiment_description.json?sign=xxx"],
  "conclusion_description": ["https://bucket/conclusion_description.json?sign=xxx"],
  "images": {
    "imgs/page_0_img_image_box_770_540_1367_860.png": {
      "Url": "https://bucket/imgs/page_0_img.png?sign=xxx",
      "Thumbnail": "https://bucket/imgs/page_0_img_thumbnail.png?sign=xxx"
    }
  }
}

Audio/Video Analysis Result Structure

{
  "markdown": "https://bucket/markdown.md?sign=xxx",
  "summary": ["https://bucket/summary.json?sign=xxx"],
  "chapter_summaries": ["https://bucket/chapter_summary.json?sign=xxx"],
  "keywords": ["https://bucket/keywords.json?sign=xxx"],
  "questions": ["https://bucket/questions.json?sign=xxx"],
  "transcript": ["https://bucket/transcript.json?sign=xxx"],
  "transcript_summaries": ["https://bucket/transcript_summary.json?sign=xxx"],
  "transcript_chapter_summaries": ["https://bucket/transcript_chapter_summary.json?sign=xxx"],
  "ppt_details": ["https://bucket/ppt_details.json?sign=xxx"],
  "images": {
    "ppts/video_snapshots_0.jpg": {
      "Url": "https://bucket/ppts/video_snapshots_0.jpg?sign=xxx",
      "Thumbnail": "https://bucket/ppts/video_snapshots_0_thumbnail.jpg?sign=xxx"
    }
  }
}

Flow 2: Use Formatter to Get Formatted Results

Analysis results contain multiple signed URLs pointing to different types of analysis files. Use formatting scripts to parse these files and generate readable output.

# Format document results
python scripts/doc_analysis_formatter.py doc_result.json -o formatted_output.txt

# Format audio/video results
python scripts/video_analysis_formatter.py video_result.json -o formatted_output.txt

Parameter Description:

• input_file: JSON result file path from analysis API (output from Flow 1)
• -o: Formatted output file path (optional, outputs to console if not specified)

Formatted Output Example

The formatting script automatically downloads all files pointed to by signed URLs and generates readable output according to preset templates:

````

================================================== 📄 【Full Summary】 ==================================================

{Summary text content}

🖼️ Image: {ImagePath} (Page {PageNumber})

================================================== 🏷️ 【Keywords】 ================================================== #{Keyword 1} | #{Keyword 2} | #{Keyword 3} | ...

================================================== 📚 【Chapter Summaries】 ==================================================

▶️ {Chapter Title} ---------------------------------------- {Chapter Content}

🖼️ Image: {ImagePath}

▶️ {Next Chapter Title} ---------------------------------------- ...

================================================== ❓ 【Guiding Questions】 ==================================================

Q1: {Question 1} A1: {Answer 1}

Q2: {Question 2} A2: {Answer 2} ````

Audio/video will also include dialogue transcripts and PPT extraction information.

---

Flow 3: Extract PPT from Video

If the analyzed video contains PPT, you can extract PPT from the results and generate a PPTX file.

Prerequisites

1. Video contains PPT content 2. Analysis results contain ppt_details field 3. Install Python PPT processing library

pip install python-pptx requests

Usage

Extract PPT from video analysis results and generate PPTX file:

python scripts/ppt_extraction.py video_result.json -o extracted_ppt.pptx

Parameter Description:

• input_file: JSON result file path from video analysis API
• -o: Output PPTX file path (default: extracted_ppt.pptx)
• --keep-aspect-ratio: Maintain image aspect ratio (default fills entire slide)
• --validate: Validate PPTX file after generation

Checklist

• [ ] PPTX file can be opened with PowerPoint/WPS/LibreOffice
• [ ] Slide count matches page count in ppt_details
• [ ] Each page image is clear, no stretching or distortion
• [ ] Page order matches appearance order in video
• [ ] (Optional) Notes contain timestamp information

Auto Validation

python scripts/ppt_extraction.py video_result.json --validate

Common Issues

1. Feature Not Enabled

{
  "code": "OperationNotSupport",
  "message": "This operation is not supported."
}

Solution: Contact PDS technical support to enable analysis feature.

2. Signed URL Expired

Cause: Download took too long, signed URL has expired.

Solution: Re-request analysis results, or download all images immediately after getting results.

RAM Permission Requirements

RAM Policy

If minimum required permissions principle is needed:

metadata:
  required_permissions:
    - "pds:ListDomains" — List domains: list-domains
    - "pds:ListUser" — List users: list-user
    - "pds:GetDomain" — Get domain info: get-domain
    - "pds:ListFile" — List or search files: list-file
    - "pds:GetUser" — Get user info: get-user
    - "pds:DownloadFile" — Download file: download-file
    - "pds:AssumeUser" — Access via user identity token: user upload (upload-file) / download (get-download-url) / process file (file-process) / get user personal space list (list-my-drive) / get user team/enterprise space list (list-my-group-drive) / user mount (mountapp)

API and Permission Reference Table (authentication_type: token, non-RAM authentication)

AssumeUser operation uses user identity access. In token scenario, except for domain management APIs and list user API, all other APIs operate after obtaining user token via AssumeUser, so the Required Permission for these operations is AssumeRole.

| API Action | Required Permission | Resource | |---------------------|---------------------|------------------------------------|| | list-domains | pds:ListDomains | "acs:pds:::domain/", | | get-domain | `pds:GetDomain` | "acs:pds:::domain/<domain_id>" | | list-user | `pds:ListUser` | "acs:pds:::domain/<domain_id>/" | | search-file | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | get-user | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | get-download-url | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | process | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | list-my-group-drive | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | list-my-drives | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | upload-file | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | mountapp | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" |

API and Permission Reference Table (authentication_type: ak, RAM authentication)

Using ak authentication method without user identity, only the following APIs are supported:

| API Action | Required Permission | Resource | |---------------------|---------------------|------------------------------------|| | list-domains | pds:ListDomains | "acs:pds:::domain/", | | get-domain | `pds:GetDomain` | "acs:pds:::domain/<domain_id>" | | search-file | `pds:ListFile` | "acs:pds:::domain/<domain_id>/" | | get-user | pds:GetUser | "acs:pds:::domain/<domain_id>/" | | list-user | `pds:ListUser` | "acs:pds:::domain/<domain_id>/" | | get-download-url | pds:DownloadFile | "acs:pds:::domain/<domain_id>/*" |

Notes

1. In addition to RAM permissions, PDS also requires assigning corresponding Drive space access permissions to users in the PDS Console 2. When calling with AK/SK method, ensure the RAM user has the above permissions 3. When calling with Bearer Token (OAuth) method, permissions are determined by the user role within PDS

PDS File Search

Scenario: When you already have the drive_id to search in and need to search for files under that drive Purpose: Find the target files and retrieve attributes such as file_id. Supports scalar search based on metadata such as filename, type, size, and time, as well as multimodal semantic search based on content understanding.

Core Workflow

Step 1: Semantic Query Analysis

Run the script python scripts/get_semantic_query_prompt.py, get the prompt from standard output (stdout), then use this prompt as the system prompt and the user's natural language query as user input, spawn a sub-agent to think and output JSON result, and report back to the main agent.

Step 2: Scalar Query Analysis

Run the script python scripts/get_scalar_query_prompt.py, get the prompt from standard output (stdout), then use this prompt as the system prompt and the user's natural language query as user input, spawn a sub-agent to think and output JSON result, and report back to the main agent.

Important: You need to prepend current time information UserQueryDatetime: {current time in ISO format} to the user input, because the scalar query prompt contains time-related examples that need to reference the current time.

Step 3: Build Query String

Pass the JSON outputs from Step 1 and Step 2 to scripts/build_query.py:

python scripts/build_query.py \
  --scalar-json '{JSON output from Step 2}' \
  --semantic-json '{JSON output from Step 1}'

The script will: 1. Recursively parse the Query object from scalar query into a query string 2. Convert semantic query to semantic_text = "..." format 3. Merge the modality from semantic query and the category conditions from scalar query according to the retrieval mode 4. Connect all parts with correct logical operators

Modality merge rules (important)

1. Pure scalar retrieval supports multi-modal filtering, for example images or videos. 2. Pure semantic retrieval supports only a single modality and must converge to exactly one of document, image, video, or audio. 3. Mixed retrieval must converge to the single modality selected by semantic retrieval.

• If the scalar category includes that semantic modality, use the semantic modality as the final modality.
• If the scalar category conflicts with the semantic modality, do not continue the search. Instead, tell the user to adjust the conditions and try again.

Important: If the script execution fails, it is strictly forbidden to construct query and order_by on your own understanding for the next step, as this will very easily produce syntax errors. You should go back to step one and restart the query process from the beginning.

If the output has_query is false, do not execute the search, and kindly inform the user of the message content.

If has_query is true, use the output query and order_by for the next step.

Step 4: Execute Search

Use the query and order_by output from build_query.py to call the aliyun CLI tool:

aliyun pds search-file \
  --drive-id "drive_id" \
  --query "{query from build_query output}" \
  --order-by "{order_by from build_query output}" \
  --limit 50 \
  --recursive true \
  --return-total-count true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Pagination: If the response contains next_marker, you can pass it via --marker parameter in subsequent requests to get the next page. Add --return-total-count to get the total count of matches.

Step 5: Display Search Results

Parse the JSON output returned by the CLI tool and format the search results for display. The response structure contains an items array and optional next_marker, total_count fields. If there is a next_marker, it means there are more results available for pagination.

Output error messages to stderr on failure.

Best Practices

1. Prefer semantic search: When users describe file content or scenarios, semantic search is more accurate than keyword matching

2. Combine conditions appropriately: Semantic search can be combined with scalar conditions, for example "beach photos from this year" can use both a time range and a semantic description

3. Distinguish pure scalar multi-modal filtering from mixed-query single-modality convergence:

• Pure scalar example: images or videos larger than 10 MB
• Mixed, convergent example: beach photos taken this year
• Mixed, conflicting example: find sunset photos inside video files

4. Note pagination limits: limit has a maximum value of 100, and large result sets require pagination

5. Time format specification: Time conditions use UTC format YYYY-MM-DDTHH:mm:ss

6. Language consistency in semantic search: The semantic query text must stay in the same language as the user's input. Do not translate it.

PDS File Upload Guide

Scenario: When you have obtained the target drive_id and directory file_id and need to upload files to PDS drive Purpose: Upload local files to PDS drive (supports enterprise space, team space, personal space)

---

File Upload Command

Use the aliyun pds upload-file command to directly upload local files to PDS. This command automatically completes the three steps: create file, upload content, and complete upload.

aliyun pds upload-file \
  --drive-id <drive_id> \
  --local-path <local_file_path> \
  --parent-file-id <parent_file_id> \
  --name <cloud_file_name> \
  --check-name-mode <auto_rename|ignore|refuse> \
  --enable-rapid-upload <true|false> \
  --part-size <part_size> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

---

Parameter Description

---

Common Examples

Basic Upload

Upload to root directory using local file name:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Specify Directory and File Name

Upload to specified directory with custom cloud file name:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --parent-file-id "root" \
  --name "my-photo.jpg" \
  --check-name-mode "auto_rename" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Enable Rapid Upload

Calculate file SHA-1 for rapid upload attempt (completes instantly if identical file exists in cloud):

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --enable-rapid-upload \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Large File Multipart Upload

Custom part size (suitable for large file uploads):

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/large-file.zip" \
  --part-size 10485760 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Upload File to Specified Directory

If you want to upload a file to a specified directory in a PDS drive, you need to convert the cloud directory name to the cloud directory file_id, and use this file_id as the value of the --parent-file-id parameter.

For example, to upload a file to the /Photos/2026/04 directory in a personal space, you need to traverse each level of the path to find the corresponding directory's file_id. If a directory does not exist in the cloud, you need to create it first.

Step 1: Find or Create Photos Directory

List all directories under the root directory to find the Photos directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id root \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

• If Photos directory exists: Note down its file_id
• If Photos directory does not exist: Create it first and get the file_id from the response:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id root \
  --name Photos \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Step 2: Find or Create 2026 Directory

List all directories under the Photos directory to find the 2026 directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id <Photos_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

• If 2026 directory exists: Note down its file_id
• If 2026 directory does not exist: Create it first:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id <Photos_directory_file_id> \
  --name 2026 \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Step 3: Find or Create 04 Directory

List all directories under the 2026 directory to find the 04 directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id <2026_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

• If 04 directory exists: Note down its file_id
• If 04 directory does not exist: Create it first:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id <2026_directory_file_id> \
  --name 04 \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Step 4: Upload File

After obtaining the file_id of the 04 directory, use it as the --parent-file-id parameter value to upload the file:

aliyun pds upload-file \
  --drive-id <drive_id> \
  --local-path "/path/to/file.jpg" \
  --parent-file-id <04_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Note: When executing the aliyun pds list-file command, if there are no valid items returned and the next_marker is not empty, it means that the query is not complete. Use the next_marker as the --marker parameter for the next list query until next_marker is empty.

Upload File to Specified Parent File ID

When uploading a file to a specified parent file ID, first verify whether the parent directory with the specified ID exists using the Get File command:

aliyun pds get-file \
  --drive-id "100" \
  --file-id "1000" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Verification Logic:

• If the specified Parent File ID does not exist: The system will prompt that the parent directory does not exist. Ask the user to confirm again.
• If the directory exists: Take the response file's parent_file_id as the new Parent File ID and continue to query through Get File until the parent_file_id is root, indicating that the top-level directory has been found.

After finding all levels, concatenate them to get the full path of the file in this PDS drive space after upload.

Note: Before uploading, you must query the full path relative to the root directory. Only after that can you proceed with the subsequent upload operations.

Upload Command:

After completing the path query, use the following command to upload the file:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --parent-file-id "1000" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Post-Upload:

After the upload is completed, inform the user that the file upload was successful and display the full path relative to the root directory. For example:

The file has been uploaded to the personal space (or team space) with the full path: /Photos/2026/04/01/file.jpg

---

Output Description

After successful command execution, returns a JSON object with complete file information, main fields include:

• file_id: Unique file ID
• name: Cloud file name
• size: File size
• created_at: Creation time
• updated_at: Update time
• parent_file_id: Parent directory ID

---

Notes

1. Same name file handling: Recommend using --check-name-mode auto_rename to avoid overwriting existing files 2. Rapid upload feature: Enable --enable-rapid-upload to complete upload instantly when identical file exists in cloud 3. Multipart upload: Large files are automatically uploaded in parts, adjust part size via --part-size 4. Network stability: Ensure stable network when uploading large files to avoid interruptions

Alibaba Cloud PDS Visual Similar Search Guide

Scenario: When you have prepared a local image file or have obtained the drive_id, file_id, revision_id of an image file, and want to perform image search, similar image search, visual similarity search, or multimodal image retrieval Purpose: Search for similar images in the cloud drive based on user-provided image

Step 1 [Optional]: Upload Local Image File to Drive System Space

Prerequisites

If the user has already provided the image file's drive_id, file_id, revision_id, skip this step

Step 1.1 Get System Space

Execute the following command to get the domain's system space configuration:

aliyun pds get-domain --domain-id <domain-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Response example:

{
  "domain_id": "bj1093",
  "system_drive_config": {
    "enable": true,
    "drive_id": 1,
    "resource_parent_file_id_map": {
      "value-add": "68d2348822056f5eea514146b4ad7183cdb94d2f"
    }
  }
}

Extract the system space ID and upload parent file ID from the response. In the above example, system space ID is 1, and upload parent file ID is 68d2348822056f5eea514146b4ad7183cdb94d2f (the value-add item).

If enable in system_drive_config is false, or drive_id is empty, or resource_parent_file_id_map does not contain value-add, there is an issue with system space configuration. Please contact PDS technical support for assistance.

Step 1.2 Upload Local File to Drive System Space

Upload the local file to the drive's system space, where drive_id is set to the system space ID obtained in the previous step, parent_file_id is set to the upload parent file ID obtained in the previous step, and record the file's file_id and revision_id.

Step 2: Construct x-pds-process

If the user searches using a local file, the source file information comes from the file uploaded to the drive in Step 1.2; otherwise, the source file information comes from the drive file information provided by the user.

Must call the existing Python script scripts/render_visual_similar_search_process.py to generate x-pds-process. The script will output x-pds-process to the terminal.

Parameter Description

• source_domain_id: Domain where the source image is located
• source_file_id: File ID of the source image
• source_drive_id: Drive ID of the source image
• source_revision_id: Revision ID of the source image
• query: Search semantic text, not required if none
• limit: Maximum number of similar images to return, not required if none

python scripts/render_visual_similar_search_process.py \
  --source_domain_id <SOURCE_DOMAIN_ID> \
  --source_file_id <SOURCE_FILE_ID> \
  --source_drive_id <SOURCE_DRIVE_ID> \
  --source_revision_id <SOURCE_REVISION_ID> \
  --query <QUERY> \
  --limit <LIMIT>

---

Step 3: Perform Image Search

Parameter Description

• search_drive_id: Drive ID to search in
• search_folder_id: File ID of the folder to search in

Search Entire Drive

aliyun pds process \
  --resource-type drive \
  --drive-id ${SEARCH_DRIVE_ID} \
  --x-pds-process ${X_PDS_PROCESS} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

Search Specific Folder

aliyun pds process \
  --resource-type file \
  --drive-id ${SEARCH_DRIVE_ID} \
  --file-id ${SEARCH_FOLDER_ID} \
  --x-pds-process ${X_PDS_PROCESS} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-multimodal-search

---

Response

Success Response:

{
  "similar_files": [
    {
      "similarity": 0.95,
      "domain_id": "bj1093",
      "drive_id": "2",
      "file_id": "5d79206586bb5dd69fb34c349282718146c55da7",
      "name": "similar_image1.jpg",
      "type": "file",
      "category": "image",
      "size": 102400,
      "created_at": "2019-08-20T06:51:27.292Z",
      "thumbnail": "https://..."
    },
    {
      "similarity": 0.84,
      "domain_id": "bj1093",
      "drive_id": "2",
      "file_id": "69c0e5c9432208927ca14d1f8af5e897486c6337",
      "name": "similar_image2.jpg",
      "type": "file",
      "category": "image",
      "size": 102400,
      "created_at": "2023-08-20T06:51:27.292Z",
      "thumbnail": "https://..."
    }
  ]
}

Field Description:

• similarity: Similarity score, range [0, 1], closer to 1 means more similar
• drive_id: Drive where the result file is located (the search scope drive)
• file_id: Similar file ID
• name: File name
• thumbnail: Thumbnail URL

---

Error Handling

| HTTP Status | Error Code | Description | Solution | |------------|--------|------|---------|| | 400 | InvalidParameter.xxx | Invalid parameter | Check parameter format and encoding | | 400 | OperationNotSupport | Feature not enabled | Contact PDS technical support to enable feature | | 403 | ForbiddenNoPermission.xxx | No permission | Check AccessToken permissions |

Common Errors:

1. Feature Not Enabled

{
  "code": "OperationNotSupport",
  "message": "This operation is not supported."
}

Solution: Contact PDS technical support to enable image search feature.

2. Insufficient Permissions

{
  "code": "ForbiddenNoPermission.file",
  "message": "No Permission to access resource file"
}

Solution:

• Ensure current user has FILE.LIST permission on the search space or folder
• Ensure current user has FILE.PREVIEW permission on the source file

---

Best Practices

1. Set Appropriate limit Parameter

• Quick preview: l_10 or l_20
• Regular search: l_50
• Comprehensive search: l_100 (maximum)

2. Prefer Image-Only Retrieval

Unless the user explicitly requests image-text hybrid retrieval, prefer using image-only retrieval for better accuracy

---

FAQ

Q: Why are fewer results returned than expected? limit only indicates the maximum number of results, it does not guarantee that limit images will be returned. A: Possible reasons: 1. Actual number of similar images is less than limit 2. Some files were filtered due to insufficient permissions 3. Total number of images in search scope is small

Q: Can I search for videos or documents? A: Not supported, only similar image search is supported.