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

参数选项

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

我的收藏

本页目录：

参数概述

执行过程中使用的一些参数值可以通过多种方式配置，按优先级从高到低的顺序为：
1. 子命令 CLI 参数：例如 cos-vectors-embed put --region ap-beijing ...。
2. 全局 CLI 参数：例如 cos-vectors-embed --region ap-guangzhou put ...。
3. 环境变量配置：例如 COS_REGION=ap-guangzhou。
4. 自动生成的默认值：COS_DOMAIN 未设置时自动生成为 vectors.{region}.coslake.com。

全局参数

用户可通过--help 选项来查看工具的全局参数和用法。
cos-vectors-embed --help
help 信息如下所示：
Usage: cos-vectors-embed [OPTIONS] COMMAND [ARGS]...

  COS Vectors Embed CLI - Vectorize content and store in COS Vector Buckets.

Options:
  --region TEXT  COS region (e.g. ap-guangzhou). Falls back to COS_REGION env
                 var.
  --domain TEXT  COS Vectors service domain (e.g. vectors.ap-
                 guangzhou.coslake.com). Falls back to COS_DOMAIN env var.
  --debug        Enable debug output with detailed logging.
  --version      Show the version and exit.
  --help         Show this message and exit.

Commands:
  put    Vectorize content and write to a COS vector index.
  query  Query a COS vector index by similarity search.
参数
说明
参数值类型
是否必选
--region TEXT
COS 地域，如果不配置环境变量则需要通过参数选项设置，关于当前开放的地域信息，请参见 产品概述。
示例值：ap-guangzhou
String
否
--domain TEXT
COS 向量服务域名，格式为 vectors.{region}.coslake.com，如果不配置环境变量则需要通过参数选项设置。其中 region 为地域信息。
示例值：vectors.ap-guangzhou.coslake.com
String
否
--debug
启用调试日志。
无参数值
否
--version
显示版本号。
无参数值
否
--help
显示帮助信息。
无参数值
否

put 子命令参数

用户可通过 --help 选项来查看 put 子命令参数和用法
cos-vectors-embed put --help
help 信息如下所示：
Usage: cos-vectors-embed put [OPTIONS]

  Vectorize content and write to a COS vector index.

Options:
  --vector-bucket-name TEXT       COS vector bucket name.  [required]
  --index-name TEXT               Vector index name.  [required]
  --model-id TEXT                 Embedding model identifier.  [required]
  --text-value TEXT               Direct text string to embed.
  --text TEXT                     Text file path, glob pattern, COS URI
                                  (cos://bucket/key), or COS prefix
                                  (cos://bucket/prefix/*).
  --video TEXT                    Local video file path (reserved for future
                                  use).
  --key TEXT                      Custom vector key. Only for single-item
                                  puts.
  --key-prefix TEXT               Prefix for generated vector keys.
  --filename-as-key               Use source filename as vector key.
  --metadata TEXT                 Custom metadata as JSON string, e.g.
                                  '{"category": "finance"}'.
  --provider TEXT                 Embedding provider type. Default: openai-
                                  compatible.
  --embedding-api-base TEXT       Embedding API base URL. Falls back to
                                  EMBEDDING_API_BASE env var.
  --embedding-api-key TEXT        Embedding API key. Falls back to
                                  EMBEDDING_API_KEY env var.
  --embedding-inference-params TEXT
                                  Extra inference parameters as JSON string.
  --max-workers INTEGER           Number of parallel worker threads for batch
                                  processing. Default: 4.
  --batch-size INTEGER            Number of items per storage batch. Default:
                                  100.
  --output [json|table]           Output format. Default: json.
  --region TEXT                   Override global --region for this command.
  --domain TEXT                   Override global --domain for this command.
  --help                          Show this message and exit.
注意：
当前的 put 子命令数据输入方式有两种，--text-value用于直接文本输入，而--text需要从文本文件读取，输入方式必须使用其中一种。
参数
说明
类型
是否必选
--vector-bucket-name TEXT
向量桶名称，<BucketName-APPID>格式，例如 examplebucket-1250000000，长度限制3-63个字符。
String
是
--index-name TEXT
索引名称，由小写字母、数字、短横线(-)、点(.)组成，首尾必须是小写字母或数字，长度限制3-63字符。
String
是
--model-id TEXT
Embedding 模型标识符。
示例值：text-embedding-3-small
String
是
--text-value TEXT
直接输入的文本字符串。
String
否
--text TEXT
文本输入路径，支持通配符同时处理多个文件。
示例值："docs/*.txt"
String
否
--key TEXT
自定义向量键，默认自动生成 UUID 作为向量键。
示例值："doc123"
String
否
--key-prefix TEXT
向量键前缀。
示例值："docs/"
String
否
--filename-as-key
使用源文件名作为向量键。
无参数值
否
--metadata TEXT
自定义元数据，是一段 JSON 表示的 kv 结构，详细要求可参见 向量桶 PutVectors 接口。
示例值：'{"category":"finance"}'
String
否
--provider TEXT
Embedding 接口类型，当前仅支持 openai-compatible，表示 OpenAI 兼容接口，默认openai-compatible。
示例值：openai-compatible
String
否
--embedding-api-base TEXT
Embedding API 接口提供的 URL，如果没有通过环境变量配置，此处必须配置。
示例值：
OpenAI Embedding 服务：https://api.openai.com/v1
本地 Ollama Embedding 服务：http://localhost:11434/v1
String
否
--embedding-api-key TEXT
Embedding API 密钥，如果没有通过环境变量配置，此处必须配置。
String
否
--max-workers INTEGER
并行线程数，建议取值 [1,16]，默认 4。
示例值：8
Integer
否
--batch-size INTEGER
每批次处理的文件数量，建议取值 [10, 500]，默认100 。
示例值：200
Integer
否

query 子命令参数

用户可通过 --help 选项来查看 query 子命令参数和用法
cos-vectors-embed query --help
help 信息如下所示：
Usage: cos-vectors-embed query [OPTIONS]

  Query a COS vector index by similarity search.

Options:
  --vector-bucket-name TEXT       COS vector bucket name.  [required]
  --index-name TEXT               Vector index name.  [required]
  --model-id TEXT                 Embedding model identifier.  [required]
  --text-value TEXT               Direct text string to query with.
  --text TEXT                     Text file path or COS URI (cos://bucket/key)
                                  containing the query.
  --top-k INTEGER                 Number of results to return. Default: 5.
  --filter TEXT                   Metadata filter as JSON string, e.g.
                                  '{"category": {"$eq": "finance"}}'.
  --return-distance / --no-return-distance
                                  Whether to return distance scores. Default:
                                  true.
  --return-metadata / --no-return-metadata
                                  Whether to return metadata. Default: true.
  --provider TEXT                 Embedding provider type. Default: openai-
                                  compatible.
  --embedding-api-base TEXT       Embedding API base URL. Falls back to
                                  EMBEDDING_API_BASE env var.
  --embedding-api-key TEXT        Embedding API key. Falls back to
                                  EMBEDDING_API_KEY env var.
  --output [json|table]           Output format. Default: json.
  --region TEXT                   Override global --region for this command.
  --domain TEXT                   Override global --domain for this command.
  --help                          Show this message and exit.
注意：
当前的 query 子命令数据输入方式有两种，--text-value用于直接文本输入，而--text需要从文本文件读取，输入方式必须使用一种。
参数
说明
类型
是否必选
--vector-bucket-name TEXT
向量桶名称，<BucketName-APPID>格式，例如 examplebucket-1250000000，长度限制3-63个字符。
String
是
--index-name TEXT
索引名称，由小写字母、数字、短横线(-)、点(.)组成，首尾必须是小写字母或数字，长度限制3-63字符。
String
是
--model-id TEXT
Embedding 模型标识符
String
是
--text-value TEXT
直接输入的查询文本
String
否
--text TEXT
文本文件路径或 COS URI
示例值：'/path/to/dir/document.txt'
String
否
--top-k INTEGER
返回结果数量，默认值 5 。
示例值：1
Integer
否
--filter TEXT
元数据过滤条件，详细语法可参见 向量桶 QueryVectors 接口。
示例值：'{"category": {"$eq": "finance"}}'
String
否
--return-distance/--no-return-distance
控制是否返回距离信息，默认返回
无参数值
否
--return-metadata/--no-return-metadata
控制是否返回元数据，默认返回
无参数值
否
--provider TEXT
Embedding 接口类型，当前仅支持 openai-compatible，表示 OpenAI 兼容接口，默认openai-compatible。
示例值：openai-compatible
String
否
--embedding-api-base TEXT
Embedding API 接口提供的 URL，如果没有通过环境变量配置，此处必须配置。
示例值：
OpenAI Embedding 服务：https://api.openai.com/v1
本地 Ollama Embedding 服务：http://localhost:11434/v1
String
否
--embedding-api-key TEXT
Embedding API 密钥，如果没有通过环境变量配置，此处必须配置。
String
否
--output [json|table]
控制检索结果的输出格式，取值 json 或 table，默认 json。
示例值：table
String
否
中国站