#嵌入向量提供者失败

#概述

本指南涵盖 OpenClaw 内存系统中的嵌入向量提供者失败,基于 src/memory/embeddings.ts。嵌入向量为内存检索提供向量相似性搜索能力。当提供者失败时,系统优雅降级到纯全文搜索(FTS)模式。

#症状

#缺少 API 密钥错误

• 日志消息: "No API key found for provider"
• 错误包含特定提供者名称(OpenAI、Voyage 等)
• 内存搜索仅使用 FTS 继续

#仅 FTS 模式

• 内存搜索仅返回文本匹配
• 无向量相似性结果
• 日志消息: "providerUnavailableReason"附带详细信息

#提供者链耗尽

• 主提供者失败
• 降级提供者也失败
• 系统报告所有提供者不可用

#搜索质量下降

• 搜索结果不如预期相关
• 缺少语义相似项
• 仅返回精确关键词匹配

#根本原因

#1. 缺少 API 密钥(第 91-94 行)

提供者已配置但 API 密钥不可用:

function isMissingApiKeyError(error: unknown): boolean {
  const msg = String(error).toLowerCase();
  return msg.includes('api key') || msg.includes('apikey');
}

检测: 解析错误消息中与密钥相关的字符串 常见原因:

• 环境变量未设置
• 配置文件缺少凭据部分
• API 密钥过期或被撤销

恢复: 优雅降级到纯 FTS 模式

#2. 降级链失败(第 204-211 行)

降级链中的所有提供者都失败:

链结构:

1. 主提供者(例如本地 Ollama)
2. 次提供者(例如 OpenAI)
3. 纯 FTS 模式(无嵌入向量)

常见原因:

• 主提供者和次提供者都缺少 API 密钥
• 网络连接问题
• 所有提供者同时被速率限制

恢复: 返回 null 提供者,启用纯 FTS 模式

#3. 降级提供者缺少密钥(第 228-246 行)

主提供者失败,降级提供者也缺少密钥:

检测逻辑:

if (isMissingApiKeyError(primaryError)) {
  // 尝试降级
  if (isMissingApiKeyError(fallbackError)) {
    // 两者都缺少密钥 - 返回 null
    return { provider: null, reason: "两个提供者都缺少 API 密钥" };
  }
}

恢复: 系统级纯 FTS 模式,记录详细原因

#4. 网络和速率限制错误

提供者可达但请求失败:

常见 HTTP 状态码:

• 429: 超出速率限制
• 500-503: 提供者服务错误
• 超时: 网络延迟或提供者过载

恢复: 使用指数退避自动重试(通过 src/memory/batch-http.ts)

#5. 自动选择失败

当配置 provider: "auto" 时:

选择逻辑:

1. 首先尝试本地提供者(node-llama-cpp)
2. 降级到远程提供者
3. 检查每个提供者的可用性

常见原因:

• node-llama-cpp 未安装或构建失败
• 本地模型文件缺失
• 不满足 GPU/内存要求

#恢复机制

#优雅降级流程