对象存储下载与安装配置

步骤一：环境准备
使用本工具前，请确保：
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 模型输出维度一致，否则写入会失败。
获取向量索引维度：可在 控制台 切换到向量桶列表页签，进入具体向量桶信息页面后，点击左侧索引列表，向量维度列的数值即为具体索引维度。
获取模型输出维度：一般可在 Embedding 服务提供商模型介绍页面可以看到，如果是使用 ollama 部署的本地模型，可使用命令 ollama show <模型名称> 获取模型详细信息，embedding length值即是维度。
步骤二：安装 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.git
cd cos-vectors-embed-cli
pip 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

变量名	说明	变量类型	是否必选
`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 安装（推荐）

方式二：源码开发安装

验证安装

步骤三：环境变量配置

工具卸载