alibabacloud-oss-manage-metaquery：支持对存储在 OSS 上的多模态数据（如文档、文本、视频、图片等）可实现自然语言的检索

OSS 向量搜索与 AI 内容感知

利用多模态 AI 模型从存储在 OSS Bucket 中的图像、视频、音频和文档中提取语义描述和简洁摘要。构建可搜索的向量索引，以实现文本到图像和文本到视频搜索等高级检索能力。

前置条件

1. Aliyun CLI（>= 3.3.3）

预检查：需要 Aliyun CLI >= 3.3.3
本 Skill 对除开启 MetaQuery 外的所有 OSS 操作使用 Aliyun CLI。

如果 Aliyun CLI 已安装，则无需单独安装 ossutil。

运行以下命令验证版本：aliyun version
如果未安装或版本低于 3.3.3，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 安装/更新，
或参阅 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保本地现有插件始终为最新版本。

1. 更新 aliyun ossutil 插件

故障排查：--user-agent 未知 flag 错误
如果运行命令时遇到 Error: unknown flag: --user-agent，ossutil 插件版本过旧。运行以下命令更新到最新版本：
```bash
aliyun ossutil update
```
更新后，重新运行原命令。

Python SDK 依赖

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

> 注意：
> - 必需：Aliyun CLI、Python 依赖 oss2 和 alibabacloud-credentials
> - 不需要：ossutil
> - 唯一需要 Python 的操作：开启 MetaQuery（AI 内容感知 + 语义搜索）
> **安全规则：**
> - **绝不**读取、回显或打印 AK/SK 值（例如 `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` 是禁止的）
> - **绝不**要求用户在对话或命令行中直接输入 AK/SK

在核心工作流**开始**时（任何 CLI 调用之前）：
**[必须] 启用 AI-Mode** —— Agent Skill 执行需要 AI-mode。
在任何 CLI 调用之前运行以下命令：

aliyun configure ai-mode enable

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

**[必须] 在每一个退出点禁用 AI-Mode** —— 在交付最终响应之前（无论何种原因），必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的场景。
AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后**绝不能**保持启用状态。

aliyun configure ai-mode disable

**[必须] CLI User-Agent** —— 每次调用 `aliyun` CLI 命令都必须包含：
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery`

架构

用户请求 -> OSS Bucket -> AI 内容感知引擎 -> 语义特征提取 -> 向量索引 -> 语义搜索
                    |
         图像/视频/音频/文档 -> 详细描述（约 100 字符）+ 简洁摘要（<=20 字符）

核心组件：OSS Bucket + 数据索引 + 向量搜索 + AI 内容感知

使用限制

支持的地域

注意：如果用户 Bucket 位于上方未列出的地域，则无法启用向量模式 MetaQuery 和内容感知，并会返回 EC Code 0037-00000001 错误。引导用户在支持的地域创建新 Bucket。

文件类型

• 支持：图像、视频、音频、文档
• 分片上传：仅显示已通过 CompleteMultipartUpload 组装的对象

性能参考

OSS 内网带宽和 QPS

此带宽和 QPS 专供向量搜索使用，不消耗 Bucket 的 QoS 配额。

现有文件索引构建时间

增量更新和搜索延迟

• 增量更新：QPS < 1250 时，延迟通常为分钟到小时
• 搜索响应：亚秒级，默认超时 30 秒

危险操作确认

执行以下任何危险操作之前，你必须先与用户确认并获得明确同意后再继续：

• 删除 Bucket：aliyun ossutil rm oss://<bucket-name> -b --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery —— 删除整个 Bucket，不可逆
• 删除 Object：aliyun ossutil rm oss://<bucket-name>/<object-key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery —— 删除特定文件
• 批量删除 Object：aliyun ossutil rm oss://<bucket-name>/ --recursive --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery —— 递归删除 Bucket 中所有文件
• 关闭 MetaQuery：aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery —— 关闭元数据索引；所有索引数据将被清除
• 开启 MetaQuery：python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint> —— 开启元数据索引；现有数据将开始被索引。如果 bucket 有超过 1000 个对象，先与用户确认。
• 创建 Bucket：aliyun ossutil api put-bucket --bucket <bucket> --region <region-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery —— 创建 Bucket

确认时，向用户解释以下内容：

1. 将要执行的具体操作
2. 影响范围（哪些文件/资源将被删除或关闭）
3. 操作是否可逆（大多数删除操作不可逆）

RAM 权限

见 references/ram-policies.md

关键规则（必须遵循）

规则 1：开启 MetaQuery 必须使用 Python 脚本

禁止：

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

要求：

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

原因： 只有 Python 脚本或 SDK 才能正确配置 WorkflowParameters 以启用 AI 内容感知（ImageInsightEnable 和 VideoInsightEnable）。没有它，语义搜索质量将严重下降。

规则 2：Bucket 名称冲突时必须询问用户

创建 Bucket 且遇到 BucketAlreadyExists 错误时：

1. 立即停止所有后续操作
2. 告知用户：“Bucket 名称已被占用”
3. 询问用户选择：

• 选项 1：使用现有 bucket（需要用户明确确认）
• 选项 2：选择新的 bucket 名称（用户提供新名称）

1. 等待用户响应后再继续

禁止：

• 自动修改 bucket 名称（例如追加 -2、-new 等）
• 未经询问用户就使用现有 bucket

规则 3：除开启 MetaQuery 外，所有操作默认使用 Aliyun CLI

以下操作应默认使用 Aliyun CLI：

• 创建 Bucket
• 查询 Bucket 信息
• 查询 Bucket 统计
• 上传文件
• 查询 MetaQuery 状态
• 执行语义搜索
• 关闭 MetaQuery
• 删除 Object / Bucket

目标：统一使用 aliyun 命令，最小化对 ossutil 的依赖。

规则 4：如果 Aliyun CLI 已安装，则不需要 ossutil

本 Skill 默认不需要安装 ossutil。

只要安装了 Aliyun CLI >= 3.3.3 且已执行：

aliyun configure set --auto-plugin-install true

它就可以作为默认执行工具。

核心工作流

任务 1：创建 Bucket 并上传文件

创建 bucket 之前始终与用户确认。仅在用户同意后继续。

1.1 创建 Bucket

aliyun ossutil api put-bucket --bucket examplebucket --region <region-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

1.2 下载文件

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 上传文件

aliyun ossutil cp /tmp/test_medias_download/ oss://example-bucket/test_medias/ -r --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

### 任务 2：启用向量搜索与 AI 内容感知（仅 Python 脚本或 SDK）
> 警告：你必须使用 `python scripts/open_metaquery.py` 开启 MetaQuery。使用 `aliyun ossutil api open-meta-query` 被**严格禁止**（它无法配置 WorkflowParameters，从而无法启用 AI 内容感知特性 ImageInsightEnable 和 VideoInsightEnable，严重降低语义搜索质量）。

#### 使用 Python 脚本（强制）
执行 Python 脚本前，完成以下环境设置：

**1. 安装 Python 依赖：**

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

**2. 配置凭证：**
Python 脚本使用 `alibabacloud-credentials` 默认凭证链自动发现凭证（支持环境变量、`~/.aliyun/config.json`、ECS 实例角色等）。代码中无需显式处理 AK/SK。确保通过 `aliyun configure` 命令配置了凭证。

**3. 验证 RAM 权限：**
用户必须具有 MetaQuery 所需的最低 RAM 权限。见 [references/ram-policies.md](references/ram-policies.md)。
如果用户遇到 `AccessDenied` 错误，检查 RAM 权限是否正确配置。

**启用流程：**
1. **准备 Bucket**：
   **a. 如果用户请求创建新 Bucket：**
   - 使用用户指定的 bucket 名运行 `aliyun ossutil api put-bucket --bucket examplebucket --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery`
   - 如果创建失败并返回 `BucketAlreadyExists` 错误：
     - **立即停止操作**
     - 告知用户：“Bucket 名称 `<bucket-name>` 已被占用（可能是你或其他用户创建的）”
     - **你必须询问用户**：“你想：1) 使用这个现有 bucket？还是 2) 选择新的 bucket 名称？”
     - **等待用户明确响应后再继续**。未经允许不要修改 bucket 名称或使用现有 bucket。
   **b. 如果用户提供现有 bucket：**
   - 先用 `aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery` 验证 bucket 存在
   - 如果不存在，询问用户是否创建

2. **验证 Bucket 对象数量**：用户提供 bucket 后，检查对象数量。如果超过 1000，警告用户启用 MetaQuery 会产生费用。
   使用以下命令获取 bucket 的对象数量：

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

   响应中的 `ObjectCount` 字段表示对象数量。
   - 如果对象数量超过 1000，警告用户启用 MetaQuery 会产生费用并确认是否继续。
   - 如果对象数量为 0，询问用户要上传哪些文件。上传命令：

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

3. **运行 Python 脚本**：上述步骤完成后，尝试使用 Python 脚本开启 MetaQuery。
**Python 脚本示例：**

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

#### MetaQuery 启用问题排查
使用 `get-meta-query-status` 命令检查 MetaQuery 状态：

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

根据返回状态：
- **状态为 `Deleted`**：MetaQuery 正在关闭。用户应稍后重试。
- **状态为 `Running` 或 `Ready`**：MetaQuery 已创建。检查以下两个条件：
  - `MetaQueryMode` 是否为 `semantic`
  - `WorkflowParameters` 是否包含以下配置：

<WorkflowParameters>

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

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

</WorkflowParameters>

  如果 `MetaQueryMode=semantic` 且 `VideoInsightEnable` 和 `ImageInsightEnable` 都为 `True`，则用户已成功启用向量模式 MetaQuery 和内容感知（这大大提升语义搜索质量）。无需进一步操作。
  如果这些条件不满足，建议用户切换到不同 bucket 并重新开始。

### 任务 3：执行语义搜索
#### MetaQuery 搜索前置条件
使用 MetaQuery 搜索前，确认以下内容：
1. **验证 MetaQuery 已启用**：

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

1. 如果 MetaQuery 未启用：先完成启用流程。参阅任务 2 使用 Python 脚本启用。
2. 检查索引扫描状态：get-meta-query-status 的 Phase 字段指示当前扫描阶段：

• FullScanning：全量扫描进行中。搜索尚不可用。等待全量扫描完成。
• IncrementalScanning：增量扫描进行中。索引已基本建立，搜索可正常执行。

1. 验证 MetaQuery 状态为 Running：仅当 State 为 Running 时 MetaQuery 才可用。如果状态为 Ready 或任何非 Running 状态，可能需要等待或重新启用。

1. 准备 meta-query.xml 文件：

创建 meta-query.xml 文件定义查询条件。详细格式、字段说明和完整示例见 references/metaquery.md。

语义向量搜索包含“person”的视频文件示例（MediaTypes 只能是以下之一：video、image、audio、document）：

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

标量搜索示例，文件大小 > 30B 且文件修改时间 > 2025-06-03T09:20:47.999Z：

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

2. 执行搜索命令：

此示例使用语义向量搜索。meta-query.xml 文件定义查询条件，搜索结果返回最相似的文件。

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

标量搜索使用 --meta-query-mode basic

详细命令参数见 references/related-apis.md 中的 DoMetaQuery 章节。

3. 优化搜索结果显示：

搜索完成后，向用户展示结果时，使用 x-oss-process 参数为图像和视频文件生成预览图或封面帧，使用户更容易可视化查看搜索结果。如果用户当前渠道支持多媒体文件，直接发送给用户。

视频文件——获取视频封面截图：

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

参数：t_0：以 0ms 帧作为封面；f_png：输出格式 PNG；w_0,h_0：宽/高 0 表示原始分辨率。

图像文件——获取图片预览链接：

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

注意：aliyun ossutil presign 命令生成签名的临时访问 URL，可在有效期内直接在浏览器打开预览。对于图像文件，你还可以通过 x-oss-process 添加图像处理参数（例如 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
```
这会生成缩略图预览以减少加载时间。

MetaQuery 搜索问题排查

#### 用户问“为什么找不到某个特定文件？”

当用户报告特定上传文件缺失于搜索结果时，根据 MetaQuery 配置排查：

a. 未启用内容感知：

如果用户的 MetaQuery 未启用内容感知（即 WorkflowParameters 中 VideoInsightEnable 或 ImageInsightEnable 不是 True），可能原因包括：

• 文件的元数据索引尚未完全建立。等待索引扫描完成（通过 aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery 检查 Phase 字段）。
• 没有内容感知，搜索仅基于基本文件元数据（文件名、大小、类型等），无法对文件内容进行语义理解，导致搜索效果有限。
• 建议：建议用户启用内容感知以提升搜索质量。由于现有 MetaQuery 配置无法直接修改，建议用户切换到新 bucket 并按照任务 2 流程重新启用带内容感知的 MetaQuery。

b. 已启用内容感知：

如果用户的 MetaQuery 已启用内容感知但特定文件仍找不到，可能原因包括：

• 文件仍在处理中：内容感知需要对文件进行深度分析（例如图像识别、视频理解），耗时更长，尤其是视频文件。通过 aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery 检查 Phase 字段：
• FullScanning：整体索引仍处于全量扫描模式。耐心等待。
• IncrementalScanning：新上传的文件正在增量处理。通常等待几分钟。
• 不支持的文件格式：某些文件格式可能不被内容感知支持。这种情况下，搜索只能使用基本元数据。
• 搜索关键词不匹配：用户的搜索关键词可能与文件内容语义不匹配。建议用户尝试调整搜索关键词，使用更接近实际文件内容的描述。

任务 4：查询数据索引状态（aliyun ossutil）

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

返回字段（State、Phase、MetaQueryMode 等）的详细说明见 references/related-apis.md 中的 GetMetaQueryStatus 章节。

验证

见 references/verification-method.md

资源清理

关闭数据索引。（危险操作——先与用户确认）

aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery

> **警告**：关闭数据索引后，所有索引数据将被清除。（危险操作——先与用户确认）

OSS 操作的替代 Python 脚本

当 aliyun ossutil 不可用时，你可以使用 Python 脚本作为替代。见 references/related-apis.md 中的 Python SDK 脚本章节。