auto-sync: 2026-04-29 17:01:33
This commit is contained in:
cfdaily
@@ -0,0 +1,254 @@
|
||||
# 本地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
|
||||
Reference in New Issue
Block a user