多格式导入: Markdown（解析 frontmatter + 按 ## 标题分页）/ 纯文本 / Word 文档（.docx，按 Heading 分页）
批量导入: 支持多文件批量导入、整个目录导入，实时进度显示
智能分块: 按段落边界切分文本，保留重叠区域（默认 chunk_size=300, overlap=50）
向量嵌入: 支持 MiniMax / OpenAI / 智谱 / DashScope / 本地 BGE 五种嵌入模型
知识导出: 支持 JSON 和 Markdown 两种格式导出
索引重建: 支持单页面重新生成嵌入向量

图片 OCR

多 Provider: DeepSeek Vision / PaddleOCR / 阿里云 / 腾讯云，支持 auto 自动 fallback（PaddleOCR → DeepSeek → 阿里云 → 腾讯云）
批量处理: 支持拖拽上传、选择文件、选择文件夹、服务器路径批量导入
上传去重: OCR 识别后自动检查内容是否已存在，避免重复录入
图片管理: 网页端管理所有图片，支持一键去重、手动删除
并发控制: 通过 asyncio.Semaphore 控制 OCR 并发数量（可配置 1-10）

AI 搜索

知识库搜索: LIKE 关键词搜索 + LLM 查询扩展（生成语义相近的替代表述）
图片搜索: MiniMax M2.7 语义匹配，SSE 流式实时返回结果
并发池: 最多 10 个 LLM 请求并发，每批数量可配置
实体检测: 自动识别知识点、技巧、人物、概念等实体类型
可配置参数: 搜索返回数量、LLM 批量判断数量、OCR 并发数量均可在网页端动态修改

企业微信机器人

WebSocket 长连接: 基于 wecom-aibot-python-sdk，无需公网 IP
关键词搜索: 用户发文字 → 清理口语化前缀 → 搜索图片 → 流式回复文本 + 逐张发送图片
图片自动入库: 用户发图片 → 下载解密 → OCR 识别 → 自动去重入库 → 回复结果
分片上传: 支持大图片的三步分片上传（init → chunk → finish）
欢迎语: 进入会话时自动发送欢迎语
集成启动: 后端启动时自动检测配置并拉起机器人（BotManager 后台线程）
网页端管理: 在设置页面配置 Bot ID / Secret，支持在线重启

MCP 协议

MCP Server: 支持 stdio 和 sse 两种传输协议，可被外部 AI Agent 直接调用
5 个工具:
- search_knowledge: 语义搜索知识库
- get_page: 获取知识页面详情
- list_courses: 列出所有课程
- get_page_chunks: 获取页面的分块内容
- search_images: 根据关键字搜索已 OCR 识别的聊天截图
命令行入口: huibrain-mcp（通过 pyproject.toml 定义）

其他

运行时配置: 所有参数均可通过网页端设置 API 动态修改，无需重启服务
服务测试: 网页端支持在线测试嵌入模型、LLM、OCR 服务连通性
Docker 部署: 单容器部署，轻量级

技术栈

层级	技术	说明
后端框架	FastAPI + Uvicorn	异步 Python Web 框架
ORM	SQLAlchemy 2.0 (async)	异步 ORM
数据库	SQLite (aiosqlite)	轻量级，WAL 模式
配置管理	pydantic-settings	环境变量 / .env 文件加载
前端	纯 HTML + CSS + JS	苹果风格 SPA 单页应用
OCR	DeepSeek Vision / PaddleOCR / 阿里云 / 腾讯云	4 种 Provider + auto fallback
LLM	MiniMax M2.7 / DeepSeek / OpenAI	搜索匹配、查询扩展、批量判断
嵌入模型	MiniMax / OpenAI / 智谱 / DashScope / 本地 BGE	5 种嵌入 Provider
搜索	LIKE 关键词 + LLM 查询扩展	知识库搜索；图片搜索走 LLM 语义匹配
企业微信	wecom-aibot-python-sdk	WebSocket 长连接模式
MCP	mcp[cli] >= 1.2.0	Model Context Protocol
部署	Docker + docker-compose	单容器部署

项目结构

huibrain/
├── app/
│   ├── __init__.py               # 包初始化，定义版本号
│   ├── main.py                   # FastAPI 入口，路由注册，生命周期管理，BotManager
│   ├── config.py                 # pydantic-settings 配置管理（所有环境变量）
│   ├── database.py               # SQLite 异步数据库连接管理
│   ├── wework_bot.py             # 企业微信智能机器人服务（WebSocket 长连接）
│   ├── api/
│   │   └── v1/
│   │       ├── pages.py          # 知识页面 CRUD（列表/详情/创建/更新/删除/重建索引）
│   │       ├── search.py         # 语义搜索（向量+全文混合）
│   │       ├── images.py         # 图片 OCR + AI 搜索（SSE 流式）+ 去重 + 删除
│   │       ├── import_export.py  # 文件导入（.md/.txt/.docx）+ 目录导入 + 导出（JSON/Markdown）
│   │       └── settings.py       # 系统设置 + 机器人管理 + 服务测试 + 统计信息
│   ├── models/
│   │   └── base.py               # ORM 模型（KnowledgePage, KnowledgeChunk, OCRImage, WebsiteSettings）
│   ├── schemas/
│   │   ├── ocr.py                # OCR 相关 Schema
│   │   ├── page.py               # 页面相关 Schema
│   │   └── search.py             # 搜索相关 Schema
│   ├── services/
│   │   ├── ocr_service.py        # OCR 识别服务（4 种 Provider + auto fallback）
│   │   ├── llm_service.py        # LLM 服务（聊天/查询扩展/批量判断）
│   │   ├── search_service.py     # 知识库搜索服务（LIKE 关键词搜索）
│   │   ├── embedding_service.py  # 嵌入模型服务（5 种 Provider）
│   │   ├── import_service.py     # 文件导入服务（分块+向量化）
│   │   └── page_service.py       # 页面 CRUD 服务
│   └── mcp/
│       └── server.py             # MCP Server 实现（5 个工具供 AI Agent 调用）
├── static/
│   └── index.html                # 前端单页应用（苹果风格 SPA）
├── data/
│   ├── images/                   # 图片存储目录
│   └── transcripts/              # 转写文字稿（.docx/.md）
├── docs/
│   ├── IMAGE_API_GUIDE.md        # 图片 API 集成指南
│   └── 软著材料/                  # 软件著作权申请材料
├── .env.example                  # 环境变量模板
├── .gitignore                    # Git 忽略规则
├── pyproject.toml                # Python 项目元数据 + 构建配置
├── requirements.txt              # Python 依赖清单
├── Dockerfile                    # Docker 镜像构建
└── docker-compose.yml            # Docker Compose 编排

数据模型

模型	表名	说明
`KnowledgePage`	knowledge_pages	知识页面（标题/内容/来源/课程/讲师/日期/向量嵌入）
`KnowledgeChunk`	knowledge_chunks	文本分块（关联页面/分块索引/内容/嵌入向量）
`OCRImage`	ocr_images	OCR 图片记录（文件路径/OCR文本/置信度/Provider/状态/文本块）
`WebsiteSettings`	website_settings	网站设置（键值对，单例模式）

快速开始

1. 环境准备

# 克隆项目
git clone <repo-url>
cd huibrain

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

# 安装依赖（Python >= 3.11）
pip install -r requirements.txt

2. 配置 .env

编辑 .env 文件，至少配置以下项：

# 数据库（默认 SQLite，无需额外配置）
DATABASE_URL=sqlite+aiosqlite:///data/hui_brain.db

# OCR（使用 DeepSeek Vision）
OCR_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-deepseek-api-key
DEEPSEEK_BASE_URL=http://your-ollama-host:11434/v1
DEEPSEEK_OCR_MODEL=deepseek-ocr:latest

# LLM（用于搜索匹配）
MINIMAX_API_KEY=your-minimax-api-key
MINIMAX_BASE_URL=https://api.minimaxi.com/v1
MINIMAX_CHAT_MODEL=MiniMax-M2.7

# 企业微信机器人（可选，不配则不启动）
WEWORK_BOT_ENABLED=true
WEWORK_BOT_ID=your-bot-id
WEWORK_BOT_SECRET=your-bot-secret

3. 启动服务

uvicorn app.main:app --host 0.0.0.0 --port 8765

启动后会自动检测企业微信机器人配置，如果 WEWORK_BOT_ENABLED=true 且 WEWORK_BOT_ID / WEWORK_BOT_SECRET 已配置，机器人会自动在后台线程启动。

访问 http://localhost:8765 即可使用。

4. Docker 部署

docker-compose up -d

单容器部署，数据持久化通过 ./data:/app/data 卷挂载
默认端口 8000，可通过 APP_PORT 环境变量调整
内置健康检查，每 30 秒检查 /health 端点

图片搜索工作流

用户上传图片
  → OCR 识别文字（DeepSeek Vision / PaddleOCR / 阿里云 / 腾讯云，支持 auto fallback）
  → 检查 OCR 内容是否已存在（去重）
  → 存入 SQLite

用户搜索 "孩子不想上学"
  → LLM 查询扩展（生成语义相近的替代表述）
  → 从 DB 倒序取图片（每批 N 张，可配置）
  → 并发池发给 MiniMax M2.7 判断
  → 匹配结果通过 SSE 实时推送到前端
  → 找够指定数量或遍历完 DB 后结束

企业微信机器人

功能

场景	说明
单聊发关键词	清理口语化前缀 → 搜索图片 → 流式回复文本 + 逐张发送图片
单聊发图片	下载解密 → OCR 识别 → 自动去重入库 → 回复结果
进入会话	自动发送欢迎语

配置

在企业微信管理后台创建智能机器人，开启 API 模式（长连接）
获取 Bot ID 和 Secret
在 .env 中配置或通过网页端设置页面配置

注意事项

图片消息仅支持单聊，群聊中发图片不会触发机器人
机器人支持多人同时使用（asyncio 异步架构）
大图片支持分片上传（init → chunk → finish）
配置修改后可通过网页端「重启机器人」按钮生效

API 概览

知识页面

方法	路径	说明
GET	`/api/v1/pages`	知识页面列表（分页）
GET	`/api/v1/pages/{id}`	获取知识页面详情
POST	`/api/v1/pages`	创建知识页面
PUT	`/api/v1/pages/{id}`	更新知识页面
DELETE	`/api/v1/pages/{id}`	删除知识页面
POST	`/api/v1/pages/{id}/rebuild-index`	重建页面嵌入索引

搜索

方法	路径	说明
POST	`/api/v1/search`	关键词搜索知识库

图片 OCR

方法	路径	说明
POST	`/api/v1/images/recognize`	上传并识别图片（两步：先上传再识别）
POST	`/api/v1/images/recognize-direct`	一步上传并识别图片
POST	`/api/v1/images/batch-recognize`	批量上传并识别
POST	`/api/v1/images/import-path`	服务器路径批量导入
GET	`/api/v1/images/search`	AI 搜索图片（SSE 流式）
GET	`/api/v1/images`	获取图片列表（分页）
GET	`/api/v1/images/{id}`	获取图片识别结果
DELETE	`/api/v1/images/{id}`	删除图片
POST	`/api/v1/images/dedup`	一键去重

导入导出

方法	路径	说明
POST	`/api/v1/import/file`	导入文件（.md/.txt/.docx）
POST	`/api/v1/import/directory`	导入整个目录
GET	`/api/v1/export`	导出知识库（JSON/Markdown）

系统设置

方法	路径	说明
GET	`/api/v1/settings`	获取系统设置
PUT	`/api/v1/settings`	更新系统设置
GET	`/api/v1/settings/stats`	获取统计信息
POST	`/api/v1/settings/test/embedding`	测试嵌入模型连通性
POST	`/api/v1/settings/test/llm`	测试 LLM 服务连通性
POST	`/api/v1/settings/test/ocr`	测试 OCR 服务连通性
GET	`/api/v1/settings/bot/status`	获取机器人状态
POST	`/api/v1/settings/bot/restart`	重启机器人

系统

方法	路径	说明
GET	`/health`	健康检查

配置说明

OCR Provider

Provider	说明	额外配置
`deepseek`	DeepSeek Vision（推荐，支持 Ollama 自部署）	`DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`
`paddleocr`	本地 PaddleOCR（免费、离线）	无
`aliyun`	阿里云 OCR	`ALIYUN_OCR_ACCESS_KEY`, `ALIYUN_OCR_SECRET`
`tencent`	腾讯云 OCR	`TENCENT_OCR_SECRET_ID`, `TENCENT_OCR_SECRET_KEY`
`auto`	自动 fallback（PaddleOCR → DeepSeek → 阿里云 → 腾讯云）	配置多个 Provider

嵌入模型

Provider	说明	额外配置
`minimax`	MiniMax 嵌入	`MINIMAX_API_KEY`
`openai`	OpenAI 嵌入（兼容硅基流动等第三方接口）	`OPENAI_API_KEY`
`zhipu`	智谱 AI 嵌入	`ZHIPU_API_KEY`
`dashscope`	阿里云 DashScope	`DASHSCOPE_API_KEY`
`local_bge`	本地 BGE 模型	`LOCAL_BGE_MODEL_PATH`

网页端可配置参数

参数	说明	默认值	范围
搜索返回数量	每次搜索最多返回多少条匹配结果	3	1-10
LLM 批量判断数量	每批发给 LLM 判断的图片数量	10	1-50
OCR 并发数量	多用户同时上传时 OCR 并发识别数量	1	1-10

架构设计

策略模式: OCR 和嵌入服务均使用抽象基类 + 工厂模式，支持多 Provider 热切换
单例模式: EmbeddingService、OCRService、LLMService 均为类方法单例，支持 reset() 重置
异步架构: 全异步（FastAPI + SQLAlchemy async + asyncio），企业微信机器人在后台线程独立事件循环运行
SSE 流式: 图片搜索使用 Server-Sent Events 实时推送结果，前端可即时展示
并发控制: OCR 并发通过 Semaphore 控制，LLM 搜索通过并发池（最多 10 个）控制
运行时配置: 所有参数均可通过网页端设置 API 动态修改，无需重启服务

许可证

MIT

README.md Unescape Escape

HuiBrain - 中文直播教育知识库系统

功能特性

知识库管理

图片 OCR

AI 搜索

企业微信机器人

MCP 协议

其他

技术栈

项目结构

数据模型

快速开始

1. 环境准备

2. 配置 .env

3. 启动服务

4. Docker 部署

图片搜索工作流

企业微信机器人

功能

配置

注意事项

API 概览

知识页面

搜索

图片 OCR

导入导出

系统设置

系统

配置说明

OCR Provider

嵌入模型

网页端可配置参数

架构设计

许可证

README.md