文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>向量存储与检索>向量存储桶>工具指南 >cos-vectors-embed-cli>常用命令示例

常用命令示例

最近更新时间：2026-05-07 15:19:11

我的收藏

本页目录：

本文通过具体示例展示 cos-vectors-embed-cli 工具的使用方式。以 Linux 环境为例，在执行后续命令之前，首先配置了如下所示环境变量（有关各环境变量的含义，可参见 下载与安装配置）：
# COS 访问凭证
export COS_SECRET_ID="your-secret-id"
export COS_SECRET_KEY="your-secret-key"

# COS 地域
export COS_REGION="ap-guangzhou"

# Embedding API 凭证
export EMBEDDING_API_BASE="https://api.openai.com/v1"
export EMBEDDING_API_KEY="api-keyxxxx"

向量写入

使用 put 命令将数据向量化并写入 COS 向量索引。工具会自动完成：读取输入内容 > 调用 Embedding 模型生成向量 > 组装键和元数据 > 写入向量存储桶。
说明：
每个文件作为一个整体生成单个向量嵌入，暂不支持文档分块。
如果不主动使用 --output table 参数，向量写入命令执行后将返回一个 json 字符串，向量写入返回内容示例如下：
{
  "processed_count": 1,
  "keys": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "content_type": "text",
  "dimensions": 768
}
字段
说明
字段类型
什么情况下返回
processed_count
成功写入的向量条数
Number
总是
failed_count
最终写入失败的向量条数
Number
批量写入
elapsed_time
批量写入总耗时，如 "1.3s"
String
批量写入
keys
成功写入的向量 key 列表
List of String
总是
content_type
本次输入内容的类型，例如文本、图片等
String
单条写入
dimensions
写入向量维度
Number
单条写入
errors
错误详情列表
Object
批量写入且存在失败
errors 字段具体格式如下：
字段
说明
字段类型
什么情况下返回
source
出错来源，可能是文件路径、COS URI 或 key
String
批量写入且存在失败
error
错误原因描述
String
批量写入且存在失败

向量写入方式

直接输入文本字符串

最简单的写入方式，将一段文本直接向量化存储。例如下列命令表示将 “北京是...”这段文本通过调用 text-embedding-3-small 模型向量化后得到的向量存入 mybucket-1250000000 桶下的 myindex 索引中。
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "北京是中国的首都，拥有故宫、长城等著名景点。"
返回示例（JSON 格式）：
{
  "processed_count": 1,
  "keys": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "content_type": "text",
  "dimensions": 768
}

读取本地文本文件作为输入

从本地文件读取内容并向量化：
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text '/path/to/dir/document.txt'

读取 COS 对象作为输入

直接从 COS 存储桶中读取对象进行向量化：
说明：
使用 cos:// URI 时，工具会自动读取对象内容。读取操作使用的 COS 凭证与写入操作相同。当前支持的文件格式可参见 常见问题。
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "cos://source-bucket-1250000000/documents/report.txt"

添加标量元数据

说明：
建议为向量添加有意义的元数据，便于后续查询和过滤，例如可以在元数据中添加分类、标签等属性信息，或者当前向量对应的文件信息，这取决于具体使用场景。
通过 --metadata 参数以 JSON 格式添加自定义标量字段，写入后可用于混合检索（向量 + 标量过滤）：
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "2024年Q4财务报告摘要" \\
  --metadata '{"category": "finance", "quarter": "Q4", "year": 2024}'
工具会自动附加以下系统元数据字段：
系统字段
说明
示例
COSVECTORS-EMBED-SRC-LOCATION
来源文件路径或 URI（仅文件/URI 输入时设置）
document.txt、cos://bucket/file.txt
COSVECTORS-EMBED-SRC-TYPE
内容类型
text
自定义元数据会与系统元数据合并。如有键名冲突，自定义值优先。

向量检索

使用 query 命令将数据向量化并查询 COS 向量索引。工具会自动完成：读取输入内容 > 调用 Embedding 模型生成向量 > 利用向量从向量存储桶指定索引检索最相似的向量。
如果不主动使用 --output table 参数，向量检索命令执行后将返回一个 json 字符串，向量检索返回内容示例如下：
{
  "distanceMetric": "euclidean",
  "vectors": [
    {
      "key": "beijing.txt",
      "metadata": {
        "COSVECTORS-EMBED-SRC-LOCATION": "/path/to/dir/beijing.txt",
        "COSVECTORS-EMBED-SRC-TYPE": "text"
      },
      "distance": 0.36225668
    }
  ]
}
其格式与向量桶 QueryVectors 接口返回内容格式一致，详情可参见 Query Vectors 接口介绍。

向量检索方式

直接使用文本检索

cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "推荐北京的旅游景点" \\
  --top-k 5
返回示例：
{
  "results": [
    {
      "key": "beijing-travel",
      "distance": 0.1234,
      "metadata": {
        "COSVECTORS-EMBED-SRC-TYPE": "text",
        "category": "travel"
      }
    }
  ]
}

使用本地文件作为检索输入

cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "/path/to/dir/query.txt" \\
  --top-k 10

使用 COS 对象作为检索输入

cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "cos://source-bucket-1250000000/queries/query.txt" \\
  --top-k 10

向量和标量混合检索

使用 --filter 参数在向量相似度检索的基础上叠加标量过滤条件。

单条件过滤

# 仅在 category 为 "finance" 的向量中检索
cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "季度收入分析" \\
  --filter '{"category": {"$eq": "finance"}}' \\
  --top-k 5

多条件组合过滤

# AND 组合：category 为 "finance" 且 year >= 2020
cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "投资趋势" \\
  --filter '{"$and": [{"category": {"$eq": "finance"}}, {"year": {"$gte": 2020}}]}'

# OR 组合：category 为 "finance" 或 "tech"
cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "行业分析" \\
  --filter '{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}'

表格形式输出

注意：
表格形式输出只会展示部分字段，每个向量的元数据信息也只展示 80 字符，如需完整信息，请使用 json 输出格式。
cos-vectors-embed query \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "搜索查询" \\
  --output table
输出示例：
                                        Query Results
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Key                                  ┃ Distance ┃ Metadata                            ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ a1398448-4a6e-47a4-b816-c35d702bdc44 │ 0        │ {"COSVECTORS-EMBED-SRC-LOCATION":   │
│   │                                      │          │ "inline",                           │
│   │                                      │          │ "COSVECTORS-EMBED-SRC-TYPE":        │
│   │                                      │          │ "text"}                             │
└───┴──────────────────────────────────────┴──────────┴─────────────────────────────────────┘

Returned 1 result(s)

进阶用法

批量处理

说明：
批量处理通常使用通配符以匹配多个对象，但本工具仅处理已识别的文本扩展名（.txt、.md、.csv、.json、.xml、.html 等），详情可参见 常见问题。

使用本地通配符批量写入

通过 glob 模式批量处理目录中的文件：
# 处理目录中所有 .txt 文件
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "/path/to/dir/*.txt" \\
  --filename-as-key

使用 COS 前缀批量写入

通过 COS URI 前缀通配符处理存储桶中的多个对象：
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "cos://source-bucket-1250000000/documents/*" \\
  --filename-as-key

并发控制

说明：
对于大量文件处理，建议搭配使用 --key-prefix 组织向量键。
通过 --max-workers 和 --batch-size 调整批量处理的性能：
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "/path/to/dir/*.txt" \\
  --filename-as-key \\
  --max-workers 8 \\
  --batch-size 200
批量处理具有错误容忍能力：单个文件处理失败不会中断整批，处理结束后会显示成功和失败的汇总信息。

自定义向量键

显式指定键值

cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "自定义键示例" \\
  --key "my-custom-key-1"

使用文件名作为键

cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text '/path/to/dir/document.txt' \\
  --filename-as-key

添加键前缀

为所有生成的键添加统一前缀，便于分类管理：
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text "/path/to/dir/*.txt" \\
  --filename-as-key \\
  --key-prefix "project-a/"

自定义模型推理参数

通过 --embedding-inference-params 传递额外的推理参数（JSON 格式）给 Embedding 模型：
# 指定输出维度为 512
cos-vectors-embed put \\
  --vector-bucket-name mybucket-1250000000 \\
  --index-name myindex \\
  --model-id text-embedding-3-small \\
  --text-value "自定义参数示例" \\
  --embedding-inference-params '{"dimensions": 512}'
中国站