admin/my-project

0 Fork 0

Files

T

root-backup 3d2e638c6a 每日备份 2026-06-10 12:57:13

2026-06-10 12:57:14 +08:00

9.3 KiB

Raw Blame History

本地向量模型配置详细解说

思考时间: 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 安装流程

# 正常网络
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 下载嵌入模型

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
ollama pull mxbai-embed-large:latest

验证：

curl http://localhost:11434/api/tags

3.3 服务管理

# 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 配置

{
  "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 向量化搜索配置

{
  "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'"

解决方案:

# 方法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

解决方案:

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 重新启动

解决方案:

# 先停止服务
systemctl --user stop ollama.service
systemctl --user disable ollama.service

# 再杀进程
pkill -9 ollama

教训: systemd 管理的服务要按正确顺序操作。

5.4 JSON 配置格式错误

问题:

JSON5: invalid character '"' at 175:3

解决: 用 heredoc 重写配置文件

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 服务验证

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 验证

# 验证 JSON 格式
python3 -m json.tool ~/.openclaw/openclaw.json

# 健康检查
openclaw doctor

# 查看配置加载日志
journalctl --user -u openclaw-gateway.service -n 50

6.3 重启 Gateway

systemctl --user restart openclaw-gateway
sleep 5
systemctl --user status openclaw-gateway

七、运维命令速查

Ollama 管理

systemctl --user status ollama      # 状态
systemctl --user start ollama       # 启动
systemctl --user stop ollama        # 停止
systemctl --user restart ollama     # 重启

OpenClaw 管理

openclaw doctor                     # 健康检查
systemctl --user restart openclaw-gateway  # 重启 Gateway

日志查看

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 到外网，如需：

export OLLAMA_HOST=0.0.0.0:11434  # 允许外部访问（不推荐）

九、配置总结

成功实现

目标	状态
本地向量化服务	✅ ThinkPad X230 成功运行
嵌入模型	✅ mxbai-embed-large:latest (334M, F16)
Provider 模式	✅ openai (Ollama 兼容)
向量记忆搜索	✅ 功能正常

关键成功因素

✅ 准确理解 provider 类型与 remote 配置的关系
✅ 正确处理代理干扰问题
✅ 严格遵守 JSON 配置格式

经验

主要问题都是环境配置（代理、进程管理）
技术方案本身成熟可靠
老旧硬件完全可以胜任

文档创建: 2026-02-04

9.3 KiB Raw Blame History Unescape Escape

本地向量模型配置详细解说

文档概述

一、配置背景与目标

1.1 应用场景分析

1.2 技术选型

二、系统环境与硬件要求

2.1 测试环境

2.2 性能表现

三、Ollama 服务部署详解

3.1 安装流程

3.2 下载嵌入模型

3.3 服务管理

四、OpenClaw 配置详解

4.1 配置文件结构

4.2 Ollama Provider 配置

4.3 向量化搜索配置

五、踩坑记录与解决方案

5.1 代理干扰问题 ⭐最重要⭐

5.2 SSL 下载失败

5.3 systemd 自动重启

5.4 JSON 配置格式错误

5.5 batch 配置项不被识别

5.6 provider 命名混淆

六、验证与测试

6.1 Ollama 服务验证

6.2 OpenClaw 验证

6.3 重启 Gateway

七、运维命令速查

Ollama 管理

OpenClaw 管理

日志查看

常见故障

八、性能优化

8.1 内存优化

8.2 启动速度

8.3 网络优化

九、配置总结

成功实现

关键成功因素

经验

9.3 KiB

Raw Blame History