# TinyMind

**Repository Path**: wjqnxw/tiny-mind

## Basic Information

- **Project Name**: TinyMind
- **Description**: 打造一个“一粒种子就能长成知识森林”的微智脑基座。企业只需准备一台普通的办公电脑或轻量云服务器，上传自有文档，系统在喝杯咖啡的时间内自动完成知识萃取与模型适配，即可拥有一个完全私有、精准应答、持续进化的专属智能体
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微智脑（TinyMind）—— 极小体量企业智能知识库系统

## 需求规格说明书 & 概要设计说明书


## 一、项目概述

### 1.1 项目背景

大语言模型正在重塑企业知识管理，但已有方案普遍存在两个极端：云端大模型服务存在数据出境风险和高昂的调用成本，而开源私有化方案又依赖高端GPU、部署运维复杂。大量中小企业拥有强烈的知识库智能化需求，却受限于IT预算有限、服务器配置不高（常见为4核CPU、8-16GB内存、无独立显卡）的现实。市场亟需一款“开箱即用、极低配置就能跑、上传文档就能变聪明”的微型智能知识库基座。

### 1.2 产品愿景

打造一个“一粒种子就能长成知识森林”的微智脑基座。企业只需准备一台普通的办公电脑或轻量云服务器，上传自有文档，系统在喝杯咖啡的时间内自动完成知识萃取与模型适配，即可拥有一个完全私有、精准应答、持续进化的专属智能体。

### 1.3 核心价值

| 维度 | 价值描述 |
| :--- | :--- |
| **极小体量** | 基座模型参数量0.5B-1.5B，经4-bit量化后内存占用不足1.5GB，纯CPU流畅推理 |
| **极速训练** | 千页文档从上传到可问答，索引构建时间控制在5分钟以内；可选LoRA微调不超过30分钟 |
| **极低配置** | 支持4核CPU、8GB内存、无GPU的服务器或PC，无需任何AI加速卡 |
| **完全私有** | 所有数据不出企业边界，知识库和模型均存储于本地，无任何外部API依赖 |
| **一问即答** | 基于RAG（检索增强生成）与可选微调，精准回答企业知识相关问题，严格溯源到原始文档 |


## 二、需求规格说明书

### 2.1 用户角色

| 角色 | 描述 | 核心诉求 |
| :--- | :--- | :--- |
| **企业知识管理员** | 负责整理并上传公司制度、产品手册、技术规范等文档 | 快速导入资料，验证问答效果，无需懂AI技术 |
| **普通员工** | 在日常工作中通过聊天界面查询内部知识 | 像问同事一样提问，立刻获得准确答案和出处 |
| **IT运维人员** | 负责在企业服务器上安装部署微智脑 | 部署过程简单（一条Docker命令），资源占用低，稳定运行 |

### 2.2 功能性需求

#### 2.2.1 文档导入与智能处理

| ID | 功能 | 详细描述 | 验收标准 |
| :--- | :--- | :--- | :--- |
| FR-1 | 多格式文档上传 | 支持上传PDF、Word(.docx)、Markdown、TXT、Excel(.xlsx)、PPT(.pptx)、HTML等常见格式，支持批量拖拽上传 | 单个文件最大100MB，单次批量不超过50个文件，解析成功率≥95% |
| FR-2 | 智能文档解析 | 自动提取文本内容，识别标题层级、表格数据和图片中的文字（OCR可选），保留文档结构信息 | 表格内容正确提取为结构化文本，目录层级保留≥3级 |
| FR-3 | 自适应文档切分 | 根据文档类型和内容结构，自动选择最佳切分策略：按标题层级切分、按语义段落切分、按固定大小重叠切分，并保留文档来源元数据 | 切分后的片段平均长度200-800 tokens，语义完整度人工抽检满意率≥85% |
| FR-4 | 向量化与索引构建 | 使用轻量级嵌入模型将文档片段转换为向量，存入本地向量数据库，构建可快速检索的语义索引 | 千页文档（约50万tokens）从上传到索引构建完成≤5分钟（4核CPU） |

#### 2.2.2 智能问答与交互

| ID | 功能 | 详细描述 | 验收标准 |
| :--- | :--- | :--- | :--- |
| FR-5 | 自然语言问答 | 员工以自然语言提问，系统从知识库检索相关片段，结合大模型生成精准答案，并标明引用出处（文档标题、页码或段落链接） | 单次问答首字生成时间≤2秒，完整答案生成速度≥15 tokens/秒 |
| FR-6 | 多轮对话支持 | 系统记忆当前会话上下文，支持对先前回答的追问、细化和澄清 | 上下文窗口可维护最近6轮对话，超出自动滑动 |
| FR-7 | 回答溯源与原文跳转 | 每个答案后附“引用来源”列表，点击可预览对应的文档原文片段，支持跳转到完整文档 | 引用来源高亮显示匹配片段，预览可上下滚动 |
| FR-8 | 答案质量反馈 | 用户可对答案进行“有用/无用”评价，评价数据用于后续知识库优化（如补充常见问题） | 反馈数据本地存储，管理员可导出分析 |

#### 2.2.3 可选高级功能：快速微调

| ID | 功能 | 详细描述 | 验收标准 |
| :--- | :--- | :--- | :--- |
| FR-9 | 一键微调启动 | 在系统运行一段时间、积累一定用户问答后，管理员可启动“专属微调”任务。系统基于历史问答对和文档内容，使用QLoRA技术对基座模型进行轻量适配 | 微调需消耗额外内存（峰值不超过16GB），训练时间不超过30分钟（千条问答对） |
| FR-10 | 模型版本管理 | 微调产出新模型权重文件，与原基座模型并存。管理员可在多个模型版本间切换，或回滚至默认基座 | 切换操作可在Web界面完成，无需重启服务 |

#### 2.2.4 管理与运维

| ID | 功能 | 详细描述 | 验收标准 |
| :--- | :--- | :--- | :--- |
| FR-11 | 知识库管理 | 管理员可查看已上传文档列表，支持按分类筛选、删除文档、重新索引、查看索引状态 | 界面响应式，支持搜索文档名称 |
| FR-12 | 使用统计仪表盘 | 展示问答总量、热门问题、知识库覆盖率、未命中问题记录等，帮助管理员了解知识缺口 | 统计数据每10分钟刷新一次 |
| FR-13 | 系统资源监控 | 实时显示CPU、内存、磁盘使用率，以及索引大小、模型加载状态 | 轻量级监控，资源占用<50MB |
| FR-14 | 一键部署与升级 | 提供Docker Compose编排文件，一条命令即可启动全部服务。新版本通过替换镜像完成升级，数据持久化保留 | 部署时间≤3分钟（不含镜像下载），升级不影响已有数据 |

### 2.3 非功能性需求

| 类别 | 要求 |
| :--- | :--- |
| **最低硬件配置** | 4核CPU（x86_64或ARM64）、8GB RAM、30GB磁盘空间，无GPU需求。推荐16GB RAM以获得更流畅的微调体验 |
| **操作系统** | 支持Ubuntu 20.04+、CentOS 7+、Windows 10/11 (WSL2)、macOS 13+ (Apple Silicon) |
| **性能基线** | 问答并发用户数≥5（8GB内存下）；千页文档索引构建≤5分钟；问答首字延迟≤2秒 |
| **安全性** | 所有数据处理均在本地进行，无任何网络外呼。管理后台可设置访问账号和密码，通信使用HTTP Basic或简单Token |
| **可靠性** | 知识库索引和模型文件支持一键备份恢复。向量数据库使用本地持久化存储，重启不丢失 |
| **可维护性** | 系统运行日志输出至标准输出，可对接Docker日志驱动。提供健康检查端点 |


## 三、概要设计说明书

### 3.1 总体架构

微智脑采用“一体式微服务”架构，将所有功能模块封装在单个或极少量Docker容器中，通过轻量级进程内调用取代复杂的分布式通信，极致简化部署拓扑。

整个系统由四个逻辑层构成。最底层为**本地存储层**，存放原始文档、向量索引、量化模型权重和用户数据。其上是**核心引擎层**，包含文档处理管道、向量检索引擎和LLM推理运行时，三者均为本地CPU进程，通过Python进程内调用协作。再上层是**API服务层**，基于FastAPI提供RESTful接口，供前端调用。最顶部为**Web管理界面**，采用极简的单页面设计，提供文档管理、问答对话和系统设置功能。

所有组件的运行完全不依赖外部云服务和专有硬件，仅需一台符合最低配置的普通服务器。

### 3.2 技术选型

#### 3.2.1 选型总览

| 领域 | 技术选型 | 理由 |
| :--- | :--- | :--- |
| **编程语言** | Python 3.11+ | 生态成熟，AI库支持最全，开发效率高 |
| **Web框架** | FastAPI | 高性能异步框架，自动生成接口文档，支持流式响应 |
| **前端** | 单页HTML + Vanilla JS / 轻量Vue | 避免重前端框架，减少构建复杂度，保持整体体积极小 |
| **文档解析** | PyMuPDF (PDF) + python-docx (Word) + Unstructured (通用) | 覆盖主流格式，纯Python运行，CPU高效 |
| **嵌入模型** | BAAI/bge-small-zh-v1.5 (ONNX量化) | 仅约100MB，384维，中文语义表现优异，CPU推理快速 |
| **向量数据库** | ChromaDB | 嵌入式运行，零配置，基于SQLite持久化，支持内存模式 |
| **基座大模型** | Qwen2.5-1.5B-Instruct 或 0.5B-Instruct (GGUF Q4_K_M) | 1.5B版内存占用约1.2GB，回答质量满足企业知识问答；0.5B版仅需0.5GB内存，适合极致低配 |
| **模型推理** | llama.cpp + llama-cpp-python | 纯CPU高效推理，支持GGUF量化模型，支持GPU可选加速 |
| **微调框架** | LLaMA-Factory（基于Unsloth加速） | 支持QLoRA微调，资源消耗极低，4GB内存即可训练1.5B模型，提供命令行与Web界面 |
| **部署容器** | Docker + Docker Compose | 环境一致性，一键启动，跨平台兼容 |
| **数据持久化** | 本地文件系统（或挂载卷） | 文档、索引、模型均持久化在宿主机目录 |

#### 3.2.2 关键选型理由详述

- **为什么是0.5B/1.5B参数模型？** 极小模型在CPU上即可实现20-50 tokens/秒的生成速度，满足实时对话需求。1.5B模型在常见企业知识问答场景中，配合高质量RAG策略，回答准确率可达85%以上，足以应对内部知识查询。0.5B模型适合极致低配（4GB内存）或简单FAQ场景。
- **为什么选择ChromaDB而非Elasticsearch/Milvus？** 极致的轻量化。ChromaDB是一个嵌入式向量数据库，无需独立服务进程，核心代码仅数千行，安装包极小，可直接嵌入应用，避免复杂的集群部署和资源开销，非常契合“微智脑”定位。
- **为什么推荐QLoRA微调？** 全量微调1.5B模型需要至少12GB GPU显存，企业无法负担。QLoRA通过4-bit量化基座并插入极少的可训练参数（通常是原参数的0.1%-1%），使得在仅有8GB内存的CPU上（使用内存训练，速度较慢）或普通消费级GPU上（如GTX 1660 6GB）即可完成定制微调，训练时长可控制在30分钟以内。

### 3.3 核心模块设计

#### 3.3.1 文档智能处理管道

文档上传后，管道按序完成解析、清洗、分块和向量化四个步骤。

解析器根据文件扩展名自动选择对应解析库。PDF优先使用PyMuPDF提取文本和目录；Word使用python-docx提取段落和表格；PPT提取文本框内容；Excel转为Markdown表格；图片可通过可选OCR模块转为文字（默认关闭以保持轻量）。解析结果统一为带结构标记的纯文本。

清洗阶段过滤页眉页脚、重复空白符号、无意义的换行，并修复编码问题。

分块是影响问答质量的关键。系统默认采用“自适应分块”策略：优先按文档的一二级标题切分，当标题层级不清晰时，自动降级为以300-500字为窗口的语义段落切分，每次滑动重叠50字，确保跨块语义连贯。分块的同时保留文档来源、标题路径和段落序号等元数据，用于后续溯源。

向量化使用ONNX量化的bge-small模型，在CPU上单次编码延迟约20ms。所有文本块被转换为384维向量，与元数据一同写入ChromaDB集合。集合名以知识库名称命名，方便未来扩展多知识库。

管道为纯CPU操作，经测试，千页标准文档（约50万tokens）在4核CPU上可在5分钟内完成从上传到索引就绪的全流程。

#### 3.3.2 RAG问答引擎

当用户提问时，引擎执行“检索-重排-生成”三步流程。

检索阶段采用混合策略：ChromaDB默认的余弦相似度召回Top-20个相关片段，同时可选并行调用一个极轻量的BM25关键词检索（基于本地TF-IDF）召回Top-10，两者结果合并去重，保留Top-15送入下一阶段。

重排阶段使用轻量级交叉编码器（如bge-reranker-base的ONNX量化版，约200MB）对这15个片段进行精细语义相关性评分，重排后取Top-5作为最终上下文。若无重排模型（内存更紧张的情况），则跳过此步直接取Top-5相似片段。

生成阶段将Top-5片段内容和用户问题填入提示模板，发送给llama.cpp推理服务。提示模板明确要求“仅基于提供的文档内容作答，若无法找到相关信息请如实告知”，并指示引用出处。模型生成时，API服务以Sever-Sent Events流式返回回答，前端实时打字机显示。

回答完成后，系统自动将答案和引用片段保存，供后续反馈和微调使用。

#### 3.3.3 可选QLoRA微调引擎

当系统积累了一定量的问答数据（含用户正反馈和编辑后的理想答案）后，管理员可启动微调以进一步提升模型对本企业知识的掌控力。

微调采用QLoRA技术。首先将已有文档内容与高质量的问答对合并，格式化为指令微调数据。数据规模通常只需几百到数千条。训练脚本基于LLaMA-Factory，调用Unsloth加速内核，以4-bit加载1.5B基座模型，冻结原有权重，插入极小秩的适配器矩阵（LoRA rank一般为8-16）。训练在纯CPU或可选GPU上运行，单条数据反传仅需几十毫秒，全量数据训练10个epoch通常不超过30分钟（千条数据，4核CPU）。

产出新的LoRA权重文件（仅几MB到几十MB），不修改原基座模型。推理时，llama.cpp加载基座模型，同时应用该LoRA权重，即实现定制效果。系统支持多个LoRA并存，可在管理界面切换。

#### 3.3.4 嵌入式API与前端

后端API由FastAPI统一提供，主要端点包括：

- 文档上传与管理（POST/DELETE /documents）
- 知识库状态查询（GET /kb/status）
- 问答接口（POST /chat，支持流式响应）
- 微调任务管理（POST /finetune/start, GET /finetune/status）
- 系统健康检查（GET /health）

前端采用极简的静态页面，从后端API获取数据，无需额外构建步骤。核心界面为两个视图：聊天视图（员工使用，类ChatGPT风格）和管理视图（文档列表、统计、设置）。前端资源可直接由FastAPI挂载的静态目录提供，或通过Nginx轻量代理。

### 3.4 部署与交付形态

微智脑被打包为一个或两个Docker镜像（核心服务镜像、可选微调服务镜像），通过Docker Compose编排。典型安装步骤：

1. 安装Docker和Docker Compose。
2. 下载微智脑发行包，包含Compose文件和模型下载脚本。
3. 执行下载脚本获取GGUF量化模型和嵌入模型（约2-3GB）。
4. 启动Compose，系统自动初始化数据库和索引。

所有数据（上传文档、向量索引、模型、配置）均映射到宿主机目录，实现持久化。备份只需打包该目录。

对于Windows和macOS用户，提供WSL2 (Ubuntu) 和原生Docker Desktop的安装指引，同样一键启动，无需额外配置。

### 3.5 性能优化与低配保障

- **模型量化**：模型以Q4_K_M精度量化，相比FP16体积减少75%，速度提升2-3倍，准确率损失小于3%。
- **上下文窗口优化**：基座模型上下文窗口限制在4096 tokens，以降低内存和计算开销。检索片段被控制在1500 tokens以内，为回答预留足够空间。
- **索引性能**：ChromaDB采用HNSW索引，内存占用约为向量总量的1.5倍。50万片段（约5GB向量）在16GB内存下绰绰有余。
- **推理并行**：llama.cpp默认使用所有CPU核心，4核下即可达到15-25 tokens/秒的生成速度，满足对话流畅度。
- **可选加速**：若有Intel酷睿12代+或AMD Zen4+ CPU，可利用AVX2指令集显著提升速度；若企业后续有GPU，可切换为CUDA/OpenCL后端。

### 3.6 安全与隐私设计

系统完全离线运行，不向任何外部地址发起请求。管理后台默认仅监听本地端口，可通过Nginx反向代理暴露给内网，并配置简单的HTTP Basic认证。更高级的认证（如LDAP集成）作为可选附加模块，但不增加核心复杂度。所有企业文档和问答数据均在本地，IT管理员可完全掌控。

### 3.7 开发与迭代路线

| 阶段 | 内容 |
| :--- | :--- |
| **第一阶段（核心闭环）** | 实现文档上传解析、分块、ChromaDB索引、RAG问答、llama.cpp集成，提供基本Web UI。 |
| **第二阶段（增强与微调）** | 加入自适应分块策略、混合检索、reranker、反馈收集、QLoRA微调功能。 |
| **第三阶段（多模态与多知识库）** | 支持图片OCR、表格问答、多知识库隔离、简单的权限控制。 |
| **持续迭代** | 跟踪更高效的小模型发布，优化prompt模板，提高长文档问答质量。 |


## 四、总结

“微智脑”重新定义了企业知识库的交付形态。它不是一个功能繁复的大平台，而是一个极轻、极快、可在任何老旧服务器上生根发芽的智能基座。通过精巧的小模型量化、嵌入式向量数据库与可选微调的结合，系统在极低的硬件门槛下实现了“上传即学会、对话即应用”的完整闭环。完全的本地私有化保障了企业数据主权，而极简的部署运维让IT人员几乎零负担。这是一款真正为千万中小企业而生的“口袋智能体”，让先进AI能力不再是大厂的专属，成为每一家企业的数字员工标配。