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

AIData搭子
1 阅读19分钟

向量数据作为 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 命令行工具的灵活自定义能力，如批量写入、自定义向量键、自定义向量模型参数等。

第一步：环境准备

在环境配置步骤中，您需要配置访问凭证、安装 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 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 官网帮助文档查看参数说明。

avatar
文章
阅读
粉丝