快速上手、理解核心概念、查阅配置参考，或在遇到问题时排查。
Synthetix 面向自托管。Windows 用户可下载安装包一键启动；开发者可从源码运行。任选其一。
git clone https://github.com/WalkCloud/Synthetix.git
cd Synthetix
npm install
copy .env.example .env
npx prisma migrate dev
npx prisma generate
npm run dev打开 http://localhost:3000 即可访问。偏好 pnpm？仓库自带 pnpm-lock.yaml，pnpm install 同样可用。
按顺序完成这 5 步，验证核心链路跑通。
Synthetix 不是简单的 RAG 工具。它把文档沉淀为三层知识，通过飞轮不断积累，让写作越用越准、越写越省。
文档被转换为 Markdown、结构化分段、生成 embedding 并建立全文索引。每个 chunk 都是逐字可查的证据来源。
集成港大开源 LightRAG，用 LLM 从语料抽取实体与关系，构建知识图谱。检索能理解概念与关联，而不只是关键词相似。
LLM 综合生成的人类可读知识层：文档摘要、主题、概念和论断，每条带来源与置信度，可检查、可编辑、可导出。
Synthetix 在所有需要 LightRAG 检索的场景（知识搜索、写作、头脑风暴、实体证据回溯）统一使用 mix 模式——它同时融合图谱、向量和 reranker 风格检索，召回最全面，无需用户手动选择。
融合 LightRAG 图谱检索 + 向量相似度 + reranker 风格重排，兼顾概念关联、语义相似和证据完整性。应用在所有检索场景统一采用此模式。
知识搜索页提供二元开关：关键词搜索走 SQLite FTS5（含中文分词），语义搜索走上述 mix 检索。这是你在前端唯一需要选的检索维度。
传统 RAG 每次查询都从原始检索重新开始。Synthetix 打破了这个循环：
结果是知识库会随着使用变得更聪明。Wiki 不只是缓存，而是你可以检查和编辑的可读综合层。
复制 .env.example 为 .env，按需修改。模型 Provider 在应用 UI 内配置。
| 变量 | 用途 |
|---|---|
JWT_SECRET | 签发访问与刷新令牌，务必使用强随机值。 |
NEXT_PUBLIC_APP_URL | 应用访问地址，本地通常 http://localhost:3000。 |
PYTHON_PATH 指定完整路径。
默认使用本地文件存储，无需额外服务。面向云端/团队部署可切换到以下后端：
| 后端 | 适用场景 | 关键环境变量 |
|---|---|---|
| 本地文件（默认） | 单机自托管，零额外依赖 | JsonKVStorageNanoVectorDBStorageNetworkXStorage |
| PostgreSQL / pgvector | 云端部署、团队协作、大规模数据 | LIGHTRAG_PG_DATABASE_URL |
| Neo4j | 大规模图谱查询优化 | NEO4J_URINEO4J_USERNAME |
| Milvus | 海量向量高性能检索 | MILVUS_URI |
| Qdrant | 轻量高效向量检索 | QDRANT_URL |
Provider 在应用设置页配置，不在 .env 中。系统是否完全离线取决于你的选择：
OpenAI 官方端点，以及 DeepSeek、Moonshot、Together 等所有 OpenAI 兼容服务均可接入。
Claude 系列模型，适合高质量长文生成。
本地运行开源模型，数据完全不离开本机，是离线优先的最佳选择。
任何 Ollama 兼容的本地推理服务均可接入。
设置环境变量 PYTHON_PATH 指向 Python 解释器的完整路径（如 C:\Python313\python.exe）。
修改 .env 中的端口号，或用 PORT=3001 npm run dev 指定其他端口。
检查设置页 Provider 是否显示已连接；确认 API Key 有效、端点可达；Ollama 用户确认服务已启动（默认 localhost:11434）。
关键词搜索基于 SQLite FTS5 并支持中文分词。若效果异常，确认文档已被正确索引，并尝试用语义搜索作为补充。