AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页 对象存储 用户指南 向量Bucket（邀测） 使用OSS Vectors Embed CLI工具写入和检索向量数据

使用OSS Vectors Embed CLI工具写入和检索向量数据

更新时间：
复制为 MD 格式
产品详情
我的收藏

OSS Vectors Embed CLI 命令行工具支持便捷调用阿里云百炼向量模型，将 OSS 或本地文件向量化并写入 OSS 向量 Bucket，同时支持多模态语义检索，简化 RAG 知识库、AI 助手等应用的开发流程。核心能力包括：

  • 无缝集成：便捷调用阿里云百炼服务实现数据向量化。

  • 多源输入：支持对本地文件、OSS对象、第三方文件 URL或文本字符串等多种数据格式进行向量化。

  • 灵活处理：支持单文件处理与某一路径下的批量向量化转换。

  • 深度定制：灵活设置向量 Key 值、标量元数据。

  • 多模态检索：支持根据文本进行相似度语义检索、根据图片进行相似度语义检索、根据视频进行相似度语义检索，赋能多元化业务场景。

通过 OSS Vectors Embed CLI，只需几条简单命令即可快速搭建多模态语义检索系统，并可按需配置批量写入、自定义向量键、自定义模型参数等灵活定制能力。

阿里云 OSS Vectors Embed CLI 目前处于预览版阶段，工具的部分参数可能会发生调整。

步骤一：环境准备

在使用 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 并配置索引：

  1. 创建向量 Bucket：在向量Bucket页面创建向量Bucket，用于存储向量数据和索引。

  2. 创建向量索引：在已创建的向量 Bucket 中创建索引，配置与向量模型匹配的向量维度。

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

步骤二：向量写入

OSS 向量 Bucket 提供 PutVectors 接口，将向量数据写入 OSS 向量 Bucket。OSS Vectors Embed CLI 将原始文件读取（GetObject）、调用阿里云百炼进行向量化、向量数据写入（PutVectors）等多次 API 调用封装为一条命令，只需执行单条put命令，即可完成向量数据的生产与写入。每个文件会被处理为一个独立的嵌入，当前不支持对长文档进行自动分块。

写入文本文件的向量

使用文本向量模型（如 text-embedding-v4）处理文本。输入源支持文本字符串、OSS 对象或本地文本文件。

直接输入文本

通过命令行直接输入文本生成向量并将其写入到向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --text-value:         直接输入文本

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "人工智能正在改变我们的生活方式"

命令返回示例（包含向量键、Bucket 信息和元数据）：

{
  "key": "3d8935dd-6395-4c9c-a501-df902846ec80",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

说明：CLI 会自动在元数据中添加源信息字段（OSSVECTORS-EMBED-SRC-*），用于追溯向量来源。

读取本地文本文件

写入本地文件以生成向量并将其写入到向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --text:               本地文件路径

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "<./documents/article.txt>"

命令返回示例：

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

读取 OSS 对象

直接写入存储在OSS中的对象（路径格式：oss://bucket-name/object-key）并将其写入到向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --region:             源文件 Bucket 所在地域
# --text:               源文件 OSS 路径

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "oss://<your-source-bucket>/<your-file>"

注意：需使用 --region 参数指定源 OSS 对象所在的地域。

命令返回示例：

{
  "key": "7ca24758-0d5b-46fe-ab90-db82be387650",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "This is a example file.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"
  }
}

写入图片文件的向量

使用多模态向量模型（如 qwen2.5-vl-embedding）处理图片和视频。输入源支持本地文件、OSS 对象或 HTTP/HTTPS URL。

读取本地图片

读取本地图片文件生成向量并将其写入向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --image:              本地图片文件路径

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "<./images/photo.jpg>"

命令返回示例：

{
  "key": "8fc8105b-d54f-464c-bf44-97b088d566ce",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "./images/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

读取 OSS 对象

读取存储在OSS图片文件（路径格式：oss://bucket-name/object-key）生成向量并将其写入向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --region:             源文件 Bucket 所在地域
# --image:              源图片 OSS 路径

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "oss://<your-source-bucket>/<your-image>"

命令返回示例：

{
  "key": "dbf57dfd-58be-4793-a484-a82eb86e0e08",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

读取图片URL

对 URL 文件生成向量并将其写入向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --image:              图片 URL 地址

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "https://example.com/photo.jpg"

命令返回示例：

{
  "key": "f15cfe75-d4de-497f-b441-3b08243cfa5e",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

写入视频文件的向量

使用多模态向量模型（如 qwen2.5-vl-embedding）处理图片和视频。输入源支持 OSS 视频文件、 HTTP/HTTPS URL 文件。视频处理会提取视频中的关键帧，并为每一帧生成一个独立的向量。每个向量都需要唯一的键，因此不支持使用 --key 或 --filename-as-key 参数。CLI 会为每一帧自动生成唯一的序列键。

读取OSS对象

对 OSS 视频文件生成预签名 URL，完成向量化并写入向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --region:             源视频 所在地域
# --video:              源视频 OSS 路径
# --presign-url:        对 OSS 地址生成签名 URL 后再访问（适用于私有 Bucket 等场景）

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "oss://<your-source-bucket>/<your-video>" \
  --presign-url

命令返回示例：

{
  "key": "55606734-8275-4329-96a3-3c156220et54",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

读取视频URL

对 URL 文件生成向量并将其写入向量 Bucket：

# 参数说明：
# --account-id:         阿里云 ID
# --vectors-region:     OSS 向量 Bucket 所在地域
# --vector-bucket-name: OSS 向量 Bucket 名称
# --index-name:         OSS 向量 Index 名称
# --model-id:           使用的向量模型
# --video:              视频 URL 地址

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "https://example.com/video.mp4"

命令返回示例：

{
  "key": "9157d87b-c44b-4c53-aceb-cd4be7fd8bd9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

写入时添加标量元数据

在向量写入的命令中添加自定义标量元数据，可用于向量和标量混合检索。

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-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",         //已添加的自定义元数据
    "OSSVECTORS-EMBED-SRC-CONTENT": "技术文档内容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

步骤三：向量检索

OSS 向量 Bucket 提供 QueryVectors 接口，可以发起向量的相似度检索。OSS-Vectors-Embed_CLI 提供query 命令用于执行相似度搜索。首先将查询内容（文本或图片）向量化，然后在向量索引中查找语义最相似的向量。

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

文本向量相似度检索

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

# --text-value: Query 检索文本
# --top-k:      检索返回最相似的向量结果数量

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "什么是人工智能" \
  --top-k 100

查询输出示例（包含向量键和元数据）：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "人工智能正在改变我们的生活方式",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

说明：默认不返回相似度距离。如需获取，添加 --return-distance 参数。

图片向量相似度检索

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

# --image:  Query 检索图片
# --top-k:  检索返回最相似的向量结果数量

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "./query-images/similar-product.jpg" \   
  --top-k 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": 100,
    "queryDimensions": 1024
  }
}

向量和标量混合检索

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

单条件简单过滤

查询 category 为 technology 的向量：

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

说明：--return-metadata 参数用于在结果中返回完整的元数据（包括用户自定义和 CLI 自动添加的字段）。

查询输出示例：

{
  "results": [
    {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSSVECTORS-EMBED-SRC-CONTENT": "技术文档内容",
        "version": "1.0",
        "OSSVECTORS-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 查询：匹配所有条件。

# AND: 两个条件都必须匹配
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-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": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSSVECTORS-EMBED-SRC-CONTENT": "API 参考",
        "version": "1.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 5,
    "queryDimensions": 1024
  }
}

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

# --output table： 指定为表格形式输出检索结果
oss-vectors-embed \
--account-id <your-account-id> \
--vectors-region cn-hangzhou \
query \
--vector-bucket-name <your-vector-bucket> \
--index-name <your-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 参数。

进阶配置

批量处理

CLI 支持使用通配符对整个目录的文件进行批量处理。在批量模式下，CLI 会自动并行发起请求以提高处理效率。以下示例使用通配符批量处理 OSS 存储桶中指定前缀下的所有文件。

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

命令返回示例：

{
  "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 参数用于控制并发请求数（默认为 4）。增加此值可以提高处理吞吐量，但会消耗更多的 API 配额。OSS 向量 Bucket 支持每个请求批量写入最多 500 行向量数据，并设置最大 5 个并发。

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

命令返回示例：

{
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 5,
  "processedFiles": 5,
  "failedFiles": 0,
  "totalVectors": 5,
  "vectorKeys": [
    "doc1.txt",
    "doc2.txt",
    "doc3.txt",
    "doc4.txt",
    "doc5.txt"
  ]
}

自定义向量键

CLI 工具支持灵活指定向量键值，可将其设置为特定自定义字符串，或直接使用原始文件名作为向量键，同时支持为向量键添加统一前缀。

自定义键值

通过 --key 参数将向量键设置为指定值：

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

命令返回示例：

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

原始文件 Key 设置为向量键

通过 --filename-as-key 参数将原始 Key 自动设置为向量键：

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

命令返回示例：

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

为向量键添加前缀

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

命令返回示例：

{
  "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": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "文档内容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

自定义模型参数

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

使用自定义模型参数写入

在向量化数据时，可以指定输出类型和维度等参数：

# dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'自定义模型的输出类型和向量维度
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-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": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "文档内容",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

使用自定义模型参数检索

检索向量时，可以控制文本截断策略等行为：

# --dashscope-inference-params '{"truncate": "END"}' 设置文本截断策略
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-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": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "技术文档",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

支持的向量模型

文本向量模型

模型 ID

默认维度

可选维度

text-embedding-v4

1024

2048/1536/768/512/256/128/64

text-embedding-v3

1024

768/512/256/128/64

text-embedding-v2

1536

-

text-embedding-v1

1536

-

多模态向量模型

模型 ID

维度

支持输入类型

qwen2.5-vl-embedding

2048/1024/768/512

文本、图片、视频、多图

tongyi-embedding-vision-plus

1152

文本、图片、视频、多图

tongyi-embedding-vision-flash

768

文本、图片、视频、多图

multimodal-embedding-v1

1024

文本、图片、视频

模型选择建议：

  • 纯文本场景：推荐使用 text-embedding-v4

  • 图文混合场景：推荐使用 qwen2.5-vl-embedding

  • 追求速度：可选用 tongyi-embedding-vision-flash

参数说明

全局参数

参数

是否必选

说明

--account-id

是

阿里云账号 ID

--vectors-region

是

向量 Bucket 所在的地域，例如cn-hangzhou

--vectors-endpoint

否

向量Bucket访问域名

--debug

否

启用调试模式

put 命令参数

参数

是否必选

说明

--vector-bucket-name

是

向量 Bucket 名称

--index-name

是

向量索引名称

--model-id

是

用于生成向量的 DashScope模型ID

--text-value

否

要处理的文本内容。与 --text、--image、--video 参数四选一

--text

否

要处理的文本文件路径或 OSS 对象路径

--image

否

要处理的图片文件路径、OSS 对象路径或 URL

--video

否

要处理的视频 URL

--key

否

为向量指定一个自定义的唯一键

--key-prefix

否

为自动生成的或指定的键添加前缀

--filename-as-key

否

使用输入文件的名称作为向量键

--dashscope-inference-params

否

传递给 DashScope 的模型特定参数（JSON 格式，例如'{"dimension": "1024"}'）

--metadata

否

以 JSON 字符串格式指定的元数据

--max-workers

否

批量处理时的最大并发请求数。默认为 4

--batch-size

否

批量写入时，单次请求包含的向量数量。取值范围：1-500。默认为 500

--output

否

指定输出格式。可选值为 json（默认）或 table

--region

否

当输入源为 OSS 对象时，指定该对象所在的地域

--presign-url

否

当输入源为 OSS 路径时，使用预签名 URL 访问。

query 命令参数

参数

是否必选

说明

--vector-bucket-name

是

向量 Bucket 名称

--index-name

是

向量索引名称

--model-id

是

用于生成向量的 DashScope模型ID

--text-value

否

要查询的文本内容

--text

否

包含查询文本的文件路径

--image

否

要查询的图片路径

--video

否

要查询的视频 URL

--top-k

否

返回最相似结果的数量，默认为 5

--filter

否

以 JSON 字符串格式指定的过滤条件

--return-distance

否

在结果中包含相似度距离值

--return-metadata

否

在结果中包含元数据。默认开启

--dashscope-inference-params

否

传递给 DashScope 的模型特定参数（JSON 格式，例如'{"truncate": "END"}'）

--output

否

指定输出格式。可选值为 json（默认）或 table

过滤语法

操作符

说明

示例

$eq

等于

{"category": {"$eq": "docs"}}

$ne

不等于

{"status": {"$ne": "deleted"}}

$in/$nin

在/不在列表中

{"tag": {"$in": ["a", "b"]}}

$and

逻辑与

{"$and": [{"a": 1}, {"b": 2}]}

$or

逻辑或

{"$or": [{"a": 1}, {"a": 2}]}

相关文档

关于OSS Vectors Embed CLI 工具的更多内容请参见GitHub 仓库。

上一篇：访问控制与日志下一篇：OSS向量Bucket最佳实践：快速构建多模态图片语义检索