# hummingbird_ocr

**Repository Path**: fireae/hummingbird_ocr

## Basic Information

- **Project Name**: hummingbird_ocr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 蜂语OCR

基于多模态大模型的智能 OCR 识别工具，支持图片转 Markdown 格式，精准识别文字、公式、表格等内容。

## 功能特性

- **智能 OCR 识别** - 基于 Qwen3-VL 多模态大模型，精准提取图片中的文字内容
- **Markdown 输出** - 自动转换为 Markdown 格式，保留标题、列表、表格等结构
- **多格式支持** - 支持 JPG、PNG、PDF 等多种图片格式
- **文件管理** - 登录用户可享受文件上传、存储和历史记录功能
- **双主题切换** - 支持绿色自然主题和蓝色海洋主题切换
- **响应式设计** - 适配桌面端和移动端设备

## 技术栈

- **前端框架**: React 18 + TypeScript
- **构建工具**: Vite 6
- **样式方案**: Tailwind CSS 3 + 自定义设计系统
- **路由管理**: React Router DOM 7
- **状态管理**: React Context (AuthContext, ThemeContext)
- **后端服务**: Supabase (认证 + 文件存储)
- **OCR 引擎**: Qwen3-VL (通过 OpenAI 兼容 API 调用)
- **UI 组件**: Lucide React (图标) + Framer Motion (动画)

## 项目结构

```
src/
├── components/          # 可复用组件
│   ├── FileUploadArea.tsx    # 文件上传区域
│   ├── FileList.tsx          # 文件列表
│   ├── SourceFilePreview.tsx # 源文件预览
│   ├── OCRResultDisplay.tsx  # OCR 结果展示
│   ├── ThemeToggle.tsx       # 主题切换按钮
│   └── Empty.tsx             # 空状态组件
├── contexts/            # React Context
│   ├── AuthContext.tsx       # 认证状态管理
│   └── ThemeContext.tsx      # 主题状态管理
├── hooks/               # 自定义 Hooks
│   └── useTheme.ts           # 主题相关 Hook
├── lib/                 # 工具库
│   ├── supabase.ts           # Supabase 客户端配置
│   ├── fileStorage.ts        # 文件存储服务
│   ├── vlmApi.ts             # VLM OCR API 服务
│   └── utils.ts              # 通用工具函数
├── pages/               # 页面组件
│   ├── Home.tsx              # 首页/落地页
│   ├── Login.tsx             # 登录页
│   ├── Signup.tsx            # 注册页
│   └── OCRPage.tsx     # OCR 识别主页面
├── static/              # 静态资源
│   └── logo.svg
├── App.tsx              # 根组件
└── main.tsx             # 应用入口
```

## 本地开发

### 环境准备

- [Node.js](https://nodejs.org/) (推荐 v18+)
- [pnpm](https://pnpm.io/installation) (包管理器)

### 安装依赖

```sh
pnpm install
```

### 环境变量配置

创建 `.env` 文件并配置以下环境变量：

```env
# Supabase 配置 (可选，用于用户认证和文件存储)
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

# VLM API 配置 (用于 OCR 识别)
VITE_VLM_API_URL=http://localhost:11434/v1
VITE_VLM_API_KEY=your_api_key
```

### 启动开发服务器

```sh
pnpm run dev
```

应用将在 http://localhost:3000 启动

### 构建生产版本

```sh
pnpm run build
```

构建产物将输出到 `dist` 目录

## 可用脚本

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动开发服务器 (端口 3000) |
| `pnpm dev:client` | 启动客户端开发服务器 |
| `pnpm build` | 构建生产版本 |
| `pnpm build:client` | 构建客户端静态文件 |

## 核心功能说明

### OCR 识别流程

1. 用户上传图片文件 (支持拖拽上传)
2. 前端将图片转换为 Base64 格式
3. 调用 VLM API (Qwen3-VL 模型) 进行识别
4. 返回 Markdown 格式、JSON 格式和纯文本格式的识别结果
5. 支持一键复制和下载结果

### 用户认证

- 基于 Supabase Auth 实现
- 支持邮箱注册/登录
- 登录用户可上传 PDF 文件并保存历史记录
- 未登录用户可使用基础的图片 OCR 功能

### 主题系统

- 内置两套配色方案：
  - **绿色主题** (默认): 自然、有机的生物亲和设计风格
  - **蓝色主题**: 清新、专业的海洋风格
- 使用 Tailwind CSS 自定义颜色配置
- 通过 ThemeContext 实现全局状态管理

## 依赖说明

### 生产依赖

- `@supabase/supabase-js` - Supabase 客户端
- `react` / `react-dom` - React 核心库
- `react-router-dom` - 路由管理
- `react-pdf` - PDF 文件预览
- `framer-motion` - 动画效果
- `lucide-react` - 图标库
- `recharts` - 图表组件
- `sonner` - Toast 通知
- `tailwind-merge` / `clsx` - 样式类名处理
- `zod` - 数据校验

### 开发依赖

- `vite` - 构建工具
- `@vitejs/plugin-react` - React 插件
- `typescript` - TypeScript 支持
- `tailwindcss` / `autoprefixer` / `postcss` - CSS 处理
- `vite-tsconfig-paths` - 路径别名支持

## 许可证

MIT License