Novel AI 本地后端

English

Novel AI 本地后端负责保存小说数据、短期/长期记忆、故事圣经、章节大纲，并通过 DeepSeek 兼容接口生成草稿、重写、质检和导出 TXT。它运行在用户自己的电脑上，API Key 和小说数据都不进入公开前端。

功能概览

• 本地 FastAPI 服务
• 小说、章节、故事圣经、大纲的文件化存储
• DeepSeek/OpenAI 兼容接口调用
• 长期记忆、短期记忆和向量记忆
• 章节草稿生成、重新生成、确认入库
• 事实抽取、一致性检查、质量检查
• TXT 导出
• 可配置数据目录和 CORS 白名单

运行要求

• 推荐 Python 3.11
• 可用 Python 3.12
• 不支持 Python 3.14+

快速启动

git clone <your-server-repo-url>
cd ai-editor-server
cp .env.example .env

编辑 .env：

deepseek_api_key=sk-your-api-key
deepseek_base_url=https://api.deepseek.com
reranker_model_name=BAAI/bge-reranker-base
AI_WRITING_DATA_DIR=~/.ai-writing/data
AI_WRITING_HOST=127.0.0.1
AI_WRITING_PORT=8001
AI_WRITING_ALLOWED_ORIGINS=http://127.0.0.1:5173,http://localhost:5173

启动后端：

./scripts/start-local.sh

Windows PowerShell：

.\scripts\start-local.ps1

启动成功后可访问：

http://127.0.0.1:8001/health
http://127.0.0.1:8001/api/health/config
http://127.0.0.1:8001/api/health/storage

前端连接

启动 ai-editor-front 后，在前端顶部 Backend 输入框填写：

http://127.0.0.1:8001

点击保存或检查连接。连接成功后即可创建小说、生成草稿、保存记忆和导出 TXT。

数据目录

所有用户数据都保存在：

AI_WRITING_DATA_DIR

默认示例：

~/.ai-writing/data

目录结构包括：

• novels/：小说元数据、章节、故事圣经、大纲
• memory/：短期记忆、长期记忆、结构化记忆和向量记忆
• writing_chroma/：写作知识向量库
• artifacts/：运行产物和导出文件

这些目录属于用户本地数据，不应该提交到 Git。

开发测试

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
python -m pytest -q

常见问题

前端连不上后端

• 确认后端正在运行。
• 确认前端填写的是 http://127.0.0.1:8001。
• 确认防火墙没有拦截本地端口。

CORS 报错

把前端地址加入 .env：

AI_WRITING_ALLOWED_ORIGINS=http://127.0.0.1:5173,http://localhost:5173

修改后重启后端。

DeepSeek Key 无效

确认 .env 中配置：

deepseek_api_key=sk-your-api-key
deepseek_base_url=https://api.deepseek.com

不要把 API Key 放到前端仓库或前端托管平台。

Python 版本不对

推荐明确使用 Python 3.11：

PYTHON_BIN=python3.11 ./scripts/start-local.sh

安全说明

• 不要提交 .env。
• 不要提交 data/novels/、data/memory/、向量库、导出文件或用户正文。
• 如果真实 API Key 曾经被提交过，请立即更换 Key，并清理 Git 历史。