# 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 >= 2020cos-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
20、并发控制
注意：说明：
注意：对于大量文件处理，建议搭配使用 –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
批量处理具有错误容忍能力：单个文件处理失败不会中断整批，处理结束后会显示成功和失败的汇总信息。
22、显式指定键值
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"
23、使用文件名作为键
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
24、添加键前缀
为所有生成的键添加统一前缀，便于分类管理：
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/"
25、自定义模型推理参数
通过 –embedding-inference-params 传递额外的推理参数（JSON 格式）给 Embedding 模型：
# 指定输出维度为 512cos-vectors-embed put \\ –vector-bucket-name mybucket-1250000000 \\ –index-name myindex \\ –model-id text-embedding-3-small \\ –text-value "自定义参数示例" \\ –embedding-inference-params '{"dimensions": 512}'