文档中心

从安装到精通，完整使用指南

快速上手、理解核心概念、查阅配置参考，或在遇到问题时排查。

№ 01 · 快速上手

桌面应用与源码运行

普通用户优先选择内置运行时的桌面应用；只有源码用户需要自行安装 Node.js、pnpm 与 Python。

推荐 · 桌面应用 v1.0.5

下载桌面应用

Windows x64 与 macOS 12+ Apple Silicon 安装包都内置 Node.js 24.18.0 和 CPython 3.14.6，无需配置开发环境。

Windows x64 安装

下载 v1.0.5 x64 安装程序并运行。当前未确认最低 Windows 版本。

文件名
Synthetix.Setup.1.0.5.exe
内置运行时
Node.js 24.18.0 · CPython 3.14.6

此版本没有 Authenticode 签名，SmartScreen 可能警告。请仅从官方链接下载并核对 SHA256。

SHA256 7f8f35873d9b64f65886810123b2e0cd833589a188b98fcd873e2c2a90d66945

下载 Windows x64
开发者 · Intel Mac · Linux

从源码运行

仅源码用户需要：Node.js ≥24.18.0 且 <25、pnpm 11.15.0，以及已测试和文档化的 Python 3.14.6；另需一个 LLM 端点。

PowerShell
git clone https://github.com/WalkCloud/Synthetix.git
cd Synthetix
pnpm install --frozen-lockfile
Copy-Item .env.example .env
pnpm exec prisma migrate dev
pnpm exec prisma generate
pnpm dev
替换默认密钥JWT_SECRET 和 ENCRYPTION_KEY 必须替换默认值。运行下面的命令两次，分别填入两个变量。
Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

运行 pnpm dev 后，打开 http://localhost:3000。

首次跑通流程

按顺序完成这 5 步，验证核心链路跑通。

  1. 01
    创建管理员账号 首次打开应用时创建第一个管理员账号。 预期：进入工作台首页，看到文档/草稿统计面板。
  2. 02
    配置模型 Provider 在设置里添加至少一个聊天模型和一个 embedding 模型（支持 OpenAI 兼容端点、Anthropic、Ollama）。 预期：设置页显示 Provider 已连接。
  3. 03
    上传并索引文档 上传一份 PDF / DOCX / Markdown 等支持的文档，等待处理完成。 预期：文档库显示状态为"已索引"，后台开始图谱与 Wiki 增强。
  4. 04
    检查知识库 打开 Search、Knowledge Wiki 或 Knowledge Graph，确认文档已被解析并可检索。 预期：搜索能返回带来源的文档块；Wiki 和图谱随后台增强逐步充实。
  5. 05
    写第一个章节 开始头脑风暴 → 生成大纲 → 生成一个章节 → 检查引用与拓扑。 预期：章节正文带完整来源引用，拓扑视图展示章节与文档的关联。
№ 02 · 核心概念

理解 Synthetix 的知识架构

Synthetix 不是简单的 RAG 工具。它把文档沉淀为三层知识，通过飞轮不断积累，让写作越用越准、越写越省。

三层知识架构

可追溯证据

第 1 层 · 原始文档块

文档被转换为 Markdown、结构化分段、生成 embedding 并建立全文索引。每个 chunk 都是逐字可查的证据来源。

概念与关联

第 2 层 · LightRAG 实体图谱

集成港大开源 LightRAG，用 LLM 从语料抽取实体与关系，构建知识图谱。检索能理解概念与关联，而不只是关键词相似。

综合 · 可编辑

第 3 层 · LLM 知识 Wiki

LLM 综合生成的人类可读知识层：文档摘要、主题、概念和论断，每条带来源与置信度，可检查、可编辑、可导出。

检索策略

Synthetix 在所有需要 LightRAG 检索的场景（知识搜索、写作、头脑风暴、实体证据回溯）统一使用 mix 模式——它同时融合图谱、向量和 reranker 风格检索，召回最全面，无需用户手动选择。

默认 · 最全面

mix 模式

融合 LightRAG 图谱检索 + 向量相似度 + reranker 风格重排，兼顾概念关联、语义相似和证据完整性。应用在所有检索场景统一采用此模式。

用户可选

关键词 / 语义

知识搜索页提供二元开关：关键词搜索走 SQLite FTS5（含中文分词），语义搜索走上述 mix 检索。这是你在前端唯一需要选的检索维度。

关于 LightRAG 的其他模式 LightRAG 库本身还支持 local / global / hybrid / naive / bypass 等模式（可在 workers/python/rag_query.py 的 CLI 参数中查看）。Synthetix 当前没有在 UI 中暴露这些选项，统一用 mix 以保证最佳召回。如有进阶需求，可在二次开发时调整。

知识飞轮

传统 RAG 每次查询都从原始检索重新开始。Synthetix 打破了这个循环：

文档 → 生成 chunks / 图谱 / Wiki 条目 → 写作时优先查 Wiki（廉价）→ Wiki 覆盖良好时自动减量原始检索 → 生成的新论断回写 Wiki → 被引用条目提升置信度 → 下次检索从更丰富的知识库开始

结果是知识库会随着使用变得更聪明。Wiki 不只是缓存，而是你可以检查和编辑的可读综合层。

№ 03 · 安装与配置参考

环境变量与后端配置

复制 .env.example 为 .env，按需修改。模型 Provider 在应用 UI 内配置。

必填项

变量 用途
JWT_SECRET签发访问与刷新令牌，务必使用强随机值。
ENCRYPTION_KEY加密敏感配置，务必使用与 JWT_SECRET 不同的强随机值。
NEXT_PUBLIC_APP_URL应用访问地址，本地通常 http://localhost:3000。
Python 路径 如果 Python 解释器未被自动识别，用环境变量 PYTHON_PATH 指定完整路径。

LightRAG 存储后端

默认使用本地文件存储，无需额外服务。面向云端/团队部署可切换到以下后端：

后端 适用场景 关键环境变量
本地文件（默认） 单机自托管，零额外依赖 JsonKVStorage
NanoVectorDBStorage
NetworkXStorage
PostgreSQL / pgvector 云端部署、团队协作、大规模数据 LIGHTRAG_PG_DATABASE_URL
Neo4j 大规模图谱查询优化 NEO4J_URI
NEO4J_USERNAME
Milvus 海量向量高性能检索 MILVUS_URI
Qdrant 轻量高效向量检索 QDRANT_URL

模型 Provider

Provider 在应用设置页配置，不在 .env 中。系统是否完全离线取决于你的选择：

OpenAI 兼容

OpenAI 官方端点，以及 DeepSeek、Moonshot、Together 等所有 OpenAI 兼容服务均可接入。

Anthropic

Claude 系列模型，适合高质量长文生成。

Ollama

本地运行开源模型；只有 chat、embedding、rerank 和 image 等所有相关 Provider 均为本地服务时，任务内容才可完全留在本机。

本地服务

任何 Ollama 兼容的本地推理服务均可接入。

隐私边界 远程 chat、embedding、rerank 或 image Provider 会接收执行任务所需的内容；只有所有相关 Provider 均为本地服务时，任务内容才可完全留在本机。
№ 04 · FAQ 与故障排查

常见问题

Synthetix 能完全离线使用吗？
取决于 Provider 配置。只有 chat、embedding、rerank 和 image 等所有相关 Provider 均为本地服务时，任务内容才可完全留在本机；任何远程 Provider 都会接收执行任务所需的内容。
支持哪些文档格式？
当前支持面向文本处理的格式：PDF、DOCX、PPTX、HTML、EPUB、TXT、Markdown。表格类格式（Excel）不在当前文档写作管线范围内。
图谱和 Wiki 什么时候才好？
图谱索引和 Wiki 综合是后台增强任务，在文档索引完成后异步运行。文档在上传后即可检索使用，不必等所有增强层完成——它们会逐步充实。
数据存储在哪里？
默认存储在本地 SQLite 数据库和 LightRAG 本地文件存储中（路径见 .env 的 DB_PATH）。面向云端部署可选 PostgreSQL、Neo4j、Milvus、Qdrant 等后端。
能多人协作使用吗？
Synthetix 支持多用户（有认证与账号体系），但当前定位是单工作台的自托管场景。云端/团队协作部署（PostgreSQL、远程存储后端）是 cloud-ready 方向的一部分。
如何切换或对比模型？
在设置中添加多个 Provider。写作工作台支持对同一章节用两个模型做 A/B 生成，并排对比后选择更优版本。
桌面安装包支持哪些平台？
v1.0.5 提供 Windows x64 和 macOS 12+ Apple Silicon（ARM64）直接安装包。当前没有 Intel、Universal 或 Linux 安装包，这些平台可从源码运行。
macOS 为什么拦截应用，如何打开？
macOS 构建采用 ad-hoc 签名，不是 Developer ID 签名且未公证。将应用拖入“应用程序”后，在 Finder 中右键 Synthetix，选择“打开”，再确认系统提示。不要全局关闭 Gatekeeper。
Windows SmartScreen 为什么警告？
Windows v1.0.5 安装程序没有 Authenticode 签名，因此 SmartScreen 可能警告。请只从官方 Release 链接下载，并在继续前核对页面公布的 SHA256。

故障排查

Python 未被识别

设置环境变量 PYTHON_PATH 指向 Python 解释器的完整路径（如 C:\Python314\python.exe）。

端口 3000 被占用

PowerShell：$env:PORT=3001; pnpm dev；CMD：set PORT=3001 && pnpm dev；Bash：PORT=3001 pnpm dev。

模型无响应

检查设置页 Provider 是否显示已连接；确认 API Key 有效、端点可达；Ollama 用户确认服务已启动（默认 localhost:11434）。

中文搜索效果差

关键词搜索基于 SQLite FTS5 并支持中文分词。若效果异常，确认文档已被正确索引，并尝试用语义搜索作为补充。

更多帮助 在 GitHub Issues 提问 · 查看完整 README