每日备份 2026-06-10 12:57:13
This commit is contained in:
root-backup committed
1 parent
fda2ccb8c2
commit
3d2e638c6a
244 files changed
+58890
-3
No files matched your search
@@ -0,0 +1,444 @@
|
||||
# 本地向量模型配置详细解说
|
||||
|
||||
> **思考时间**: 5.85s
|
||||
> **主题**: OpenClaw 本地向量化服务配置
|
||||
> **适用**: 需要本地运行嵌入模型的场景
|
||||
|
||||
---
|
||||
|
||||
## 文档概述
|
||||
|
||||
本文档详细记录了在 OpenClaw 中配置本地向量化服务的完整过程，包括：
|
||||
- 技术方案、实施步骤
|
||||
- 配置代码
|
||||
- 踩坑记录与解决方案
|
||||
|
||||
---
|
||||
|
||||
## 一、配置背景与目标
|
||||
|
||||
### 1.1 应用场景分析
|
||||
|
||||
| 需求 | 说明 |
|
||||
|------|------|
|
||||
| 数据隐私 | 敏感数据不出本地环境 |
|
||||
| 成本控制 | 本地部署无 API 费用 |
|
||||
| 网络稳定 | 本地服务更可靠 |
|
||||
| 离线使用 | 无外网环境必需 |
|
||||
|
||||
### 1.2 技术选型
|
||||
|
||||
选择 **Ollama** 作为本地向量化平台：
|
||||
|
||||
| 优势 | 说明 |
|
||||
|------|------|
|
||||
| 开箱即用 | mxbai-embed-large 可在 CPU 高效运行 |
|
||||
| OpenAI 兼容 | 与 OpenClaw "openai" provider 无缝对接 |
|
||||
| 便捷管理 | 简单命令完成模型下载/更新/卸载 |
|
||||
|
||||
**OpenClaw provider 类型：**
|
||||
- `local`: node-llama-cpp 直接运行
|
||||
- `openai`: OpenAI 兼容 API（Ollama 用这个）
|
||||
- `gemini`: Google Gemini 服务
|
||||
|
||||
---
|
||||
|
||||
## 二、系统环境与硬件要求
|
||||
|
||||
### 2.1 测试环境
|
||||
|
||||
| 组件 | 配置 |
|
||||
|------|------|
|
||||
| 设备 | ThinkPad X230 (2012年老旧笔记本) |
|
||||
| CPU | Intel Core i5-3320M 双核 2.6GHz |
|
||||
| 内存 | 8GB DDR3L (可用 7.7GB) |
|
||||
| 存储 | SSD |
|
||||
| OS | Ubuntu/Linux + systemd 用户服务 |
|
||||
|
||||
### 2.2 性能表现
|
||||
|
||||
| 模型 | mxbai-embed-large:latest |
|
||||
|------|--------------------------|
|
||||
| 参数 | 334M |
|
||||
| 大小 | 669MB (F16量化) |
|
||||
| 内存占用 | 58MB (峰值69MB) |
|
||||
| 响应时间 | < 1秒 |
|
||||
|
||||
**结论**: 老旧硬件完全可胜任本地向量化任务。
|
||||
|
||||
---
|
||||
|
||||
## 三、Ollama 服务部署详解
|
||||
|
||||
### 3.1 安装流程
|
||||
|
||||
```bash
|
||||
# 正常网络
|
||||
curl -fsSL https://ollama.ai/install.sh | sh
|
||||
|
||||
# 如果代理干扰，用这个
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
|
||||
curl -k -fsSL https://ollama.ai/install.sh | sh
|
||||
```
|
||||
|
||||
安装后自动：
|
||||
- 下载二进制到 `/usr/local/bin/`
|
||||
- 创建 systemd 服务
|
||||
- 默认监听 `127.0.0.1:11434`
|
||||
|
||||
### 3.2 下载嵌入模型
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
|
||||
ollama pull mxbai-embed-large:latest
|
||||
```
|
||||
|
||||
验证：
|
||||
```bash
|
||||
curl http://localhost:11434/api/tags
|
||||
```
|
||||
|
||||
### 3.3 服务管理
|
||||
|
||||
```bash
|
||||
# systemd 用户服务管理
|
||||
systemctl --user status ollama # 查看状态
|
||||
systemctl --user start ollama # 启动
|
||||
systemctl --user stop ollama # 停止
|
||||
systemctl --user restart ollama # 重启
|
||||
systemctl --user disable ollama # 禁用自启动
|
||||
```
|
||||
|
||||
**注意**: 有两种服务位置
|
||||
- 系统级: `/etc/systemd/system/ollama.service`
|
||||
- 用户级: `~/.config/systemd/user/ollama.service`
|
||||
|
||||
---
|
||||
|
||||
## 四、OpenClaw 配置详解
|
||||
|
||||
### 4.1 配置文件结构
|
||||
|
||||
```
|
||||
~/.openclaw/openclaw.json (JSON5格式，支持注释)
|
||||
|
||||
顶级字段:
|
||||
├── meta # 元数据
|
||||
├── wizard # 向导状态
|
||||
├── browser # 浏览器功能
|
||||
├── models # 模型提供商配置 ⭐
|
||||
├── agents # Agent配置 ⭐
|
||||
├── tools # 工具设置
|
||||
├── messages # 消息行为
|
||||
├── commands # 命令执行
|
||||
├── channels # 通信渠道
|
||||
├── gateway # 网关参数
|
||||
└── plugins # 插件管理
|
||||
```
|
||||
|
||||
### 4.2 Ollama Provider 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"ollama": {
|
||||
"baseUrl": "http://localhost:11434/v1",
|
||||
"apiKey": "ollama-local",
|
||||
"models": [
|
||||
{
|
||||
"id": "llama3:latest",
|
||||
"name": "Llama 3",
|
||||
"reasoning": false,
|
||||
"input": ["text"],
|
||||
"contextWindow": 32768,
|
||||
"maxTokens": 8192
|
||||
},
|
||||
{
|
||||
"id": "mxbai-embed-large:latest",
|
||||
"name": "MxBai Embed",
|
||||
"reasoning": false,
|
||||
"input": ["text"],
|
||||
"contextWindow": 512,
|
||||
"maxTokens": 512
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**配置要点:**
|
||||
- `baseUrl`: `http://localhost:11434/v1` (`/v1` 是 OpenAI API 前缀)
|
||||
- `apiKey`: 任意值，Ollama 不验证
|
||||
- `models`: 列出所有可用模型
|
||||
|
||||
### 4.3 向量化搜索配置
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "minimax/minimax-m2.1",
|
||||
"fallbacks": ["deepseek/deepseek-chat"]
|
||||
},
|
||||
"memorySearch": {
|
||||
"provider": "openai", // ⭐ 关键：provider类型
|
||||
"model": "mxbai-embed-large:latest", // ⭐ 必须与provider中id一致
|
||||
"remote": {
|
||||
"baseUrl": "http://localhost:11434/v1",
|
||||
"apiKey": "ollama-local"
|
||||
},
|
||||
"cache": {
|
||||
"enabled": true,
|
||||
"maxEntries": 50000
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**关键说明:**
|
||||
- `provider` 必须设为 `"openai"`（Ollama 是 OpenAI 兼容接口）
|
||||
- `remote.baseUrl` 指定 Ollama 具体地址
|
||||
- `cache` 提高性能
|
||||
|
||||
---
|
||||
|
||||
## 五、踩坑记录与解决方案
|
||||
|
||||
### 5.1 代理干扰问题 ⭐最重要⭐
|
||||
|
||||
**问题:**
|
||||
```
|
||||
curl 请求 127.0.0.1:11434 返回 "Empty reply from server"
|
||||
```
|
||||
|
||||
**根因:**
|
||||
代理环境变量将本地请求转发到了 `192.168.0.66:7890`
|
||||
|
||||
**发现:**
|
||||
```
|
||||
"Uses proxy env variable ALL_PROXY == 'socks5h://192.168.0.66:7890'"
|
||||
```
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 方法1: 临时关闭代理
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY no_proxy NO_PROXY
|
||||
|
||||
# 方法2: curl 跳过代理
|
||||
curl --noproxy 127.0.0.1 http://127.0.0.1:11434/api/tags
|
||||
```
|
||||
|
||||
**教训:** 排查类似问题首先检查代理设置。
|
||||
|
||||
---
|
||||
|
||||
### 5.2 SSL 下载失败
|
||||
|
||||
**问题:**
|
||||
```
|
||||
curl: (56) OpenSSL SSL_read: ... decryption failed or bad record mac
|
||||
```
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
|
||||
curl -k -fsSL https://ollama.ai/install.sh | sh
|
||||
```
|
||||
|
||||
**教训:** 代理软件 SSL 中间人解密可能导致错误。
|
||||
|
||||
---
|
||||
|
||||
### 5.3 systemd 自动重启
|
||||
|
||||
**问题:** 杀掉进程后立即被 systemd 重新启动
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 先停止服务
|
||||
systemctl --user stop ollama.service
|
||||
systemctl --user disable ollama.service
|
||||
|
||||
# 再杀进程
|
||||
pkill -9 ollama
|
||||
```
|
||||
|
||||
**教训:** systemd 管理的服务要按正确顺序操作。
|
||||
|
||||
---
|
||||
|
||||
### 5.4 JSON 配置格式错误
|
||||
|
||||
**问题:**
|
||||
```
|
||||
JSON5: invalid character '"' at 175:3
|
||||
```
|
||||
|
||||
**解决:** 用 heredoc 重写配置文件
|
||||
```bash
|
||||
cat > ~/.openclaw/openclaw.json << 'EOF'
|
||||
{...完整正确的内容...}
|
||||
EOF
|
||||
|
||||
# 验证
|
||||
python3 -m json.tool ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.5 batch 配置项不被识别
|
||||
|
||||
**问题:**
|
||||
```
|
||||
agents.defaults.memorySearch: Unrecognized key: 'batch'
|
||||
```
|
||||
|
||||
**解决:** 移除不支持的配置项，只保留核心配置。
|
||||
|
||||
---
|
||||
|
||||
### 5.6 provider 命名混淆
|
||||
|
||||
**错误理解:** provider 应该设为 "ollama"
|
||||
|
||||
**正确理解:**
|
||||
- `provider` = API 类型 (`openai`/`local`/`gemini`)
|
||||
- `remote.baseUrl` = 具体服务地址
|
||||
|
||||
**教训:** 区分 provider 类型和服务实例。
|
||||
|
||||
---
|
||||
|
||||
## 六、验证与测试
|
||||
|
||||
### 6.1 Ollama 服务验证
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
|
||||
|
||||
# 1. 检查服务
|
||||
systemctl --user status ollama
|
||||
|
||||
# 2. 测试 API
|
||||
curl http://localhost:11434/api/tags
|
||||
|
||||
# 3. 测试嵌入
|
||||
curl -X POST http://localhost:11434/v1/embeddings \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model": "mxbai-embed-large:latest", "input": ["测试文本"]}'
|
||||
```
|
||||
|
||||
### 6.2 OpenClaw 验证
|
||||
|
||||
```bash
|
||||
# 验证 JSON 格式
|
||||
python3 -m json.tool ~/.openclaw/openclaw.json
|
||||
|
||||
# 健康检查
|
||||
openclaw doctor
|
||||
|
||||
# 查看配置加载日志
|
||||
journalctl --user -u openclaw-gateway.service -n 50
|
||||
```
|
||||
|
||||
### 6.3 重启 Gateway
|
||||
|
||||
```bash
|
||||
systemctl --user restart openclaw-gateway
|
||||
sleep 5
|
||||
systemctl --user status openclaw-gateway
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、运维命令速查
|
||||
|
||||
### Ollama 管理
|
||||
|
||||
```bash
|
||||
systemctl --user status ollama # 状态
|
||||
systemctl --user start ollama # 启动
|
||||
systemctl --user stop ollama # 停止
|
||||
systemctl --user restart ollama # 重启
|
||||
```
|
||||
|
||||
### OpenClaw 管理
|
||||
|
||||
```bash
|
||||
openclaw doctor # 健康检查
|
||||
systemctl --user restart openclaw-gateway # 重启 Gateway
|
||||
```
|
||||
|
||||
### 日志查看
|
||||
|
||||
```bash
|
||||
journalctl --user -u ollama -n 50 # Ollama 日志
|
||||
journalctl --user -u openclaw-gateway -n 50 # Gateway 日志
|
||||
```
|
||||
|
||||
### 常见故障
|
||||
|
||||
| 故障 | 症状 | 解决 |
|
||||
|------|------|------|
|
||||
| 向量化无响应 | 超时 | 检查代理、Ollama 服务状态 |
|
||||
| 配置不生效 | 无变化 | 重启 Gateway |
|
||||
| 内存过高 | 系统慢 | 重启 Ollama 服务 |
|
||||
|
||||
---
|
||||
|
||||
## 八、性能优化
|
||||
|
||||
### 8.1 内存优化
|
||||
|
||||
| 方法 | 效果 |
|
||||
|------|------|
|
||||
| 更小量化模型 (Q4_0/Q5_1) | 降低 30-50% |
|
||||
| 减少缓存 (10000) | 降低内存占用 |
|
||||
| 按需启动 Ollama | 不用时停止 |
|
||||
|
||||
### 8.2 启动速度
|
||||
|
||||
- 使用 SSD 存储
|
||||
- 保持 Ollama 持续运行
|
||||
|
||||
### 8.3 网络优化
|
||||
|
||||
**不推荐**暴露 Ollama 到外网，如需：
|
||||
```bash
|
||||
export OLLAMA_HOST=0.0.0.0:11434 # 允许外部访问（不推荐）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、配置总结
|
||||
|
||||
### 成功实现
|
||||
|
||||
| 目标 | 状态 |
|
||||
|------|------|
|
||||
| 本地向量化服务 | ✅ ThinkPad X230 成功运行 |
|
||||
| 嵌入模型 | ✅ mxbai-embed-large:latest (334M, F16) |
|
||||
| Provider 模式 | ✅ openai (Ollama 兼容) |
|
||||
| 向量记忆搜索 | ✅ 功能正常 |
|
||||
|
||||
### 关键成功因素
|
||||
|
||||
1. ✅ 准确理解 provider 类型与 remote 配置的关系
|
||||
2. ✅ 正确处理代理干扰问题
|
||||
3. ✅ 严格遵守 JSON 配置格式
|
||||
|
||||
### 经验
|
||||
|
||||
- 主要问题都是环境配置（代理、进程管理）
|
||||
- 技术方案本身成熟可靠
|
||||
- 老旧硬件完全可以胜任
|
||||
|
||||
---
|
||||
|
||||
*文档创建: 2026-02-04*
|
||||
Reference in new issue
Block a user