sanguo/sanguo_quant_live

Fork 0

Files

T

cfdaily baf3b5dd7c auto-sync: 2026-04-29 17:01:33

2026-04-29 17:01:33 +08:00

6.2 KiB

Raw Blame History

本地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服务不可用的根本原因：

hunyuan-embedding 为腾讯云在线服务，存在网络依赖
API Key 可能过期或配置错误
网络连接可能不稳定导致服务超时

二、解决方案对比

方案一：本地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

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

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

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

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 端点指向本地服务：

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

步骤4：验证服务可用性

# 启动本地服务
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 切换步骤

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

六、风险与注意事项

6.1 技术风险

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

6.2 迁移注意事项

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

七、实施计划

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

八、备选方案：快速修复

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

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服务）

理由：

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

下一步行动：

请司马懿评审本方案
评审通过后立即实施搭建
完成后提交验收报告

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

6.2 KiB Raw Blame History Unescape Escape