KnowledgeVault — 智能知识库检索与隐私保护分析系统

一个零门槛、本地运行的知识库问答系统。上传你的文档（或输入网址），系统自动理解内容、建立索引，然后用 AI 生成带有引用来源的专业分析报告。

你不需要会编程——只需要跟着下面的步骤做，10 分钟就能跑起来。

你能用它做什么

上传文档即用 — 拖拽 .txt 文件到网页，系统自动分词、向量化、建立索引
输入网址提炼知识库 — 粘贴网页链接，AI 自动抓取内容并提炼成结构化文档（支持新闻、百科、博客等）
自然语言提问 — 像聊天一样问问题，系统从知识库中检索相关内容，结合 AI 生成专业报告
自动匹配合适的分析视角 — 系统识别内容领域（财经/时政/科技/医疗/法律/教育），自动切换对应的专家角色
隐私保护 — 报告发送到云端 API 前，自动隐藏手机号、身份证、银行卡号等敏感信息
全过程可视化 — 在网页上查看完整的 Prompt 是如何组装的，了解 AI 在「看什么」

环境要求

你需要有	说明
一台电脑	Windows / Mac / Linux 都可以
Python 3.10+	python.org 下载安装
DeepSeek API Key	platform.deepseek.com 注册获取（新用户有免费额度）
网络连接	调用 DeepSeek API 时需要

不需要 GPU，不需要 Docker，不需要数据库服务。所有组件都在本地运行。

5 分钟快速上手

第 1 步：下载项目

git clone https://github.com/Vinceli-9527/KnowledgeVault.git
cd KnowledgeVault

如果你没有 Git，也可以直接在 GitHub 页面点击绿色的「Code」按钮 →「Download ZIP」，解压后进入文件夹。

第 2 步：安装依赖

打开终端（Windows 按 Win+R 输入 cmd，Mac 打开「终端」），进入项目文件夹后运行：

pip install -r requirements.txt

如果提示 pip 找不到，试试 pip3 install -r requirements.txt。

首次运行时会自动下载一个约 100MB 的中文 Embedding 模型，之后就不需要再下载了。

第 3 步：配置 API Key

# 复制一份配置文件
cp .env.example .env

然后用记事本打开 .env 文件，把里面的内容改成你真实的 API Key：

DEEPSEEK_API_KEY = "sk-你的真实密钥"

.env 文件已加入 .gitignore，不会被上传到 GitHub，放心。

第 4 步：启动服务

python server.py

看到 Server ready! Open http://localhost:8765 就说明启动成功了。

第 5 步：打开浏览器

在浏览器地址栏输入 http://localhost:8765，就能看到界面了。

Web 界面指南

打开网页后你会看到以下几个区域：

顶部状态栏

显示三个状态指示灯：

管道就绪（绿色=正常）
API Key 已配置（绿色=已配置好）
向量索引数量（显示知识库中有多少条可检索的数据）

搜索区域

搜索框：输入你想问的问题
快捷提示词：点击即可自动填入示例问题（可以点 × 删除不需要的）
点击「开始分析」或按回车键提交

知识库管理（可折叠面板）

上传文档：拖拽 .txt 文件或点击选择文件
文档列表：查看已上传的文档、分块数、字数
删除：每个文档旁有删除按钮
编写指南：点击「如何编写高质量知识库文档？」查看格式规范（详见下方）

分析报告 Tab

AI 生成的专业分析报告，支持 Markdown 格式
报告顶部显示生成耗时和使用的分析视角（如「🏦 财经分析视角」）

Prompt 工程 Tab

查看完整的 System Prompt（角色设定）和 User Prompt（组装后的上下文）
不同颜色标注：检索上下文（紫色）、结构化数据（绿色）、用户查询（橙色）
帮助你理解 AI 是如何「看到」你的知识库内容的

检索结果 Tab

展示从知识库中检索到的文档片段
每个片段显示相关度分数和来源文档

知识库文档编写指南

为了让 AI 更好地理解你的知识库，建议遵循以下格式规范。

基本要求

文件格式：.txt 纯文本
编码：UTF-8（用记事本保存时默认就是）
文件第一行会自动成为文档标题

段落规则

系统会按照空行来切分段落，所以：

✅ 不同主题之间用空行隔开（按两次回车）
✅ 每个段落保持在 100-800 字之间
✅ 段落内信息尽量独立完整
❌ 不要几千字不分段
❌ 不要写超短的段落（少于 50 字会被跳过）

小贴士

使用清晰的标题标注不同主题
涉及数字、日期、人名等信息时，确保在同一段落内完整表达
避免大段无标点的连续文字

网页界面的知识库管理面板中有展开的编写指南，随时可参考。

网址提炼功能（偷懒模式）

不想手动写文档？直接把网址贴进来，AI 帮你搞定。

使用方法

展开「想偷懒？试试输入网址帮你快速构成知识库」面板
粘贴网址，每行一个（支持新闻、百科、博客等网页）
点击「抓取并提炼」，系统会自动：
- 抓取网页内容
- 提取正文（去掉广告、导航等无关信息）
- 用 AI 提炼成结构化的知识库文档
- 保存到本地 data/sample_docs/ 目录
提炼完成后会弹窗告诉你文件保存在哪里
点击「导入已提炼的文档」即可加载到知识库中

支持的网址类型

类型	说明
新闻文章	自动提取标题和正文
百科页面	提取知识条目并结构化
博客文章	提取核心观点和组织结构
在线文档	提取文本内容
JSON 接口	提取前 50000 字符

不支持图片、视频、PDF 等非文本内容。

智能领域识别

系统会自动分析你的知识库内容属于哪个领域，然后切换对应的专家角色来生成报告。你不需要手动选择。

领域	专家角色	触发关键词举例
🏦 财经	资深金融分析师（20年投行经验）	营收、利润、并购、上市、股票
🏛️ 时政	资深时政评论员（15年智库经验）	政府、政策、法规、改革、国务院
💻 科技	资深科技行业分析师（10年TMT经验）	AI、芯片、算法、云计算、新能源
🏥 医疗	资深医疗行业分析师（临床+产业背景）	医院、药品、临床、疫苗、医保
⚖️ 法律	资深法律分析师（20年商业法律经验）	法律、诉讼、合规、合同、专利
📚 教育	资深教育研究员（教育学博士）	教育、学校、课程、高考、学术
🌐 通用	专业信息分析师（兜底角色）	无匹配关键词时使用

每个领域不仅有专属的角色设定，还有不同的报告结构模板——财经侧重财务指标分析，时政侧重政策解读，科技侧重竞争格局，等等。

项目结构

KnowledgeVault/
├── server.py                     # Web 服务入口（FastAPI）
├── main.py                       # 命令行管道（批处理模式）
├── config.py                     # 所有参数集中管理
├── requirements.txt              # Python 依赖包清单
├── .env.example                  # API Key 配置模板
│
├── frontend/
│   └── index.html                # Vue3 单页应用（浏览器直接运行）
│
├── modules/
│   ├── data_loader.py            # 读取 .txt 文档
│   ├── chunker.py                # 段落感知分块（重叠策略）
│   ├── extractor.py              # LLM 结构化信息抽取
│   ├── embedder.py               # 本地 Embedding + ChromaDB 存储
│   ├── retriever.py              # 查询向量化 + 语义检索
│   ├── generator.py              # RAG 报告生成（含隐私脱敏）
│   ├── evaluator.py              # 抽取/检索/生成质量评估
│   ├── privacy.py                # 敏感信息检测与脱敏
│   ├── domain_classifier.py      # 内容领域自动识别
│   └── url_ingester.py           # 网址抓取 + AI 提炼
│
├── prompts/
│   ├── personas.py               # 领域-人格注册表（6大领域）
│   ├── extraction.py             # 抽取 Prompt 模板
│   └── generation.py             # 报告生成 Prompt 模板（动态角色）
│
├── db/
│   ├── schema.py                 # 数据库建表语句
│   └── repository.py             # 数据库读写操作
│
├── data/
│   ├── sample_docs/              # 知识库文档存放目录
│   └── ground_truth.json         # 评估用人工标注数据
│
├── utils/
│   └── helpers.py                # 日志、计时等工具函数
│
├── chroma_store/                 # 向量数据库文件（自动生成）
└── output/                       # 生成的报告文件（自动生成）

API 接口

所有接口均在 http://localhost:8765 下：

方法	路径	说明
`GET`	`/`	Web 交互界面
`GET`	`/api/health`	系统健康检查
`POST`	`/api/query`	提交查询，返回检索结果 + AI 报告
`POST`	`/api/extract`	触发 LLM 信息抽取
`GET`	`/api/knowledge`	查看知识库文档列表
`POST`	`/api/knowledge/upload`	上传 .txt 文件到知识库
`DELETE`	`/api/knowledge/{doc_id}`	删除指定文档
`POST`	`/api/knowledge/ingest-url`	提交网址列表，AI 提炼为知识库文档
`POST`	`/api/knowledge/import-saved`	将已提炼的文档导入知识库

查询示例

curl -X POST http://localhost:8765/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "深圳创新科技2024年的财务状况如何？", "top_k": 5}'

返回内容包含：AI 生成的 Markdown 报告、检索到的文档片段（含相关度）、PII 脱敏数量、使用的领域和专家角色。

上传文件示例

curl -X POST http://localhost:8765/api/knowledge/upload \
  -F "files=@我的文档.txt"

网址提炼示例

curl -X POST http://localhost:8765/api/knowledge/ingest-url \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/news/article1", "https://example.com/wiki/page2"]}'

命令行模式

# 运行完整管道（一次性批处理）
python main.py

# 跳过 LLM 调用，仅测试本地模块
python main.py --skip-extraction --skip-generation

# 追加自定义查询
python main.py -q "分析这三家公司的盈利能力对比"

隐私保护机制

系统在将检索到的文本发送给 DeepSeek API 之前，自动检测并替换以下敏感信息：

类型	检测方式	替换为
手机号	正则精确匹配	`[手机号已隐藏]`
身份证号	18位 + 校验位验证	`[身份证号已隐藏]`
银行卡号	16-19位连续数字	`[银行卡号已隐藏]`
电子邮箱	标准邮箱正则	`[邮箱已隐藏]`
人员姓名	上下文模式匹配	`[姓名已隐藏]`
表格数据	Markdown 表格 / TSV 行	`[表格行已隐藏]`

脱敏后的实际 Prompt 可在 Web 界面的「Prompt 工程」标签页查看验证。

技术架构

上传 .txt / 输入网址 → 段落分块 → LLM 抽取字段 → SQLite 存储
                              ↘
                        本地 Embedding → ChromaDB 向量索引

用户提问 → 领域识别 → 向量检索 → 匹配专家人格 → 组装 Prompt → LLM 生成报告
                                              ↑
                                        PII 自动脱敏

组件	选型	说明
大语言模型	DeepSeek Chat	负责信息抽取和报告生成
Embedding	BAAI/bge-small-zh-v1.5	本地运行，无需 API，中文优化
向量数据库	ChromaDB	持久化存储，重启不丢失数据
结构化存储	SQLite	文件级数据库，无需安装服务
前端	Vue 3 + marked.js	CDN 引入，零构建，浏览器即用
后端	FastAPI + uvicorn	Python Web 框架，自动生成 API 文档

不使用 LangChain 等重量级框架，所有代码纯 Python 实现，逻辑清晰可读。

可配置参数

在 config.py 中集中管理，API Key 通过 .env 文件设置：

参数	默认值	说明
`CHUNK_MAX_CHARS`	1000	分块最大字符数
`CHUNK_OVERLAP_CHARS`	200	相邻块重叠字符数
`CHUNK_MIN_CHARS`	50	低于此长度的内容会被过滤
`TOP_K_RETRIEVAL`	5	每次检索返回的片段数
`EXTRACTION_TEMPERATURE`	0.1	信息抽取时的 LLM 温度（越低越稳定）
`GENERATION_TEMPERATURE`	0.3	报告生成时的 LLM 温度
`API_TIMEOUT_SECONDS`	60	API 请求超时时间

常见问题

Q: 启动时报错 "DEEPSEEK_API_KEY not configured"

A: 检查 .env 文件是否存在，以及里面的 Key 是否正确（不要有多余的引号或空格）。

Q: 提示 "No module named 'xxx'"

A: 运行 pip install -r requirements.txt 确保所有依赖都安装了。

Q: 网页打开了但是搜索报错

A: 看一下终端里的错误信息。最常见的原因是：

API Key 余额不足
网络连接问题（需要能访问 api.deepseek.com）
知识库还没有上传任何文档

Q: 怎么添加自己的文档？

A: 准备 .txt 文件（用记事本写就行），在网页上拖拽上传。编写格式参考知识库文档编写指南。

Q: 支持 PDF / Word / 网页吗？

A: 直接上传只支持 .txt。但你可以用「网址提炼」功能粘贴网页链接，AI 会自动抓取并提炼。PDF/Word 请先复制内容到 .txt 文件中。

Q: 数据存在哪里？安全吗？

A: 所有数据都在你电脑的 data/ 和 chroma_store/ 目录下。只有生成报告时会把脱敏后的文本片段发送给 DeepSeek API，原始文档不会离开你的电脑。

Q: 怎么关掉服务？

A: 在终端里按 Ctrl+C 即可。

许可证

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
data		data
db		db
frontend		frontend
modules		modules
prompts		prompts
utils		utils
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.py		config.py
main.py		main.py
requirements.txt		requirements.txt
server.py		server.py

Folders and files

Latest commit

History

Repository files navigation