1

README.md

@@ -0,0 +1,119 @@
+# rag-local 本地知识库
+
+纯本地的 RAG（检索增强生成）知识库系统，基于 SQLite 全栈文件型存储，无外部数据库依赖。
+
+## 功能
+
+- **文档流水线**：上传 txt / md / pdf / docx / html → 自动解析 → 标题感知分块 → 向量化 + 全文索引
+- **混合检索**：sqlite-vec 向量 KNN + FTS5 全文 BM25，RRF 融合排序，中文 gse 分词
+- **RAG 问答**：SSE 流式对话，检索引用（含来源与得分）随回答展示，会话历史持久化
+- **知识图谱**：解析时 LLM 抽取实体与关系，问答时实体链接 + 一跳邻居注入提示词，图谱页可视化实体/关系
+- **单用户门禁**：启动生成访问令牌，登录后 JWT 鉴权
+
+## 技术栈
+
+| 层 | 技术 |
+|---|---|
+| 后端 | Go + GoFrame v2 + Eino（LLM 编排） |
+| 存储 | SQLite（modernc 纯 Go 驱动 + sqlite-vec 扩展） |
+| 全文 | SQLite FTS5 + gse 中文分词 |
+| 前端 | Vue 3 + Element Plus + Vite（前后端不分离，单端口） |
+| 部署 | Docker Compose 一键启动 |
+
+三个 SQLite 文件各司其职：
+
+| 库 | 文件 | 内容 |
+|---|---|---|
+| business | `data/business.db` | 数据集/文档/分块/向量/全文/解析任务/知识图谱 |
+| system | `data/system.db` | 系统配置（令牌、默认模型）与模型配置 |
+| chat | `data/chat.db` | 会话与消息 |
+
+## 快速开始（Docker）
+
+```bash
+docker compose up -d --build
+```
+
+- 浏览器打开 http://localhost:8080
+- 启动日志中查看访问令牌（`docker compose logs rag-local` 搜索"访问令牌"）
+- 登录后按以下流程使用：
+  1. **设置** 页添加对话模型与向量模型（OpenAI 兼容接口，如 Ollama / vLLM / one-api），并点击"测试"验证连通
+  2. **数据集** 页新建数据集，绑定向量模型（不绑定则仅全文检索）
+  3. 进入数据集上传文档，等待解析完成
+  4. **问答** 页选择知识库开始提问，回答可展开查看引用来源
+  5. **知识图谱** 页查看解析时抽取的实体与关系
+
+数据保存在 `./data` 与 `./workspace`，删除容器不丢失。
+
+## 本地开发
+
+```bash
+# 后端（Go 1.26+）
+go run .            # 监听 :8080，启动日志打印访问令牌
+
+# 前端（开发热更新）
+cd ui-src
+npm install
+npm run dev         # Vite 开发服务器，API 代理见 vite.config.js
+```
+
+生产构建时前端产物在 `ui-src/dist`，由 Go 直接托管。
+
+## 模型配置
+
+任意 OpenAI 兼容接口均可使用：
+
+- **对话模型**（`/v1/chat/completions`，支持 SSE 流式）：用于问答与知识图谱实体抽取
+- **向量模型**（`/v1/embeddings`）：用于分块向量化与语义检索；维度须与 `config.yml` 中 `vector.dim` 一致（默认 1024）
+
+示例（Ollama）：
+
+```bash
+# 拉取模型
+ollama pull qwen2.5:7b
+ollama pull nomic-embed-text
+
+# 设置页配置：
+#   对话模型：endpoint http://localhost:11434/v1，模型名 qwen2.5:7b
+#   向量模型：endpoint http://localhost:11434/v1，模型名 nomic-embed-text，维度 768
+```
+
+> 注意：向量维度变更需清空 `data/business.db` 重建（vec0 表建表维度固定）。
+
+## 配置说明（config.yml）
+
+| 配置 | 说明 |
+|---|---|
+| `server.address` | 监听地址，默认 `:8080` |
+| `server.clientMaxBodySize` | 上传文件上限，默认 200MB |
+| `vector.dim` | 向量维度，须与向量模型一致 |
+| `database.cache.ttl` | DAO 查询缓存秒数 |
+
+## API 概览
+
+| 分组 | 接口 |
+|---|---|
+| `/system-config` | 登录、设置读写、令牌查看/重新生成 |
+| `/model-config` | 模型配置 CRUD、连通性测试 |
+| `/dataset` | 数据集 CRUD |
+| `/document` | 上传、列表、删除、重新向量化 |
+| `/chunk` | 分块列表、编辑（改后自动重向量化） |
+| `/parse-task` | 解析任务列表、失败重试 |
+| `/conversation` `/message` | 会话管理、消息列表、SSE 问答流（`/message/chat`） |
+| `/kg-entity` `/kg-relation` | 知识图谱实体/关系列表 |
+
+所有接口除 `/system-config/login` 外均需 `Authorization: Bearer <JWT>`。
+
+## 项目结构
+
+```
+common/          通用层：HTTP 服务/鉴权/文件解析/中文分词/向量 JSON
+kb/
+  consts/        表名、状态、常量
+  model/         entity / dto / domain
+  dao/           数据访问（每表一个文件）
+  service/       业务逻辑（每表一个文件 + chat_service 问答编排）
+  controller/    接口层（每表一个文件）
+ui-src/          Vue 3 前端
+docs/            实现方案文档
+```