alibabacloud-oss-manage-metaquery

OSS 向量搜索与 AI 内容感知

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

前提条件

1. Aliyun CLI（>= 3.3.3）

预检查：需要 Aliyun CLI >= 3.3.3 除打开 MetaQuery 外，此技能的所有 OSS 操作均使用 Aliyun CLI。 如果已安装 Aliyun CLI，则无需单独安装 ossutil。 运行以下命令以验证版本：aliyun version 如果尚未安装或版本低于 3.3.3， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md 获取安装说明。

接着，[必须]运行 aliyun configure set --auto-plugin-install true 以启用插件自动安装。 [必须]运行 aliyun plugin update，确保本地计算机上已有的所有插件始终为最新版本。

2. 更新 aliyun ossutil 插件

故障排除：出现 --user-agent 未知标志错误 如果运行命令时遇到 Error: unknown flag: --user-agent，说明 ossutil 插件版本过旧。运行以下命令更新到最新版本：

aliyun ossutil update

更新后，重新运行原命令。

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

说明：

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

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

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

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

aliyun configure ai-mode disable

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

架构

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

核心组件：OSS Bucket + Data Index + Vector Search + AI Content Awareness

使用限制

支持的区域

区域类别	区域列表
华东	cn-hangzhou, cn-shanghai
华北	cn-qingdao, cn-beijing, cn-zhangjiakou
华南	cn-shenzhen, cn-guangzhou
西南	cn-chengdu
其他	cn-hongkong, ap-southeast-1（Singapore）, us-east-1（Virginia）

注意：如果用户的 Bucket 位于上述列表以外的区域，则无法启用向量模式 MetaQuery 和内容感知，并会返回 EC 错误代码 0037-00000001。请引导用户在支持的区域创建新的 Bucket。

文件类型

• 支持：图像、视频、音频、文档
• 分片上传：仅显示通过 CompleteMultipartUpload 完成合并的对象

---

性能参考

OSS 内网带宽和 QPS

区域	内网带宽	默认 QPS
cn-beijing, cn-hangzhou, cn-shanghai, cn-shenzhen	10Gbps	1250
其他区域	1Gbps	1250

此带宽和 QPS 专用于向量搜索，不占用 Bucket 的 QoS 配额。

现有文件索引构建时间

文件类型	1,000 万个文件	1 亿个文件	10 亿个文件
结构化数据和图像	2-3 小时	1 天	约 10 天
视频、文档、音频	2-3 天	7-9 天	-

增量更新和搜索延迟

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

---

危险操作确认

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

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

确认时，向用户说明以下内容：

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

RAM 权限

参见 references/ram-policies.md

---

关键规则（必须遵守）

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

禁止：

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

必须：

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

**原因：**只有 Python 脚本或 SDK 才能正确配置 WorkflowParameters，以启用 AI 内容感知（ImageInsightEnable 和 VideoInsightEnable）。如果不这样做，语义搜索质量会大幅下降。

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

创建 Bucket 时遇到 BucketAlreadyExists 错误：

1. 立即停止所有后续操作
2. 告知用户：“Bucket 名称已被占用”
3. 询问用户选择：
   • 选项 1：使用现有 Bucket（需要用户明确确认）
   • 选项 2：选择新的 Bucket 名称（由用户提供新名称）
4. 等待用户回复后再继续 禁止：

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

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

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

• 创建 Bucket
• 查询 Bucket 信息
• 查询 Bucket 统计信息
• 上传文件
• 查询 MetaQuery 状态
• 执行语义搜索
• 关闭 MetaQuery
• 删除对象 / Bucket 目标：统一使用 aliyun 命令，尽量减少对 ossutil 的依赖。

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

此技能默认无需安装 ossutil。 只要已安装 Aliyun CLI >= 3.3.3，并已执行以下命令：

aliyun configure set --auto-plugin-install true

即可将其用作默认执行工具。

核心工作流

任务 1：创建存储桶并上传文件

创建存储桶前，务必先向用户确认。只有在用户同意后才能继续。

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

任务 2：启用向量搜索和 AI 内容感知（仅限 Python 脚本或 SDK）

WARNING：必须使用 python scripts/open_metaquery.py 打开 MetaQuery。严禁使用 aliyun ossutil api open-meta-query（该命令无法配置 WorkflowParameters，因此无法启用 ImageInsightEnable 和 VideoInsightEnable 这两项 AI 内容感知功能，会严重降低语义搜索质量）。

使用 Python 脚本（必需）

执行 Python 脚本前，请完成以下环境设置：

1. 安装 Python 依赖项：

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

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

3. 验证 RAM 权限： 用户必须拥有 MetaQuery 所需的最低 RAM 权限。请参阅 references/ram-policies.md。 如果用户遇到 AccessDenied 错误，请检查 RAM 权限是否已正确配置。

启用流程：

1. 准备存储桶： a. 如果用户要求创建新存储桶：

   • 使用用户指定的存储桶名称运行 aliyun ossutil api put-bucket --bucket examplebucket --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery
   • 如果创建失败并出现 BucketAlreadyExists 错误：
     • 立即停止操作
     • 告知用户：“存储桶名称 <bucket-name> 已被占用（可能由您或其他用户创建）”
     • 必须询问用户：“您想要：1）使用此现有存储桶，还是 2）选择新的存储桶名称？”
     • 等待用户明确回复后再继续。未经许可，不得修改存储桶名称或使用现有存储桶。 b. 如果用户提供的是现有存储桶：
   • 首先使用 aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oss-manage-metaquery 验证存储桶是否存在
   • 如果不存在，询问用户是否要创建该存储桶

2. 验证存储桶对象数量：用户提供存储桶后，检查对象数量。如果超过 1000 个，请提醒用户启用 MetaQuery 会产生费用。 使用以下命令获取存储桶的对象数量：

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

   响应中的 ObjectCount 字段表示对象数量。

   • 如果对象数量超过 1000 个，请提醒用户启用 MetaQuery 会产生费用，并确认是否继续。
   • 如果对象数量为 0，请询问用户要上传哪些文件。上传命令：

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

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

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

排查 MetaQuery 启用问题

使用 get-meta-query-status 命令检查 MetaQuery 状态：

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

根据返回的状态：

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

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

  如果 MetaQueryMode=semantic，且 VideoInsightEnable 和 ImageInsightEnable 均为 True，则用户已成功启用具备内容感知能力的向量模式 MetaQuery（这会大幅提升语义搜索质量）。无需进一步操作。 如果不满足这些条件，建议用户切换到其他存储空间并重新开始。

任务 3：执行语义搜索

MetaQuery 搜索的前提条件

使用 MetaQuery 搜索前，请确认以下事项：

1. 验证 MetaQuery 已启用：

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

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

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

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

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

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

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

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

对于标量搜索，请使用 --meta-query-mode basic

有关详细的命令参数，请参阅 references/related-apis.md 中的 DoMetaQuery 部分。

3. 优化搜索结果展示： 搜索完成后，向用户展示结果时，使用 x-oss-process 参数为图像和视频文件生成预览图或封面帧，方便用户直观地查看搜索结果。如果用户当前使用的渠道支持多媒体文件，请直接发送给用户。

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

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

参数：t_0：在 0ms 处截取画面作为封面；f_png：输出格式为 PNG；w_0,h_0：宽度和高度为 0 表示原始分辨率。

图像文件 -- 获取图像预览链接：

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

注意：aliyun ossutil presign 命令会生成一个带签名的临时访问 URL，在有效期内可直接通过浏览器打开预览。对于图像文件，也可以通过 x-oss-process 添加图像处理参数（例如调整大小、裁剪）：

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

这会生成缩略图预览，缩短加载时间。

排查 MetaQuery 搜索问题

用户询问“为什么没有找到特定文件？”

当用户报告某个已上传的文件未出现在搜索结果中时，请根据 MetaQuery 配置进行排查：

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

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

清理资源

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

警告：关闭数据索引后，所有已索引的数据都会被清除。（危险操作——请先与用户确认）

OSS 操作的 Python 脚本替代方案

当无法使用 aliyun ossutil 时，可以使用 Python 脚本作为替代方案。请参阅 references/related-apis.md 中的 Python SDK Scripts 部分。

---