常见问题

Ollama 未运行怎么办？

如果启动 AI Reader 后提示无法连接 LLM 服务，请检查 Ollama 是否正常运行：

1. 确认已安装 Ollama：从 ollama.com 下载安装
2. 启动服务：运行 ollama serve（macOS 安装后通常会自动运行）
3. 确认模型已下载：运行 ollama pull qwen3:8b
4. 检查端口：确认 http://localhost:11434 可访问

如果更换了 Ollama 的监听地址，需设置环境变量 OLLAMA_BASE_URL 指向正确地址。

分析速度很慢？

分析速度主要取决于模型大小和硬件配置：

• 模型越大越慢：qwen3:32b 比 qwen3:8b 慢数倍，但质量更好
• 硬件影响：GPU 显存越大速度越快，Apple Silicon 设备使用 MPS 加速
• 云端加速：如果本地硬件有限，可切换到云端模式（如 DeepSeek），速度通常快 3-10 倍
• 尝试小模型：先用 qwen3:8b 体验功能，确认需要后再换大模型

每章分析耗时因设备和模型而异，通常在 10 秒到 2 分钟之间。长篇小说（数百章）可能需要数小时，建议在后台运行。

分析失败了怎么办？

AI Reader 内置了自动重试机制，大多数临时性错误会自动恢复。如果仍有章节分析失败：

1. 查看错误类型：在分析页面查看失败章节的错误类型
   • timeout：模型响应超时，可能是模型过大或 GPU 负载高
   • parse_error：模型输出格式异常，通常重试可解决
   • content_policy：内容触发了模型的安全策略，此类章节会跳过重试
   • http_error：网络或服务错误，检查 Ollama/API 服务状态
   • unknown：未知错误，查看后端日志排查
2. 手动重试：在设置页面或分析页面可对失败章节发起重试
3. 换用更稳定的模型：部分模型输出格式稳定性较差，推荐使用 qwen3 系列

数据存储在哪里？

所有数据默认存储在本地：

• 数据库文件：~/.ai-reader-v2/data.db（SQLite）
• 向量数据库：~/.ai-reader-v2/chroma/（ChromaDB）

可通过环境变量 AI_READER_DATA_DIR 修改存储目录，例如：

export AI_READER_DATA_DIR=/path/to/custom/dir

如何备份和恢复数据？

单本小说备份

在导出页面选择 .air 格式导出，该文件包含该小说的所有分析数据。恢复时在书架页面导入 .air 文件即可。

全量备份

在设置页面提供全量数据备份功能，会备份整个数据库文件。也可以直接复制 ~/.ai-reader-v2/ 目录进行手动备份。

迁移到新设备

1. 在旧设备上逐本导出 .air 文件（或复制整个数据目录）
2. 在新设备上安装 AI Reader
3. 导入 .air 文件或将数据目录放到对应位置

支持哪些小说格式？

目前支持 TXT 纯文本格式，文件需包含可识别的章节标记（如"第一章""第1回""Chapter 1"等）。

系统内置了智能的章节分割算法，能识别多种常见的中文章节格式，包括：

• "第X章""第X回""第X节"等数字章节
• "卷一""上部""第一部"等分卷标记
• 自定义章节分隔符

如果 TXT 文件没有明确的章节标记，系统会按段落或固定长度进行分割。

能分析英文小说吗？

当前版本针对中文小说做了深度优化，包括中文分词（jieba）、中文地名识别、中文关系类型归一化等。

英文小说的分析属于实验性支持：

• 基本的章节分割和实体提取可以工作
• 地名匹配、别名解析等中文特化功能效果有限
• 推荐使用英文能力较强的模型（如 GPT-4o 或 Claude）

如何更新？

网页版（开发者）

cd AI-Reader-V2
git pull

# 更新后端依赖
cd backend && uv sync

# 更新前端依赖
cd ../frontend && npm install

然后重启前后端服务即可。

桌面版

从 GitHub Releases 下载最新版本安装包，覆盖安装即可。已有数据不会丢失。

云端模式安全吗？

AI Reader 在云端模式下的隐私保护策略：

• 仅发送 LLM 请求：只有章节文本片段会发送到配置的 API 端点进行分析
• 无遥测数据：AI Reader 不会向任何第三方发送使用统计或遥测数据
• 无外部存储：小说文本不会被存储到本地以外的任何地方（LLM API 调用是即时的）
• 密钥本地保存：API 密钥仅存储在本地配置中

如果对数据隐私有严格要求，建议使用本地 Ollama 模式，所有数据和计算完全在本地完成。

免费版有什么限制？

免费版已包含完整的分析功能，适合大多数个人用户。Pro 版主要面向需要多格式导出和大量小说管理的重度用户。