---
#领域/未知

#复盘/0 #临时/备忘 #状态/待处理

20260508-备忘-主题名-文件内容

## 一句话描述

[________]

---

## 1. 下载 bge-large-zh 到服务器

### 1.1 安装 git-lfs（必须，否则下不全）

```bash
sudo apt update
sudo apt install git-lfs -y
git lfs install
```

### 1.2 创建模型目录并下载

```bash
# 创建目录（统一放这里）
sudo mkdir -p /opt/maxkb/model/embedding
cd /opt/maxkb/model/embedding

# 克隆 bge-large-zh-v1.5
sudo git clone https://huggingface.co/BAAI/bge-large-zh-v1.5
```

---

## 2. 修改 docker-compose.yml，把模型挂载进容器

### 2.1 找到你的 compose 文件

```bash
/opt/maxkb/docker-compose.yml
```

### 2.2 编辑添加 volumes 和环境变量

```bash
sudo nano /opt/maxkb/docker-compose.yml
```

在 `services → maxkb` 下添加 / 修改：

```yaml
services:
  maxkb:
    ...
    environment:
      # 关键：指定默认向量模型为本地 bge-large-zh-v1.5
      - MAXKB_EMBEDDING_MODEL_NAME=/opt/maxkb/model/embedding/bge-large-zh-v1.5
    volumes:
      # 关键：把宿主机模型目录挂载到容器内
      - /opt/maxkb/model/embedding:/opt/maxkb/model/embedding
      # 原有数据卷保留
      - ${MAXKB_BASE}/maxkb/logs:/opt/maxkb/app/data/logs
      - /tmp:/tmp
    ...
```

---

## 3. 重启 MaxKB 使挂载生效

```bash
cd /opt/maxkb
sudo docker-compose down
sudo docker-compose up -d
```

---

## 4. WebUI 添加 “本地向量模型”

1. 登录->（上方）模型->(左侧)私有模型->本地模型->添加模型
2. 模型名称自定义：`bge-large-zh-local`
3. 模型类型：向量模型
4. 基础模型和模型目录：/opt/maxkb/model/embedding/bge-large-zh-v1.5

    

## 5. 设为默认向量模型（关键）

1. 回到 **模型管理 → 向量模型**
2. 找到 `bge-large-zh-local` → 点右上角 **设为默认**
    
    ![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%27256%27%20height=%27192%27/%3e)![image](https://p11-flow-imagex-sign.byteimg.com/labis/image/180889f4d868fe33a81fa34f756a2900~tplv-a9rns2rl98-pc_smart_face_crop-v1:512:384.image?lk3s=8e244e95&rcl=202605072001221C24623F1EEF7153B17A&rrcfp=cee388b0&x-expires=2093515305&x-signature=D0AQspr8MPEneTnGkk6GP2lmq3I%3D)
    

✅ 现在新建知识库 / 上传文档，都会自动用 **bge-large-zh** 做向量，不再用内置 maxkb-embedding。

---

## 6. 验证是否生效（可选）

1. 新建一个测试知识库，上传一个 txt
2. 进入知识库 → 文档管理 → 看 “向量模型” 列是否为：`bge-large-zh-local`
3. 问一个问题，正常返回，说明成功。