From baf3b5dd7ca58a05786ce40da2e5987160be6d1e Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 29 Apr 2026 17:01:33 +0800 Subject: [PATCH] auto-sync: 2026-04-29 17:01:33 --- .../final/本地Embedding服务搭建方案报告.md | 254 ++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 jiangwei-platform/research/local-embedding-service/final/本地Embedding服务搭建方案报告.md diff --git a/jiangwei-platform/research/local-embedding-service/final/本地Embedding服务搭建方案报告.md b/jiangwei-platform/research/local-embedding-service/final/本地Embedding服务搭建方案报告.md new file mode 100644 index 000000000..1b4d8b0e5 --- /dev/null +++ b/jiangwei-platform/research/local-embedding-service/final/本地Embedding服务搭建方案报告.md @@ -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