使用 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 命令行工具的灵活自定义能力，如批量写入、自定义向量键、自定义向量模型参数等。
第一步：环境准备
在环境配置步骤中，您需要配置访问凭证、安装 OSS-Vectors-Embed-CLI 工具、创建向量 Bucket。
配置访问凭证
在使用 CLI 工具前，需要准备以下访问凭证：
将访问凭证配置为环境变量。CLI 在执行时会自动读取这些变量，无需在命令中重复提供。
安全提示：请勿在脚本中硬编码凭证，建议使用环境变量。
安装 OSS-Vectors-Embed-CLI 工具
支持 Python 3.9 或更高版本。
方式一：pip 安装（推荐）
方式二：开发模式安装
验证安装：
创建向量 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-
请求示例：
返回示例：
- 对本地文本文件生成向量并将其写入向量 Bucket
- 对 OSS 文本文件生成向量并将其写入向量 Bucket
请求示例：
返回示例：
写入图片文件的向量
以阿里云百炼多模态向量模型qwen2.5-vl-embedding为例，您可以根据自己的需求选择其他合适的向量模型。输入源支持本地文件、OSS 对象或 HTTP/HTTPS URL。
- 对本地图片文件生成向量并将其写入向量 Bucket-
请求示例：
返回示例：
- 对 OSS 图片文件生成向量并将其写入向量 Bucket
请求示例：
返回示例：
- 对 URL 文件生成向量并将其写入向量 Bucket
请求示例：
返回示例：
写入视频文件的向量
以阿里云百炼多模态向量模型qwen2.5-vl-embedding为例，您可以根据自己的需求选择其他合适的向量模型。输入源支持 OSS 视频文件、 HTTP/HTTPS URL 文件。
- 对 OSS 视频文件生成向量并将其写入向量 Bucket
请求示例：
返回示例：
- 对 URL 文件生成向量并将其写入向量 Bucket
请求示例：
返回示例：
同时添加标量元数据
您可以参照以下方式，在上述向量写入的命令中添加自定义标量元数据。添加后，可以用于向量和标量混合检索。
请求示例：
返回示例：
第三步：向量检索
OSS 向量 Bucket 提供 QueryVectors 接口，可以发起向量的相似度检索。使用向量的相似度检索之前，需要先将 Query 内容（文本或图片）进行向量化，然后在向量索引中查找语义最相似的向量。OSS-Vectors-Embed_CLI 提供简单的命令语句，快速完成 Query 内容的向量化和相似度检索。
重要：查询时使用的向量模型必须与索引数据所用的模型保持一致。
根据文本进行向量相似度检索
根据文本查询相似向量，其中 --top-k 参数控制检索返回的结果数量。执行以下命令示例，在 my-index 索引中搜索与“什么是人工智能”语义最相似的向量结果。
请求示例：
返回示例：
根据图片进行向量相似度检索
可以根据图片来检索最相似的向量数据，以实现“以图搜图”（查找与图像匹配的图片）等应用场景。
请求示例：
返回示例：
若希望使用以表格形式输出检索结果，也可以使用 --output table 参数可将默认的 JSON 输出转换为表格格式，更便于人工阅读、交互式探索和调试。
请求示例：
返回示例：
注意：Distance 列显示 N/A 表示查询时未指定返回距离值。如需显示，请在命令中添加 --return-distance 参数。
使用向量和标量混合检索
可以使用 --filter 参数来进行标量元数据后过滤，进而缩小查询范围，实现更精确的搜索。OSS-Vectors-Embed-CLI 命令行工具支持根据单一标量元数据进行简单过滤，也可以根据多个条件进行组合过滤。
- 使用单一标量元数据进行简单过滤
如查询 category 为 technology 的向量：
请求示例：
返回示例：
- 使用过滤语法根据多个过滤条件进行组合过滤
OSS-Vectors-Embed-CLI 命令行工具支持基于过滤语法组合多个过滤条件查询，如 AND、OR 等。以下对 AND 条件进行举例。
请求示例：
返回示例：
更多的灵活自定义能力
批量处理能力
CLI 工具支持使用通配符对整个目录的文件进行批量处理。在批量模式下，CLI 会自动并行发起请求以提高处理效率。以下为批量处理 OSS 某一 prefix 下文件的命令示例。
请求示例：
返回示例：
还可以使用 --max-workers 参数用于控制并发请求数。OSS 向量 Bucket 支持每个请求批量写入最多 500 行向量数据，并设置最大 5 个并发，即每秒最多写入 2500 行向量。若您有 1000 万行向量需要写入，大概需要 1 小时左右。
请求示例：
自定义向量键
CLI 工具可以灵活指定向量 Key 值，如设置为特定 Key，或者将向量 Key 设置为原始对象 Key 值。同时，也可以指定向量 Key 值的前缀。
- 将某一自定义 Key 设置为向量 Key
请求示例：
返回示例：
- 将原始文件 Key 值设置为向量 Key
请求示例：
返回示例：
- 为向量 Key 值添加 Prefix
请求示例：
返回示例：
自定义模型参数
通过 --dashscope-inference-params 参数可以精细控制向量模型的行为，以满足不同业务场景的需求。
- 向量写入时自定义模型的输出类型和向量维度
请求示例：
返回示例：
- 检索向量时自定义文本截断策略
请求示例：
返回示例：
更多参考
OSS-Vectors-Embed-CLI 命令行工具支持阿里云百炼的向量化模型，包括文本向量模型和多模态向量模型，详情可以查看 OSS 官网帮助文档说明。同时，关于向量写入参数、向量检索参数和过滤语法说明，可以查看 OSS 官网帮助文档查看参数说明。
浙公网安备 33010602011771号