问题

核心原因

解决方案

混淆了LLM与嵌入模型

误将llama3.2等大语言模型用作嵌入模型，导致检索失效（问A答B）

嵌入模型用 bge-m3，LLM用 qwen2.5:7b，二者不能互换

不理解RAG各组件的分工

不清楚AnythingLLM、Ollama、BGE-M3、Qwen2.5的职责

AnythingLLM是编排层，Ollama是引擎，BGE-M3负责检索，Qwen2.5负责生成

纠结选择桌面版还是服务版

桌面版数据存储在 ~/Library/Application Support/anythingllm/，服务版在项目目录 storage/ 下

个人用选桌面版；需多用户或API集成选服务版

问题

核心原因

解决方案

端口 3001 被占用

桌面版 AnythingLLM 在运行

停止桌面版应用，或更改映射端口

yarn 命令不存在

系统未安装 yarn 包管理器

npm install -g yarn

cross-env: command not found

项目依赖未完全安装，cross-env包缺失

执行 yarn install 重新安装所有依赖

unable to open database file 或 ReadOnly

数据库文件权限不足

chmod 755 目录，chmod 644 数据库文件

cd 进入目录失败

路径拼写错误（如大小写、空格），或目录不存在

使用 ls 查看目录名，用 cd <name> 进入，善用 Tab 键自动补全

问题

核心原因

解决方案

AnythingLLM 连接不上 Ollama

Ollama 服务未启动；API地址或端口配置错误

1. ollama list 确认服务运行；2. 检查 Base URL 是否为 http://localhost:11434

Ollama 下载模型速度极慢

默认从国外服务器下载

设置国内镜像源：export HF_ENDPOINT=https://hf-mirror.com

模型响应速度慢

硬件性能不足（尤其CPU）或模型过大

换用小模型或量化版本（如 q4_0）

嵌入模型下拉框没有 bge-m3

AnythingLLM 未刷新模型列表

ollama list 确认已安装；手动输入模型名称；重启 AnythingLLM

切换模型后 AnythingLLM 报错

新模型超出硬件资源上限

查看资源占用；换用更小的量化模型

问题

核心原因

解决方案

RAG效果差（问A答B）

1. 嵌入模型错误（用了LLM）；2. 分块不合理；3. 相似度阈值过高

1. 换用 bge-m3；2. 设置块大小512，重叠50；3. 调低或关闭相似度阈值

服务版看不到桌面版的工作区

桌面版和服务版数据隔离，数据库文件不互通

方案一：迁移数据库文件（需兼容）；方案二：在服务版重建工作区

备份恢复后工作区为空

备份文件解压到了错误路径，或权限/数据库不兼容

确认数据目录路径，检查文件权限，必要时在服务版重建

嵌入时提示 input length exceeds context length

文本块大小超过嵌入模型的 token 上限（nomic-embed-text 上限 8192）

调小"文本块大小"至 512 或 1024，并删除文档重新嵌入

上传文档后AI"睁眼瞎"

未正确将文档添加到工作区；或未点击嵌入（Embed）

1. 确保上传后点击 "Save and Embed"；2. 将文档 "Move to Workspace"

AI回答不准确/有幻觉

分块不合理导致关键信息被切断；检索召回片段不足

1. 调整分块大小 512；2. 增加检索数量(Top-K)至5-10；3. 优化提问方式

问题

核心原因

解决方案

localhost:3001 无法访问

服务未启动、端口被占用、防火墙拦截

检查服务状态，lsof -i :3001 查看端口占用

浏览器创建工作区报错

数据库权限问题（ReadOnly）或服务未完全启动

修改数据库文件权限，确认三个服务都启动成功

前端构建后文件未更新

浏览器缓存旧版本

强制刷新（Cmd+Shift+R）或清除缓存

问题

核心原因

解决方案

curl http://localhost:3001 返回 404

桌面版 HTTP 服务器不提供前端；或未构建

使用命令行版 + npm run build

API 请求返回 401 Unauthorized

API 密钥缺失或错误

从 settings.json 获取正确密钥，在 Header 中添加 Authorization: Bearer <key>

连接本地 Ollama 失败（Docker版）

容器内无法通过 localhost 访问宿主机服务

Ollama 地址应填 http://host.docker.internal:11434