使用OSS Vectors Embed CLI工具写入和检索向量数据 - 对象存储 OSS

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

无缝集成：便捷调用阿里云百炼服务实现数据向量化。
多源输入：支持对本地文件、OSS对象、第三方文件 URL或文本字符串等多种数据格式进行向量化。
灵活处理：支持单文件处理与某一路径下的批量向量化转换。
深度定制：灵活设置向量 Key 值、标量元数据。
多模态检索：支持根据文本进行相似度语义检索、根据图片进行相似度语义检索、根据视频进行相似度语义检索，赋能多元化业务场景。

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

环境准备

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

已开通OSS服务，并获取AccessKey ID 和 AccessKey Secret 。
已开通阿里云百炼服务，并获取 API Key。

配置访问凭证

将访问凭证配置为环境变量。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 中创建索引，配置与向量模型匹配的向量维度。

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

写入向量

put 命令用于将输入数据生成向量嵌入，并存储到 OSS 向量索引。每个文件会被处理为一个独立的嵌入，当前不支持对长文档进行自动分块。

写入文本

使用文本向量模型（如 text-embedding-v4）处理文本。

直接输入文本

通过命令行直接输入文本以生成向量：

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 "人工智能正在改变我们的生活方式"

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

{
  "key": "3d8935dd-6395-4c9c-a501-df902846ec80",
  "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"
  }
}

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

读取本地文本文件

写入本地文件以生成向量：

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

读取 OSS 对象

直接写入存储在OSS中的对象，路径格式：oss://bucket-name/object-key：

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

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

命令返回示例：

{
  "key": "7ca24758-0d5b-46fe-ab90-db82be387650",
  "bucket": "my-vector-bucket",
  "index": "my-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"
  }
}

写入图片

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

读取本地图片

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 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": {
    "OSS-VECTORS-EMBED-SRC-LOCATION": "./images/photo.jpg",
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

读取 OSS 对象

直接写入存储在OSS图片对象，路径格式：oss://bucket-name/object-key：

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

命令返回示例：

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

读取图片URL

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 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": {
    "OSS-VECTORS-EMBED-SRC-LOCATION": "https://example.com/photo.jpg",
    "OSS-VECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

写入视频

使用多模态向量模型（如 qwen2.5-vl-embedding）处理图片和视频。输入源只支持 HTTP/HTTPS URL，不支持直接处理本地视频文件。

读取视频URL

视频处理会提取视频中的关键帧，并为每一帧生成一个独立的向量。每个向量都需要唯一的键，因此不支持使用 --key 或 --filename-as-key 参数。CLI 会为每一帧自动生成唯一的序列键。

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 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": {
    "OSS-VECTORS-EMBED-SRC-LOCATION": "https://example.com/video.mp4",
    "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"
  }
}

检索向量

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 "什么是人工智能" \
  --top-k 10

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

{
  "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
  }
}

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

元数据过滤检索

使用 --filter 参数可根据元数据筛选结果，缩小查询范围，实现更精确的搜索。

简单过滤

查询 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"}}' \
  --top-k 20 \
  --return-metadata

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

查询输出示例：

{
  "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
  }
}

组合过滤

基于过滤语法组合多个过滤条件查询。

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
  }
}

OR 查询：匹配任一条件。

# OR: 任一条件匹配
oss-vectors-embed \
  --account-id 1234567890123456 \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name my-vector-bucket \
  --index-name my-index \
  --model-id text-embedding-v4 \
  --text-value "入门指南" \
  --filter '{"$or": [{"category": "tutorial"}, {"category": "quickstart"}]}' \
  --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": "入门指南",
        "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
  }
}

多模态检索

多模态检索支持对同一向量集合同时进行文本查询和图像查询。这可以实现“以文搜图”（查找与文本描述相似的图像）或“以图搜图”（查找与图像匹配的图片）等应用场景。

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" \
  --top-k 10

查询输出示例：

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",
      "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 参数。

批量处理

CLI 支持使用通配符对整个目录的文件进行批量处理。在批量模式下，CLI 会自动并行发起请求以提高处理效率。

批量处理本地文件

处理本地目录下的所有文本文件：

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 "./documents/*.txt" \
  --filename-as-key

输出示例（与单文件不同，批量处理的输出返回处理摘要）：

{
  "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"
  ]
}

处理过程中会显示进度提示（Processing chunk 1..., STORED BATCH: 5 vectors 等）。

批量处理 OSS 文件

支持使用通配符批量处理 OSS 存储桶中指定前缀下的所有文件。

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/*"

输出示例：

{
  "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-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 8

输出示例：

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

自定义向量键

使用自定义键

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",
 "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"
 }
}

使用文件名作为键

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",
  "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"
  }
}

添加键前缀

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": "project-a/doc-001",
  "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
  }
}

支持的向量模型

文本向量模型

模型 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 对象时，指定该对象所在的地域

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

方式一：pip 安装（推荐）

方式二：开发模式安装

验证安装

创建向量存储资源

写入向量

写入文本

直接输入文本

读取本地文本文件

读取 OSS 对象

写入图片

读取本地图片

读取 OSS 对象

读取图片URL

写入视频

读取视频URL

添加元数据

检索向量

文本相似度检索

元数据过滤检索

简单过滤

组合过滤

多模态检索

表格输出格式

批量处理

批量处理本地文件

批量处理 OSS 文件

控制并发

自定义向量键

使用自定义键

使用文件名作为键

添加键前缀

自定义模型参数

使用自定义模型参数写入

使用自定义模型参数检索

支持的向量模型

文本向量模型

多模态向量模型

参数说明

全局参数

put 命令参数

query 命令参数

过滤语法

相关文档