一、步骤一：环境准备
使用本工具前，请确保：
1. 已安装 Python 3.9 或更高版本。
·环境安装与配置详细操作请参见 Python 安装与配置。
·pip 环境安装与配置详细操作请参见 pip 安装说明。
2. 已开通腾讯云 COS 服务并获取访问凭证（SecretId / SecretKey）。获取方式请参见 腾讯云 API 密钥管理。
3. 已获取可用的 Embedding API 服务地址和密钥（如 OpenAI API Key、自建模型服务地址等）。若没有 API Key，可使用 Ollama 本地部署 Embedding 服务。
4. 已在腾讯云控制台创建 COS 向量存储桶和至少一个向量索引。创建方式请参见 COS 向量存储桶快速入门。
注意：创建向量索引时设置的维度必须与所使用的 Embedding 模型输出维度一致，否则写入会失败。
二、步骤二：安装 COS Vectors Embedding CLI 工具
本工具依赖 Python 环境，支持 Windows, Linux, MacOS 不同平台。
三、方式一：pip 安装（推荐）
pip install cos-vectors-embed-cli
四、方式二：源码开发安装
git clone https://github.com/TencentCloud/cos-vectors-embed-cli.gitcd cos-vectors-embed-clipip install -e .
五、验证安装
cos-vectors-embed –version
输出 cos-vectors-embed, version 0.1.1 即表示安装成功。
六、步骤三：环境变量配置
| 变量名 | 说明 | 变量类型 | 是否必选 |
| COS_SECRET_ID | 密钥 ID，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取请参见 子账号访问密钥管理。 | String | 是 |
| COS_SECRET_KEY | 密钥 Key，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取请参见 子账号访问密钥管理。 | String | 是 |
| COS_TOKEN | 当使用临时密钥时需要配置，关于临时密钥的更多信息，请参见 使用临时密钥访问 COS。 | String | 否 |
| COS_REGION | COS 地域，如果不配置环境变量则需要通过参数选项设置，关于当前开放的地域信息，请参见 产品概述。示例值：ap-guangzhou | String | 否 |
| COS_DOMAIN | COS 向量服务域名，格式为 vectors.{region}.coslake.com，如果不配置环境变量则需要通过参数选项设置。其中 region 为地域信息。示例值：vectors.ap-guangzhou.coslake.com | String | 否 |
| EMBEDDING_API_BASE | Embedding API 基础 URL，如果不配置环境变量则需要通过参数选项设置。示例值：Openai Embedding 服务：https://api.openai.com/v1本地 Ollama Embedding 服务：http://localhost:11434/v1 | String | 否 |
| EMBEDDING_API_KEY | Embedding API 密钥，如果不配置环境变量则需要通过参数选项设置，本地 Ollama Embedding 服务可配置为任意值。 | String | 否 |
七、工具卸载
若你不再需要 COS Vectors Embedding CLI 工具，可正常使用 pip 工具按如下方式卸载：
pip uninstall cos-vectors-embed-cli