该文章免费开放，不会收费，当心某平台

第一部分：准备阶段 (模型提供商上游确认)

在操作 VCPToolBox 之前，我这里使用的是LiteLLM作为聚合，这是需要确认的信息。

1. 检查 LiteLLM 运行状态

• 确保 LiteLLM 容器正在运行。
• 确保端口 4000 已在宿主机开放。

2. 确认模型别名配置 (LiteLLM Config)

• 对话模型： Chat (映射到 Qwen/GPT 等)。
• 嵌入模型： Embedding (映射到 Qwen-Embedding-8B)。
• 图像模型 (可选)： Image (如果你打算使用画图功能)。

3. 确认嵌入模型参数

• 确认使用的模型为 Qwen-Embedding-8B，其物理输出维度为 4096。

当然你也可能不用 LiteLLM，但只要是能用兼容OPANAI的接口，VCPToolBox 都能连。你只需要把 config.env 里的 API_URL 和 API_Key 换成对应服务的就行。

---

第二部分：安装与配置阶段 (核心)

此阶段涉及代码获取和配置文件的精确修改。

1. 初始化环境

• 拉取源码：执行 git clone https://github.com/lioensky/VCPToolBox.git
• 进入目录：cd VCPToolBox
• 创建配置：执行 copy config.env.example config.env

2. 修改 config.env (逐项执行)

请使用编辑器打开 config.env 并执行以下修改：

A. 网络连接与上游鉴权

• 找到 API_URL：修改为 http://host.docker.internal:4000

• 找到 API_Key：修改为 LiteLLM 或模型提供商的的 APIKey。

• (注意：如果 LiteLLM 未设置鉴权，请填入任意字符如 sk-placeholder，不可留空)

B. VCP 服务安全加固

• 找到 PORT：确认默认为 6005。
• 找到 Key：务必修改为强随机字符串（这是后续客户端连接的密码）。
• 找到 AdminPassword：修改为强随机字符串（管理面板密码）。
• 找到 Image_Key、File_Key、VCP_Key：全部修改为不同的强随机字符串。

C. 向量数据库配置 (关键)

• 找到 WhitelistEmbeddingModel：修改为 Embedding。

• (必须与 LiteLLM 中的别名或模型供应商提供的模型名完全一致)

• 找到 VECTORDB_DIMENSION：修改为 4096。

• (适配 Qwen-Embedding-8B)

D. 图像模型配置 (可选)

• 找到 WhitelistImageModel：如果 LiteLLM 中配置了 Image 模型，请将此项修改为 Image。

E. 插件 API 配置 (真实密钥方案)

• 天气插件：

• 修改 WeatherKey：填入从 和风天气控制台 获取的 Key。

• 修改 WeatherUrl：填入 devapi.qweather.com (或其他付费节点域名)。

• 搜索插件：

• 修改 TavilyKey：填入从 Tavily 获取的 Key。

• 硅基流动插件：

• 修改 SILICONFLOW_API_KEY：填入从 硅基流动 获取的 Key。

F. 语法特殊说明

• 检查 MultiModalPrompt 字段（约358行），该处可能存在双引号嵌套语法问题。
• 执行动作：暂时保持原样，不要修改，不要转义。 (基于之前的测试经验)

---

第三部分：部署与验证阶段

1. 执行构建

• 执行命令：docker compose build --no-cache

• 问题：

• 构建失败（依赖包丢失/网络错误）。

• 默认的国内镜像源（清华源）可能缺失某些特定版本的包（如日志 setuptools）或偶尔连接超时，导致 pip install 步骤中断。

• 编辑 VCPToolBox/Dockerfile 文件（约第 49 行），用以下代码替换原有的 RUN pip3 install ... 及其上方的相关注释：

# 定义镜像源变量（主源 + 官方备用源）
ARG PIP_INDEX_URL="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
ARG PIP_EXTRA_INDEX_URL="https://pypi.org/simple"

• 将所有 -i https://pypi.tuna.tsinghua.edu.cn/simple 替换为-i ${PIP_INDEX_URL} --extra-index-url ${PIP_EXTRA_INDEX_URL}

• 网络错误处理：

• 构建过程中（尤其是 npm install 或 pip install 阶段）如果出现 getaddrinfo ENOTFOUND 或域名解析失败。

• 应对方案：不要更改 Dockerfile，直接重复执行构建命令，直到所有步骤顺利通过。

2. 启动服务

• 执行命令：docker compose up -d

3. 运行状态检查

• 查看日志：docker compose logs -f
• 成功标准：日志末尾显示 “Server is running on port 6005”，且无严重报错（如 Crash 或 ECONNREFUSED）。

4. 连通性测试 (Curl 验证)

• 在WSL测试对话 (Chat)：

curl http://127.0.0.1:6005/v1/chat/completions \
  -H "Authorization: Bearer <你设置的Key>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "Chat", "messages": [{"role": "user", "content": "hi"}] }'

(注意模型名必须使用 Chat，注意大小写)

• 在WSL测试记忆 (Embedding)：

curl http://127.0.0.1:6005/v1/embeddings \
  -H "Authorization: Bearer <你设置的Key>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "Embedding", "input": "test" }'

(成功标志：返回一串向量数字数组)

5. 客户端接入 (酒馆/WebUI)

• API 地址：http://127.0.0.1:6005/v1
• API Key：填入你在 Config 中设置的 Key。
• 模型名称：填入 Chat。