ai-localbase

Name: ai-localbase
Author: veyliss

352stars48forks

How to install ai-localbase?

veyliss/ai-localbase

$git clone https://github.com/veyliss/ai-localbase

Installs into the current project.

Summary

一个本地优先的 AI 知识库系统（RAG），用于将本地文档接入向量检索与大模型对话流程。项目提供 Web UI，支持知识库管理、文档上传、检索增强问答、聊天记录持久化，以及基于 Ollama 或 OpenAI 兼容接口的模型接入。

Files · 1

View on GitHub

README.md

1	# AI LocalBase
2
3	一个本地优先的 AI 知识库系统（RAG），用于将本地文档接入向量检索与大模型对话流程。项目提供 Web UI，支持知识库管理、文档上传、检索增强问答、聊天记录持久化，以及基于 Ollama 或 OpenAI 兼容接口的模型接入。
4
5	![首页预览](./assets/home-page.png)
6
7	## 项目简介
8
9	AI LocalBase 适合个人或小团队在本地环境、自托管环境中快速搭建可用的知识库问答系统。
10
11	- 后端：Go + Gin
12	- 前端：React + Vite + TypeScript
13	- 向量数据库：Qdrant
14	- 模型接入：Ollama / OpenAI Compatible API
15	- 部署方式：Docker Compose（推荐），本地单进程调试作为补充
16	- 扩展能力：内置 MCP Server，可供外部 Agent / 工具系统接入
17
18	---
19
20	## 核心能力
21
22	- 知识库管理：创建、删除知识库，查看文档列表
23	- 文档上传与索引：支持 TXT、Markdown、PDF、xlsx、csv 文件上传与解析
24	- 检索增强问答：基于 Qdrant 做向量检索并把命中内容注入对话上下文
25	- 聊天记录持久化：会话消息保存到本地 SQLite 数据库
26	- 配置持久化：模型配置与知识库状态保存到本地 JSON 文件
27	- Docker Compose 部署：支持一键拉起前端、后端、Qdrant
28
29	### 检索增强能力
30
31	- 文本自动切分与批量嵌入
32	- 候选结果动态召回
33	- 关键词覆盖增强重排
34	- MMR 去冗余选择
35	- 低置信度场景二次扩召回
36	- 嵌入缓存与可选语义缓存
37	- 可选 Hybrid Search、Semantic Reranker、Query Rewrite、Context Compression
38	- 可从现有知识库文档生成 RAG 评估数据集，用于小样本效果验证
39
40	---
41
42	## 适用场景
43
44	- 本地个人知识库
45	- 团队内部文档问答
46	- 自托管 RAG 原型验证
47	- Ollama / OpenAI 兼容模型接入测试
48	- 检索策略实验与评估
49	- 作为 MCP 能力后端供 Agent 调用
50
51	---
52
53	## 快速开始
54
55	最短体验路径：
56
57	1. 复制环境变量模板：
58
59	```bash
60	cp .env.example .env
61	```
62
63	2. 启动全部服务：
64
65	```bash
66	docker compose up --build
67	```
68
69	3. 打开 `http://localhost:4173`，进入设置页配置 Chat 与 Embedding 模型。
70
71	如需更完整的命令、环境变量与接口说明，请查看 [`docs/getting-started.md`](docs/getting-started.md)。
72
73	---
74
75	## 启动与部署
76
77	### Docker Compose 一键启动（推荐）
78
79	适合快速体验和自托管部署。
80
81	```bash
82	cp .env.example .env
83	docker compose up --build
84	```
85
86	常用运行配置已集中在 `.env.example`。其中 `QDRANT_VECTOR_SIZE` 必须与 Embedding 模型维度一致；如果你更换了不同维度的 Embedding 模型，需要换新的 `QDRANT_COLLECTION_PREFIX` 或重建旧集合。开启 `ENABLE_HYBRID_SEARCH` 前也建议换新前缀并重建索引，以便 Qdrant collection 使用 named dense/sparse vectors。
87
88	Docker 自托管建议设置：
89
90	- `ENABLE_AUTH=true`：开启 Web 登录与 API Key 鉴权。
91	- `AUTH_USERNAME=root`：默认 root 用户名。
92	- `AUTH_PASSWORD=<强密码>`：首次启动自动创建 root 用户。
93	- `AUTH_SETUP_TOKEN=<随机值>`：如果不使用 `AUTH_PASSWORD`，建议设置初始化保护 Token。
94	- `QDRANT_BIND_ADDRESS=127.0.0.1`：默认只允许宿主机本机访问 Qdrant 端口，避免服务器部署时暴露向量库。
95	- `MAX_UPLOAD_BYTES=26214400`：默认单文件上传上限为 25 MiB，可按资源情况调大。
96
97	如果 `ENABLE_AUTH=true` 且未设置 `AUTH_PASSWORD`，首次访问 Web 页面会进入初始化向导。公网部署时请优先设置 `AUTH_PASSWORD` 或 `AUTH_SETUP_TOKEN`，避免初始化窗口被他人抢占。
98
99	默认服务地址：
100
101	- 前端：`http://localhost:4173`
102	- 后端：`http://localhost:8080`
103	- Qdrant HTTP API：`http://localhost:6333`
104	- Qdrant gRPC：`localhost:6334`
105
106	默认情况下 Qdrant 端口只绑定在 `127.0.0.1`。如果需要让其他机器直接访问 Qdrant，请显式设置 `QDRANT_BIND_ADDRESS=0.0.0.0`，并同时配置 `QDRANT_API_KEY` 与服务器防火墙。
107
108	默认数据目录由 `.env` 控制，主要包括上传文件、应用状态、聊天 SQLite 数据库和 Qdrant 持久化目录。升级或迁移前建议先备份这些路径，详见 [`docs/backup-restore.md`](docs/backup-restore.md)。
109
110	### 使用预构建镜像部署
111
112	如果不想本地编译，可直接使用预构建镜像：
113
114	```bash
115	docker compose -f docker-compose.prod.yml up -d
116	```
117
118	更多镜像、版本与部署细节见 [`DOCKER_DEPLOY.md`](DOCKER_DEPLOY.md)。
119
120	### 仅启动应用编排
121
122	如果希望单独使用应用编排文件，也可以执行：
123
124	```bash
125	docker compose -f docker-compose.app.yml up --build
126	```
127
128	### 本地开发启动（推荐）
129
130	适合日常开发、调试接口、修改前端页面。该编排会同时启动 Qdrant、后端和前端开发服务器，并通过 volume 挂载本地代码：
131
132	```bash
133	cp .env.example .env
134	docker compose -f docker-compose.dev.yml up --build
135	```
136
137	默认开发地址：
138
139	- 前端：`http://localhost:4173`
140	- 后端：`http://localhost:8080`
141	- Qdrant：`http://localhost:6333`
142
143	如果需要单独运行后端、前端或测试命令，可参考 [`docs/getting-started.md`](docs/getting-started.md) 中的开发命令。
144
145	---
146
147	## 设置页面配置
148
149	### 设置页面
150
151	![设置页面](./assets/setting.png)
152
153	打开前端后，进入 Settings 页面，分别配置 Chat 与 Embedding。
154
155	### Ollama 示例
156
157	Chat 配置
158
159	- Provider: `ollama`
160	- Base URL: `http://localhost:11434`
161	- Model: `qwen2.5:7b` 或 `llama3.2`
162	- API Key: 留空
163
164	Embedding 配置
165
166	- Provider: `ollama`
167	- Base URL: `http://localhost:11434`
168	- Model: `bge-m3` 或 `nomic-embed-text`
169	- API Key: 留空
170
171	### OpenAI Compatible 示例
172
173	Chat 配置
174
175	- Provider: `openai`
176	- Base URL: 你的兼容接口地址，例如 `https://your-api.example.com/v1`
177	- Model: 对应聊天模型名
178	- API Key: 对应访问密钥
179
180	Embedding 配置
181
182	- Provider: `openai`
183	- Base URL: 你的兼容接口地址
184	- Model: 对应嵌入模型名
185	- API Key: 对应访问密钥
186
187	---
188
189	## MCP 支持
190
191	项目内置基础 MCP Server 能力，作为后端内嵌工具服务运行，可供外部 Agent、脚本或工具系统通过 HTTP / JSON-RPC 接入。
192
193	当前支持：
194
195	- MCP Server 版本：0.2.0
196	- HTTP 形式 MCP 入口
197	- 工具列表发现能力
198	- 只读 / 写入 / 危险工具权限分级
199	- API Key Scope 鉴权，旧 MCP Token 已废弃，仅保留迁移兼容开关
200	- 限流、超时与审计日志
201	- 危险工具一次性确认机制
202	- 复用现有知识库、会话、配置与检索服务
203	- MCP 能力自检工具：`get_mcp_capabilities`
204	- 文档详情、检索调试、结构化查询、评估集生成和重建索引工具
205	- MCP Job 工作流：异步导入、状态查询、取消和最近任务列表
206	- A

People who liked this also viewed

6 picks

Type

ai-localbase

352stars48forks

View on GitHub

How to install ai-localbase?

veyliss/ai-localbase

$git clone https://github.com/veyliss/ai-localbase

Installs into the current project.

Summary

Files · 1

View on GitHub

README.md

1	# AI LocalBase
2
3	一个本地优先的 AI 知识库系统（RAG），用于将本地文档接入向量检索与大模型对话流程。项目提供 Web UI，支持知识库管理、文档上传、检索增强问答、聊天记录持久化，以及基于 Ollama 或 OpenAI 兼容接口的模型接入。
4
5	![首页预览](./assets/home-page.png)
6
7	## 项目简介
8
9	AI LocalBase 适合个人或小团队在本地环境、自托管环境中快速搭建可用的知识库问答系统。
10
11	- 后端：Go + Gin
12	- 前端：React + Vite + TypeScript
13	- 向量数据库：Qdrant
14	- 模型接入：Ollama / OpenAI Compatible API
15	- 部署方式：Docker Compose（推荐），本地单进程调试作为补充
16	- 扩展能力：内置 MCP Server，可供外部 Agent / 工具系统接入
17
18	---
19
20	## 核心能力
21
22	- 知识库管理：创建、删除知识库，查看文档列表
23	- 文档上传与索引：支持 TXT、Markdown、PDF、xlsx、csv 文件上传与解析
24	- 检索增强问答：基于 Qdrant 做向量检索并把命中内容注入对话上下文
25	- 聊天记录持久化：会话消息保存到本地 SQLite 数据库
26	- 配置持久化：模型配置与知识库状态保存到本地 JSON 文件
27	- Docker Compose 部署：支持一键拉起前端、后端、Qdrant
28
29	### 检索增强能力
30
31	- 文本自动切分与批量嵌入
32	- 候选结果动态召回
33	- 关键词覆盖增强重排
34	- MMR 去冗余选择
35	- 低置信度场景二次扩召回
36	- 嵌入缓存与可选语义缓存
37	- 可选 Hybrid Search、Semantic Reranker、Query Rewrite、Context Compression
38	- 可从现有知识库文档生成 RAG 评估数据集，用于小样本效果验证
39
40	---
41
42	## 适用场景
43
44	- 本地个人知识库
45	- 团队内部文档问答
46	- 自托管 RAG 原型验证
47	- Ollama / OpenAI 兼容模型接入测试
48	- 检索策略实验与评估
49	- 作为 MCP 能力后端供 Agent 调用
50
51	---
52
53	## 快速开始
54
55	最短体验路径：
56
57	1. 复制环境变量模板：
58
59	```bash
60	cp .env.example .env
61	```
62
63	2. 启动全部服务：
64
65	```bash
66	docker compose up --build
67	```
68
69	3. 打开 `http://localhost:4173`，进入设置页配置 Chat 与 Embedding 模型。
70
71	如需更完整的命令、环境变量与接口说明，请查看 [`docs/getting-started.md`](docs/getting-started.md)。
72
73	---
74
75	## 启动与部署
76
77	### Docker Compose 一键启动（推荐）
78
79	适合快速体验和自托管部署。
80
81	```bash
82	cp .env.example .env
83	docker compose up --build
84	```
85
86	常用运行配置已集中在 `.env.example`。其中 `QDRANT_VECTOR_SIZE` 必须与 Embedding 模型维度一致；如果你更换了不同维度的 Embedding 模型，需要换新的 `QDRANT_COLLECTION_PREFIX` 或重建旧集合。开启 `ENABLE_HYBRID_SEARCH` 前也建议换新前缀并重建索引，以便 Qdrant collection 使用 named dense/sparse vectors。
87
88	Docker 自托管建议设置：
89
90	- `ENABLE_AUTH=true`：开启 Web 登录与 API Key 鉴权。
91	- `AUTH_USERNAME=root`：默认 root 用户名。
92	- `AUTH_PASSWORD=<强密码>`：首次启动自动创建 root 用户。
93	- `AUTH_SETUP_TOKEN=<随机值>`：如果不使用 `AUTH_PASSWORD`，建议设置初始化保护 Token。
94	- `QDRANT_BIND_ADDRESS=127.0.0.1`：默认只允许宿主机本机访问 Qdrant 端口，避免服务器部署时暴露向量库。
95	- `MAX_UPLOAD_BYTES=26214400`：默认单文件上传上限为 25 MiB，可按资源情况调大。
96
97	如果 `ENABLE_AUTH=true` 且未设置 `AUTH_PASSWORD`，首次访问 Web 页面会进入初始化向导。公网部署时请优先设置 `AUTH_PASSWORD` 或 `AUTH_SETUP_TOKEN`，避免初始化窗口被他人抢占。
98
99	默认服务地址：
100
101	- 前端：`http://localhost:4173`
102	- 后端：`http://localhost:8080`
103	- Qdrant HTTP API：`http://localhost:6333`
104	- Qdrant gRPC：`localhost:6334`
105
106	默认情况下 Qdrant 端口只绑定在 `127.0.0.1`。如果需要让其他机器直接访问 Qdrant，请显式设置 `QDRANT_BIND_ADDRESS=0.0.0.0`，并同时配置 `QDRANT_API_KEY` 与服务器防火墙。
107
108	默认数据目录由 `.env` 控制，主要包括上传文件、应用状态、聊天 SQLite 数据库和 Qdrant 持久化目录。升级或迁移前建议先备份这些路径，详见 [`docs/backup-restore.md`](docs/backup-restore.md)。
109
110	### 使用预构建镜像部署
111
112	如果不想本地编译，可直接使用预构建镜像：
113
114	```bash
115	docker compose -f docker-compose.prod.yml up -d
116	```
117
118	更多镜像、版本与部署细节见 [`DOCKER_DEPLOY.md`](DOCKER_DEPLOY.md)。
119
120	### 仅启动应用编排
121
122	如果希望单独使用应用编排文件，也可以执行：
123
124	```bash
125	docker compose -f docker-compose.app.yml up --build
126	```
127
128	### 本地开发启动（推荐）
129
130	适合日常开发、调试接口、修改前端页面。该编排会同时启动 Qdrant、后端和前端开发服务器，并通过 volume 挂载本地代码：
131
132	```bash
133	cp .env.example .env
134	docker compose -f docker-compose.dev.yml up --build
135	```
136
137	默认开发地址：
138
139	- 前端：`http://localhost:4173`
140	- 后端：`http://localhost:8080`
141	- Qdrant：`http://localhost:6333`
142
143	如果需要单独运行后端、前端或测试命令，可参考 [`docs/getting-started.md`](docs/getting-started.md) 中的开发命令。
144
145	---
146
147	## 设置页面配置
148
149	### 设置页面
150
151	![设置页面](./assets/setting.png)
152
153	打开前端后，进入 Settings 页面，分别配置 Chat 与 Embedding。
154
155	### Ollama 示例
156
157	Chat 配置
158
159	- Provider: `ollama`
160	- Base URL: `http://localhost:11434`
161	- Model: `qwen2.5:7b` 或 `llama3.2`
162	- API Key: 留空
163
164	Embedding 配置
165
166	- Provider: `ollama`
167	- Base URL: `http://localhost:11434`
168	- Model: `bge-m3` 或 `nomic-embed-text`
169	- API Key: 留空
170
171	### OpenAI Compatible 示例
172
173	Chat 配置
174
175	- Provider: `openai`
176	- Base URL: 你的兼容接口地址，例如 `https://your-api.example.com/v1`
177	- Model: 对应聊天模型名
178	- API Key: 对应访问密钥
179
180	Embedding 配置
181
182	- Provider: `openai`
183	- Base URL: 你的兼容接口地址
184	- Model: 对应嵌入模型名
185	- API Key: 对应访问密钥
186
187	---
188
189	## MCP 支持
190
191	项目内置基础 MCP Server 能力，作为后端内嵌工具服务运行，可供外部 Agent、脚本或工具系统通过 HTTP / JSON-RPC 接入。
192
193	当前支持：
194
195	- MCP Server 版本：0.2.0
196	- HTTP 形式 MCP 入口
197	- 工具列表发现能力
198	- 只读 / 写入 / 危险工具权限分级
199	- API Key Scope 鉴权，旧 MCP Token 已废弃，仅保留迁移兼容开关
200	- 限流、超时与审计日志
201	- 危险工具一次性确认机制
202	- 复用现有知识库、会话、配置与检索服务
203	- MCP 能力自检工具：`get_mcp_capabilities`
204	- 文档详情、检索调试、结构化查询、评估集生成和重建索引工具
205	- MCP Job 工作流：异步导入、状态查询、取消和最近任务列表
206	- A

People who liked this also viewed

6 picks

Type