附录 C 常见报错与排查

文档摘要

附录 C 常见报错与排查按现象 → 原因 → 处理组织，便于生产值班快速定位。 C.1 安装与环境现象 | 可能原因 | 处理不满足 | 版本 < 3.13 | 升级 Python；用 pyenv / conda | 包名错误 | 导入失败 | 未装可选依赖 | 工具不可用 | 未装 extra | C.2 API Key 与 LLM 调用现象 | 可能原因 | 处理 HTTP 401 / Invalid API Key | 密钥错误或过期 | 检查环境变量与 Profile 中的 apikey 连接失败 | 端点 URL 错误 | 核对兼容 API 地址（含后缀） Model not found | 模型名拼写错误 | 对照 Provider 模型列表 Rate limit

附录 C 常见报错与排查

按现象 → 原因 → 处理组织，便于生产值班快速定位。

C.1 安装与环境

现象	可能原因	处理
`Python version` 不满足	版本 < 3.13	升级 Python；用 pyenv / conda
`No module named 'memu'`	包名错误	`pip install memu-py`
`postgres extra` 导入失败	未装可选依赖	`pip install "memu-py[postgres]"`
`langgraph` 工具不可用	未装 extra	`pip install "memu-py[langgraph]"`

C.2 API Key 与 LLM 调用

现象	可能原因	处理
HTTP 401 / Invalid API Key	密钥错误或过期	检查环境变量与 Profile 中的 api_key
`base_url` 连接失败	端点 URL 错误	核对兼容 API 地址（含 `/v1` 后缀）
Model not found	模型名拼写错误	对照 Provider 模型列表
Rate limit exceeded	QPS 超限	指数退避；升级配额；队列化 memorize
Vision / Transcribe 失败	未配对应 Profile	添加 vision / transcribe Profile 或换支持多模态的 default 模型

C.3 memorize 相关

现象	可能原因	处理
下载 resource 失败	URL 不可达、403	检查网络、签名 URL、本地路径权限
items 为空	文本过短或无信息	检查内容与 modality 是否匹配
items 质量差 / 幻觉	模型弱或噪声大	换更强 chat_model；预清洗输入
处理极慢	大文档 / 长视频	应用层切块；异步队列；离线预处理
modality 不匹配	如把 JSON 对话当 document	改用 `conversation`

C.4 retrieve 相关

现象	可能原因	处理
返回 items 为空	where 与写入 scope 不一致	对齐 user_id / agent_id
返回 items 为空	库中确实无数据	先 memorize 再 retrieve
召回不相关	RAG embedding 弱	换 embed_model；试 LLM 模式
延迟过高	LLM 模式 + 大库	改 RAG；开启 sufficiency_check 早停
needs_retrieval=False	路由判断无需查库	检查 query 是否过于泛泛

C.5 存储与 Postgres

现象	可能原因	处理
连接 refused	Postgres 未启动	`docker ps` 检查容器
DSN 格式错误	缺少 driver 前缀	使用 `postgresql+psycopg://...`
pgvector 扩展失败	镜像无 vector	用 `pgvector/pgvector` 镜像
迁移失败	权限不足	确保 DB 用户有 CREATE 权限
重启后 inmemory 数据丢失	预期行为	换 sqlite / postgres

C.6 Embedding 与 RAG

现象	可能原因	处理
embedding 维度不匹配	中途更换 embed_model	清空记忆库或 re-embed
RAG 模式报错缺 embedding	未配 embedding Profile	添加 embedding Profile
相似度始终很低	查询语言与记忆语言不一致	统一语言；试 LLM 模式

C.7 作用域（Scope）

现象	可能原因	处理
用户 A 看到用户 B 记忆	未传 where	所有 retrieve 显式 where
字段过滤无效	UserConfig 未声明字段	在 user_config.model 中声明
写入成功但检索不到	键名不一致	写入 user 与检索 where 键名统一

C.8 Markdown 导出

现象	可能原因	处理
export 无输出	enabled=False	memory_files_config.enabled=True
skill 目录空	无足够来源描述	先 memorize 多来源
合成失败	synthesis Profile 报错	检查 LLM 配额与模型
导出慢	LLM 合成开启	synthesize=False 做确定性导出

C.9 asyncio 相关

现象	可能原因	处理
`RuntimeError: no running event loop`	同步上下文调 async API	用 `asyncio.run()` 或 async 框架
嵌套 event loop 冲突	Jupyter / 已有 loop	使用 nest_asyncio 或纯 async 入口

C.10 Cloud API

现象	可能原因	处理
401 Unauthorized	Bearer Token 无效	检查 Cloud API Key
task 一直 pending	后端排队	延长轮询；联系支持
task failed	来源格式错误	检查请求 body 与 modality
与自托管结果不一致	版本差异	对齐 API 版本号 v3

C.11 调试技巧

1. 打印 memorize 全量返回


import json
result = await service.memorize(...)
print(json.dumps(result, indent=2, ensure_ascii=False))

2. 对比 RAG / LLM 召回

同一 query 分别调用两种 retrieve_config 的实例，diff items 列表。

3. 检查 scope


print("write scope:", {"user_id": "u1"})
print("read scope:", where)
assert where.get("user_id") == "u1"

4. 启用 LLM 拦截器

记录每次 chat / embed 调用的 latency 与 token，定位慢步骤。

C.12 求助渠道

渠道	用途
GitHub Issues	Bug 报告、功能请求
Discord 社区	用法讨论
info@nevamind.ai	企业部署
memu.pro/docs	官方 API 文档

参见：第 1 章安装；第 4 章配置；第 8 章 Postgres；附录 B API 速查。

附录 B API 速查表

下一篇

评论区 (0)

U

0/500