# 本地Embedding服务搭建方案报告

**调研人**: 姜维（平台总督）
**日期**: 2026-04-29
**状态**: 待评审

---

## 一、问题现状

### 1.1 当前状态
通过 `openclaw status` 排查确认：

| 项目 | 状态 |
|------|------|
| Memory插件 | memory-lancedb-pro@1.1.0-beta.9 |
| 当前Embedding模型 | hunyuan-embedding |
| 服务状态 | **enabled but unavailable** |
| 数据库位置 | /Users/chufeng/.openclaw/memory/lancedb-pro |

### 1.2 问题分析
Embedding服务不可用的根本原因：
1. `hunyuan-embedding` 为腾讯云在线服务，存在网络依赖
2. API Key 可能过期或配置错误
3. 网络连接可能不稳定导致服务超时

---

## 二、解决方案对比

### 方案一：本地Embedding服务（推荐） ✅

**优点：**
- 零网络依赖，完全离线可用
- 响应速度快，无API调用延迟
- 成本为零，无调用费用
- 数据隐私保护，无需发送文本到第三方

**缺点：**
- 需要本地计算资源（CPU/GPU）
- 向量维度固定，模型选择有限

**适用场景：** 本地开发、内网部署、隐私敏感数据

---

### 方案二：切换到火山方舟Embedding API

**配置信息：**
- 模型: `doubao-seed-2-0-lite-260215`
- API Key: `d9aaff82-7fe3-4c8b-a44b-3b4c83c48965`
- 端点: `https://ark.cn-beijing.volces.com/api/v3`

**优点：**
- 向量质量高，语义理解能力强
- 维度灵活，支持多种模型
- 已有可用的API Key（测试通过）

**缺点：**
- 仍有网络依赖
- 有调用成本
- 存在隐私风险

---

## 三、本地Embedding服务实施方案

### 3.1 技术选型

| 方案 | 技术栈 | 说明 |
|------|--------|------|
| **方案A** | text-embeddings-inference | HuggingFace官方推荐，高性能 |
| **方案B** | Ollama Embedding | 简单易用，支持多模型 |
| **方案C** | fastembed | 轻量级纯Python方案 |

**推荐：方案C (fastembed)**
- 纯Python，无复杂依赖
- 自动下载模型，开箱即用
- 支持多种主流Embedding模型
- 性能满足本地需求

### 3.2 fastembed 特性

**支持的模型：**
- BAAI/bge-small-en-v1.5 (默认，384维)
- BAAI/bge-base-en-v1.5 (768维)
- BAAI/bge-large-en-v1.5 (1024维)
- BAAI/bge-small-zh-v1.5 (中文优化)
- sentence-transformers/all-MiniLM-L6-v2

**性能：**
- CPU: ~500 tokens/sec (M1 Mac)
- GPU: ~5000 tokens/sec
- 内存占用: ~500MB

---

## 四、详细部署步骤

### 步骤1：安装fastembed

```bash
# 进入sanguo_vnpy项目
cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy

# 安装依赖
pip install fastembed
# 或者
poetry add fastembed
```

### 步骤2：创建本地Embedding服务脚本

```python
from fastembed import TextEmbedding
from fastapi import FastAPI
import uvicorn

app = FastAPI(title="本地Embedding服务")
model = TextEmbedding(model_name="BAAI/bge-small-zh-v1.5")

@app.post("/embeddings")
async def get_embeddings(input: list[str]):
    embeddings = list(model.embed(input))
    return {
        "data": [
            {"embedding": emb.tolist(), "index": i}
            for i, emb in enumerate(embeddings)
        ],
        "model": "BAAI/bge-small-zh-v1.5",
        "usage": {"total_tokens": sum(len(t) for t in input)}
    }

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8787)
```

### 步骤3：配置OpenClaw使用本地服务

修改 OpenClaw 配置文件，将 embedding 端点指向本地服务：

```yaml
plugins:
  memory-lancedb-pro:
    embedding:
      baseUrl: "http://127.0.0.1:8787"
      model: "local-bge-small-zh"
```

### 步骤4：验证服务可用性

```bash
# 启动本地服务
python local_embedding_service.py

# 测试接口
curl -X POST http://127.0.0.1:8787/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": ["测试文本"]}'
```

---

## 五、OpenClaw内存系统配置说明

### 5.1 当前配置参数

根据 TOOLS.md 记录：
- 嵌入模型: doubao-seed-2.0-lite
- 检索模式: hybrid (vector 0.7, bm25 0.3)
- 最小相似度分数: 0.3
- 自动召回阈值: 6 characters

### 5.2 配置文件位置

OpenClaw 配置通常位于：
- `~/.openclaw/config.yaml`
- 或通过 Control UI: `http://127.0.0.1:18789/`

### 5.3 切换步骤

1. 打开 Control UI → Settings → Plugins
2. 找到 memory-lancedb-pro 配置
3. 修改 embedding 相关参数指向本地服务
4. 重启 Gateway 服务生效

---

## 六、风险与注意事项

### 6.1 技术风险

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 向量质量下降 | 检索准确率降低 | 使用中文优化模型(bge-small-zh) |
| 本地服务稳定性 | 服务中断导致Memory不可用 | 配置进程守护(systemd/PM2) |
| 模型切换兼容性 | 已存储向量不兼容 | 全量重建向量数据库 |

### 6.2 迁移注意事项

1. **向量维度不兼容**：切换模型后所有已存储的embedding向量需要重新生成
2. **数据库重建**：建议备份当前的 lancedb-pro 数据库目录
3. **渐进切换**：可以先在测试环境验证，再生产环境切换

---

## 七、实施计划

| 阶段 | 任务 | 预计工时 | 责任人 |
|------|------|----------|--------|
| 第一阶段 | 搭建本地fastembed服务并测试 | 30分钟 | 姜维 |
| 第二阶段 | 配置OpenClaw使用本地服务 | 15分钟 | 姜维 |
| 第三阶段 | 验证Memory功能恢复 | 15分钟 | 姜维 |
| 第四阶段 | 性能测试与调优 | 30分钟 | 姜维 |
| **总计** | | **1.5小时** | |

---

## 八、备选方案：快速修复

如果需要快速恢复服务而不做架构变更，可以直接切换到已验证的火山方舟API：

```yaml
plugins:
  memory-lancedb-pro:
    embedding:
      baseUrl: "https://ark.cn-beijing.volces.com/api/v3"
      apiKey: "d9aaff82-7fe3-4c8b-a44b-3b4c83c48965"
      model: "doubao-seed-2-0-lite-260215"
```

此方案可以在5分钟内恢复服务，但不解决根本的网络依赖问题。

---

## 九、结论与建议

**建议采纳：方案一（本地fastembed服务）**

理由：
1. 消除网络单点故障，提高系统稳定性
2. 符合本地开发场景的需求
3. 零成本运行，长期收益显著
4. 部署简单，维护成本低

**下一步行动：**
1. 请司马懿评审本方案
2. 评审通过后立即实施搭建
3. 完成后提交验收报告

---

**文档版本**: v1.0
**最后更新**: 2026-04-29