AI 助理
文档备案控制台
开发者社区 云存储 技术博文 文章 正文

使用 OSS-Vectors-Embed-CLI 工具三步搭建多模态语义检索系统

2026-03-17 27
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
本文涉及的产品
对象存储 OSS，OSS 加速器 50 GB 1个月
简介： 本文将介绍如何使用 OSS Vectors Embed CLI 命令行工具，通过若干简单的命令快速构建多模态语义检索系统。同时介绍 OSS Vectors Embed CLI 命令行工具的灵活自定义能力，如批量写入、自定义向量键、自定义向量模型参数等。

向量数据作为 AI 应用的基础设施，正呈现爆炸式增长的趋势。OSS 向量 Bucket 于 2025 年 9 月发布，是阿里云对象存储 OSS 提供的一种专门用于存储、查询和管理向量数据的 Bucket 类型，具有低成本、大规模和简单易用的特点，面向多模态检索、知识库、RAG、AI Agent 等 AI 场景提供向量数据存储和查询的能力。目前，已经有众多客户基于向量 Bucket 来构建自身的语义检索系统。

近期，OSS 全新发布 OSS Vectors Embed CLI 命令行工具，用户可以便捷地调用阿里云百炼向量模型，将 OSS 中原始文件或存储在本地的海量文件进行向量化，并将向量化结果写入到 OSS 向量 Bucket。同时，该命令行工具也支持发起多模态语义检索，简化如 RAG 知识库、AI 助手、多模态语义检索等各类 AI 应用的开发流程，核心能力包括：

  • 无缝集成：便捷调用阿里云百炼服务实现数据向量化。
  • 多源输入：支持对本地文件、OSS 对象、第三方文件 URL 或文本字符串等多种数据格式进行向量化。
  • 批量处理：支持将原始文件的向量化结果批量写入到向量 Bucket。
  • 灵活自定义：支持灵活设置向量 Key 值、灵活自定义模型参数，并支持将向量数据携带的标量元数据一同写入到向量 Bucket。
  • 多模态检索：支持根据文本、图片等检索条件进行相似度语义检索，满足多模态语义检索需求。


本文将在下面介绍如何使用 OSS Vectors Embed CLI 命令行工具，通过若干简单的命令快速构建多模态语义检索系统。同时，本文将介绍 OSS Vectors Embed CLI 命令行工具的灵活自定义能力，如批量写入、自定义向量键、自定义向量模型参数等。

image.png

第一步：环境准备

在环境配置步骤中，您需要配置访问凭证、安装 OSS-Vectors-Embed-CLI 工具、创建向量 Bucket。

配置访问凭证

在使用 CLI 工具前，需要准备以下访问凭证：

将访问凭证配置为环境变量。CLI 在执行时会自动读取这些变量，无需在命令中重复提供。

# 阿里云账户 AccessKey 
export OSS_ACCESS_KEY_ID="<your-access-key-id>"
export OSS_ACCESS_KEY_SECRET="<your-access-key-secret>"
# 百炼 API Key
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"

安全提示：请勿在脚本中硬编码凭证，建议使用环境变量。

安装 OSS-Vectors-Embed-CLI 工具

支持 Python 3.9 或更高版本。


方式一：pip 安装（推荐）

pip install oss-vectors-embed-cli

方式二：开发模式安装

git clone https://github.com/aliyun/oss-vectors-embed-cli.git
cd oss-vectors-embed-cli
pip install -e .

验证安装

oss-vectors-embed --version
# 输出: oss-vectors-embed, version 0.1.0

创建向量 Bucket

写入向量数据之前，需要创建向量 Bucket 并配置索引：

  • 创建向量 Bucket：在向量 Bucket页面创建向量 Bucket，用于存储向量数据和索引。
  • 创建向量索引：在已创建的向量 Bucket 中创建索引，配置与向量模型匹配的向量维度。

重要：向量索引的维度必须与所用向量模型输出维度一致。例如，使用 text-embedding-v4 模型（默认 1024 维）时，索引维度也应设为 1024。

第二步：向量写入

OSS 向量 Bucket 提供 PutVectors 接口，将向量数据写入到 OSS 向量 Bucket 中。OSS-Vectors-Embed-CLI 命令行工具将原始文件读取（GetObject）、调用阿里云百炼做向量化、向量数据写入（PutVectors）等多次 API 调用封装为一条命令，用户仅需调用一条命令便可以快速完成向量数据的生产和写入。阿里云百炼提供文本向量模型和多模态向量模型，支持对来自 OSS 和客户本地的文本、图片和视频文件进行向量化，您可以将任意文件的向量化结果写入到向量 Bucket 中。以下分别介绍通过 OSS-Vectors-Embed-CLI 命令行工具来写入“文本文件向量”、“图片文件向量”和“视频文件向量”的使用方式。

写入文本文件的向量

以阿里云百炼文本向量模型text-embedding-v4为例，您可以根据自己的需求选择其他合适的向量模型。输入源支持文本字符串、OSS 对象或本地文本文件。

  • 直接输入文本来生成向量并将其写入到向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \              //阿里云 ID
  --vectors-region cn-hangzhou \                //OSS 向量 Bucket 所在地域
  put \
  --vector-bucket-name my-vector-bucket \       //OSS 向量 Bucket 名称
  --index-name my-index \                       //OSS 向量 Index 名称
  --model-id text-embedding-v4 \                //使用的向量模型
  --text-value "人工智能正在改变我们的生活方式"      //直接输入文本

返回示例

{
  "key": "3d8935dd-6395-4c9c-a501-df902846ec80",                     //向量 Key 值
  "bucket": "my-vector-bucket",                                      //OSS 向量 Bucket 名称
  "index": "my-index",                                               //OSS 向量 Index 名称
  "model": "text-embedding-v4",                                      //使用的向量模型
  "contentType": "text",                                             //原始文件类型
  "embeddingDimensions": 1024,                                       //向量维度
  "metadata": {                                                      //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式",    //原始文本
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",                    //原始文件类型
    "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"            //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
  }
}
  • 对本地文本文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \ 
  --account-id <your-account-id> \              //阿里云 ID
  --vectors-region cn-hangzhou \                //OSS 向量 Bucket 所在地域
  put \
  --vector-bucket-name my-vector-bucket \       //OSS 向量 Bucket 名称
  --index-name my-index \                       //OSS 向量 Index 名称
  --model-id text-embedding-v4 \                //使用的向量模型
  --text "./documents/article.txt"              //本地文本文件所在路径

返回示例

{
  "key": "415c108e-d653-4d54-a241-d3b70e996666",                     //向量 Key 值
  "bucket": "my-vector-bucket",                                      //OSS 向量 Bucket 名称
  "index": "my-index",                                               //OSS 向量 Index 名称
  "model": "text-embedding-v4",                                      //使用的向量模型
  "contentType": "text",                                             //原始文件类型
  "embeddingDimensions": 1024,                                       //向量维度
  "metadata": {                                                      //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式。从清晨被智能闹钟根据睡眠周期轻柔唤醒，到通勤途中语音助手为我们规划最优路线；从家中智能音箱播放个性化新闻摘要，到工作时AI工具自动生成报告、翻译文档、优化流程——AI已悄然融入日常的每个角落。",   //原始文本
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",                    //原始文件类型
    "OSS-VECTORS-EMBED-SRC-LOCATION": "./documents/article.txt"      //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
  }
}
  • 对 OSS 文本文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                       //阿里云 ID
  --vectors-region cn-hangzhou \                         //OSS 向量 Bucket 所在地域
  put \
  --region cn-hangzhou \                                 //OSS 原始文件所在 Bucket 的地域
  --vector-bucket-name my-vector-bucket \                //OSS 向量 Bucket 名称
  --index-name my-index \                                //OSS 向量 Index 名称
  --model-id text-embedding-v4 \                         //使用的向量模型
  --text "oss://source-bucket/documents/file.txt"        //OSS 文件 URL

返回示例

{
  "key": "7ca24758-0d5b-46fe-ab90-db82be387650",                                  //向量 Key 值
  "bucket": "my-vector-bucket",                                                   //OSS 向量 Bucket 名称
  "index": "my-index",                                                            //OSS 向量 Index 名称
  "model": "text-embedding-v4",                                                   //使用的向量模型
  "contentType": "text",                                                          //原始文件类型
  "embeddingDimensions": 1024,                                                    //向量维度
  "metadata": {                                                                   //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-CONTENT": "This is a example file.",                   //原始文件的文本内容
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",                                 //原始文件类型
    "OSS-VECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"    //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
  }
}


写入图片文件的向量

以阿里云百炼多模态向量模型qwen2.5-vl-embedding为例，您可以根据自己的需求选择其他合适的向量模型。输入源支持本地文件、OSS 对象或 HTTP/HTTPS URL。

  • 对本地图片文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                      //阿里云 ID
  --vectors-region cn-hangzhou \                        //OSS 向量 Bucket 所在地域
  put \
  --vector-bucket-name my-vector-bucket \               //OSS 向量 Bucket 名称
  --index-name my-index \                               //OSS 向量 Index 名称
  --model-id qwen2.5-vl-embedding \                     //使用的向量模型
  --image "./images/photo.jpg"                          //本地图片文件所在路径

返回示例

{
  "key": "8fc8105b-d54f-464c-bf44-97b088d566ce",                       //向量 Key 值
  "bucket": "my-vector-bucket",                                        //OSS 向量 Bucket 名称
  "index": "my-index",                                                 //OSS 向量 Index 名称
  "model": "qwen2.5-vl-embedding",                                     //使用的向量模型
  "contentType": "image",                                              //原始文件类型
  "embeddingDimensions": 1024,                                         //向量维度
  "metadata": {                                                        //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-LOCATION": "./images/photo.jpg",            //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"                      //原始文件类型
  }
}
  • 对 OSS 图片文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                      //阿里云 ID
  --vectors-region cn-hangzhou \                        //OSS 向量 Bucket 所在地域
  put \
  --region cn-hangzhou \                                //OSS 原始文件所在 Bucket 的地域
  --vector-bucket-name my-vector-bucket \               //OSS 向量 Bucket 名称
  --index-name my-index \                               //OSS 向量 Index 名称
  --model-id qwen2.5-vl-embedding \                     //使用的向量模型
  --image "oss://source-bucket/photo.jpg"               //OSS 文件 URL

返回示例

{
  "key": "dbf57dfd-58be-4793-a484-a82eb86e0e08",                        //向量 Key 值
  "bucket": "my-vector-bucket",                                         //OSS 向量 Bucket 名称
  "index": "my-index",                                                  //OSS 向量 Index 名称
  "model": "qwen2.5-vl-embedding",                                      //使用的向量模型
  "contentType": "image",                                               //原始文件类型
  "embeddingDimensions": 1024,                                          //向量维度
  "metadata": {                                                         //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/photo.jpg",  //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"                       //原始文件类型
  }
}
  • 对 URL 文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                     //阿里云 ID
  --vectors-region cn-hangzhou \                       //OSS 向量 Bucket 所在地域
  put \
  --vector-bucket-name my-vector-bucket \              //OSS 向量 Bucket 名称
  --index-name my-index \                              //OSS 向量 Index 名称
  --model-id qwen2.5-vl-embedding \                    //使用的向量模型
  --image "https://example.com/photo.jpg"              //文件 URL

返回示例

{
  "key": "f15cfe75-d4de-497f-b441-3b08243cfa5e",                        //向量 Key 值
  "bucket": "my-vector-bucket",                                         //OSS 向量 Bucket 名称
  "index": "my-index",                                                  //OSS 向量 Index 名称
  "model": "qwen2.5-vl-embedding",                                      //使用的向量模型
  "contentType": "image",                                               //原始文件类型
  "embeddingDimensions": 1024,                                          //向量维度
  "metadata": {                                                         //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-LOCATION": "https://example.com/photo.jpg",  //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"                       //原始文件类型
  }
}

写入视频文件的向量

以阿里云百炼多模态向量模型qwen2.5-vl-embedding为例，您可以根据自己的需求选择其他合适的向量模型。输入源支持 OSS 视频文件、 HTTP/HTTPS URL 文件。

  • 对 OSS 视频文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                      //阿里云 ID
  --vectors-region cn-hangzhou \                        //OSS 向量 Bucket 所在地域
  put \
  --region cn-hangzhou \                                //OSS 原始文件所在 Bucket 的地域
  --vector-bucket-name my-vector-bucket \               //OSS 向量 Bucket 名称
  --index-name my-index \                               //OSS 向量 Index 名称
  --model-id qwen2.5-vl-embedding \                     //使用的向量模型
  --video "oss://source-bucket/myvideo.mp4"             //OSS 文件 URL

返回示例

{
  "key": "dbf57dfd-58be-4793-a484-a82eb86e0e08",                          //向量 Key 值
  "bucket": "my-vector-bucket",                                           //OSS 向量 Bucket 名称
  "index": "my-index",                                                    //OSS 向量 Index 名称
  "model": "qwen2.5-vl-embedding",                                        //使用的向量模型
  "contentType": "video",                                                 //原始文件类型
  "embeddingDimensions": 1024,                                            //向量维度
  "metadata": {                                                           //向量数据所携带的标量元数据
    "OSS-VECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/myvideo.mp4",  //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"                         //原始文件类型
  }
}
  • 对 URL 文件生成向量并将其写入向量 Bucket

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \                    //阿里云 ID
  --vectors-region cn-hangzhou \                      //OSS 向量 Bucket 所在地域
  put \
  --vector-bucket-name my-vector-bucket \             //OSS 向量 Bucket 名称
  --index-name my-index \                             //OSS 向量 Index 名称
  --model-id qwen2.5-vl-embedding \                   //使用的向量模型
  --video "https://example.com/video.mp4"             //文件 URL

返回示例

{
  "key": "9157d87b-c44b-4c53-aceb-cd4be7fd8bd9",                        //向量 Key 值
  "bucket": "my-vector-bucket",                                         //OSS 向量 Bucket 名称
  "index": "my-index",                                                  //OSS 向量 Index 名称
  "model": "qwen2.5-vl-embedding",                                      //使用的向量模型
  "contentType": "video",                                               //原始文件类型
  "embeddingDimensions": 1024,                                          //向量维度
  "metadata": {
    "OSS-VECTORS-EMBED-SRC-LOCATION": "https://example.com/video.mp4",  //CLI 会自动在向量 Bucket 该向量所在行添加源信息字段（OSS-VECTORS-EMBED-SRC-*），用于追溯向量来源。
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"                       //原始文件类型
  }
}

同时添加标量元数据

您可以参照以下方式，在上述向量写入的命令中添加自定义标量元数据。添加后，可以用于向量和标量混合检索。

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "技术文档内容" \                                                      
  --metadata '{"category": "technology", "version": "1.0", "author": "admin"}'     //添加自定义标量元数据，用户向量和标量混合检索

用户自定义的元数据字段将与系统自动添加的字段合并存储。

返回示例

{
  "key": "c0ed4d9d-5301-49a5-82b7-eaf9d02b04a9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "category": "technology",      //已添加的自定义元数据
    "version": "1.0",              //已添加的自定义元数据
    "author": "admin",             //已添加的自定义元数据
    "OSS-VECTORS-EMBED-SRC-CONTENT": "技术文档内容",
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

第三步：向量检索

OSS 向量 Bucket 提供 QueryVectors 接口，可以发起向量的相似度检索。使用向量的相似度检索之前，需要先将 Query 内容（文本或图片）进行向量化，然后在向量索引中查找语义最相似的向量。OSS-Vectors-Embed_CLI 提供简单的命令语句，快速完成 Query 内容的向量化和相似度检索。

重要：查询时使用的向量模型必须与索引数据所用的模型保持一致。

根据文本进行向量相似度检索

根据文本查询相似向量，其中--top-k 参数控制检索返回的结果数量。执行以下命令示例，在 my-index 索引中搜索与“什么是人工智能”语义最相似的向量结果。

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "什么是人工智能" \               // Query 检索文本
  --top-k 100                                 // 检索返回 100 个最相似的向量结果

返回示例

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",                   //检索返回的向量结果，返回向量 Key-Value 和标量元数据
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSS-VECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

根据图片进行向量相似度检索

可以根据图片来检索最相似的向量数据，以实现“以图搜图”（查找与图像匹配的图片）等应用场景。

请求示例

oss-vectors-embed \
  --account-id 1234567890123456 \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id qwen2.5-vl-embedding \
  --image "./query-images/similar-product.jpg" \     //Query 检索图片
  --top-k 100                                        // 检索返回 100 个最相似的向量结果

返回示例

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          //检索返回的向量结果，返回向量 Key-Value 和标量元数据
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "similar-product.png"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "image",
    "model": "qwen2.5-vl-embedding",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

若希望使用以表格形式输出检索结果，也可以使用 --output table 参数可将默认的 JSON 输出转换为表格格式，更便于人工阅读、交互式探索和调试。

请求示例

oss-vectors-embed \
--account-id <your-account-id> \
--vectors-region cn-hangzhou \
query \
--vector-bucket-name my-vector-bucket \
--index-name my-index \
--model-id text-embedding-v4 \
--text "./queries/user-question.txt" \
--top-k 3 \
--output table                            //指定为表格形式输出检索结果

返回示例

Query Results
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Rank ┃ Vector Key             ┃ Distance ┃ Metadata               ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1    │ doc:auth-setup         │ N/A      │ {"category": "docs"}   │
│ 2    │ doc:security-config    │ N/A      │ {"category": "docs"}   │
│ 3    │ doc:api-reference      │ N/A      │ {"category": "docs"}   │
└──────┴────────────────────────┴──────────┴────────────────────────┘
Query Summary:
  Model: text-embedding-v4
  Results Found: 3
  Query Dimensions: 1024

注意：Distance 列显示 N/A 表示查询时未指定返回距离值。如需显示，请在命令中添加 --return-distance 参数。

使用向量和标量混合检索

可以使用 --filter 参数来进行标量元数据后过滤，进而缩小查询范围，实现更精确的搜索。OSS-Vectors-Embed-CLI 命令行工具支持根据单一标量元数据进行简单过滤，也可以根据多个条件进行组合过滤。

  • 使用单一标量元数据进行简单过滤

如查询 category 为 technology 的向量：

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "技术文档" \
  --filter '{"category": {"$eq": "technology"}}' \  //通过 Filter 参数实现标量元数据过滤
  --top-k 20 \
  --return-metadata

返回示例

{
  "results": [
    {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSS-VECTORS-EMBED-SRC-CONTENT": "技术文档内容",
        "version": "1.0",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "test1",
    "resultsFound": 4,
    "queryDimensions": 1024
  }
}
  • 使用过滤语法根据多个过滤条件进行组合过滤

OSS-Vectors-Embed-CLI 命令行工具支持基于过滤语法组合多个过滤条件查询，如 AND、OR 等。以下对 AND 条件进行举例。

请求示例

# AND: 两个条件都必须匹配
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "API 参考" \
  --filter '{"$and": [{"category": "documentation"}, {"version": "3.0"}]}' \  //组合过滤条件
  --top-k 5

返回示例

{
  "results": [
  {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSS-VECTORS-EMBED-SRC-CONTENT": "API 参考",
        "version": "1.0",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 5,
    "queryDimensions": 1024
  }
}

更多的灵活自定义能力

批量处理能力

CLI 工具支持使用通配符对整个目录的文件进行批量处理。在批量模式下，CLI 会自动并行发起请求以提高处理效率。以下为批量处理 OSS 某一 prefix 下文件的命令示例。

请求示例

oss-vectors-embed \
  --account-id 1234567890123456 \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text "oss://bucket/path/*"             //对 OSS 该 Prefix 下的文件批量发起向量化和向量结果的写入

返回示例

{
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 2,
  "processedFiles": 2,
  "failedFiles": 0,
  "totalVectors": 2,
  "vectorKeys": [
    "1001dfcb-1e78-450b-8526-a9c92fa308c6",
    "b6aa1da0-adc7-489e-83e2-e39ff2e1fb9d"
  ]
}

还可以使用 --max-workers 参数用于控制并发请求数。OSS 向量 Bucket 支持每个请求批量写入最多 500 行向量数据，并设置最大 5 个并发，即每秒最多写入 2500 行向量。若您有 1000 万行向量需要写入，大概需要 1 小时左右。

请求示例

oss-vectors-embed \
  --account-id 1234567890123456 \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text "./documents/*.txt" \
  --max-workers 5                            //设置并发

自定义向量键

CLI 工具可以灵活指定向量 Key 值，如设置为特定 Key，或者将向量 Key 设置为原始对象 Key 值。同时，也可以指定向量 Key 值的前缀。

  • 将某一自定义 Key 设置为向量 Key

返回示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "文档内容" \
  --key "doc-001"                             //自定向量 Key 值为“doc-001”

返回示例

{
 "key": "doc-001",         //向量 Key 值为“doc-001”    
 "bucket": "my-test-2",
 "index": "test1",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSS-VECTORS-EMBED-SRC-CONTENT": "文档内容",
   "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}
  • 将原始文件 Key 值设置为向量 Key

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text "article.txt" \
  --filename-as-key                //将原始文件 Key 值“article.txt”设置为向量 Key 值

返回示例

{
  "key": "article.txt",            //向量 Key 值设置为“article.txt”   
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSS-VECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式。从清晨被智能闹钟根据睡眠周期轻柔唤醒，到通勤途中语音助手为我们规划最优路线；从家中智能音箱播放个性化新闻摘要，到工作时AI工具自动生成报告、翻译文档、优化流程——AI已悄然融入日常的每个角落。",
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSS-VECTORS-EMBED-SRC-LOCATION": "article.txt"
  }
}
  • 为向量 Key 值添加 Prefix

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "文档内容" \
  --key "doc-001" \
  --key-prefix "project-a/"            //添加向量 Key 值的 Prefix

返回示例

{
  "key": "project-a/doc-001",          //向量 Key 值添加了“project-a/”的 Prefix
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSS-VECTORS-EMBED-SRC-CONTENT": "文档内容",
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

自定义模型参数

通过 --dashscope-inference-params 参数可以精细控制向量模型的行为，以满足不同业务场景的需求。

  • 向量写入时自定义模型的输出类型和向量维度

请求示例

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "技术文档内容" \
  --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'  //自定义模型的输出类型和向量维度

返回示例

{
 "key": "73359c62-55a7-458a-a171-003755f3338e",
 "bucket": "my-vector-bucket",
 "index": "my-index",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSS-VECTORS-EMBED-SRC-CONTENT": "文档内容",
   "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}
  • 检索向量时自定义文本截断策略

请求示例

oss-vectors-embed \
  --account-id 1234567890123456 \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id qwen2.5-vl-embedding \
  --text-value "技术文档" \
  --dashscope-inference-params '{"truncate": "END"}' \   //设置文本截断策略
  --top-k 10
  --return-distance

返回示例

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSS-VECTORS-EMBED-SRC-CONTENT": "技术文档",
        "OSS-VECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

更多参考

OSS-Vectors-Embed-CLI 命令行工具支持阿里云百炼的向量化模型，包括文本向量模型和多模态向量模型，详情可以查看 OSS 官网帮助文档说明。同时，关于向量写入参数、向量检索参数和过滤语法说明，可以查看 OSS 官网帮助文档查看参数说明。

文章标签：
对象存储
对象存储
索引
人工智能
存储
API
相关实践学习
对象存储OSS快速上手——如何使用ossbrowser
本实验是对象存储OSS入门级实验。通过本实验，用户可学会如何用对象OSS的插件，进行简单的数据存、查、删等操作。
阿里云存储
目录
相关文章
问号云
|
8天前
|
人工智能 安全 Linux
【OpenClaw保姆级图文教程】阿里云/本地部署集成模型Ollama/Qwen3.5/百炼 API 步骤流程及避坑指南
2026年，AI代理工具的部署逻辑已从“单一云端依赖”转向“云端+本地双轨模式”。OpenClaw（曾用名Clawdbot）作为开源AI代理框架，既支持对接阿里云百炼等云端免费API，也能通过Ollama部署本地大模型，完美解决两类核心需求：一是担心云端API泄露核心数据的隐私安全诉求；二是频繁调用导致token消耗过高的成本控制需求。
问号云
5142 9
OpenClaw
|
15天前
|
人工智能 JavaScript Ubuntu
5分钟上手龙虾AI！OpenClaw部署（阿里云+本地）+ 免费多模型配置保姆级教程（MiniMax、Claude、阿里云百炼）
OpenClaw（昵称“龙虾AI”）作为2026年热门的开源个人AI助手，由PSPDFKit创始人Peter Steinberger开发，核心优势在于“真正执行任务”——不仅能聊天互动，还能自动处理邮件、管理日程、订机票、写代码等，且所有数据本地处理，隐私完全可控。它支持接入MiniMax、Claude、GPT等多类大模型，兼容微信、Telegram、飞书等主流聊天工具，搭配100+可扩展技能，成为兼顾实用性与隐私性的AI工具首选。
OpenClaw
21058 114
想当龙的猫
|
7天前
|
JavaScript Linux API
保姆级教程，通过GACCode在国内使用Claudecode、Codex！
保姆级教程，通过GACCode在国内使用Claudecode、Codex！
想当龙的猫
4576 1
保姆级教程，通过GACCode在国内使用Claudecode、Codex！
阿里云云原生
|
12天前
|
人工智能 安全 前端开发
Team 版 OpenClaw：HiClaw 开源，5 分钟完成本地安装
HiClaw 基于 OpenClaw、Higress AI Gateway、Element IM 客户端+Tuwunel IM 服务器（均基于 Matrix 实时通信协议）、MinIO 共享文件系统打造。
阿里云云原生
8060 7
一条云
|
14天前
|
人工智能 JavaScript API
保姆级教程：OpenClaw阿里云/本地部署配置Tavily Search skill 实时联网，让OpenClaw“睁眼看世界”
默认状态下的OpenClaw如同“闭门造车”的隐士，仅能依赖模型训练数据回答问题，无法获取实时新闻、最新数据或训练截止日期后的新信息。2026年，激活其联网能力的最优方案是配置Tavily Search技能——无需科学上网、无需信用卡验证，每月1000次免费搜索额度完全满足个人需求，搭配ClawHub技能市场，还能一键拓展天气查询、邮件管理等实用功能。
一条云
8035 5
云存储

技术博文

热门文章

最新文章

  • 1
    【推荐几款实用的网盘资源搜索引擎】
  • 2
    AI时代：云存储加速多模态数据存储与管理创新
  • 3
    U盘文件损坏且无法读取怎么修复？五个方法帮你搞定
  • 4
    如何使用基站查询API帮你解析地理位置？
  • 5
    SMB协议基础篇
  • 6
    【提取翻译竖排文字日文图片的软件】竖排的日语图片文字识别翻译，竖排的日语图片文字如何识别，竖排日语图片识别后转横排，竖排的日语识别比较友好的方法
  • 7
    银行卡归属地及开户行查询API查询实战指南
  • 8
    【qemu虚拟化】将img镜像文件转换为VMware虚拟机
  • 9
    商品条码查询 API 实战指南：掌握商品“唯一身份标识”
  • 10
    阿里云联合上海交大荣膺 FAST'26 最佳论文：揭秘云上本地存储的演进与未来发展
  • 1
    最佳实践：OSS AP 和云网络 Gateway Endpoint
    18
  • 2
    OSS 向量 Bucket 最佳实践：快速构建多模态图片语义检索
    21
  • 3
    使用 OSS-Vectors-Embed-CLI 工具三步搭建多模态语义检索系统
    27
  • 4
    【服务器数据恢复】H3C华三Ceph分布式存储文件丢失数据恢复案例
    228
  • 5
    基于 Cloudflare Workers 构建高性能知识库镜像服务：反向代理与 HTML 动态重写实践
    1066
  • 6
    银行卡归属地及开户行查询API查询实战指南
    2254
  • 7
    银行卡三要素API实践指南：实现交易安全闭环
    658
  • 8
    手机空号检测API：接口技术详解
    1124
  • 9
    全国空气质量查询API：让空气质量数据成为智慧生活的基石（含Python接入指南）
    600
  • 10
    银行卡联行号查询API：在风控中的落实践
    738

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    云安全中心：病毒查杀